Lunaris is a production-grade agent-memory engine written in pure Rust, with first-class Python (pip install lunaris) and TypeScript (npm i @pilotspace/lunaris) SDKs generated from the same source of truth.

You feed it raw observations — chat turns, documents, tool outputs — as Episodes. It chunks, embeds, and (optionally) extracts entities, relations, and facts using a small local LLM, then stores everything in a bi-temporal MVCC store backed by Moon, a high-performance Redis-compatible substrate (and, as of 0.7.0, the only backend). Agents query it through a composable retrieval DSL that fuses semantic search, graph traversal, and BM25 keyword lookup, with an optional cross-encoder rerank pass on top.

async fn demo() -> Result<(), lunaris::LunarisError> {
async fn demo() -> Result<(), Box<dyn std::error::Error>> {
use lunaris::{EpisodeBuilder, Lunaris, Query, Scope};

let lunaris = Lunaris::open("moon://127.0.0.1:6380").await?;
let scope   = Scope::new("acme.agent-1")?;
let scoped  = lunaris.scoped(scope);

let lsn  = scoped.ingest(EpisodeBuilder::new("user-msg", "Alice loves chocolate.")).await?;
let hits = scoped.recall(Query::text("what does Alice like?")).await?;
Ok(())
}
Ok(())
}

Want a hybrid plan (vector + BM25, fused, reranked)? Compose it with the retrieval DSL:

use lunaris::{Lunaris, Scope};
async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{Lunaris, Scope};
async fn demo() -> Result<(), Box<dyn std::error::Error>> {
let lunaris = Lunaris::open("moon://127.0.0.1:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
use lunaris::{Keyword, Query, Vector};

let hits = scoped
    .dsl()
    .with_root(Vector::new("chunks", 30).and(Keyword::bm25("chunks", 30)).fuse_rrf(60).top(5))
    .execute(Query::text("what does Alice like?"))
    .await?;
Ok(())
}
Ok(())
}

Use it from your agent (MCP)

Don’t want to write SDK code? Lunaris ships an MCP server so coding agents — Claude Code, Codex, or any MCP client — get persistent, scope-isolated memory over stdio. Install the binary and register it:

# no Rust toolchain needed — both download a prebuilt binary on first run
claude mcp add --transport stdio lunaris \
  -e LUNARIS_MCP_STORAGE=moon://127.0.0.1:6381 \
  -- npx -y @pilotspace/lunaris-mcp
# or: claude mcp add --transport stdio lunaris \
  -e LUNARIS_MCP_STORAGE=moon://127.0.0.1:6381 \
  -- uvx lunaris-mcp

Building from source instead? lunaris-mcp is not on crates.io (it depends on a publish = false crate), so use the git form: cargo install --git https://github.com/pilotspace/lunaris lunaris-mcp.

The agent then calls eleven memory.* tools — seven durable-memory tools (ingest, recall, forget, list_scopes, record_decision, record_edit, status) plus four working-memory scratchpad tools (scratchpad_write, scratchpad_read, scratchpad_grep, scratchpad_consolidate):

memory.ingest  source="src:notes"  content="The ingest pipeline writes one atomic_write per episode."
memory.recall  query="ingest atomicity"  k=3

Scope is derived per-repo from the git remote. LUNARIS_MCP_STORAGE must name a Moon — there is no default store as of 0.7.0, and the server refuses to boot without one. memory.recall then runs hybrid vector + BM25 recall. See MCP Server for the full guide.

The three moats

Three properties define what Lunaris is. Every commit is reviewed against them; any feature that weakens any of the three is rejected.

If everything else fails, that performance + correctness contract must hold — it’s what differentiates Lunaris from Mem0, Zep, and Cognee. See Why Lunaris for the honest “use a different tool when…” criteria.

How this book is organized

• Getting Started — install, a 10-minute quickstart, and the core concepts (episodes, scope, bi-temporal MVCC, the atomic write).
• Guides — one chapter per capability: ingest, the retrieval DSL, forget, the opt-in graph pipeline, consolidation & verification, multi-agent scoping.
• Cookbook — the built-in recipe types (chat agents, document corpora, Slack/email archives, code-repo memory, timelines) as copy-pasteable how-tos.
• Reference — the exhaustive configuration reference (every feature flag and LUNARIS_* env var), the generated API docs, and the error taxonomy.
• Operations — running the HTTP server, choosing a backend, durability & recovery.
• SDKs — Python and TypeScript surface notes.
• Integrations (MCP) — the MCP server and its Claude Code / Codex integration guides.
• Migrating From — Mem0 / Zep / Cognee mapping tables.
• Protocol — the MemoryProtocol 0.1 HTTP/SSE wire spec and its conformance suite.

Source of truth. Where a claim in this book disagrees with the Rust source, the source wins. Many pages carry path:line cross-references back into the crates; the generated API reference is built from cargo doc on every release.