Introduction

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.

Why Lunaris

Read this before evaluating Lunaris. It is the one-page elevator pitch plus the honest “use a different tool when…” criteria — the page a maintainer points at when someone asks “how does this compare to X?” The migration chapters go deeper; this page is the pitch and the exclusions.

The one-line claim

Sub-25 ms recall at 100,000 documents per scope, with provable atomicity and an opt-in graph. Embedded Rust core. Python + TypeScript bindings generated from the same source of truth. Apache 2.0. That’s it.

The latency half is measured: p50 19.2–22.4 ms / p99 23.4–24.4 ms engine-side at 100k docs/scope on single-shard Moon v0.8.5 (Apple M4 Pro, graph OFF, rerank OFF, k=30) — capacity.md. We do not claim “millions”: the 1k → 100k trend (0.7 ms → ~20 ms p50) says a million-fact scope would not meet 25 ms p50 on that hardware, and no run at that size exists.

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, since 0.7.0, only Moon: the Postgres and SQLite backends were removed. 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.

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.

A few more differentiators, with proof:

When Lunaris is the answer

Pick Lunaris when you can say yes to most of these:

• My agent’s recall p50 is on the hot path of user experience — 300 ms feels slow.
• I want a single substrate (Moon) instead of running a vector DB + graph DB + relational DB.
• I need bi-temporal queries: “what did the agent believe at time T?” (bi-temporal writes always; as-of reads on the search and graph lanes only — a historical KV read is refused on Moon, so if you need to hydrate a row as it was, Lunaris v0 is not the tool)
• I need multi-tenant isolation that the type system enforces, not just a user_id string the caller could swap.
• I want a composable retrieval DSL where vector + keyword + graph fuse in one typed expression, not three API calls glued together.
• My stack is Rust, or Python with a Rust binary in the build chain is acceptable, or TypeScript with a NAPI binding is acceptable.
• Apache 2.0 + open source matters; I want to read the substrate code, not depend on a hosted service.
• I need a hosted SaaS with zero infra ownership. - Lunaris-cloud in progress (shared and managed memories in graph)
• My recall latency budget is 500+ ms anyway. The 25 ms contract isn’t free to operate; if you don’t need it, pick the hosted option.

How Lunaris compares to Mem0 / Zep / Cognee

Already running one of these? The migration chapters walk through ingest, recall, time-travel, and forget — code-side, with honest “stay on $incumbent if…” criteria:

• Migrating from Mem0 — Mem0 has no bi-temporal layer, so the migration is the bi-temporal upgrade.
• Migrating from Zep — Zep already has bi-temporal facts, so the conversation is latency + substrate simplification (1 service vs 2).
• Migrating from Cognee — Cognee is pipeline-oriented; Lunaris is operator-oriented. The question is “where does your domain logic live — ingest time or recall time?”

What’s still on the runway

v0.2.x is the OSS-publish milestone, not the end state:

• v0.3 self-hosted — Docker / Helm, SLOs, design partners. The hosted-substrate experience for teams that want Lunaris but don’t want to operate Moon themselves. Also lands the typed Scope + EpisodeBuilder surface in the Python / TS SDKs and per-scope ScopedLunaris::forget.
• Ecosystem (shipped) — LangGraph / CrewAI / Letta adapters via the lunaris-integrations package (pip install lunaris-integrations[langgraph], [crewai], [letta] — published from the next v* tag; until then install it from a checkout, see integrations/README.md). The “drop Lunaris into your existing agent framework” experience: LangGraph and CrewAI are drop-in store / storage classes; Letta ships as a client-backed connector shim + recipe (its archival store is server-side). The MCP server remains the universal shim for frameworks without a dedicated adapter.

Where to go next

• Try it now → Installation, then the 10-Minute Quickstart.
• Understand the model → Core Concepts.
• Evaluate against your corpus → read the moat table above + the migration chapter for your current tool, then run examples/quickstart-py/ against your real data.

Architecture at a Glance

Three pictures explain Lunaris. If you only have ninety seconds, read the captions; the full architecture page carries the crate-level detail and the proof links.

1. The layers

Lunaris is a pure-Rust engine with thin SDK shells. Your agent talks to the surface layer (Python, TypeScript, HTTP, or MCP). The engine turns observations into structured memory and queries into fused result sets. Everything below the engine is a port — a Rust trait — with one implementation behind it:

• Moon — our Redis-compatible substrate, and since 0.7.0 the only backend. The Postgres portability proof and the SQLite onboarding backend were removed; the port stays a trait, so a third-party substrate is still an open extension point.

You never write Moon commands or SQL. You write one typed expression (see The Retrieval DSL for the full operator set):

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{Keyword, Lunaris, Query, Scope, Vector};

let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped  = lunaris.scoped(Scope::new("acme.agent-1")?);
let last_tuesday = lunaris_core::Hlc::from_parts(1_736_467_200_000, 0, 0);

// Hybrid recall: vector + BM25 fused server-side, with a time-travel cut.
let hits = scoped
    .dsl()
    .with_root(Vector::new("chunks", 30).and(Keyword::bm25("chunks", 30)).fuse_rrf(60).top(5))
    .as_of(last_tuesday)
    .execute(Query::text("what did we decide about the pricing page?"))
    .await?;
Ok(())
}

2. The data path

Ingest flows left to right: observation → chunking → local embedding (no API key, no network — models run in-process on CPU) → optional entity/fact extraction → one atomic commit. That last box is the heart of the system: vectors, keywords, graph edges, audit trail, and the consolidation queue land in a single transaction. Either your agent’s memory is complete, or the write didn’t happen. There is no “the vector store has it but the graph doesn’t” state — the failure mode every fan-out memory stack eventually hits.

Recall flows right to left: your query fans out across semantic, keyword, and graph lanes inside the substrate, gets fused by reciprocal-rank fusion, optionally reranked by a cross-encoder, and returns in p50 19.2–22.4 ms · p95 22.3–24.1 ms · p99 23.4–24.4 ms against the target corpus of 100,000 documents per scope — engine-side (query embedding excluded), graph OFF, rerank OFF, k=30, single-shard Moon v0.8.5 on an Apple M4 Pro, 500 timed queries after 50 warmup, run-to-run p50 drift ± 3 ms (envelope + method, raw samples). The published contract is p50 < 25 ms, so the headroom is ≤ 25 %. Since the 2026-06-10 concurrent-hydration fan-out the tail is flat even at k=30 — p50 6.0 ms / p99 6.2 ms (A/B methodology). The contract was re-validated on Moon v0.3.0 with the 4-bit GGUF granite embedder — retrieval-only p50 3.1 ms / p99 3.6 ms on a 3k-doc SQuAD corpus (v0.3.0 rerun, which also sizes the Navigate operator’s recall edge on graph-linked corpora: plain 0.00 → nav 1.00 recall@5 for +0.05 ms).

3. Why Moon makes this possible

The conventional agent-memory stack is three databases and a broker: a vector DB for similarity, a graph DB for relationships, a relational DB for records, and a queue for background work. Four systems, four failure domains, four consistency boundaries — and no transaction that spans them.

Moon collapses the stack into one process. The payoff isn’t abstract — it shows up feature by feature. Each Lunaris capability you actually use maps onto something Moon does natively, so the engine never reimplements a vector index, a BM25 scorer, a graph engine, or a transaction log on top of a dumb key-value store:

The same story as a lookup table — the command family behind each row:

One substrate, one transaction boundary, one operational surface. That is the design bet — and the measured sub-25 ms recall is what the bet pays out.

How that lands against other tools

Most agent-memory engines do the same job; what differs is the guarantees. Because Lunaris pushes vectors, keywords, the graph, the queue, and a transaction boundary into a single substrate, several rows below are a ✓ for Lunaris where the fan-out tools can only manage a partial or an ✗:

Every cell above is taken straight from the full comparison table in Why Lunaris, which carries the nuance each mark compresses — plus the honest “use a different tool when…” criteria. The short version: Lunaris trades a hosted-SaaS option and Python-native simplicity for a latency contract and an atomicity guarantee the fan-out tools structurally can’t make.

Honest footnote: plain key-value point reads on Moon are not natively temporal (the engine applies the temporal cut itself), and index schemas are fixed at creation. The architecture page lists every limit next to every advantage.

Where next

• 10-Minute Quickstart — first recall against a local Moon
• Core Concepts — episodes, primitives, scopes, bi-temporal time
• The Retrieval DSL — composing vector / keyword / graph queries
• The Storage Backend — Moon setup and its honest limits

Installation

Add Lunaris to a Rust, Python, or TypeScript project, stand up the storage backend it needs, and (optionally) run the HTTP server. For the exhaustive list of feature flags and LUNARIS_* environment variables, see the Configuration Reference.

Prerequisites

Lunaris needs a running Moon and an embedder. As of 0.7.0 there is one storage scheme:

Every retired spelling — memory://, sqlite:///path, postgres://… — is rejected by Lunaris::open with an UnsupportedScheme error carrying the migration link. The Postgres and SQLite backends were deleted in 0.7.0; if you have data in one, migrate it before you bump your lunaris pin — see 0.6 → 0.7.

Storage: Moon

docker run -d --name lunaris-moon -p 6380:6379 \
  ghcr.io/pilotspace/moon:0.8.5 \
  --shards 1 --protected-mode no --appendonly yes

use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = lunaris::Lunaris::open("moon://127.0.0.1:6380").await?;
Ok(())
}

--shards 1 is not optional: a Lunaris ingest is one MULTI/EXEC transaction, and a sharded Moon rejects cross-shard writes. The image defaults to --shards 0 (auto), so the flag has to be passed explicitly. --appendonly yes is what makes the store survive a restart.

Moon provides native FT.SEARCH (vector + BM25), GRAPH.QUERY, a message queue, and native RRF fusion — the fuse_rrf operator collapses a (Vector + Keyword) pair on the same index into one round trip.

Full production setup — persistence, memory limits, backups, health probes — is in Running an external Moon. See Choosing a Backend for the embedding-dimension story (the Moon adapter sizes its vector index to the embedder — default 768-d, set wider via connect_with_dim).

Embedder: in-process llama.cpp, no external service required

v0.6 llama.cpp-only cutover. The candle inference stack is deleted. The only local embed/rerank runtime is lunaris-llamacpp — in-process llama.cpp FFI, static-linked, no external server. See docs/decisions/2026-07-10-llamacpp-only-cutover.md (the cutover ADR) and docs/migration/0.5-to-0.6-llamacpp-only.md (the migration guide).

The default embedder is granite-embedding-311m-multilingual-r2 (768-d), loaded from a Q4_K_M GGUF (~240 MiB) via in-process llama.cpp — no Ollama, no external service required. The default reranker is bge-reranker-v2-m3 (Q5_K_M GGUF, ~446 MiB), lazy-loaded on first recall. Both GGUFs are expected at ~/.lunaris/models/; the MCP server stages them lazily on first recall, other deployments download them out-of-band. An air-gapped Ollama HTTP embedder remains available as an operator escape hatch behind --features embed-remote (resolves after the llama.cpp step).

Override the artifact paths with LUNARIS_EMBEDDER_GGUF=<path> / LUNARIS_RERANKER_GGUF=<path>. There is no auto-download in the umbrella crate — a missing GGUF logs a WARN and falls back to NoopEmbedder / NoopReranker. Operators running an air-gapped Ollama for embedding (not the supported path) can set LUNARIS_EMBEDDER_OLLAMA_URL=<endpoint> alongside --features embed-remote.

Building the llamacpp feature (default) needs cmake + a C++ toolchain. For a pure-Rust, no-inference build (Tier-0, small devices): default-features = false → NoopEmbedder/NoopReranker.

See the Configuration Reference for the full feature matrix.

Rust

The umbrella crate is published as lunaris-memory (the bare lunaris name on crates.io is owned by an unrelated project); the library itself is still named lunaris, so you import it as use lunaris::…. Rename it in Cargo.toml:

[dependencies]
lunaris = { package = "lunaris-memory", version = "0.6" }
tokio   = { version = "1", features = ["macros", "rt-multi-thread"] }

cargo add lunaris-memory --rename lunaris
cargo add tokio --features macros,rt-multi-thread

Feature flags on the lunaris umbrella crate (full table in the Configuration Reference):

Note. llamacpp is the only local embed/rerank runtime and is on by default — building it needs cmake + a C++ toolchain. The flags below also gate the extractor/verifier remote-provider backends and the escape-hatch paths.

default = ["llamacpp"]. Extractor and verifier are remote-only — LUNARIS_EXTRACT_PROVIDER / LUNARIS_VERIFY_PROVIDER (anthropic|openai|gemini|minimax|openai-compat, the last covering Ollama / llama-server / vLLM / LM Studio via LUNARIS_OPENAI_COMPAT_BASE_URL) or a caller-supplied with_extractor / with_verifier impl; unset resolves to NoopExtractor/NoopVerifier. For a pure-Rust, no-C++-toolchain build (Tier-0): default-features = false.

Smoke test — needs the Moon from Prerequisites running:

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = lunaris::Lunaris::open("moon://127.0.0.1:6380").await?;
    println!("{lunaris:?}");
    Ok(())
}

There is no zero-dependency scheme to start from since 0.7.0 — open either reaches a Moon or returns an error naming what to start.

Python — pip install lunaris

pip install lunaris          # or: uv add lunaris

PyO3 0.26 baseline; Python 3.11+. The wheel bundles the compiled extension — no Rust toolchain needed at install time. The Python surface mirrors the Rust handle: await lunaris.open(url) → await handle.ingest(episode) → await handle.recall(). See the Python SDK chapter for the full surface.

Developing against this repo before the PyPI release? Build the binding in place with maturin develop --release from crates/lunaris-py/, then import lunaris resolves to the local build. lunaris-py is a cdylib and is excluded from cargo test --workspace.

TypeScript — npm i @pilotspace/lunaris

npm i @pilotspace/lunaris

napi-rs 3.x, Node 20+ ABI. Prebuilt .node binaries ship in the package. The surface mirrors the Rust handle: await lunaris.open(url) → await handle.ingest(episode) → await handle.recall(). See the TypeScript SDK chapter.

Developing against this repo before the npm release? Run npm run build (= napi build) from crates/lunaris-ts/, then npm install ../../crates/lunaris-ts from your project. lunaris-ts is a cdylib and is excluded from cargo test --workspace.

Running the HTTP server

Non-Rust runtimes talk to Lunaris through lunaris-server — an axum service implementing MemoryProtocol 0.1 (/v1/{ingest,recall,forget,snapshot}, HTTP + SSE). It needs a storage URL and a bearer-token map:

# One-time: a bearer-token map. Every /v1/* request needs a token from it.
cat > /tmp/lunaris-tokens.json <<'EOF'
{
  "dev-token-xxx": { "tenant": "acme", "scopes": ["acme.agent-1", "acme.agent-2"] }
}
EOF

cargo run -p lunaris-server -- \
  --storage moon://127.0.0.1:6380 \
  --bind 0.0.0.0:8080 \
  --tokens-file /tmp/lunaris-tokens.json

Every CLI flag has a matching LUNARIS_* env var (the CLI flag wins). The key knobs:

The tenant claim from the bearer token is the only source of truth for the partition scope — route handlers ignore any scope / tenant field on the request body. Probe surfaces /healthz and /metrics are unauthenticated. Full route list, DTOs, and the SSE contract: Running the HTTP Server and the MemoryProtocol 0.1 spec.

Removed in 0.7.0. lunaris-server migrate and lunaris-server bootstrap-db were Postgres-only (embedded migration set, RLS app-role provisioning) and went with the backend, along with LUNARIS_ADMIN_URL. Moon needs no schema migration and no role bootstrap — start it, point --storage at it. Indexes are created on first connect.

Next

• 10-Minute Quickstart — ingest and recall your first episode, Rust / Python / TypeScript side by side.
• Core Concepts — episodes, scope, bi-temporal MVCC, the atomic write.
• Configuration Reference — every feature flag and LUNARIS_* variable.

10-Minute Quickstart

From a fresh checkout to your first ingest + recall against a local Moon in under ten minutes — Rust is canonical, with Python and TypeScript mirrors side by side. Moon is the only backend as of 0.7.0; the Postgres and SQLite paths this chapter used to open with were deleted (see 0.6 → 0.7). The default embedder is in-process llama.cpp granite-r2 (GGUF) — no Ollama needed for embedding. The shipped examples/quickstart-rs crate opts into the ollama build to enable the Ollama extractor + verifier path — see step 2.

API note. This chapter uses the retrieval surface that exists in the v0.2.x source: ScopedLunaris::recall(Query::text(...)) returns Vec<Hit> directly, and ScopedLunaris::dsl() (or the bare Lunaris::recall()) returns a RetrievalBuilder you drive with .with_root(...) + .execute(Query::text(...)). A fluent shorthand like recall().vector("chunks", 30).top(5).execute() is a planned ergonomic wrapper that is not yet on the builder — RetrievalBuilder has no .vector(...) method today. When in doubt, the Rust source wins.

0. Get the code

git clone https://github.com/pilotspace/lunaris && cd lunaris

1. Bring up Moon

The examples/quickstart-*/ directories share one compose file, which runs the published ghcr.io/pilotspace/moon image on localhost:6380:

cd examples/quickstart-rs
docker compose up -d
docker compose ps        # wait until lunaris-quickstart-moon is "healthy"

There is no schema step — Moon needs no migration, and Lunaris creates its indexes on first connect. Note the compose file passes --shards 1: a Lunaris ingest is one MULTI/EXEC transaction and a sharded Moon rejects it.

2. Point Lunaris at it

export LUNARIS_STORE_URL="moon://127.0.0.1:6380"

The quickstart binary has no default URL — an unset LUNARIS_STORE_URL is an error, not a fallback to an in-process store.

The default embedder is granite-embedding-311m-multilingual-r2 (768-d), loaded from a Q4_K_M GGUF in-process via llama.cpp (staged at ~/.lunaris/models/) — no Ollama needed for embedding.

The shipped examples/quickstart-rs crate pins features = ["ollama"] in its Cargo.toml to enable the Ollama extractor + verifier path (the smallest external-dep build that exercises a real extraction + verification flow). The embedder and reranker remain in-process llama.cpp regardless. So for this walkthrough, start Ollama and pull the extractor model:

ollama serve &
ollama pull gemma3:4b

Prefer a cloud extractor instead of Ollama? Set LUNARIS_EXTRACT_PROVIDER=minimax (or anthropic/openai/gemini) and the matching API key — extraction and verification are remote-only in v0.6, so there is no all-in-process alternative to Ollama for those two stages.

3–6. Open a handle, ingest, recall, forget

What follows is the canonical Rust flow; the Python and TypeScript mirrors come right after.

Rust

use std::env;

use anyhow::{Context, Result};
use lunaris::{EpisodeBuilder, ForgetTarget, Lunaris, Query, Scope, ScopeSpec, Vector};

#[tokio::main]
async fn main() -> Result<()> {
    tracing_subscriber::fmt::init();

    // 3. Open a handle. `moon://host:port` is the only scheme `open`
    //    accepts since 0.7.0; anything else is an UnsupportedScheme error.
    let url = env::var("LUNARIS_STORE_URL")
        .context("set LUNARIS_STORE_URL — see examples/quickstart-rs/README.md")?;
    let lunaris = Lunaris::open(&url).await.context("Lunaris::open")?;

    // The Scope newtype is the multi-agent partition key (RFC 0001).
    // Scope::new validates the string against [A-Za-z0-9_\-.]{1,128}.
    let scope  = Scope::new("quickstart").context("Scope::new")?;
    let scoped = lunaris.scoped(scope);

    // 4. Ingest one episode. ScopedLunaris::ingest takes an
    //    EpisodeBuilder (scope-less payload); the wrapper stamps the
    //    bound scope on. Exactly one atomic_write per call (INGEST-04).
    let lsn = scoped
        .ingest(EpisodeBuilder::new(
            "quickstart:demo",
            "# Hello from Lunaris\n\nAlice loves chocolate.",
        ))
        .await
        .context("ingest")?;
    println!("ingested at lsn={lsn:?} under scope `quickstart`");

    // 5a. Recall — the one-shot form. ScopedLunaris::recall(query) runs the
    //     default plan (Vector over `chunks`, no fusion/rerank) and returns
    //     Vec<Hit> directly. Least ceremony for a plain semantic lookup.
    let hits = scoped
        .recall(Query::text("who loves chocolate"))
        .await
        .context("recall")?;
    println!("recalled {} hit(s)", hits.len());
    for h in &hits {
        println!("  hit id={:?} score={:.3}", h.id, h.score);
    }

    // 5b. Recall — the composable form. ScopedLunaris::dsl() returns a
    //     RetrievalBuilder pre-seeded with this scope; .with_root sets the
    //     operator tree, .execute runs the plan once and returns Vec<Hit>.
    //     Reach for this when you want hybrid fusion, graph/tree, as_of,
    //     or rerank. (Here: cap the same default Vector plan at top-5.)
    let hits = scoped
        .dsl()
        .with_root(Vector::new("chunks", 30).top(5))
        .execute(Query::text("who loves chocolate"))
        .await
        .context("recall (dsl)")?;
    println!("recalled {} hit(s) via the DSL", hits.len());

    // 6. Forget — soft delete (MVCC: stamps bt.sys_to; prior as_of
    //    reads still see it). A dry-run preview never writes.
    //
    //    NOTE (v0.2.x): Lunaris::forget is hard-coded to Scope::dev()
    //    today, so a forget issued under a real scope like `quickstart`
    //    silently matches zero rows. The dry-run preview below is safe
    //    to run regardless; per-scope ScopedLunaris::forget lands in
    //    v0.3. See CHANGELOG.md "v0.2.0 — Known issues".
    let preview = lunaris
        .forget(ForgetTarget::Scope(ScopeSpec::BySource("quickstart:".into())).dry_run())
        .await
        .context("forget dry-run")?;
    println!("forget preview: preview={} rows_would_write={}", preview.preview, preview.rows_written);

    Ok(())
}

Run it:

cargo run --release

Expected output (LSN values vary):

ingested at lsn=Lsn { wall_ms: 1713789012345, counter: 0 } under scope `quickstart`
recalled 1 hit(s)
  hit id=... score=...
forget preview: preview=true rows_would_write=...

Hybrid recall, one line more. Add BM25 keyword search and fuse it with reciprocal-rank fusion — when both legs sit on the same Moon index fuse_rrf collapses them into a single round trip, otherwise it fuses the leg results client-side. Same API either way:

use lunaris::{Keyword, Lunaris, Query, Scope, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("quickstart")?);
use lunaris::{Keyword, Vector};
let hits = scoped
    .dsl()
    .with_root(
        Vector::new("chunks", 30)
            .and(Keyword::bm25("chunks", 30))
            .fuse_rrf(60)
            .top(5),
    )
    .execute(Query::text("who loves chocolate"))
    .await?;
Ok(())
}

Add .rerank(lunaris.reranker()) before .top(5) for the cross-encoder pass. The full operator catalogue is in The Retrieval DSL.

Python (pip install lunaris)

The typed Scope + EpisodeBuilder Python surface lands in v0.3; today the wire shape is a dict that mirrors lunaris_core::primitives::Episode (the scope field is required).

import asyncio, os
import lunaris
import ulid  # pip install python-ulid


def build_episode(scope: str, content: str) -> dict:
    return {
        "id": str(ulid.ULID()),
        "scope": scope,
        "source": "quickstart:demo",
        "content": content,
        "t_ref": None,
        "bt": {
            "valid": [{"wall_ms": 0, "counter": 0, "node_id": 0}, None],
            "sys":   [{"wall_ms": 0, "counter": 0, "node_id": 0}, None],
        },
        "metadata": {},
    }


async def main() -> None:
    url = os.environ["LUNARIS_STORE_URL"]
    handle = await lunaris.open(url)                          # 3. open
    lsn = await handle.ingest(build_episode("quickstart",     # 4. ingest
                                            "Alice loves chocolate."))
    print(f"ingested at lsn={lsn} under scope `quickstart`")
    # 5. recall — the DSL is reachable from handle.recall(); the typed
    #    Scope binding and the recall walkthrough land alongside the v0.3
    #    SDK story. See examples/quickstart-py/README.md.


asyncio.run(main())

Run: python quickstart.py (or maturin develop --release from crates/lunaris-py/ first if you’re on a repo checkout). See the Python SDK chapter.

TypeScript (npm i @pilotspace/lunaris)

Same story — dict-shaped episode today, typed surface in v0.3.

import * as lunaris from "@pilotspace/lunaris";

function buildEpisode(scope: string, content: string): object {
  const ts = Date.now();
  const id = `01${ts.toString(32).toUpperCase().padStart(10, "0")}`
    .padEnd(26, "0").slice(0, 26);
  return {
    id,
    scope,
    source: "quickstart:demo",
    content,
    t_ref: null,
    bt: {
      valid: [{ wall_ms: 0, counter: 0, node_id: 0 }, null],
      sys:   [{ wall_ms: 0, counter: 0, node_id: 0 }, null],
    },
    metadata: {},
  };
}

const handle = await lunaris.open(process.env.LUNARIS_STORE_URL!);  // 3. open
const lsn = await handle.ingest(buildEpisode("quickstart",          // 4. ingest
                                             "Alice loves chocolate."));
console.log(`ingested at lsn=${lsn} under scope \`quickstart\``);
// 5. recall — handle.recall() exposes the DSL; the typed-Scope binding
//    and the recall walkthrough land with the v0.3 SDK story. See
//    examples/quickstart-ts/README.md.

Run: npx tsx quickstart.mts (or npm run build from crates/lunaris-ts/ first on a repo checkout). See the TypeScript SDK chapter.

Tear-down

docker compose down -v   # -v wipes the pg data volume

What you just did

Next

• Core Concepts — the Episode → ingest → storage → recall mental model, bi-temporal MVCC, the Scope keyspace, the single atomic_write invariant.
• The Retrieval DSL — every operator and fusion / rerank / fallback combinator.
• Ingesting Observations — chunking, embedding, the graph pipeline.

Core Concepts

The mental model behind Lunaris: you write Episodes, ingest turns them into stored primitives, recall composes a read plan over them — and every layer is bi-temporal, scope-partitioned, and committed in one atomic write. Read this once and the rest of the book is configuration detail.

The flow: Episode → ingest → storage → recall

          Episode
             |
             v
      +-------------+        (optional)         +----------------+
      |   ingest    | -- graph pipeline ON --> |  extract       |
      |  (chunk,    |                          |  entities +    |
      |   embed,    |                          |  relations +   |
      |   atomic    |                          |  facts         |
      |   write)    | <---- validator --------+----------------+
      +------+------+
             |                                            ^
             v                                            |
      +-------------+                             +--------------+
      |   storage   | <-- MVCC supersede -------> | forget       |
      | (KV/Vector/ |       (soft/hard)           | (GDPR/audit) |
      |   Graph/    |                             +--------------+
      |   Queue)    |
      +------+------+
             |
   recall    v        rerank
   builder -+-> [vector] ----\                       queue
            +-> [bm25 ]  ---- fuse_rrf --> rerank --> Hit[]
            +-> [graph] ----/                          |
                                                       v
                                               +-------+-------+
                                               | __lunaris_    |
                                               |  verify__     |  <-- verifier worker (default OFF)
                                               | __lunaris_    |
                                               |  consolidate__|  <-- consolidator worker (default OFF)
                                               | __lunaris_    |
                                               |  audit__      |  <-- audit sink
                                               +---------------+

• ingest chunks the episode body (markdown-aware, ~500-token target with ~100-token overlap), embeds each chunk in batches, and commits everything — episode KV row, per-chunk KV rows, per-chunk vector upserts, plus graph/fact rows if the graph pipeline is on — in a single StoragePort::atomic_write call. Then it publishes one message to __lunaris_consolidate__ (best-effort; the data is already durable).
• forget is the inverse: it also commits in one atomic_write (soft delete stamps the MVCC sys end; hard delete is a KvDelete fan-out behind a two-step confirmation token), and emits one audit event.
• recall is read-only: a RetrievalBuilder composes Vector, Keyword, Graph, and Tree (RAPTOR hierarchical) operators (plus fusion / rerank / fallback wrappers) into a plan, executes it once, and returns Vec<Hit>. The one-shot ScopedLunaris::recall(query) is the same builder with its default root left in place. No LLM is on this path — that’s the sub-25 ms moat.

The primitives

Six primitive types, each carrying a BiTemporal stamp and a Scope (crates/lunaris-core/src/primitives.rs):

Only Episode is written by your code; everything below it is derived. Recall queries one of four whitelisted index names — chunks, entities, facts, communities — e.g. Vector::new("chunks", 30).

Bi-temporal MVCC + the HLC

Every primitive carries a BiTemporal (crates/lunaris-core/src/bitemporal.rs):

use lunaris_core::Hlc;
async fn demo() -> Result<(), lunaris::LunarisError> {
pub struct BiTemporal {
    pub valid: (Hlc, Option<Hlc>),  // when the fact is true in the world
    pub sys:   (Hlc, Option<Hlc>),  // when the system observed/recorded it
}
Ok(())
}

Both are half-open [from, to) intervals; to = None means “still current”. valid is world time — “Alice loved chocolate from Jan to March”. sys is system time — “we recorded that on Feb 3rd, and superseded it on April 1st”. The two axes are independent, which is what lets you ask “what did the agent believe at time T?” as a query (.as_of(ts) on the retrieval builder, or read_as_of on the storage port) rather than reconstructing it from a log.

Updates are MVCC supersede, never in-place mutation: a soft delete or an arbitration outcome stamps the old row’s sys end and writes a new row — old as_of reads still resolve correctly. (Backends derive persisted bitemporal from the payload bytes, so a typed-only mutation would be silently lost; the supersede writers patch both.)

Which half is universal. The bi-temporal write model above holds on every backend. As-of reads do not: StoragePort::read_as_of can answer a historical pin only where the backend keeps a KV version chain (supports_historical_kv_reads() == true), and the two backends that did were deleted in 0.7.0. Moon stores Lunaris rows as plain hashes with no version chain, so since v0.6.2 it refuses a historical pin with StorageError::NotSupported (HTTP 501 not_supported) rather than answering with present-time data. Latest-state reads — what every recall, hydrate and forget actually issues — work everywhere, and Moon’s search/graph lanes remain temporal via FT.SEARCH AS_OF and GRAPH.QUERY VALID_AT. Closing the KV gap upstream is tracked against Moon’s TemporalKvIndex.

The clock is a Hybrid Logical Clock (crates/lunaris-core/src/hlc.rs): Hlc { wall_ms: u64, counter: u32, node_id: u16 }, totally ordered by (wall_ms, counter, node_id). When the wall clock doesn’t advance between two ticks, the counter increments — so no two stamps ever collide, even under burst writes. node_id is 0 in single-node v0.

Scope: the multi-agent partition key (RFC 0001)

Every Lunaris operation is partitioned by a Scope — a validated newtype (crates/lunaris-core/src/scope.rs), not a user_id string the caller could swap:

use lunaris::{EpisodeBuilder, Scope};
use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scope  = Scope::new("acme.agent-1")?;   // validates against [A-Za-z0-9_\-.]{1,128}
let scoped = lunaris.scoped(scope);          // ScopedLunaris — every op partitioned
scoped.ingest(EpisodeBuilder::new("user-msg", "Alice loves chocolate.")).await?;
Ok(())
}

Scope::new rejects the empty string, anything over 128 bytes, and any character outside [A-Za-z0-9_\-.]. : is not in the alphabet — by design, so the KV key format can’t byte-alias across scopes (see below). Scope does not derive Deserialize transparently — the hand-rolled impl re-runs the validating constructor, so the wire can’t smuggle an invalid or unintended scope past the type. (Scope::dev() exists but is #[doc(hidden)] — a migration crutch for code paths that haven’t threaded a real scope through yet.)

On the HTTP surface, the tenant claim resolved for the bearer token is the only source of truth for the partition scope — route handlers ignore any scope field on the request body. On Moon, the scope is baked into the key, the FT index name and the graph name (lunaris:{scope}:{kind}:{ulid}, lunaris_{scope}_{kind}_idx), so a cross-scope read has nothing to address rather than being filtered after the fact. Same ULID under two different scopes = two distinct rows, no leak.

Through 0.6.2 a second boundary existed: Postgres row-level security (USING + WITH CHECK, under a NOSUPERUSER NOBYPASSRLS role). That backend was removed in 0.7.0, so today the isolation is structural in the Moon keyspace rather than row-filtered in a database. Details: Multi-Agent & Scope.

The keyspace

KV keys are minted exclusively by lunaris_core::keyspace — episode_key, chunk_key, entity_key, relation_key, fact_key, community_key — in the canonical format:

lunaris:{scope}:{kind}:{ulid}

e.g. lunaris:acme.agent-1:chunk:01J.... Backend crates re-export these helpers; minting a Lunaris KV key from a local helper is a bug. Because : is forbidden in Scope, the {scope} segment can never absorb the :{kind} delimiter — scope isolation is closed at the type level, not by operator discipline.

The single atomic_write invariant (INGEST-04)

This is the correctness moat. One ingest call = exactly one StoragePort::atomic_write — never one commit per chunk. The pipeline builds the full Vec<WriteOp> (episode KV + per-chunk KV + per-chunk vector upsert, plus graph/fact rows when the graph pipeline is on) and hands it to the backend in a single call. Either all of it lands or none of it does — across the vector index, the KV store, the BM25 index, the audit log, and the queue. Fan-out architectures (write to the vector DB, then the store, then the graph) can’t make that guarantee; Lunaris can because it owns the substrate.

It’s grep-pinned and CI gates on it on every push: after stripping comment lines, exactly one real storage.atomic_write call site must remain in crates/lunaris-ingest/src/pipeline.rs (grep -v '^\s*//' crates/lunaris-ingest/src/pipeline.rs | grep -c 'storage\.atomic_write' == 1) — see Ingesting Observations for the exact gate and the graph-on counterpart. Any new ingest fan-out extends the single WriteOp vector — it does not add a second atomic_write. forget holds the same property: one atomic_write per call (zero for a dry-run preview).

Opt-in pipelines: graph, verify, consolidate

Three background pipelines, all default OFF — your dev box doesn’t download a Gemma extractor until you ask:

Each handle is obtained from the Lunaris value after open. The consolidator handle additionally exposes .enable_for_scope(prefix) (a source-prefix filter) for per-scope rollout; the graph and verify handles are .enable() / .disable() only in v0.2.x. Enabling a pipeline with no real backend wired just runs the shipped Noop* impl — no crash, but no useful work either. Details: The Graph Pipeline and Consolidation & Verification.

The two backends

Lunaris::open(url) dispatches on the URL scheme:

Moon is the only backend. Start it with --shards 1 — an ingest is one MULTI/EXEC transaction and a sharded Moon rejects it. Embedding-dimension details and the STORE-07 as-of gap: The Storage Backend.

Next

• The Retrieval DSL — every operator and combinator.
• Ingesting Observations — the chunker, the embedder driver, the graph branch.
• Durability & Recovery — how the bi-temporal store survives a crash.
• Configuration Reference — every feature flag and LUNARIS_* variable.

Where this chapter disagrees with the Rust source, the source wins — the path:line references above point back into the crates.

Data Structures: A Visual Tour

Lunaris transforms raw observations into a rich set of structured primitives before storing them in a bi-temporal MVCC store. This page walks through each stage visually — from the Episode envelope that wraps every input, through chunking and embedding, all the way to the indexed storage layer that makes sub-25ms recall possible.

Step 1 — Observation → Episode

Every agent turn, tool result, or document arrives as a raw Observation and is immediately wrapped in an Episode envelope. The Episode captures identity (id, scope, source), the content string, a reference timestamp (t_ref), free-form metadata, and a BiTemporal record (bt) that tracks both valid-time and system-time intervals.

Step 2 — Chunking + DocTree

The episode content is split into overlapping Chunks using a BPE token counter (target 500 tokens, overlap 100). Each Chunk carries its heading breadcrumb (heading_path), the overlap bridge to the previous chunk (overlap_tail), and a parent_id that will point to its RAPTOR parent node. Heading records also build a DocTree capturing the document’s structural outline.

Step 3 — Embedding + RAPTOR Tree

Each Chunk receives a 768-dimensional embedding from the granite-embedding-311m model in batches of 32. The RAPTOR tree then connects Chunks upward: Community nodes at each level carry a bottom-up extractive summary and a summary_embedding, forming a hierarchy that lets recall query at any granularity.

Step 4 — Graph Primitives

When graph extraction is enabled — or when structured ingest supplies pre-parsed data — Entities, Relations, and Facts are derived. Entity IDs are deterministic blake3 hashes so the same real-world entity always maps to the same id across ingests. Facts carry an activation field that the ACT-R consolidator uses for recency weighting.

Step 5 — Atomic Persist

All write operations — DocTree KvPuts, Episode KvPut, per-Chunk KvPut + VectorUpsert into the “chunks” FT index, per-Community KvPut + VectorUpsert into the “communities” FT index, and optional GraphEdge writes — are collected into a single Vec<WriteOp> and submitted via one storage.atomic_write call. The INGEST-04 invariant guarantees exactly one atomic_write per ingest.

Step 6 — Keyspace

Every primitive is stored under the canonical key format lunaris:{scope}:{kind}:{ulid}, where scope is a validated string (alphabet [A-Za-z0-9_-.]{1,128}, : explicitly rejected), kind is one of episode, chunk, entity, relation, fact, or community, and the ulid provides a sortable 128-bit unique identifier.

Step 7 — Bi-temporal MVCC

Every primitive carries a BiTemporal record with two interval fields: valid (when the fact was true in the world) and sys (when it was recorded in Lunaris). Each write appends a new version row; old versions are never deleted.

read_as_of(T) returns the version visible at logical time T — on a backend that keeps a KV version chain. No 0.7.0 backend does. Moon’s Lunaris rows are plain hashes, so a historical read_as_of returns an explicit StorageError::NotSupported (HTTP 501 not_supported) instead of quietly handing back today’s row, and the Postgres/SQLite backends that answered it (supports_historical_kv_reads() == true) were deleted in 0.7.0. Latest-state reads are unaffected, and the search and graph lanes stay temporal through FT.SEARCH AS_OF / GRAPH.QUERY VALID_AT.

Step 8 — Indexes

Three indexes sit over the store. A vector FT index on “chunks” and a separate one on “communities” enable 768-d cosine similarity search. A BM25 keyword index enables term-frequency scoring. Graph edges capture Relations for graph traversal. Moon’s native FT.* commands serve all three modes — Lunaris does not bundle a separate HNSW or BM25 library. At query time, results from all lanes are fused using RRF (k=60).

Ingesting Observations

Reach for this chapter when you need to put data into Lunaris — durably, with exactly one storage transaction per call. Every write begins with ScopedLunaris::ingest. One call commits one atomic_write on the backend, whether the graph pipeline is on or off.

The shape

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{EpisodeBuilder, Lunaris, Scope};

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

let lsn = scoped
    .ingest(EpisodeBuilder::new("notes.md", "# Notes\nThe quick brown fox."))
    .await?;
Ok(())
}

EpisodeBuilder (crates/lunaris/src/episode_builder.rs) is a scope-less payload builder — source, content, and the optional t_ref / metadata / id. The scope is stamped exactly once, by ScopedLunaris::ingest, via the pub(crate) EpisodeBuilder::into_episode. Callers cannot reach around the ScopedLunaris wrapper to inject an arbitrary scope — that is the type-level guard behind multi-agent isolation.

The returned value is an Lsn — a replay cursor, not a primary key. It tells the snapshot endpoint (GET /v1/snapshot/{lsn}) where to resume. De-dupe on Episode::id, never on Lsn.

What ingest does

ScopedLunaris::ingest stamps the scope and delegates to Lunaris::ingest, which reads the graph-pipeline toggle once at the top and picks a branch (crates/lunaris/src/ingest.rs:64-152). Either branch runs:

1. Chunk — lunaris_ingest::chunk_markdown(&content, 500, 100): a markdown-aware chunker, ~500-token target, 100-token overlap, heading path preserved on every chunk (crates/lunaris-ingest/src/chunker.rs).
2. Embed — embedder.embed_batch(&[..]) in batches of INGEST_EMBED_BATCH_SIZE = 32. On a batch error, it degrades to per-chunk single-input embeds; a per-chunk failure surfaces immediately as LunarisError::Storage(Backend(_)) (crates/lunaris-ingest/src/pipeline.rs:120-178). The default embedder is granite-embedding-311m-multilingual-r2 (768-d, Q4_K_M GGUF), running in-process via llama.cpp — no external service required; the GGUF is staged at ~/.lunaris/models/ (the MCP server stages it lazily on first recall; other deployments download it out-of-band). See Configuration → Embedder.
3. Assemble one Vec<WriteOp> — one KvPut for the episode, plus per chunk a KvPut (chunk JSON) and a VectorUpsert (768-d embedding + {episode_id, heading_path, offset, text, source} metadata). The text field is what lets Moon’s BM25 index score chunk content.
4. One atomic_write — storage.atomic_write(&scope, &ops).await. All chunks for an episode land or none do; that is the Phase 1 atomicity contract.

After commit (and only after — the data is already durable), ingest fire-and-forgets one __lunaris_consolidate__ envelope carrying {episode_id, lsn, source}. A publish failure logs and continues — it never fails the ingest. See Consolidation & Verification.

The INGEST-04 invariant

Exactly one atomic_write per ingest call. ingest does not commit per chunk — it builds the full Vec<WriteOp> and hands it to the backend once. The invariant is enforced separately per branch:

• Graph OFF — the single call site is crates/lunaris-ingest/src/pipeline.rs:116. CI runs a grep gate on every push: grep -v '^\s*//' crates/lunaris-ingest/src/pipeline.rs | grep -c 'storage\.atomic_write' must equal 1 (comments mentioning atomic_write are stripped first).
• Graph ON — the single call site is in ingest_episode_graph_on (crates/lunaris/src/ingest.rs, the ONE atomic_write call (INGEST-04 …) comment). The extended fan-out (entities, relations, facts) extends the same WriteOp vector — it does not introduce a second atomic_write.

Any new ingest fan-out must extend the existing vector. A second atomic_write is a bug.

With the graph pipeline on

When lunaris.graph_pipeline().enable() has been called (or LUNARIS_GRAPH_ENABLED=1 was set at open time), Lunaris::ingest routes to the graph-on branch:

• Each chunk is run through the Extractor → validator::validate → ValidatedExtraction. (A NoopExtractor — installed automatically when no LUNARIS_EXTRACT_PROVIDER is configured — short-circuits this: applies() == false skips the extract call entirely, so no GraphNodes are written.)
• The single WriteOp vector grows to include, per extracted entity, a GraphNode + a VectorUpsert into the entities index; per relation, a GraphEdge; per fact, a KvPut + a VectorUpsert into the facts index.
• After commit, every NeedsReview item also publishes one __lunaris_verify__ message (consumed only when the verifier pipeline is enabled).

A toggle change during an in-flight ingest takes effect on the next call — never mid-call.

Gotchas

• Bare Lunaris::ingest(Episode) still exists but the scoped path is the one to use. The HTTP server already routes every POST /v1/ingest through ScopedLunaris::ingest keyed on the JWT tenant claim.
• GGUF staging. The default embedder (llama.cpp granite-r2) expects its GGUF at ~/.lunaris/models/granite-embedding-311m-multilingual-r2.Q4_K_M.gguf — there is no auto-download in the umbrella crate; a missing GGUF logs a WARN and falls back to NoopEmbedder. The MCP server stages GGUFs lazily on first recall. Point LUNARIS_EMBEDDER_GGUF at an existing local copy, or build with --features embed-remote and set LUNARIS_EMBEDDER_OLLAMA_URL to use the Ollama HTTP escape hatch (resolves after the llama.cpp step).
• Embedding dimension. The Moon adapter creates its vector index at the configured embedder’s dimension (default 768-d; Lunaris::open passes embedder.dim(), or use MoonStorage::connect_with_dim directly), so a 1536-d embedder works out of the box. Footgun: Moon’s FT.CREATE won’t resize an existing index — drop it first if you switch embedder width. See Choosing a Backend.
• Higher-level wrappers exist. If you don’t want to hand-build episodes, the Cookbook recipes (DocumentKnowledgeBase, ChatAgentMemory, …) forward to ingest with opinionated source prefixes.

See also

• The Retrieval DSL — reading the data back.
• Forgetting — taking it out again.
• Configuration Reference — every feature flag and LUNARIS_* env var.

The Retrieval DSL

DSL = Domain-Specific Language — here, a small composable query API (operators you chain into a plan), not a separate language you write or parse. Prefer ScopedLunaris::recall(query) for a one-shot default query; reach for the DSL builder below when you need to compose operators.

Reach for this chapter for every read beyond a single-key fetch. The DSL composes a small set of operators — Vector, Keyword, Graph, Tree (RAPTOR hierarchical), plus fusion / rerank / modifier wrappers — into a plan, then executes it in one pass and returns Vec<Hit>. It is declarative (“feel like Keras, not like a query language”, blueprint §8) and tower::Service-shaped at the edge so rate-limit / retry / timeout / tracing middleware drops in for free.

All names below are re-exported at the lunaris:: top level — never reach into lunaris_retrieve::.

Two ways to query

There are two query forms over the same engine. Both run on the same storage / embedder / scope; the only difference is how much of the plan you spell out.

Form A — scoped.recall(query) (one-shot). A single .await that returns Vec<Hit> directly. It runs the default plan: a Vector search over the chunks index — no keyword fusion, no graph, no rerank. Reach for it when a plain semantic lookup is all you need.

use lunaris::{Hit, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{Lunaris, Query, Scope};

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

// One call, Vec<Hit> back. Default plan = Vector over `chunks`.
let hits = scoped.recall(Query::text("who loves chocolate")).await?;
Ok(())
}

Form B — scoped.dsl()…execute(query) (composable). Returns a RetrievalBuilder you customise (.with_root(...), .filter(...), .as_of(...), .rerank(...)) before the single .execute(query).await. Reach for it the moment you want hybrid fusion, the graph or tree operators, time-travel, or reranking.

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

// `scoped` is the handle from Form A above.
let hits = scoped
    .dsl()
    .with_root(Vector::new("chunks", 30).and(Keyword::bm25("chunks", 30)).fuse_rrf(60).top(5))
    .execute(Query::text("who loves chocolate"))
    .await?;
Ok(())
}

They are the same machinery: recall(query) is exactly dsl() with the default root left in place, then .execute(query) — verify it in crates/lunaris/src/handle.rs (recall at the ScopedLunaris impl delegates to engine.recall().with_scope(scope).execute(query); dsl() returns the same pre-seeded builder). So there is nothing recall() can do that dsl() cannot — recall() is the convenience name for the common default.

See it run. Querying Three Ways runs all three forms — direct recall, DSL fusion, and the Tree operator — over one ingested document.

Mind the three recall names. ScopedLunaris::recall(query) (above) returns Vec<Hit> and is the canonical one-shot. ScopedLunaris::dsl() returns the builder. The bare Lunaris::recall() (no scope) is a legacy path that returns a RetrievalBuilder (not Vec<Hit>) seeded with Scope::dev() and warns on every call — see the note under Seeding a builder.

Seeding a builder

ScopedLunaris::dsl() returns a RetrievalBuilder pre-seeded with the handle’s storage / embedder / keyword Arcs and the bound scope, so only hits from that scope’s partition come back. Its default root operator is Vector::new("chunks", 30); you replace it with .with_root(...).

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{Keyword, Lunaris, Query, Scope, Vector};

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

let hits = scoped
    .dsl()
    .with_root(Vector::new("chunks", 30).top(5))
    .execute(Query::text("brown fox"))
    .await?;
Ok(())
}

Lunaris::recall() exists too, but it seeds Scope::dev() and emits a tracing::warn! on every call (crates/lunaris/src/recall.rs:78-80). It is the v0.1 backwards-compatible path; new code uses engine.scoped(scope).dsl() (or engine.scoped(scope).recall(query) for the one-shot form).

RetrievalBuilder is synchronous — with_root, filter / filter_str, as_of, rerank, degraded_fallback all run before any IO. .execute(query) is the only .await; it wires the operator tree into a QueryContext, runs it, and hydrates the results. This keeps the builder Send without future-boxing.

The operators

Vector::new(index, k)

Top-k chunks by vector (cosine) similarity. index is one of the four whitelisted names: chunks | entities | facts | communities. The chunker fills chunks; the extractor fills entities and facts. RAPTOR’s ingest-time tree now fills communities with embedded summary nodes — query them directly here, or via the Tree operator (below) for hierarchical descent. (The consolidator’s Leiden run also contributes community nodes.) (crates/lunaris-retrieve/src/operators/vector.rs)

Keyword::bm25(index, k)

Top-k chunks by BM25 keyword score (min-max normalized). (crates/lunaris-retrieve/src/operators/keyword.rs)

Graph::anchored(entity_ids, hops)

Breadth-first traversal out from known entities — “everything we know about Alice”. entity_ids are pre-resolved EntityIds:

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{EntityId, Graph};
let alice = EntityId::from_name_and_type("Alice", "Person");   // deterministic content hash
let g = Graph::anchored(vec![(alice, 1.0)], 2);
Ok(())
}

hops is clamped to [1, MAX_GRAPH_HOPS = 5]; DEFAULT_GRAPH_HOPS = 2. Empty entity_ids short-circuits to an empty result without touching storage. Per-hit score is 1.0 / (1 + bfs_rank). .with_k(n) caps the candidate set (default DEFAULT_GRAPH_K = 30); .with_graph(name) overrides the graph key (default lunaris_graph). Requires the graph pipeline and an extractor — see The Graph Pipeline. (crates/lunaris-retrieve/src/operators/graph.rs)

Tree::new(index, k) — RAPTOR hierarchical retrieval

Climbs the RAPTOR community tree instead of searching flat chunks. It vector-searches the communities index for the k nearest summary nodes, then descends Community.members breadth-first to collect the leaf chunks beneath them. Because a summary node semantically aggregates its chunks, this surfaces whole-document and multi-hop answers whose constituent chunks fall outside a flat search’s top-k budget.

use lunaris::Lunaris;
use lunaris::Scope;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
use lunaris::{Query, Tree};

// operator form — pass to .with_root() or compose with .and()/.fuse_rrf()
scoped.dsl()
    .with_root(Tree::new("communities", 5))
    .execute(Query::text("What are the main themes across both reports?"))
    .await?;

// builder shortcut — .tree(index, k, depth) replaces the root in one call
scoped.dsl()
    .tree("communities", 5, 1)
    .execute(Query::text("What are the main themes across both reports?"))
    .await?;
Ok(())
}

• k — number of top community summary nodes to seed from (clamped to MAX_K).
• depth — BFS descent levels. 1 (default, DEFAULT_TREE_DEPTH) collects the seed communities’ direct members; 2 also expands sub-communities one level deeper, and so on. Clamped to [1, MAX_TREE_DEPTH] where MAX_TREE_DEPTH = 4. Only the first level issues a vector search — deeper levels read community KV rows only, so cost scales with depth × fan-out, not index size.
• Composes like any operator: .and() / .or() / .then() / .fuse_rrf() / .top(). Fuse it with a flat Vector branch to get pinpoint chunks and tree-aggregated coverage in one plan:

use lunaris::Lunaris;
use lunaris::Scope;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
use lunaris::{Query, Tree, Vector};
scoped.dsl().with_root(
    Vector::new("chunks", 30)
        .and(Tree::new("communities", 5))
        .fuse_rrf(60)
        .top(10),
).execute(Query::text("Summarize the incident and its root cause")).await?;
Ok(())
}

Prerequisite: the communities index must be populated. RAPTOR fills it at ingest (community summary_embedding, since the 2026-06-04 change). If .tree() comes back empty, the scope hasn’t ingested a document large enough to build a tree yet — see Ingesting Observations.

What’s proven today: .tree() is verified wired and traversed — on a whole-document query it returns the full leaf set where flat top-k returns a single chunk. Relevance-vs-flat ranking with a production embedder is not yet benchmarked; treat .tree() as a coverage / recall lever, fused with Vector for precision. (crates/lunaris-retrieve/src/operators/tree.rs)

Combinators — .and() / .or() / .then()

Each operator carries .and(other), .or(other), .then(other) (crates/lunaris-retrieve/src/operators/combinators.rs):

• .and(other) — run both retrievers; both result sets flow into the next operator (the typical input to .fuse_rrf).
• .or(other) — fall back to other only if the left side yields nothing.
• .then(other) — feed the left side’s hits as the input to other (re-ranking / refinement chains).

Fusion — .fuse_rrf(k)

Reciprocal-rank fusion over the upstream branches. Each branch contributes 1 / (k + rank_i); k = 60 is the conventional constant.

use lunaris::{Keyword, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
let _operator_tree =
Vector::new("chunks", 30)
    .and(Keyword::bm25("chunks", 30))
    .fuse_rrf(60)
    .top(5)
;
Ok(())
}

Moon-native vs client-side. When the handle was opened against a moon:// URL and the shape is Vector + Keyword(BM25) on the same index, fuse_rrf dispatches to Moon’s native text().hybrid_search — one round trip instead of two (crates/lunaris-retrieve/src/operators/fuse.rs, governed by StorageCapabilities::native_rrf). Anything else folds client-side (crates/lunaris-retrieve/src/operators/fuse.rs::client_side_rrf). Any Graph branch in the tree forces client-side RRF — the Moon one-trip path only fires for the Vector+Keyword(BM25) case. The API is identical either way.

Modifiers — .top(k), filter_str, .as_of(ts)

• .top(k) — cap the final result set. Available on every operator and on the builder.
• RetrievalBuilder::filter_str(s) — parse a v0 string predicate into a Filter. Returns a Result<Self, FilterParseError> at builder time so invalid syntax surfaces before any IO. The v0 grammar parses two predicate forms only — field = 'value' (→ Filter::Eq) and field LIKE 'prefix%' (→ Filter::StartsWith; the % must be the last character, no embedded %). Anything else is a parse error (crates/lunaris-retrieve/src/operators/modifiers.rs:80). Never .unwrap() on user input — propagate with ?. .filter(Filter) takes a pre-built filter (use it for Filter::And / Filter::Or composition).
• RetrievalBuilder::as_of(ts) — pin the bi-temporal snapshot to an Hlc. Builder-level filter / as_of override the per-Query fields only if the query didn’t already set them.

rerank(reranker)

Wrap the current root with a cross-encoder rerank pass over the top DEFAULT_RERANK_TOP_IN = 30 candidates. Pass lunaris.reranker():

use lunaris::{Keyword, Query, Vector};
use lunaris::Lunaris;
use lunaris::Scope;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
scoped.dsl()
    .with_root(
        Vector::new("chunks", 30)
            .and(Keyword::bm25("chunks", 30))
            .fuse_rrf(60)
            .top(30),
    )
    .rerank(lunaris.reranker())
    .top(5)
    .execute(Query::text("brown fox"))
    .await?;
Ok(())
}

The default reranker is BGE-Reranker-v2-m3. Budget seconds, not milliseconds: it measures p50 1301.3 ms at the default top_in=60 (575.6 ms at top_in=30), plus a one-time ~1.0–1.4 s lazy GGUF load on the first reranked recall of the process (capacity.md §4). Rerank is a quality stage; enabling it voids the 25 ms p50 recall contract and the 100 ms latency SLO. When its weights are missing, Lunaris::open installs NoopReranker and lunaris.reranker() still returns a working Arc<dyn Reranker> that passes scores through unchanged — Hit::rerank_applied is false in that case. Builders constructed via Lunaris::with_parts get NoopReranker by default; opt into rerank yourself in tests/benches.

degraded_fallback(fallback)

Wrap the current root so that on any error from the primary it switches to fallback and tags every returned hit with Hit::degraded = true (crates/lunaris-retrieve/src/operators/degraded.rs). Pair it with Lunaris::recall_with_degraded_check(), which reads the verifier queue depth once and pre-flags every hit when the depth crosses LUNARIS_VERIFY_QUEUE_WARN_THRESHOLD (default 1000) — see Consolidation & Verification.

The build-up in four steps

use lunaris::{Keyword, Query, Vector};
use lunaris::Lunaris;
use lunaris::Scope;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
// 1 — pure vector
scoped.dsl().with_root(Vector::new("chunks", 30).top(5)).execute(Query::text("brown fox")).await?;

// 2 — add BM25
scoped.dsl().with_root(
    Vector::new("chunks", 30).and(Keyword::bm25("chunks", 30)).top(5),
).execute(Query::text("brown fox")).await?;

// 3 — fuse with reciprocal rank
scoped.dsl().with_root(
    Vector::new("chunks", 30).and(Keyword::bm25("chunks", 30)).fuse_rrf(60).top(5),
).execute(Query::text("brown fox")).await?;

// 4 — rerank
scoped.dsl().with_root(
    Vector::new("chunks", 30).and(Keyword::bm25("chunks", 30)).fuse_rrf(60).top(30),
).rerank(lunaris.reranker()).top(5).execute(Query::text("brown fox")).await?;
Ok(())
}

Graph-aware: swap a branch for Graph::anchored:

use lunaris::Lunaris;
use lunaris::Scope;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
use lunaris::{EntityId, Graph, Query, Vector};
let alice = EntityId::from_name_and_type("Alice", "Person");
scoped.dsl().with_root(
    Vector::new("chunks", 30)
        .and(Graph::anchored(vec![(alice, 1.0)], 2))
        .fuse_rrf(60)
        .top(30),
).rerank(lunaris.reranker()).top(5).execute(Query::text("Tell me about Alice")).await?;
Ok(())
}

The Hit you get back

use lunaris::{Hit, SourceOp};
use lunaris_core::Hlc;
async fn demo() -> Result<(), lunaris::LunarisError> {
pub struct Hit {
    pub id: Vec<u8>,            // backend id (a ULID's 16 bytes for chunks)
    pub score: f32,
    pub text: String,           // chunk body — from the chunk's KV row
    pub source: String,         // episode source, "" if the episode row is gone
    pub heading_path: Vec<String>,
    pub valid_from: Hlc,
    pub valid_to: Option<Hlc>,  // None = still valid
    pub degraded: bool,         // came from a degraded_fallback path
    pub rerank_applied: bool,   // the real cross-encoder ran (not the noop)
    pub source_op: SourceOp,    // which operator produced it (RRF groups by this)
}
Ok(())
}

Query::text(t) builds a default query (k = 30, no filter, no as_of); the struct-literal form lets you set every field explicitly.

tower::Service

For middleware-stacked use, RetrievalService implements tower::Service<Query, Response = Vec<Hit>, Error = LunarisError> (crates/lunaris-retrieve/src/service.rs), so tower::ServiceBuilder::new().rate_limit(..).timeout(..).retry(..).service(retriever) works. Note RetrievalService itself has no scope context (it uses Scope::dev()); for scope-isolated reads go through ScopedLunaris::dsl().

Gotchas

• Empty hits are usually a filter problem. Over-tight filter_str, or an index that nothing wrote to. (communities is now populated at ingest by RAPTOR — if it’s empty, this scope hasn’t ingested a document big enough to build a tree.) Drop the filter and re-run.
• filter_str parse errors are builder-time, not execute-time. Catch them with ? where you build the chain.
• execute_raw returns un-hydrated RawHits — for bench harnesses that measure search-path latency over non-chunks indices. Production callers use execute so “every hit has chunk text” holds.

See also

• Ingesting Observations — how the chunks index gets filled.
• The Graph Pipeline — populating entities / facts for Graph::anchored.
• Cookbook → Document Knowledge Base — RRF-fused RAG without hand-composing the DSL.
• Configuration Reference — reranker / embedder backends and the degraded-check threshold.

How Recall Works — Memory Structure & the Millisecond Budget

This page answers two questions evaluators keep asking:

1. How is a memory actually structured once Lunaris has ingested it?
2. Where do the milliseconds go on a recall — i.e. how does the sub-25 ms contract hold, mechanically?

It mirrors the canonical docs/ARCHITECTURE.md sections of the same names. Every claim is anchored to a code path or a published benchmark.

How a memory is structured

One ingested episode fans out into a small constellation of rows, all minted under the canonical keyspace lunaris:{scope}:{kind}:{ulid} (lunaris_core::keyspace) and all committed by the same atomic_write (invariant INGEST-04 — see Core Concepts):

Episode  lunaris:{scope}:episode:{ulid}     source, raw content, metadata, bt
  └─ Chunk(s)  lunaris:{scope}:chunk:{ulid} text + heading_path + episode_id
       ├─ vector        768-d embedding — same HSET document
       ├─ BM25 payload  tokenized text — same FT index as the vector
       └─ bt stamp      [sys_from, sys_to) × [valid_from, valid_to)
  └─ (opt-in graph) Entity / Relation / Fact rows + GraphNode/GraphEdge
       in the per-scope named graph
  └─ Audit row + one __lunaris_consolidate__ queue message

Three structural decisions carry the whole recall story:

• The chunk is the retrieval unit; the episode is the provenance unit. Vector and BM25 hits return chunk ULIDs. Hydration walks chunk → episode_id → episode, so every hit arrives with its source attached.
• One document, two indices’ worth of duty. On Moon, a chunk’s embedding, BM25-tokenized text, TAG filter fields, and bi-temporal stamp live in a single HSET document indexed by one per-scope FT index (lunaris_{scope}_{kind}_idx). There is no “sync the vector DB with the text index” job because there is nothing to sync.
• Every row is bi-temporal. The bt field records system time (when Lunaris learned the fact) and valid time (when it was true in the world) as two half-open intervals. forget and supersession close intervals instead of destroying rows — which is why .as_of(ts) can answer “what did the agent believe last Tuesday?”

Where the milliseconds go — anatomy of a recall

The sub-25 ms contract is not one trick — it is the absence of four round trips. Here is how a typical vector.and(keyword).fuse_rrf(60) recall spends its budget:

CJK and other case-less scripts — vector-only auto-planning

Two v0 behaviours to know if your corpus or queries are in Chinese, Japanese, or Korean (or any script without case):

• The auto-planner never picks the keyword leg for CJK queries. The plan_query helper (exported by lunaris-retrieve; RETRIEVE-13) chooses Hybrid (vector + BM25) only when it sees an entity-like ASCII-uppercase token mid-query — an English-only heuristic (crates/lunaris-retrieve/src/planner.rs). CJK text has no ASCII uppercase, so a CJK query always plans VectorOnly and BM25 is never consulted on that path. This is pinned by the cjk_query_always_plans_vector_only unit test in planner.rs, so the behaviour change will be visible when the graph-anchored planner replaces the heuristic. The multilingual granite-r2 embedder carries CJK recall in the meantime — and note this only affects auto-planned recall: an explicit DSL query (vector.and(keyword).fuse_rrf(60)) runs exactly the legs you wrote, in any script.
• Sentence segmentation splits on ASCII terminals only. The ingest chunker’s sentence mode splits paragraphs on . ! ? (crates/lunaris-ingest/src/chunker/segment.rs); the full-width 。 ！ ？ terminals are not split points, so CJK prose in sentence mode degrades to paragraph-sized units. Chunks stay retrievable (the embedder is multilingual), just coarser.

The 86 ms lesson (historical — v0.1.1, 2026-04-23)

The same 10k-document SQuAD harness (scripts/bench-squad-kb.py) measured:

• p50 86 ms when query embedding went through an out-of-process Ollama HTTP server, and
• ~11 ms on the strict-replay path that removes that hop (scripts/ollama-replay-server.py + scripts/precompute-embeds.py).

Treat the absolute numbers here as retired. That run used Ollama + EmbeddingGemma 300M at k=3 on a 10k corpus — a stack removed in v0.4 (Ollama) and again in v0.6 (candle). What survives is the ratio, not the milliseconds. The current latency envelope is the GA-2b one in capacity.md.

The engine’s own search + hydrate path was ~10 ms all along; the network hop to the embedder was ~75 ms of pure overhead. That measurement is why v0.4 moved embedding in-process as the default — the shipped configuration is the configuration the contract was proven on. (v0.4 ran the in-process embedder on candle; the v0.6 llama.cpp-only cutover (docs/decisions/2026-07-10-llamacpp-only-cutover.md) replaced candle with llama.cpp as the in-process runtime — the “no network hop” property this lesson describes is unchanged.)

The same decomposition repeated on Moon v0.3.0 with the 4-bit GGUF granite embedder (3k-doc SQuAD train corpus): end-to-end p50 61.5 ms, retrieval-only p50 3.1 ms / p99 3.6 ms — the gap is now in-process quantized embedding compute, not a network hop, and the engine path still sits far inside the 25 ms contract (v0.3.0 rerun).

The 97 ms tail lesson

Hydration used to await one storage read per hit, serially — at k=30 that chain of round trips amplified every scheduler hiccup into the tail. The 2026-06-10 fan-out change (one HMGET per row, all rows concurrently over the multiplexed connection) flattened a measured p50 12 ms / p99 97.3 ms at k=30 into p50 6.0 ms / p99 6.2 ms — the tail now sits inside the p50 contract. Methodology and the full A/B table: docs/benchmarks/v0.6-recall-fanout-ab.md.

Why a fan-out stack can’t follow

A typical agent-memory deployment runs a vector DB + a text-search engine + a graph DB + a message broker. That stack pays:

1. one network round trip per lane, plus app-side fusion;
2. no shared TAG / temporal pushdown — you over-fetch, then post-filter in application code;
3. no common snapshot — the lanes can disagree about what exists.

Lunaris-on-Moon spends its entire budget inside one process and one index, with one transaction boundary across all four lanes.

Where to go next

• The query language itself: The Retrieval DSL
• The primitives and the keyspace: Core Concepts
• Backend setup and its honest limits: The Storage Backend
• The published numbers: docs/benchmarks/v0.2.x/

Forgetting (GDPR / audit)

Reach for this chapter when a primitive must stop being visible to future queries — GDPR right-to-be-forgotten, retention windows, session cleanup. Three variants, one entry point (Lunaris::forget, crates/lunaris/src/forget.rs:208), one __lunaris_audit__ event per successful call.

v0.2.x headline gotcha — read this first

Lunaris::forget is hard-coded to Scope::dev() internally for its atomic_write / read_as_of / scan_range calls (crates/lunaris/src/forget.rs:300-303). Under any non-_dev_ scope it silently returns rows_written = 0, rows_deleted = 0 — the Moon SCAN prefix filters everything out. It emits a tracing::warn! on every call so the line above your forget(...) says so. The real per-scope routing — ScopedLunaris::forget(target) with a 403/404 cross-scope contract — is a v0.3 deliverable. See RFC 0001 §11.6 and CHANGELOG.md “Known issues”. Until then, forget works against the _dev_ scope only.

The three targets

// Shape only — this mirrors the real declaration rather than calling it,
// so it is `ignore`d: compiling a shadow copy of an enum proves nothing.
pub enum ForgetTarget {
    Id(Ulid),               // OPS-01 — single-primitive purge across KV + vector + graph
    Scope(ScopeSpec),       // OPS-02 — prefix / metadata / episode-id predicate
    Before(Hlc),            // OPS-03 — AS_OF cutoff
}

pub enum ScopeSpec {
    BySource(String),           // prefix match on episode.source
    ByMetadata(String, String), // exact match on metadata[key] == value
    ByEpisode(Ulid),            // exact match on episode.id
}

(ForgetTarget and ScopeSpec are #[non_exhaustive], crates/lunaris/src/forget.rs:49-73.)

Soft vs hard delete

D-19 single-call invariant: every successful forget issues at most one atomic_write (zero for dry-run or no-match).

Soft delete writes the sys_to inside the payload bytes — backends derive persisted bi-temporal from the payload, so a typed-only mutation would be silently lost. build_soft_delete_op patches both the in-memory BiTemporal and payload["bt"]["sys"][1] (crates/lunaris/src/forget.rs), the same cross-plan contract the verifier’s apply_supersede uses. This is what makes “forget” compatible with bi-temporal MVCC: the data is hidden from default-time queries but a recall().as_of(t_before_forget) still returns it.

Code

use lunaris::Scope;
use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
use lunaris::{ForgetTarget, ScopeSpec};

// Soft delete a session prefix.
let target = ForgetTarget::Scope(ScopeSpec::BySource("helios:fs/session-42/".into()));
let receipt = lunaris.forget(target.clone()).await?;
assert!(!receipt.preview);
// receipt.rows_written == number of MVCC rows stamped (0 under a non-_dev_ scope!)

// Dry-run preview.
let preview = lunaris.forget(target.clone().dry_run()).await?;
assert!(preview.preview);

// Hard delete — two steps.
let token = lunaris.confirm_hard_forget(preview).await?;
let hard  = lunaris.forget(target.hard().with_token(token)).await?;
assert!(!hard.preview);
assert_eq!(hard.rows_written, 0);  // hard delete writes zero MVCC rows
// hard.rows_deleted == one KvDelete per match
Ok(())
}

confirm_hard_forget only accepts a preview: true receipt — replaying a non-preview receipt returns the same ConfirmationRequired error (crates/lunaris/src/forget.rs:333).

The receipt

use lunaris::{ForgetTarget, Graph, IndexKind, Lsn, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
pub struct ForgetReceipt {
    pub target: ForgetTarget,
    pub indices_affected: Vec<IndexKind>,  // Kv | Vector | Graph
    pub rows_written: u64,                 // soft-delete MVCC writes; 0 for hard / dry-run
    pub rows_deleted: u64,                 // irreversible deletes; 0 for soft / dry-run
    pub audit_lsn: Lsn,                    // __lunaris_audit__ publish offset
    pub preview: bool,                     // true iff dry_run (no atomic_write happened)
}
Ok(())
}

ForgetConfirmation carries for_audit_lsn and cannot be constructed by the caller — only returned from confirm_hard_forget.

GDPR / audit notes

• One audit event per successful call — soft, hard, and dry-run. The audit publish lands even on dry-run so operators have a complete trail. The receipt’s audit_lsn is the __lunaris_audit__ offset.
• Use dry_run first for any destructive run — it’s also the only way to mint the hard-delete confirmation token.
• Hard delete is irreversible. Soft delete is the GDPR-friendly default: the data leaves default-time queries immediately, and MVCC retention keeps it auditable until your retention policy hard-deletes it.

HTTP

Over the wire (POST /v1/forget), the request DTO carries #[serde(deny_unknown_fields)] — a scope / tenant field is a 422. Hard delete is two requests: dry_run: true, read the audit_lsn out of the receipt, then repeat with hard: true and a confirmation_token formed from the prior audit LSN. See the MemoryProtocol spec.

See also

• Cookbook → Helios Scratchpad — uses a BySource prefix soft delete (pad.forget()).
• Durability & Recovery — bi-temporal MVCC and what as_of recovers after a forget.
• Multi-Agent & Scope — why forget is _dev_-only in v0.2.x.

The Graph Pipeline (opt-in)

Reach for this chapter when you want to follow relations out from a known entity — “everything we know about Alice that also matches this query”. The graph is default OFF (blueprint §5.2). Turning it on makes ingest also extract entities, relations, and facts with a small local LLM, and unlocks the Graph::anchored retrieval operator.

Turning it on

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::Lunaris;

let lunaris = Lunaris::open("moon://localhost:6380").await?;

// Runtime toggle — idempotent.
lunaris.graph_pipeline().enable();
// ... or LUNARIS_GRAPH_ENABLED=1 seeds the initial state at open time.
Ok(())
}

GraphPipelineHandle (crates/lunaris/src/graph_pipeline.rs) exposes enable() / disable() / is_enabled(), plus set_extractor(arc) / snapshot_extractor(). The enabled bit is read once per ingest call — a toggle change during an in-flight ingest takes effect on the next call. There is no per-scope enable_for_scope on the graph handle (only the consolidator handle has that).

See Configuration → Backend / pipeline selection.

What extraction produces

With the pipeline on, the graph-on ingest branch runs each chunk through the Extractor → validator::validate → ValidatedExtraction, then extends the single WriteOp vector (the INGEST-04 invariant still holds — one atomic_write per ingest call) with:

• per entity — a GraphNode (props include id_hex) + a VectorUpsert into the entities index;
• per relation — a GraphEdge;
• per fact — a KvPut + a VectorUpsert into the facts index.

EntityId is deterministic: the 16-byte truncation of blake3(normalized_name || "::" || entity_type) — stable across re-ingest, across chunks, across episodes. No second-pass dedupe round trip. (crates/lunaris-extract/src/lib.rs, types::EntityId::from_name_and_type.)

The validator routes invalid items to a NeedsReview queue with one of four structured reasons — InvalidBitemporal, StructuralContradiction (same (subject, predicate) with overlapping validity and conflicting object, within one episode), GbnfFailure, TransientAfterRetry. After the atomic_write, every NeedsReview item publishes one __lunaris_verify__ message; it is only consumed when the verifier pipeline is enabled. Cross-episode contradictions are deferred to the verifier.

Graph-aware recall

Once entities/relations have been written, compose Graph::anchored into the DSL:

use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
use lunaris::{EntityId, Graph, Query, Scope, Vector};

let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
let alice  = EntityId::from_name_and_type("Alice", "Person");

let hits = scoped
    .dsl()
    .with_root(
        Vector::new("chunks", 30)
            .and(Graph::anchored(vec![(alice, 1.0)], 2))
            .fuse_rrf(60)
            .top(30),
    )
    .rerank(lunaris.reranker())
    .top(5)
    .execute(Query::text("Tell me about Alice"))
    .await?;
Ok(())
}

• hops is clamped to [1, MAX_GRAPH_HOPS = 5]; DEFAULT_GRAPH_HOPS = 2.
• Empty entity_ids short-circuits to an empty result without touching storage.
• .with_k(n) caps the candidate set (DEFAULT_GRAPH_K = 30); .with_graph(name) overrides the graph key (default lunaris_graph).
• Any Graph branch forces client-side RRF — the Moon-native one-trip fusion path only fires for Vector + Keyword(BM25) on the same index.

Extractor tiers (RFC 0004, superseded by the v0.6 llama.cpp-only cutover)

RFC 0004 originally defined an in-process candle extractor tier (Medium: Gemma-3-4B) alongside Ollama and cloud-API backends. The candle tier was deleted in the v0.6 llama.cpp-only cutover (docs/decisions/2026-07-10-llamacpp-only-cutover.md) — the extractor is now remote-only, plus a NoopExtractor fallback:

(crates/lunaris-extract/src/lib.rs; RFC 0004 “extractor tiers” — historical, its candle tier no longer exists.)

Gotchas

• The extractor is required for graph ingest. With no LUNARIS_EXTRACT_PROVIDER set (and no with_extractor override), Lunaris::open substitutes NoopExtractor and emits a tracing::warn! — in that state graph_pipeline().enable() is a no-op and zero GraphNodes get written. Fix by setting LUNARIS_EXTRACT_PROVIDER (e.g. minimax, or openai-compat pointed at a local Ollama/llama-server) or supplying a custom with_extractor impl.
• communities stays empty until the consolidator’s Leiden community-detection run lands (v1) — recall over that index returns nothing meanwhile.
• Apply with_extractor before .enable() — .enable() snapshots the current extractor; a swap afterwards propagates via set_extractor.
• Cross-scope graph references are disallowed by construction — Relation.src / Relation.dst must resolve within the same scope (RFC 0001 §2.3).

See also

• The Retrieval DSL — the full Graph::anchored surface.
• Consolidation & Verification — what consumes the __lunaris_verify__ messages this pipeline emits.
• Configuration Reference — extractor feature flags and LUNARIS_* env vars.

Consolidation & Verification (opt-in)

Reach for this chapter when your deployment has latency budget to spare and you want quality/provenance signals landing in the audit stream. These are the two opt-in slow paths — neither runs on the recall hot path. Both ship default OFF (blueprint §5.1); turn them on once your queue-lag SLOs hold.

The verifier is remote-only since the v0.6 llama.cpp-only cutover — see docs/decisions/2026-07-10-llamacpp-only-cutover.md (the cutover ADR). No local model tiers to build or stage; a set-but-broken provider degrades loudly to NoopVerifier (warn), never a silent backend swap. See Configuration Reference.

The consolidator (ACT-R)

lunaris-consolidate consumes the __lunaris_consolidate__ queue (one message per ingest commit, consumer group lunaris-consolidate-v0), debounces per episode_id, and runs a consolidation pass:

• ACT-R base-level activation — Anderson 1996, decay d = 0.5, with the Petrov 2006 O(1) incremental approximation (ActRScorer, crates/lunaris-consolidate/src/act_r.rs). High-activation episodes/notes get promoted to Fact primitives; stale facts get archived.
• Leiden community detection — a hand-rolled label-propagation pass (leiden_pass, crates/lunaris-consolidate/src/leiden.rs) over the graph, producing Community primitives (the communities recall index). Rustworkx is deliberately rejected — it carries unsafe blocks.

The crate has no LLM backends — community summaries are produced by the Phase-3 Extractor acting as a summarizer, wired at the umbrella handle.

use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
lunaris.consolidator_pipeline().enable();
Ok(())
}

ConsolidatorPipelineHandle (crates/lunaris/src/consolidator_pipeline.rs) exposes enable() / disable() / is_enabled(), set_consolidator(arc), bind_storage(arc), join_worker(), state_change_count(), and — uniquely among the three pipeline handles — enable_for_scope(prefix):

use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
// Promote only events whose source starts with "helios:fs/" — Consolidator
// stays off for every other tenant. Prefix match is exact: no regex, no glob.
lunaris.consolidator_pipeline().enable_for_scope("helios:fs/");
Ok(())
}

The prefix is a source-prefix filter on the consolidate-event stream, not a Scope partition key — Consolidator::consolidate_scoped drops events whose event.source doesn’t start with it before forwarding to consolidate() (crates/lunaris-consolidate/src/lib.rs). An empty prefix is rejected. lunaris_recipes::WorkingMemory::consolidate() and the HeliosScratchpad recipe use this path (see Cookbook → Helios Scratchpad).

Per-event audit records match the AuditEvent enum verbatim — one ConsolidatorPromotion { episode_id, fact_id, activation_score } per promotion, one ConsolidatorArchive { fact_id, final_activation, moved_to } per archive. There is no rolled-up “report” audit variant.

The verifier (slow-path arbitration)

lunaris-verify consumes the __lunaris_verify__ queue (emitted by the graph-on ingest path, consumer group lunaris-verify-v0). For each NeedsReviewItem it produces a VerifyDecision naming the winner / loser / reason; a non-deferred decision flows through one atomic_write (the MVCC supersede invariant — the loser’s bt.sys_to is stamped via read_as_of + BiTemporal::invalidate_sys), followed by one fire-and-forget audit publish.

use lunaris::Lunaris;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
lunaris.verify_pipeline().enable();
Ok(())
}

VerifierPipelineHandle (crates/lunaris/src/verify_pipeline.rs) exposes enable() / disable() / is_enabled(), set_verifier(arc), bind_storage(arc), bind_clock(arc), join_worker(). No enable_for_scope — the verifier runs handle-wide. Returning VerifyDecision::deferred() is “abstain”: the worker skips the supersede write for that item.

Remote-only verifier (v0.6 llama.cpp-only cutover)

RFC 0006 originally shipped a candle-based laptop floor (verify-small, Gemma-3-270M) vs a “get it right” tier (verify-large, Gemma-3-27B). Both were deleted in the v0.6 llama.cpp-only cutover — see docs/decisions/2026-07-10-llamacpp-only-cutover.md (the cutover ADR). There is no in-process verifier model anymore; LUNARIS_VERIFY_PROVIDER selects a remote provider, or the effective verifier is NoopVerifier:

A provider that is set but fails to construct (bad URL, missing key) logs a tracing::warn! and degrades to NoopVerifier — it never silently falls back to a different backend. Rust callers can still supply any custom impl via with_verifier.

Surfacing backlog to readers — recall_with_degraded_check

The verifier is asynchronous, so recall results can be stale relative to pending arbitrations. Lunaris::recall_with_degraded_check() reads the verifier queue depth once and, if it exceeds LUNARIS_VERIFY_QUEUE_WARN_THRESHOLD (default 1000, crates/lunaris/src/recall.rs:26-31), seeds the builder so every returned Hit::degraded is true:

use lunaris::{Lunaris, Query, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let hits = lunaris
    .recall_with_degraded_check()
    .await?
    .with_root(lunaris::Vector::new("chunks", 30).top(5))
    .execute(lunaris::Query::text("status of x"))
    .await?;
for h in &hits {
    if h.degraded {
        tracing::warn!("verifier backlog — results may be stale");
    }
}
Ok(())
}

It is best-effort: if the backend’s queue_depth returns NotSupported, the call falls through with degraded = false and still returns hits.

Gotchas

• Both pipelines default OFF. .enable() with no real backend installed runs NoopConsolidator / NoopVerifier — no crashes, no work done. Wire a backend (with_consolidator / with_verifier, or the right Cargo feature + env) first.
• Apply component swaps before .enable() — .enable() snapshots the current component; later swaps propagate via set_*.
• Queue topics are hard-coded constants (__lunaris_consolidate__, __lunaris_verify__, crates/lunaris/src/ingest.rs:48-54). The shipped workers use the -v0 consumer groups so a future schema bump can land on a fresh group.
• Per-scope supervisors exist but the pipeline handles still drive the deprecated single-topic workers in v0.2.x; the supervisor migration is a v0.3 item (RFC 0001 §11.6). See Multi-Agent & Scope for LUNARIS_SCOPE_CONCURRENCY etc.

See also

• The Graph Pipeline — produces the __lunaris_verify__ messages.
• Ingesting Observations — produces the __lunaris_consolidate__ messages.
• Configuration Reference — every feature flag and LUNARIS_* env var.

Multi-Agent & Scope

Reach for this chapter when one Lunaris deployment serves more than one agent or tenant. Scope is the partition key: every ingest, recall, and consolidation/verification operation is bound to a scope, and an agent cannot read, write, or delete across scope boundaries. Multi-agent isolation is the headline OSS positioning — Lunaris enforces it at the type level (RFC 0001), not by convention.

The Scope newtype

Scope (lunaris_core::Scope, crates/lunaris-core/src/scope.rs) is a thin newtype around SmolStr — short identifiers stay inline, clones are O(1). Two scopes compare equal iff their strings match byte-for-byte. There is no implicit “default” scope — you construct one explicitly.

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::Scope;
let s = Scope::new("acme.agent-1")?;   // -> Ok(Scope)
assert_eq!(s.as_str(), "acme.agent-1");
Ok(())
}

Alphabet — [A-Za-z0-9_\-.]{1,128}, no colons

Scope::new validates against ^[A-Za-z0-9_\-.]{1,128}$. The hand-rolled Deserialize impl re-runs the same validator on wire bytes — wire data is never trusted (RFC 0001 §11). The colon was removed in v0.2.1 so the Moon KV format lunaris:{scope}:{kind}:{ulid} cannot byte-alias across scopes (RFC 0001 §11.3, RC-2). Use dots in identifiers: acme.agent-42, not acme:agent-42.

Upgrading from v0.2.0? Any scope/tenant string containing : now fails at the HTTP boundary with invalid scope. Rewrite the tenant entries in your server-side bearer-tokens file (LUNARIS_TOKENS_FILE) and restart (acme:agent-42 → acme.agent-42) — there are no JWTs in v0; the tenant lives in the tokens file, not inside the token (see Security & Hardening). Moon keys are immutable — re-ingest colon-keyed data under the rewritten scope. Recipe: RFC 0001 §11.4.

Scope::dev() is #[doc(hidden)] pub — a test/migration crutch only. Any Scope::dev() call site in production code is a carry-over, not a pattern. (Lunaris::forget still uses it internally in v0.2.x — see Forgetting.)

Binding an engine to a scope — ScopedLunaris<'a>

async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::{EpisodeBuilder, Lunaris, Query, Scope, Vector};

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

let lsn  = scoped.ingest(EpisodeBuilder::new("notes.md", "Alice met Bob.")).await?;
let hits = scoped.dsl()
    .with_root(Vector::new("chunks", 30).top(5))
    .execute(Query::text("Alice"))
    .await?;
Ok(())
}

ScopedLunaris::ingest takes an EpisodeBuilder (scope-less payload) and stamps its own scope — callers cannot override the bound scope mid-call. That is the compile-time guard: “ingest into agent A, retrieve from agent B” can’t type-check. ScopedLunaris::recall(query) is the one-shot form; .dsl() returns a RetrievalBuilder pre-seeded with the scope for chained queries. .scope() returns the bound &Scope.

Under the hood &Scope is threaded through every partitioned StoragePort method (atomic_write, vector_search, graph_traverse, scan_range, read_as_of, publish, subscribe, queue_depth) and KeywordPort::keyword_search — Moon partitions via a per-scope keyspace prefix lunaris:{scope}: and per-scope FT/GRAPH/MQ resources.

Per-scope worker supervision

The consolidator and verifier slow paths run a JoinSet<()> of one task per active scope (ConsolidateSupervisor / VerifySupervisor, crates/lunaris-consolidate/src/supervisor.rs, crates/lunaris-verify/src/supervisor.rs). A new scope is registered from a heartbeat the HTTP server sends on every authenticated request. Failure isolation: a panic in scope A’s worker doesn’t stall scope B — the supervisor restarts only the failed scope’s task.

Operational ceiling: N scopes ⇒ N Moon FT indices and N MQ topics. Moon’s soft limit is ~512 FT indices per node before recall p99 degrades — surfaced as StorageCapabilities::max_scopes_recommended. Above that, multi-tenant pooling is a future RFC.

See Configuration → Supervision / worker pool.

The HTTP multi-agent contract

Over lunaris-server, the scope comes from the JWT tenant claim in the bearer-token map — it is the only source of truth for the partition scope. Route handlers ignore any scope / tenant field on the request body; all public request DTOs carry #[serde(deny_unknown_fields)].

{
  "my-bearer-token": { "tenant": "agent.helios", "scopes": ["ingest", "recall", "forget"] }
}

tenant must match ^[A-Za-z0-9_\-.]{1,128}$ — anything else is 401 on every request that uses the token. A token lacking the route’s required scope (the scopes array) is 403. The five executable UAT scenarios below map 1:1 to crates/lunaris-server/tests/multi_agent_uat.rs; an external consumer’s CI gate is met when all five pass.

UAT-1 — cross-scope ingest + recall isolation

Two tokens, tenants agent.alpha and agent.beta.

# ingest under alpha
curl -X POST http://localhost:8080/v1/ingest -H "Authorization: Bearer tok-alpha" \
  -H "Content-Type: application/json" \
  -d '{"source":"agent-alpha:notes","content":"Alice met Bob today"}'
# -> 200 {"lsn":{"wall_ms":...,"counter":1},"queue_lag_warn":false}

# ingest under beta
curl -X POST http://localhost:8080/v1/ingest -H "Authorization: Bearer tok-beta" \
  -H "Content-Type: application/json" \
  -d '{"source":"agent-beta:reports","content":"Quarterly revenue grew 12%"}'

# recall "Alice" as alpha -> 200, non-empty, first hit text contains "Alice"
curl -X POST http://localhost:8080/v1/recall -H "Authorization: Bearer tok-alpha" \
  -H "Content-Type: application/json" -d '{"query":"Alice","k":5}'

# recall "Alice" as beta -> 200, EMPTY array [] — no cross-scope leak
curl -X POST http://localhost:8080/v1/recall -H "Authorization: Bearer tok-beta" \
  -H "Content-Type: application/json" -d '{"query":"Alice","k":5}'

# recall "revenue" as beta -> 200, non-empty (its own data)
curl -X POST http://localhost:8080/v1/recall -H "Authorization: Bearer tok-beta" \
  -H "Content-Type: application/json" -d '{"query":"revenue","k":5}'

UAT-2 — malformed scope → 401

A token whose tenant is empty, longer than 128 chars, or contains a character outside [A-Za-z0-9_\-.] (%, space, \, :) is rejected before any handler runs:

{"error":"unauthorized","message":"token tenant is not a valid scope identifier"}

UAT-3 — request body cannot override scope

IngestBody is #[serde(deny_unknown_fields)], so a "scope" or "tenant" key in the body is 422 Unprocessable Entity before the handler runs — and zero episodes are written for the caller’s scope (no partial writes).

curl -X POST http://localhost:8080/v1/ingest -H "Authorization: Bearer tok-alpha" \
  -H "Content-Type: application/json" \
  -d '{"source":"evil","content":"x","scope":"victim-scope"}'
# -> 422 {"error":"unprocessable_entity","message":"... unknown field `scope` ..."}

UAT-4 — forget honors scope

A cross-scope forget finds zero rows in the caller’s partition and has no effect on anyone else’s data — rows_written == 0, rows_deleted == 0, preview reflects the request. (Note the v0.2.x forget caveat: Lunaris::forget is _dev_-scoped internally; full ScopedLunaris::forget with a 403/404 cross-scope contract lands in v0.3 — consumers should be ready for both shapes.)

UAT-5 — concurrent multi-agent traffic smoke

10 agents (tenants agent.0 … agent.9), each 3 ingest + 3 recall calls concurrently (60 HTTP calls). All 200 OK; no agent sees another’s data in its recall results.

Multi-agent patterns

There are three ways memory gets partitioned in Lunaris, nested from hardest to softest. Pick the level that matches the boundary you actually need — a tenant wall costs Moon resources; a thread label costs nothing.

Scope  "acme.agent-a"                      ← hard wall (RLS / per-scope keyspace)
  └─ source prefix  "conv:"                ← soft, client-side filter on Hit.source
       └─ thread id  "conv:mon/"           ← a segment of the source string
            └─ episode  "conv:mon/" + ULID + chunks
  └─ source prefix  "task:"
       └─ thread id  "task:deploy/"

The honest caveat: recipes use Scope::dev() today

The recipe wrappers — ChatAgentMemory, MultiTurnConversation, MessageStream, EmailThreading, MeetingNotesMemory, … — currently construct every Episode with Scope::dev() and partition only by source prefix (verified in crates/lunaris-recipes/src/message_stream.rs: scope: lunaris_core::Scope::dev()). Threading a real Scope through the recipe surface is a v0.3 SDK item. So today:

• Hard per-agent isolation goes through the low-level lunaris.scoped(scope) handle (or, in lunaris-server, the JWT tenant claim → scope). That is the only path with an RLS-grade / type-level wall.
• The recipes give you source-prefix + thread partitioning within one (dev) scope — fine for a single-tenant agent that wants per-conversation organization, not fine for multi-tenant isolation.

If you need both — a chat-agent ergonomic surface and a tenant wall — wrap your own thin type over ScopedLunaris for now, mirroring MultiTurnConversation’s shape but taking a Scope.

Worked snippets (from the runnable example)

These are distilled from examples/multi-agent-rs/ — a standalone crate that runs end-to-end against a live Moon backend. It builds the handle by hand (Lunaris::with_parts_keyword(storage, keyword, embedder, clock) with MoonStorage as both the storage and the BM25 keyword port, and a deterministic StubEmbedder::new(768)) so it needs no external services and no model download — swap the stub for Lunaris::open("moon://…") (the native granite-r2 default) and the same code recalls semantically.

Handle construction (what the example actually does — no model download):

async fn demo() -> Result<(), lunaris::LunarisError> {
use std::sync::Arc;
use lunaris::{Embedder, HlcClock, KeywordPort, Lunaris, MoonStorage, StoragePort, StubEmbedder};

let moon = Arc::new(MoonStorage::connect("moon://localhost:6380").await?);
let storage: Arc<dyn StoragePort> = moon.clone();
let keyword: Arc<dyn KeywordPort>  = moon.clone();              // MoonStorage IS the BM25 port too
let embedder: Arc<dyn Embedder>    = Arc::new(StubEmbedder::new(768));   // 768d == Moon's `chunks` FT index
let lunaris = Lunaris::with_parts_keyword(storage, keyword, embedder, HlcClock::new(0));
// Production: `let lunaris = Lunaris::open("moon://localhost:6380").await?;` instead — the
// native granite-r2 default downloads granite-embedding-311m-multilingual-r2 weights once and recalls semantically.
Ok(())
}

Agent-a vs agent-b — the scoped handle is the wall:

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

let scoped_a = lunaris.scoped(Scope::new("acme.agent-a")?);
let scoped_b = lunaris.scoped(Scope::new("acme.agent-b")?);

scoped_a.ingest(EpisodeBuilder::new("agent-a:notes", "The acme widget ships Friday. Owner: Alice.")).await?;
scoped_b.ingest(EpisodeBuilder::new("agent-b:notes", "The beta gadget recall is paused. Owner: Bob.")).await?;

let a_hits = scoped_a.dsl().with_root(Vector::new("chunks", 30).top(5)).execute(Query::text("owner")).await?;
let b_hits = scoped_b.dsl().with_root(Vector::new("chunks", 30).top(5)).execute(Query::text("owner")).await?;
assert!(a_hits.iter().all(|h| h.source.starts_with("agent-a:")));   // no agent-b leak
assert!(b_hits.iter().all(|h| h.source.starts_with("agent-b:")));   // no agent-a leak
Ok(())
}

Sessions / tasks within one agent — the source field:

use lunaris::{EpisodeBuilder, Hit, Query, Vector};
use lunaris::Lunaris;
use lunaris::Scope;
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped_a = lunaris.scoped(Scope::new("acme.agent-1")?);
// The first arg to EpisodeBuilder::new IS the `source` — encode the session there.
// EpisodeBuilder auto-generates a fresh ULID per episode; override with `.id(...)`
// only for idempotent replay.
scoped_a.ingest(EpisodeBuilder::new("conv:mon",    "Monday standup: acme widget rollout Friday.")).await?;
scoped_a.ingest(EpisodeBuilder::new("conv:tue",    "Tuesday sync: QA signed off on the acme widget.")).await?;
scoped_a.ingest(EpisodeBuilder::new("task:deploy", "Deploy task: cut the acme widget release branch.")).await?;

// One recall spans all sessions:
let all = scoped_a.dsl().with_root(Vector::new("chunks", 30).top(5)).execute(Query::text("acme widget")).await?;
// Narrow to one session — client-side over Hit.source (there is no server-side
// source-prefix push-down today; the v0 `filter_str` DSL targets episode
// METADATA, not the source string):
let mon_only: Vec<_> = all.iter().filter(|h| h.source.starts_with("conv:mon")).collect();
Ok(())
}

Resume across a process boundary — re-open + re-scope, no load step:

use lunaris::{Lunaris, Query, Scope, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
let scoped = lunaris.scoped(Scope::new("acme.agent-1")?);
drop(lunaris);                                          // process exits
let lunaris = Lunaris::open("moon://localhost:6380").await?;   // new process
let scoped_a = lunaris.scoped(Scope::new("acme.agent-a")?);
let hits = scoped_a.dsl().with_root(Vector::new("chunks", 30).top(5)).execute(Query::text("owner")).await?;
assert!(!hits.is_empty());                              // agent-a's episodes are still there
Ok(())
}

Episode IDs. EpisodeBuilder auto-generates a fresh ULID per episode (into_episode does self.id.unwrap_or_else(Ulid::new)), so distinct ingests never collide on a KV row. Override the id with .id(...) only when you want idempotent replay — re-ingesting the same logical episode without creating a duplicate.

Verified run output

The example was run against a single-shard Moon server (moon://localhost:6380, moon --port 6380 --shards 1) — cargo run exits 0 with all assertions passing. Verbatim stdout (RUST_LOG=error):

multi-agent: run id 36619
multi-agent: scope_a = acme.agent-a-36619
multi-agent: scope_b = acme.agent-b-36619

=== 1. hard isolation between two agents (distinct Scopes) ===
multi-agent: ingested agent-a episode at lsn=Lsn { wall_ms: 1778570918020, counter: 0 }
multi-agent: ingested agent-b episode at lsn=Lsn { wall_ms: 1778570918061, counter: 0 }
multi-agent: scope_a recall("owner") -> 1 hit(s), sources=["agent-a:notes"]
multi-agent: scope_b recall("owner") -> 1 hit(s), sources=["agent-b:notes"]
multi-agent: OK — neither agent can see the other's episode

=== 2. multiple sessions / tasks within agent-a (source-prefix partition) ===
multi-agent: ingested 3 session/task episodes under scope_a
multi-agent: scope_a recall("acme widget") -> 4 hit(s), sources=["agent-a:notes", "conv:mon", "conv:tue", "task:deploy"]
multi-agent: distinct source-prefix kinds seen across the recall: ["agent-a", "conv", "task"]
multi-agent: client-side narrowed to source-prefix `conv:mon` -> 1 hit(s): ["conv:mon"]
multi-agent: NOTE — there is no server-side `source`-prefix filter today; the v0 `filter_str` DSL targets Episode metadata, not the source string. Narrowing is client-side over `Hit.source` (matches the recipes' MessageStream behaviour).

=== 3. resume across a process boundary (drop handle, re-open, re-scope) ===
multi-agent: dropped the Lunaris handle (simulating process exit)
multi-agent: after re-open, scope_a recall("owner") -> 4 hit(s), sources=["agent-a:notes", "conv:mon", "conv:tue", "task:deploy"]
multi-agent: after re-open, scope_b recall("owner") -> 1 hit(s)
multi-agent: OK — agent-a memory is durable across the process boundary

multi-agent: ALL ASSERTIONS PASSED ✔
multi-agent: NOTE — the recipe wrappers (MultiTurnConversation, ChatAgentMemory, MessageStream) currently build episodes with Scope::dev() and partition only by source prefix; hard per-agent isolation today goes through the low-level lunaris.scoped(scope) handle shown above (or, in lunaris-server, the JWT `tenant` claim). See docs/book/src/guides/multi-agent.md.

What this proves and what it doesn’t. The StubEmbedder emits deterministic, non-semantic 768-d vectors, so cosine scores are all 0.0 and ranking is meaningless — the assertions check “≥ 1 hit” / “no cross-scope source leak”, not “the right hit ranked first”. What the run does establish: (1) the ingest → recall round-trip works against a real Moon backend; (2) two Scopes under one handle are isolated — neither agent’s recall returns the other’s chunks; (3) several source-tagged episodes under one scope all show up in a single recall, and the source prefix is preserved on Hit.source; (4) the data survives dropping and re-opening the handle (Moon is durable; there is no explicit load step). Run it yourself: examples/multi-agent-rs/.

Shared scratchpad across agents

Within one scope, the four memory.scratchpad_* MCP tools act as a shared blackboard for agent teams:

• Scope is the hard boundary — every agent that resolves the same scope (same git remote + branch, or the same explicit override) reads and writes the same store, even across runtimes (Claude Code and Codex side by side).
• Namespaces partition by agent — the full key is {namespace}{key} (default namespace scratchpad/, / allowed), so teams carve per-agent areas like scratchpad/executor/status. This is an organizational prefix, not a security boundary; teammates are supposed to read each other’s entries (scratchpad_grep on a prefix).
• Handoffs are immediate — write-then-read is read-your-writes consistent on every backend, and scratchpad writes never load the embedder.
• scratchpad_consolidate promotes the team’s hot items — the ACT-R drain moves high-activation entries into durable memory (where semantic recall finds them later) and archives stale working state. Requires a native-queue backend.

Gotchas

• No hierarchical scopes in v0.2 — flat strings only. org/team/agent tree semantics are a future RFC.
• Cross-scope graph references are disallowed by construction — Relation.src / Relation.dst must resolve within the same scope.
• Scope is an identifier, not a permission system — AuthZ stays in the lunaris-server middleware (the token map’s scopes array).
• v0.1 → v0.2 had no on-the-wire compatibility. Pre-scope rows were backfilled to scope = '_legacy' (the reserved fallback literal), and metadata.tenant is no longer silently honored as a tenant key. The SQL-driven half of that recipe went with the Postgres backend in 0.7.0. Full recipe — including the v0.2.0 → v0.2.1 colon-removal step (migrations/20260512000007_scope_regex_tighten.sql) — in docs/migration/0.1-to-0.2.md.

See also

• Ingesting Observations and The Retrieval DSL — the scoped surface in detail.
• Forgetting — why forget is _dev_-only in v0.2.x.
• Configuration Reference — the bearer-token map format and supervision env vars.
• MemoryProtocol 0.1 — the full HTTP/SSE wire spec.

Cookbook

Reach for the cookbook when you don’t want to hand-write episodes and retrieval plans — pick the named recipe that matches your data shape and you get a ≤ 30-LOC, parity-tested API instead.

Want the raw query surface instead of a recipe wrapper? Querying Three Ways composes the same operators by hand — direct recall, DSL fusion, and the Tree operator. Same Moon, no wrapper.

Lunaris ships a small library of recipe types in the lunaris-recipes crate (plus HeliosScratchpad in the umbrella lunaris crate). They are layered:

• 4 primitives — MessageStream, DocumentCorpus, TemporalQuery<S>, WorkingMemory. The building blocks. Each wraps an Arc<lunaris::Lunaris> handle and exposes 3–6 public methods.
• 5 conversational wrappers (lunaris_recipes::conversational) — ChatAgentMemory, MultiTurnConversation, SlackArchive, EmailThreading, MeetingNotesMemory. Thin compositions over MessageStream (+ WorkingMemory, + an optional graph-pipeline toggle).
• 5 documentary wrappers (lunaris_recipes::documentary) — DocumentKnowledgeBase, ResearchPaperCorpus, CodeRepoMemory, TimelineReconstruction, CustomerSupportHistory. Thin compositions over DocumentCorpus and TemporalQuery<Documents> (+ MessageStream for the support history).

Every wrapper forwards into at most two primitive method invocations per public method and holds zero business logic — they exist to make a blueprint §7 recipe discoverable from the public surface, not to add behaviour. None of them bundle a second vector or BM25 library; the fused recall plan they assemble (Vector + Keyword ⊕ RRF) lowers through the retrieval DSL and dispatches to Moon-native FT.* inside RetrievalBuilder::execute.

All ten wrappers carry live-Moon tests under crates/lunaris-recipes/tests/*_parity.rs (and the documentary trio also under tests/documentary_rust_integration.rs). They were Moon-vs-Postgres byte-identity assertions until 0.7.0 removed the second backend; what remains is the same hit-count + hit-id-ordering contract, asserted against Moon alone. The tests are feature-gated behind moon-it and probe the backend with a 1-second TCP check, so a default cargo test -p lunaris-recipes stays zero-config.

The recipe map

Each remaining chapter in this section is one (or a small group of) recipes with a runnable-shaped example derived from the parity test for that recipe.

Primitives

MessageStream — recency-weighted message recall

MessageStream (crates/lunaris-recipes/src/message_stream.rs) is the substrate every conversational wrapper composes over. It binds an Arc<Lunaris> to a thread prefix ("messages:", "slack:archive/", …) and exposes:

ingest delegates to Lunaris::ingest — the umbrella pipeline performs chunking + embedding + a single atomic_write (the INGEST-04 contract). One call = one message = one internal atomic write.

Reach for it when your data is a flowing stream of short messages — chat turns, Slack posts, email bodies, meeting notes — and recency matters to recall ordering.

Sessions persist automatically. MessageStream (and the conversational wrappers over it) are stateless handles over durable storage — there is no “save”/“load session” step. To resume, reconstruct the wrapper with the same id (and, for MultiTurnConversation, the same thread_id on remember); the backend already holds every prior turn. See Chat Agent Memory → Resuming a session.

DocumentCorpus — hybrid Vector + Keyword RAG

DocumentCorpus (crates/lunaris-recipes/src/document_corpus.rs) is the RAG primitive. It binds an Arc<Lunaris> to a source prefix ("kb:papers/", "repo:src/", …) and is a small fluent builder:

The native-RRF vs client-side-fold branch lives inside RetrievalBuilder::execute; the primitive is pure plan composition.

Reach for it when your data is a mostly-static document corpus and the hot path is retrieval, not ingest.

TemporalQuery<S> — typestate time-travel

TemporalQuery<S> (crates/lunaris-recipes/src/temporal_query.rs) is a time-travel combinator where S is a compile-only phantom marker — Messages, Documents, or Facts. Method availability is bound by sealed traits (SupportsAsOf, SupportsBetween), so an invalid combination fails at cargo check, not at runtime.

Reach for it when you need “what did the agent know at time T” as a query rather than a rebuild — audit replay, post-incident debugging, pinned regression fixtures. See Durability & Recovery for the bi-temporal MVCC model underneath.

WorkingMemory — scope-prefixed scratchpad

WorkingMemory lives in lunaris::primitives::working_memory (it is re-exported as lunaris_recipes::WorkingMemory so use lunaris_recipes::WorkingMemory; keeps compiling). It is a key-prefixed scratchpad: (k, v) pairs stored under {scope_prefix}{k} as Episodes.

consolidate() is the engine behind MultiTurnConversation::consolidate() and HeliosScratchpad’s per-scope promotion toggle. See Consolidation & Verification.

Reach for it when an agent needs a small mutable working set that lives in the same bi-temporal store as everything else, and you want the option of promoting hot scratchpad notes into long-term facts.

Querying Three Ways

Reach for this page when you want to see the raw retrieval surface — not a recipe wrapper. One ingested document, one question, asked three ways: the one-shot recall(query), a composed DSL plan that fuses flat chunks with RAPTOR tree descent, and the Tree operator on its own.

This page used to be the zero-deps SQLite tour. 0.7.0 deleted the embedded backend, so it now needs a Moon like every other page:

docker run -d -p 6380:6379 ghcr.io/pilotspace/moon:0.8.5 \
  --shards 1 --protected-mode no --appendonly yes

What it still is: the unwrapped surface. The recipe pages (DocumentKnowledgeBase, …) hand you a prebuilt Vector + Keyword(BM25) ⊕ RRF plan; this page composes the operators by hand so you can see what a plan is made of.

The three forms

All three are the same engine: recall(query) is just dsl() with the default root left in place. See Two ways to query for the distinction.

Example

Shaped after the ingest fixtures in crates/lunaris-ingest/tests/raptor_wiring.rs (which ingest a headed document and assert RAPTOR builds communities with 768-d summary embeddings) and the Tree discrimination benchmark in crates/lunaris-retrieve/tests/tree_recall.rs.

use anyhow::{Context, Result};
use lunaris::{EpisodeBuilder, Lunaris, Query, Scope, Tree, Vector};

/// A multi-section document, sized like `MULTI_SECTION_DOC` in the
/// `tree_recall.rs` test we cite. RAPTOR builds an H1 → H2 → chunk community
/// tree at ingest, so `communities` is populated and `Tree` at `depth=2` has
/// sub-communities to descend into. The chunker targets ~500 tokens, so the doc
/// must clear that threshold (~two padded headed sections) to produce ≥2 chunks
/// and a non-flat topology — a one-paragraph blurb collapses to a single chunk
/// and `Tree` would return nothing.
const DOC: &str = "# Agent Memory Architecture

# Section A: Core Design

The agent memory system uses a bi-temporal MVCC store. Each observation is
recorded with both a valid-time and a transaction-time. This dual timestamp
enables point-in-time queries and auditing of historical states: we can ask
what was known at any point in transaction time, and what was true at any
point in valid time. That is essential for agents reconciling information
gathered at different moments and reasoning about how the world has changed.

Writes commit through a single atomic_write, so a multi-primitive ingest —
episode row, chunk rows, vector upserts, and the RAPTOR community tree — is
all-or-nothing. There is no window in which the chunks exist but their
community summaries do not; a reader either sees the whole ingest or none of
it. This is the atomicity contract that fan-out architectures cannot make.

Memory isolation between agents uses scope partitioning. Each agent receives a
unique scope key that prefixes its KV entries and FT index slots, so the
backend enforces isolation at the data layer rather than trusting application
code to filter correctly. A misconfigured caller cannot read another agent's
memories, because the partition boundary is encoded into the keyspace itself.

# Section B: Retrieval and Performance

Recall fuses semantic vector search with BM25 keyword search using Reciprocal
Rank Fusion, which combines per-branch reciprocal ranks into one score that is
robust to the scale differences between cosine similarity and normalized BM25.
Each branch contributes independently, and the fused score reflects consensus
across retrieval strategies rather than the idiosyncrasies of either one.

RAPTOR organises related chunks into a hierarchy of summary communities. Each
community node aggregates the semantic content of its child chunks into a
single embedded vector, so a whole-document question can match the summary
node and then descend to every leaf chunk underneath it — including chunks
that would never score into a flat top-k on their own. This is the core
insight: summarise at multiple granularities, then match at the right level.

The system targets sub-25 ms recall, measured at 100k documents per scope. Vector
search runs in single-digit milliseconds, community summary embeddings let
whole-document queries bypass flat chunk retrieval, and no LLM sits on the read
path. Summaries are embedded with the same model as chunks, so cosine scores
are directly comparable across the chunks and communities indices.
";

#[tokio::main]
async fn main() -> Result<()> {
    // `moon://host:port` is the only scheme 0.7.0 accepts.
    let lunaris = Lunaris::open("moon://127.0.0.1:6380").await.context("open")?;
    let scoped = lunaris.scoped(Scope::new("demo").context("scope")?);

    // Ingest once. The umbrella pipeline chunks + embeds + builds the RAPTOR
    // community tree, all under one atomic_write (INGEST-04).
    scoped
        .ingest(EpisodeBuilder::new("demo:architecture.md", DOC))
        .await
        .context("ingest")?;

    let question = "What are the main themes across the whole document?";

    // ── Form 1: one-shot recall ────────────────────────────────────────────
    // Default plan = Vector over `chunks`. No fusion, no rerank. Vec<Hit> back.
    let flat = scoped.recall(Query::text(question)).await.context("recall")?;
    println!("[recall]  {} hit(s)", flat.len());

    // ── Form 2: DSL fusion (flat chunks ⊕ RAPTOR tree) ─────────────────────
    // Compose two vector-backed operators and fold their rankings with RRF.
    // Both branches run on the embedded backend — no server needed.
    let fused = scoped
        .dsl()
        .with_root(
            Vector::new("chunks", 20)
                .and(Tree::new("communities", 3).with_depth(2))
                .fuse_rrf(60)
                .top(8),
        )
        .execute(Query::text(question))
        .await
        .context("recall (dsl fusion)")?;
    println!("[fusion]  {} hit(s)", fused.len());

    // ── Form 3: Tree on its own (RAPTOR hierarchical descent) ──────────────
    // Find the nearest community summary, then descend to its leaf chunks.
    // depth=2 walks H1 root → H2 sub-communities → leaf chunks.
    let tree = scoped
        .dsl()
        .with_root(Tree::new("communities", 1).with_depth(2))
        .execute(Query::text(question))
        .await
        .context("recall (tree)")?;
    println!("[tree]    {} hit(s)", tree.len());

    Ok(())
}

What’s proven where

• Ingest builds communities. raptor_wiring.rs ingests a headed document and asserts each community carries a 768-d summary_embedding — the communities vector index is populated at ingest, via the single atomic_write in crates/lunaris-ingest/src/pipeline.rs.
• Tree uses only vector_search + read_as_of (see crates/lunaris-retrieve/src/operators/tree.rs) — both core StoragePort methods, no Cypher and no GRAPH.QUERY.
• The tree-beats-flat discrimination benchmark (tree_recall.rs) is measured against Moon, which since 0.7.0 is the only place it could be measured.

Scaling up: hybrid BM25 fusion

The classic hybrid plan fuses semantic vector search with lexical BM25:

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("who loves chocolate"))
    .await?;

The Keyword branch rides Moon’s native inverted index, and when both legs sit on the same index fuse_rrf collapses them into one round trip instead of two. For a batteries-included hybrid-RAG wrapper over the same plan, reach for DocumentKnowledgeBase.

Notes

• recall(query) ≠ hybrid. The one-shot form is pure vector over chunks. If you reached for recall() expecting fusion or rerank, use dsl() instead.
• Tree returns empty when the scope has no communities. A freshly-created scope (nothing ingested) or a single-paragraph document that collapses to a flat topology will yield zero tree hits — that is the normal graceful-empty state, not an error. Ingest a multi-section document first.
• Depth costs fan-out, not index scans. Tree::with_depth(d) issues one vector search, then walks community KV rows up to d levels — latency scales with depth × fan-out, capped at MAX_TREE_DEPTH = 4.
• See The Retrieval DSL for the full operator and combinator surface, and The Storage Backend for the Moon setup this page assumes.

Chat Agent Memory

Reach for ChatAgentMemory when you want a single chat agent to remember turns and recall them per user, with nothing else to wire.

ChatAgentMemory (crates/lunaris-recipes/src/conversational/chat_agent_memory.rs) is the thinnest conversational wrapper: a per-user MessageStream + a per-user WorkingMemory, both bound to the same "chat:<user_id>/" scope prefix (the shared prefix is what keeps a later consolidator pass from leaking across users). It exposes three methods:

Chat sessions are a flat stream in this wrapper — thread_id is always "default". If you need per-session partitioning, use MultiTurnConversation instead.

Recall ordering is the ACT-R recency-weighted blend inherited from MessageStream::recall: the fused Vector + Keyword ⊕ RRF(60) score is summed with an Anderson-1996 base-level activation term (d = 0.5), so a turn from a minute ago outranks a same-relevance turn from an hour ago.

Example

Shaped after chat_agent_memory_moon_postgres_parity in crates/lunaris-recipes/tests/conversational_parity.rs: open a handle, construct a per-user memory, replay a handful of turns, then recall.

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::ChatAgentMemory;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    // One handle per process — share via Arc. URL scheme picks the backend.
    let lunaris = Arc::new(Lunaris::open("moon://127.0.0.1:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-support-bot")?;

    let mem = ChatAgentMemory::new(lunaris.clone(), scope.clone(), "user-42");

    // Record conversational turns as they happen.
    mem.remember("I'm planning a trip to Kyoto in April.").await?;
    mem.remember("My budget is around 3000 USD.").await?;
    mem.remember("I'd like a ryokan with an onsen for at least one night.").await?;

    // Later — recall what's relevant to the next prompt.
    let hits = mem.recall("what kind of accommodation does the user want?").await?;
    for h in &hits {
        println!("score={:.3} source={} text={}", h.score, h.source, h.text);
    }

    Ok(())
}

Swap the URL for moon://localhost:6380 and the code is byte-for-byte identical — that is the parity contract.

Resuming a session

There is no explicit “load session” step — you resume by reconstructing ChatAgentMemory with the same user_id. The wrapper is a stateless handle over durable storage: ChatAgentMemory::new does no I/O, it just builds the "chat:<user_id>/" scope prefix; every prior remember already wrote an Episode into the backend keyspace (lunaris:{scope}:{kind}:{ulid}). So a fresh process — a new request handler, a restarted service, a different machine — that constructs the same id immediately recalls the full history:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::ChatAgentMemory;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    // A brand-new process. Nothing was kept in memory between runs.
    let lunaris = Arc::new(Lunaris::open("moon://127.0.0.1:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-support-bot")?;

    // Same user id as before ⇒ same `"chat:user-42/"` scope ⇒ same memory.
    // `new` is pure — the first storage round-trip is the `recall` below.
    let mem = ChatAgentMemory::new(lunaris.clone(), scope.clone(), "user-42");

    let prior = mem.recall("what has the user told me so far?").await?;
    for h in &prior {
        println!("score={:.3} text={}", h.score, h.text);
    }
    // ... then carry on: `mem.remember(...)` appends to the same history.
    Ok(())
}

Same id ⇒ same memory; that is the whole contract. There is nothing to serialize, snapshot, or hand back between turns — the backend is the session store, and constructing the wrapper is just a name binding.

Notes

• One ChatAgentMemory per user. Construction is pure (no I/O); the first storage round-trip happens on the first remember / recall.
• new takes &str for the user id, not impl Into<String> — the scope prefix is built immediately as "chat:<user_id>/".
• No consolidate() here. The wrapper holds a WorkingMemory for future additive surface, but the cross-session promotion pass is MultiTurnConversation’s differentiator. See Multi-Turn Conversation.
• Multi-agent scoping. The "chat:<user_id>/" prefix isolates one user’s turns inside this MessageStream — but MessageStream builds episodes with Scope::dev(), so that is source-prefix isolation, not a tenant wall. For RLS-grade per-agent isolation (separate agent platforms, the HTTP tenant claim, the low-level lunaris.scoped(scope) handle), see Multi-Agent & Scope → Multi-agent patterns and the runnable examples/multi-agent-rs/.
• Embedder / backend tuning lives in the Configuration Reference — the recipe adds no knobs of its own beyond MessageStream::with_top_k on the underlying primitive (not surfaced on ChatAgentMemory).

Multi-Turn Conversation

Reach for MultiTurnConversation when a chat agent runs many sessions per user and you want a cross-session consolidation pass that promotes hot scratchpad notes into long-term facts — without leaking across users.

MultiTurnConversation (crates/lunaris-recipes/src/conversational/multi_turn_conversation.rs) adds one thing to the ChatAgentMemory shape: a consolidate() method. It composes a MessageStream + a WorkingMemory, both captured at the same "chat:<user_id>/" scope prefix. That shared prefix is the load-bearing invariant — consolidate() runs through Consolidator::consolidate_scoped(Some("chat:<user_id>/")), so any event whose source does not start with that prefix is rejected by the scope filter (closing the cross-user consolidator-leak risk).

Note remember here takes a session id (thread_id) — turns from different sessions land under different Episode source segments but all recall together.

consolidate() is a no-op unless a Consolidator is installed on the handle — the consolidator pipeline defaults OFF (blueprint §5.2). Install one with lunaris.consolidator_pipeline().set_consolidator(...); see Consolidation & Verification for the ACT-R promotion model and the ConsolidationReport shape.

Example

Shaped after multi_turn_conversation_cross_session_consolidation_parity in crates/lunaris-recipes/tests/conversational_parity.rs: seed turns across two sessions for one user, recall across both, then run a scoped consolidation pass.

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::MultiTurnConversation;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-support-bot")?;

    // (Optional) install a consolidator — without one, consolidate() is a
    // no-op that returns an empty report. The default pipeline is OFF.
    // lunaris.consolidator_pipeline().set_consolidator(Arc::new(my_consolidator));

    let conv = MultiTurnConversation::new(lunaris.clone(), scope.clone(), "user-42");

    // Session "trip-planning".
    conv.remember("I'm planning a trip to Kyoto in April.", "trip-planning").await?;
    conv.remember("Budget is around 3000 USD.", "trip-planning").await?;

    // A later session, same user.
    conv.remember("Booked a ryokan in Higashiyama for two nights.", "booking").await?;

    // Recall spans every session for this user.
    let hits = conv.recall("where is the user staying in Kyoto?").await?;
    for h in &hits {
        println!("score={:.3} source={} text={}", h.score, h.source, h.text);
    }

    // One scope-filtered consolidation pass: only `chat:user-42/` events are
    // eligible for promotion; another user's turns are rejected by the
    // scope filter.
    let report = conv.consolidate().await?;
    println!("promotions this pass: {}", report.promotions.len());

    Ok(())
}

Resuming a session

Like ChatAgentMemory, there is no explicit load — reconstruct MultiTurnConversation::new(handle, scope, "user-42") with the same user_id and the backend already holds every prior turn. To resume one specific session, pass the same thread_id to remember again: turns from that session keep landing under the same Episode source segment. recall still spans all sessions for that user — the thread_id only shapes how turns are grouped, not what recall sees:

use lunaris::{Lunaris, Scope};
async fn demo() -> Result<(), lunaris::LunarisError> {
let lunaris = Lunaris::open("moon://localhost:6380").await?;
use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::MultiTurnConversation;
async fn run(lunaris: Arc<Lunaris>) -> Result<(), lunaris::LunarisError> {
let scope = Scope::new("acme-support-bot")?;
// A new process — same user, continuing the "trip-planning" session.
let conv = MultiTurnConversation::new(lunaris.clone(), scope.clone(), "user-42");
conv.remember("Confirmed the ryokan for the 14th.", "trip-planning").await?;

// Recall still spans every session this user has ever had.
let hits = conv.recall("what's confirmed for the Kyoto trip?").await?;
let _ = hits;
Ok(())
}
Ok(())
}

Construction is pure — MessageStream::new / WorkingMemory::new do no I/O — so resuming is just a name binding; the durable backend is the session store.

Notes

• The scope prefix is captured at new. Both the write path (MessageStream::ingest) and the promotion filter (WorkingMemory::consolidate) see "chat:<user_id>/", so isolation is enforced at both ends.
• consolidate() is bounded. Each call drains at most 1024 recent consolidate events with a 50 ms per-pull timeout — heavy callers should invoke it repeatedly rather than expect one call to drain everything.
• Successful promotions emit an audit event. Each promotion publishes AuditEvent::ConsolidatorPromotion to the __lunaris_audit__ topic.
• Use ChatAgentMemory instead if you don’t need sessions or consolidation — it’s the same recall behaviour with a flatter surface.

Slack / Email / Meeting Notes

Reach for these three when your conversational data arrives in channels, threads, or headings — SlackArchive for a workspace export, EmailThreading for mail threads, MeetingNotesMemory for meeting minutes.

All three wrap MessageStream (the email and meeting wrappers also hold a WorkingMemory for future additive surface, and expose an opt-in graph pipeline toggle). Each has a hard-coded source prefix — they are named recipes, not general-purpose composers. If you need an alternate prefix, compose MessageStream directly.

SlackArchive

crates/lunaris-recipes/src/conversational/slack_archive.rs — a channel + user-filtered message archive. Read-heavy, so it holds only a MessageStream (no WorkingMemory).

SlackArchiveQuery adds with_user(id) (chain a user narrow on top of a channel narrow → Filter::And) and recall(query). The narrowed recall builds the same Vector + Keyword ⊕ RRF(60) plan and attaches a pre-built Filter::Eq on the channel / participant_id field — no new retrieval DSL is introduced.

The channel / participant_id chunk-payload fields are not yet emitted by the ingest pipeline, so the metadata-Eq narrow is structurally wired (it passes both backend translators) but currently matches an empty set until that payload extension lands. The archive-wide recall and the source-prefix narrowing path are fully wired end-to-end. See the module rustdoc for the full caveat.

Example

Shaped after slack_archive_channel_filter_parity in crates/lunaris-recipes/tests/conversational_parity.rs:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::SlackArchive;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-workspace")?;
    let archive = SlackArchive::new(lunaris.clone(), scope.clone());

    // Bulk-ingest a workspace export, message by message.
    archive.ingest_channel("general", "U_ALICE", "Standup in 5, room Helios.").await?;
    archive.ingest_channel("general", "U_BOB",   "I'll be 2 min late.").await?;
    archive.ingest_channel("incident-2025-05-12", "U_ALICE", "Rolled back deploy 0.2.3.").await?;

    // Recall across the whole archive.
    let wide = archive.recall("what happened with the deploy?").await?;
    println!("archive-wide hits: {}", wide.len());

    // Narrowed to one channel.
    let narrow = archive.channel("general").recall("standup").await?;
    println!("#general hits: {}", narrow.len());

    Ok(())
}

EmailThreading

crates/lunaris-recipes/src/conversational/email_threading.rs — a thread-scoped email archive with an opt-in graph builder.

Example

Shaped after email_threading_graph_off_parity / email_threading_graph_on_opt_in:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::EmailThreading;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://127.0.0.1:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-workspace")?;

    // Opt in to the sender/recipient graph BEFORE ingest if you want edges
    // (the extractor runs inside the ingest hot path, not after the fact).
    let email = EmailThreading::new(lunaris.clone(), scope.clone()).with_graph_pipeline(true);

    email.ingest("RFC-0042", "alice@example.com", "Proposing the new retention sweep.").await?;
    email.ingest("RFC-0042", "bob@example.com",   "+1, but let's cap it at 90 days.").await?;
    email.ingest("RFC-0042", "alice@example.com", "Done, capped at 90d in v2.").await?;

    // Recall across all threads.
    let all = email.recall("retention sweep cap").await?;
    println!("all-threads hits: {}", all.len());

    // Narrow to one thread, then recall within it.
    let in_thread = email.thread("RFC-0042").recall("what was the cap?").await?;
    println!("RFC-0042 hits: {}", in_thread.len());

    Ok(())
}

MeetingNotesMemory

crates/lunaris-recipes/src/conversational/meeting_notes_memory.rs — stores meeting headings as thread_id and note bodies as message content; supports attendee-narrowed recall and the same graph toggle.

MeetingNotesQuery::recall(query) emits a Filter::And of per-attendee Filter::Eq { field: "participant_id", .. } (all attendees must be present) — same metadata-payload caveat as SlackArchive’s channel narrow.

Example

Shaped after meeting_notes_memory_transcript_parity:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::conversational::MeetingNotesMemory;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-workspace")?;
    let notes = MeetingNotesMemory::new(lunaris.clone(), scope.clone());

    notes.note("2025-05-12 / Roadmap", "Decided to ship the 90-day retention cap in v2.").await?;
    notes.note("2025-05-12 / Roadmap", "Action item: Alice to write the migration doc.").await?;
    notes.note("2025-05-13 / Standup", "Migration doc drafted, in review.").await?;

    // Recall across the whole corpus.
    let hits = notes.recall("what was decided about retention?").await?;
    println!("corpus hits: {}", hits.len());

    // Narrow to notes attributed to a set of attendees (owned Vec<String>).
    let by_alice = notes.attendees(vec!["scribe".to_string()]).recall("action items").await?;
    println!("attendee-narrowed hits: {}", by_alice.len());

    Ok(())
}

Notes

• Hard-coded prefixes. slack:archive/, email:thread/, meeting:notes/ — if you need different roots, compose MessageStream yourself; these wrappers won’t take a prefix argument.
• Graph is opt-in and ingest-time. with_graph_pipeline(true) must be called before ingest if you want entity/relation edges; retrofitting graph on an already-ingested corpus requires re-ingest. See The Graph Pipeline.
• Tenant isolation is orthogonal to these channel prefixes — see Multi-Agent & Scope.

Document Knowledge Base

Reach for DocumentKnowledgeBase when you have a corpus of documents and want hybrid RAG over it — semantic + BM25 fused with RRF — with metadata filters and a result cap.

DocumentKnowledgeBase (crates/lunaris-recipes/src/documentary/document_knowledge_base.rs) is a thin wrapper over DocumentCorpus. It exists to make “knowledge base over a document source” discoverable from the public surface; every method forwards into at most one primitive call and there is no business logic of its own.

search returns Vec<Hit> ranked by the fused RRF score. The dispatch to Moon’s native RRF (versus a client-side merge for a backend that does not declare the capability) lives inside RetrievalBuilder::execute — the wrapper is pure plan composition. Source prefix scoping runs post-hydrate (the chunks FT schema does not carry source), so a modest over-fetch is applied before pruning to the corpus’s prefix.

If your documents are pre-chunked already, pass them directly; otherwise chunk them upstream (the umbrella ingest pipeline’s markdown chunker targets ~500 tokens with 100-token overlap — see Ingesting Observations).

Example

Shaped after document_knowledge_base_parity_quickstart_rag in crates/lunaris-recipes/tests/documentary_parity.rs:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::documentary::DocumentKnowledgeBase;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://127.0.0.1:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-docs")?;

    let kb = DocumentKnowledgeBase::new(lunaris.clone(), scope.clone(), "kb:docs/");

    // Ingest pre-chunked content with metadata.
    let chunks = vec![
        (
            "Lunaris commits all storage fan-out in a single atomic_write.".to_string(),
            serde_json::Map::from_iter([
                ("lang".to_string(), serde_json::json!("en")),
                ("section".to_string(), serde_json::json!("architecture")),
            ]),
        ),
        (
            "The retrieval DSL fuses Vector, Keyword, and Graph operators via RRF.".to_string(),
            serde_json::Map::from_iter([
                ("lang".to_string(), serde_json::json!("en")),
                ("section".to_string(), serde_json::json!("retrieval")),
            ]),
        ),
    ];
    kb.ingest(chunks).await?;

    // Hybrid RAG: filter on metadata, cap results, search.
    let hits = kb
        .filter("lang", "en")
        .top(5)
        .search("how does Lunaris guarantee atomicity?")
        .await?;

    for h in &hits {
        println!("score={:.3} source={} text={}", h.score, h.source, h.text);
    }

    Ok(())
}

Swap the URL for moon://localhost:6380 — same code, same result set (parity contract).

Notes

• Builder methods consume self. kb.filter(..).top(..).search(..) is the idiom; you can’t reuse a DocumentKnowledgeBase after calling search.
• filter is metadata-Eq only (Filter::Eq from lunaris-core is canonical — never build SQL WHERE strings). Multiple .filter calls AND together. For valid-time filtering use TimelineReconstruction or TemporalQuery directly.
• No batch-ingest helper — ingest issues one internal atomic_write per chunk. A true batched bulk-ingest path is a post-v0.1 addition; for large static corpora today, prefer the bench-crate bulk helpers (see the RAG scenario in Helios Scratchpad) or accept the per-chunk write cost.
• For citation-graph-aware paper corpora, see ResearchPaperCorpus.

Research Papers & Code Repos

Reach for ResearchPaperCorpus when you want a paper corpus with an opt-in citation graph; reach for CodeRepoMemory when you want “function body as-of commit N” — point-in-time recall over committed code.

Both wrap DocumentCorpus on the ingest side; CodeRepoMemory adds TemporalQuery<Documents> on the recall side.

ResearchPaperCorpus

crates/lunaris-recipes/src/documentary/research_paper_corpus.rs — a DocumentCorpus plus an opt-in citation graph. The graph-on path toggles Lunaris::graph_pipeline().enable() (the graph defaults OFF per blueprint §5.2; opt in via the explicit builder call).

Put the paper’s id / venue / year in the chunk metadata so a later metadata-Eq filter (via the underlying DocumentCorpus) can narrow by year or venue. To get citation edges in the graph, call with_graph_pipeline(true) before ingest — extraction runs inside the ingest hot path.

Example

Shaped after research_paper_corpus_parity_graph_off_recall in crates/lunaris-recipes/tests/documentary_parity.rs:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::documentary::ResearchPaperCorpus;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-research")?;

    // Opt in to the citation graph before ingest. Default is OFF.
    let papers = ResearchPaperCorpus::new(lunaris.clone(), scope.clone(), "papers:")
        .with_graph_pipeline(true);

    let chunks = vec![
        (
            "Reciprocal Rank Fusion outperforms Condorcet fusion on TREC runs.".to_string(),
            serde_json::Map::from_iter([
                ("paper_id".to_string(), serde_json::json!("cormack2009")),
                ("year".to_string(), serde_json::json!(2009)),
            ]),
        ),
        (
            "ACT-R base-level activation models declarative memory decay.".to_string(),
            serde_json::Map::from_iter([
                ("paper_id".to_string(), serde_json::json!("anderson1996")),
                ("year".to_string(), serde_json::json!(1996)),
            ]),
        ),
    ];
    papers.ingest(chunks).await?;

    let hits = papers.search("how is rank fusion evaluated?").await?;
    for h in &hits {
        println!("score={:.3} source={} text={}", h.score, h.source, h.text);
    }

    Ok(())
}

CodeRepoMemory

crates/lunaris-recipes/src/documentary/code_repo_memory.rs — models “function body as-of commit N”. Each commit is ingested once per chunk with commit_sha and committer_date_unix_ms stamped into the Episode metadata; recall time-travels via TemporalQuery::<Documents>::as_of.

Hlc’s native shape is Unix-milliseconds ({wall_ms: u64, counter: u32, node_id: u16}) — there is nowhere on the Hlc surface for RFC3339-nanos. ingest_commit takes the committer date as an i64 of Unix-ms; recall(..., as_of: Hlc) takes the Hlc directly, so you control the counter / node-id disambiguation in dense-commit scenarios. Build one with Hlc::from_parts(unix_ms as u64, 0, 0).

TemporalQuery recalls across all Documents — CodeRepoMemory does not partition by repo at the recall layer. If you store more than one repo on the same handle, isolate them with distinct prefixes and a metadata filter, or use separate handles. The parity tests are fixture-isolated.

Example

Shaped after code_repo_memory_as_of_commit_50_round_trip_moon_postgres in crates/lunaris-recipes/tests/documentary_rust_integration.rs:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_core::hlc::Hlc;
use lunaris_recipes::documentary::CodeRepoMemory;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://127.0.0.1:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-research")?;
    let repo = CodeRepoMemory::new(lunaris.clone(), scope.clone(), "repo:lunaris/");

    // Commit A — first version of the function.
    let commit_a_ms: i64 = 1_715_000_000_000; // committer date, Unix-ms
    repo.ingest_commit(
        "a1b2c3",
        commit_a_ms,
        vec![(
            "fn recall(query: &str) -> Vec<Hit> { /* v1 */ }".to_string(),
            serde_json::Map::from_iter([("path".to_string(), serde_json::json!("src/recall.rs"))]),
        )],
    ).await?;

    // Commit B — the function changed.
    let commit_b_ms: i64 = 1_715_600_000_000;
    repo.ingest_commit(
        "d4e5f6",
        commit_b_ms,
        vec![(
            "fn recall(query: &str, as_of: Hlc) -> Vec<Hit> { /* v2 */ }".to_string(),
            serde_json::Map::from_iter([("path".to_string(), serde_json::json!("src/recall.rs"))]),
        )],
    ).await?;

    // Time-travel: what did `recall` look like at commit A's timestamp?
    let as_of_a = Hlc::from_parts(commit_a_ms as u64, 0, 0);
    let hits = repo.recall("recall function signature", as_of_a).await?;
    for h in &hits {
        println!("source={} text={}", h.source, h.text);
    }

    Ok(())
}

Notes

• recall has no builder — as_of is a positional Hlc argument. Use Hlc::from_parts(unix_ms as u64, 0, 0) (or capture a causal timestamp from lunaris.clock().tick()).
• ingest_commit is one atomic_write per chunk, batched per invocation — preserves the INGEST-04 contract at the per-chunk grain.
• Graph posture — only ResearchPaperCorpus exposes a graph toggle; CodeRepoMemory does not. For commit-graph-style traversal, drop to the Lunaris handle and compose Graph::anchored(...) yourself — see The Graph Pipeline.
• For a corpus without either citation graph or time-travel, use DocumentKnowledgeBase.

Timeline Reconstruction

Reach for TimelineReconstruction when you have a stream of dated events and want to stitch a narrative for a time window — “what happened between Jan 10 and Jan 16” or “what did the timeline look like as of Jan 13”.

TimelineReconstruction (crates/lunaris-recipes/src/documentary/timeline_reconstruction.rs) is a deliberately thin two-call composition of DocumentCorpus (ingest) and TemporalQuery<Documents> (recall). Its value is discoverability as a named recipe, not code volume.

The boundary gotcha

between is lower-bound inclusive, upper-bound exclusive — the Phase 9.1 renderer emits @valid_time:[lo hi] (crates/lunaris-recipes/src/documentary/timeline_reconstruction.rs:15-19). To include “days 10 through 15 inclusive” (six days), pass hi = Jan 16 00:00:00Z, not hi = Jan 15. This carries straight into the Python / TS parity tests too — same convention everywhere.

Hlc’s native shape is Unix-milliseconds; build bounds with Hlc::from_parts(unix_ms as u64, 0, 0).

Example

Shaped after timeline_reconstruction_between_returns_exactly_6_events in crates/lunaris-recipes/tests/documentary_rust_integration.rs:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_core::hlc::Hlc;
use lunaris_recipes::documentary::TimelineReconstruction;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-ops")?;
    let timeline = TimelineReconstruction::new(lunaris.clone(), scope.clone(), "timeline:events/");

    // Ingest dated events. Stamp the event's valid time into metadata so
    // your own queries can filter on it; the bi-temporal `valid_from` the
    // backend stamps drives `.between` / `.as_of`.
    let events = vec![
        (
            "Deploy 0.2.3 shipped to 5% of traffic.".to_string(),
            serde_json::Map::from_iter([
                ("event_id".to_string(), serde_json::json!("e-001")),
                ("event_valid_time_unix_ms".to_string(), serde_json::json!(1_736_467_200_000_i64)), // 2025-01-10
            ]),
        ),
        (
            "Deploy 0.2.3 rolled back after error spike.".to_string(),
            serde_json::Map::from_iter([
                ("event_id".to_string(), serde_json::json!("e-002")),
                ("event_valid_time_unix_ms".to_string(), serde_json::json!(1_736_726_400_000_i64)), // 2025-01-13
            ]),
        ),
    ];
    timeline.ingest(events).await?;

    // "What happened between Jan 10 and Jan 16?" — note hi is Jan 16, so
    // Jan 10..=Jan 15 are all included.
    let lo = Hlc::from_parts(1_736_467_200_000, 0, 0); // 2025-01-10T00:00:00Z
    let hi = Hlc::from_parts(1_737_072_000_000, 0, 0); // 2025-01-16T00:00:00Z (exclusive)
    let window = timeline.between("deploy 0.2.3", lo, hi).await?;
    println!("events in [Jan 10, Jan 16): {}", window.len());

    // "What did the timeline look like as of Jan 13?"
    let as_of_jan13 = Hlc::from_parts(1_736_726_400_000, 0, 0);
    let snapshot = timeline.as_of("deploy 0.2.3", as_of_jan13).await?;
    println!("snapshot hits: {}", snapshot.len());

    Ok(())
}

The recipe tests assert the returned set for both between and as_of against a live Moon; moon://host:port is the only URL scheme 0.7.0 accepts.

Notes

• Always add a day to hi if you mean an inclusive upper bound. This is the single doc-worthy footgun of this recipe.
• between panics if lo > hi — the bound check lives in TemporalQuery::between (check_between_bounds). Equal endpoints are allowed (empty-or-single-instant window).
• No metadata filter on the recipe itself — TemporalQuery<Documents> recalls across all Documents on the handle. Isolate distinct timelines with distinct prefixes (and a metadata filter via the underlying DocumentCorpus) or separate handles.
• For point-in-time recall over code rather than generic events, see CodeRepoMemory. For the bi-temporal MVCC model underneath, see Durability & Recovery.

Customer Support History

Reach for CustomerSupportHistory when your support data is split across two shapes — ticket bodies and chat transcripts — and you want one recall call that returns hits from both.

CustomerSupportHistory (crates/lunaris-recipes/src/documentary/customer_support_history.rs) composes a DocumentCorpus for ticket bodies (source = "ticket:<ulid>", ticket_id lands in metadata) and a MessageStream for chat transcripts (source = "chat:<ticket_id>/<turn_idx>/"), plus an opt-in graph pipeline toggle for a product/customer relationship graph.

How recall fuses the two buckets

It doesn’t fuse across types. RRF runs within each primitive’s own bucket — ticket hits are RRF-fused among themselves, chat hits among themselves — and recall returns tickets ++ chats. Ordering across the two buckets is not normalised (tie-bucket behaviour is deferred). Each returned hit is checked to carry its expected source prefix (ticket: vs chat:) — a record double-indexed under both prefixes would be caught here rather than silently collapsing duplicates.

The prefixes are hard-coded — this wrapper is a named recipe, not a general composer. If you need different prefixes, compose DocumentCorpus

• MessageStream directly.

Example

Shaped after the "refund" recall scenario in crates/lunaris-recipes/tests/documentary_rust_integration.rs:

use std::sync::Arc;
use lunaris::{Lunaris, Scope};
use lunaris_recipes::documentary::CustomerSupportHistory;

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://127.0.0.1:6380").await?);
    // The partition every recipe below reads and writes in.
    let scope = Scope::new("acme-support-bot")?;
    let hist = CustomerSupportHistory::new(lunaris.clone(), scope.clone());

    // Ticket bodies → DocumentCorpus under `ticket:<id>`.
    hist.ingest_ticket("T-1042", "Customer requests a refund for order #5567 — duplicate charge.").await?;
    hist.ingest_ticket("T-1043", "Shipment delayed; customer asks for partial refund.").await?;

    // Chat transcripts → MessageStream under `chat:<ticket_id>/<turn>`.
    hist.ingest_chat("T-1042", 0, "customer", "Hi, I was charged twice for order #5567.").await?;
    hist.ingest_chat("T-1042", 1, "agent",    "Apologies — I've issued a full refund, 3-5 business days.").await?;
    hist.ingest_chat("T-1042", 2, "customer", "Thank you!").await?;

    // One recall across BOTH buckets — returns ticket hits ++ chat hits.
    let hits = hist.recall("refund for a duplicate charge").await?;
    for h in &hits {
        let bucket = if h.source.starts_with("ticket:") { "ticket" } else { "chat" };
        println!("[{bucket}] score={:.3} source={} text={}", h.score, h.source, h.text);
    }

    Ok(())
}

Swap the URL for moon://localhost:6380 — the parity test asserts both backends return the same set and that source prefixes are preserved.

Notes

• turn_idx is usize, not u32 — pass a plain index.
• recall returns a concatenation, not a globally ranked list. If you need a single ranked stream across tickets and chats, re-rank the combined Vec<Hit> yourself (e.g. by Hit::score) or use the cross-encoder reranker on a hand-composed plan — see The Retrieval DSL.
• Graph is opt-in and ingest-time. Call with_graph_pipeline(true) before ingesting if you want product/customer edges.
• GDPR / retention — to purge one customer’s data, route through Lunaris::forget(ForgetTarget::Scope(...)) on the relevant ticket: / chat: prefixes; see Forgetting.

Helios Scratchpad

Reach for CodingSessionMemory when an agent needs a filesystem-shaped working store — write / read / edit / grep / ls over a session-scoped namespace — backed by Lunaris’s bi-temporal MVCC store, with as_of time-travel for free.

CodingSessionMemory is exported by the umbrella lunaris crate (not lunaris-recipes) — use lunaris::{CodingSessionMemory, Lunaris, Scope, Hlc};. It was built for Helios, Lunaris’s first downstream consumer, which replaces deepagents’ ephemeral dict-backed mock filesystem with a real bi-temporal store. It is a convenience over the WorkingMemory primitive — Lunaris doesn’t know Helios exists; the recipe is not a coupling.

This chapter is the public-facing recipe summary. For the full integration story — multi-session servers, GDPR purge, graph-aware entity recall, degraded-state handling, dual-backend portability, and a production checklist — see docs/helios-integration.md.

The frozen 9-method surface

CodingSessionMemory holds an Arc<Lunaris> + a session_prefix (e.g. "helios:fs/session-42/") + a delegated WorkingMemory (itself Arc<Lunaris> + String), and is Clone (every field is cheap). Its public surface is frozen at nine symbols — the helios_scratchpad_public_surface_under_50_loc test asserts exactly nine at compile time, so the surface can neither grow nor shrink without an HELIOS-* requirement update:

A few load-bearing facts:

• new is pure — no I/O. The session prefix is helios:fs/<session_id>/, frozen by convention. The first storage round-trip happens on the first write / read / grep / ls / forget. Use a Ulid (or UUIDv7) for the session id in multi-session servers — two pads with the same id co-mingle and one forget() wipes both.
• write / read route through WorkingMemory — the content String is wrapped as serde_json::Value::String(...) on write and unwrapped on read. read returns None for “never written / already purged” (not Some("")); for large payloads that the chunker split, read falls back to a multi-chunk reconstruction path that concatenates up to 8 hits.
• edit is a plain write of the new content. _old is accepted for Helios’s Read/Edit symmetry but unused — MVCC supersede stamps the prior version’s bt.sys[1] automatically when the new ingest commits. No history is overwritten in place; pad.as_of(pre_edit_ts).read(path) returns the pre-edit bytes.
• grep is hybrid recall (Vector + Keyword(BM25) + RRF + rerank per Lunaris::recall defaults) scoped to the helios:fs/<sid>/ prefix via Filter::StartsWith — never a SQL wildcard fragment. It surfaces Hit::degraded per hit when the verifier queue is backed up; the agent UX decides what to do with that flag.
• forget() is soft-delete only. It lowers to ForgetTarget::Scope(ScopeSpec::BySource(session_prefix)) with default options — an MVCC supersede that stamps bt.sys[1]; rows are still physically present and return from read_as_of(ts) for any ts before the delete. There is no pad.hard_forget() — for GDPR-irreversible purge you drop to the Lunaris handle’s two-step confirm_hard_forget rail. See Forgetting.
• as_of returns a borrowed, read-only view. AsOfScratchpad<'a> holds &CodingSessionMemory so the borrow checker stops you moving the pad while a time-travel view is alive. Its only method is read(path). There is no historical write / edit / grep / forget.

Everything else — graph-aware recall, dry-run forget, hard-delete confirmation, verifier queue tuning — drops one level to the Lunaris handle itself. The recipe is intentionally narrow.

Example — basic session lifecycle

use std::sync::Arc;
use lunaris::{CodingSessionMemory, Lunaris, Scope};

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    // One handle per process — share via Arc. URL scheme picks the backend.
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);

    // Session prefix becomes "helios:fs/session-42/".
    let scope = Scope::new("helios")?;
    let pad = CodingSessionMemory::new(lunaris.clone(), scope, "session-42");

    // Write two docs.
    pad.write("notes.md", "# Notes\nFirst draft.").await?;
    pad.write("todo.md",  "- [ ] finish draft").await?;

    // Read back. `read` returns `Option<String>` — `None` means no hit.
    let notes = pad.read("notes.md").await?;
    assert!(notes.is_some());

    // Edit — `_old` is accepted for symmetry but unused; MVCC supersedes
    // the prior version automatically.
    pad.edit("notes.md", "First draft.", "# Notes\nSecond draft.").await?;

    // Hybrid recall over this session's namespace.
    let hits = pad.grep("draft", 5).await?;
    for h in &hits {
        println!("source={} score={:.3} degraded={}", h.source, h.score, h.degraded);
    }

    // List stored paths (session-prefix stripped, sorted, deduped).
    let paths = pad.ls(None).await?;
    println!("session paths: {paths:?}");

    // End of session: soft-delete every primitive under the session prefix.
    let _receipt = pad.forget().await?;

    Ok(())
}

Example — time-travel debugging

use std::sync::Arc;
use lunaris::{CodingSessionMemory, Hlc, Lunaris, Scope};

#[tokio::main]
async fn main() -> Result<(), lunaris::LunarisError> {
    let lunaris = Arc::new(Lunaris::open("moon://localhost:6380").await?);
    let scope = Scope::new("helios")?;
    let pad = CodingSessionMemory::new(lunaris.clone(), scope, "session-42");

    // t1: agent writes the first draft.
    pad.write("plan.md", "Plan v1: go left").await?;

    // Capture a causal timestamp at the decision point. `HlcClock::tick()`
    // (via `lunaris.clock()`) is the only monotonic-now source — `Hlc::now()`
    // does not exist.
    let decision_hlc: Hlc = lunaris.clock().tick();

    // t2: agent edits the plan.
    pad.edit("plan.md", "Plan v1: go left", "Plan v2: go right").await?;

    // The live read sees the latest version.
    let latest = pad.read("plan.md").await?;
    assert_eq!(latest.as_deref(), Some("Plan v2: go right"));

    // ... but the time-travel view reads the state as-of t1.
    let as_of_view = pad.as_of(decision_hlc);
    let historical = as_of_view.read("plan.md").await?;
    assert_eq!(historical.as_deref(), Some("Plan v1: go left"));

    Ok(())
}

Notes

• Resuming a session needs no load step. CodingSessionMemory::new(handle, session_id) is pure (no I/O) — it just builds the "helios:fs/<session_id>/" prefix. A later process that reconstructs the pad with the same session_id sees every prior write / edit (the data lives in the durable backend keyspace lunaris:{scope}:{kind}:{ulid}); a pad.as_of(ts) view still reads any historical state. Same id ⇒ same pad — which is also why two pads with the same id co-mingle.
• CodingSessionMemory is the recipe; WorkingMemory is the primitive. If you want a JSON-valued scratchpad rather than a string-valued filesystem, use WorkingMemory directly. If you want consolidator promotion of hot notes, that is toggled per-scope on the consolidator pipeline ( lunaris.consolidator_pipeline()...) — CodingSessionMemory itself adds no consolidate method.
• Backend — moon://host:port is the only selector as of 0.7.0. The latency budget is Moon recall p50 ≤ 25 ms; see The Storage Backend.
• For everything beyond the basics — multi-session servers, hard delete, graph-aware entity recall, degraded-state handling, the production checklist — read docs/helios-integration.md.

Configuration Reference

Lunaris is configured along four axes:

1. Cargo feature flags — chosen at build time; decide which embedder / reranker / extractor / verifier backends are compiled in.
2. Environment variables (LUNARIS_*) — read at runtime, mostly when Lunaris::open resolves the default pipeline. CLI flags on the lunaris-server binary override the matching env var (12-factor; see CONTEXT.md D-26).
3. Builder / pipeline toggles — programmatic switches on the Lunaris handle (graph pipeline on/off, verifier on/off, per-scope enablement).
4. The storage URL scheme — moon://… is the only one 0.7.0 accepts.

Defaults are tuned for “a Moon you run, a local embedder, graph and verifier off” — the safe production floor. Turn things on deliberately.

1. Cargo feature flags

lunaris (umbrella crate)

v0.6 llama.cpp-only cutover. The candle inference stack (native, embedder-gguf, reranker-gguf, verify-small, verify-large, cpu-accelerate, cpu-mkl, cuda-fa2) is deleted. llamacpp is the only local embed/rerank runtime and is on by default; it needs cmake + a C++ toolchain. See docs/decisions/2026-07-10-llamacpp-only-cutover.md (the cutover ADR) and docs/migration/0.5-to-0.6-llamacpp-only.md (the migration guide).

default = ["llamacpp"]. CPU is the default device; device selection is a runtime probe, overridden by LUNARIS_DEVICE=cpu (the kill-switch that forces zero GPU layers even on an accelerated build). Extractor and verifier are remote-only — LUNARIS_EXTRACT_PROVIDER / LUNARIS_VERIFY_PROVIDER (anthropic|openai|gemini|minimax|openai-compat) or a caller-supplied with_extractor / with_verifier impl; unset resolves to NoopExtractor/NoopVerifier. For a pure-Rust, no-C++-toolchain build (Tier-0, small devices): default-features = false → NoopEmbedder/NoopReranker. (The umbrella also forwards moon-it / pg-it integration features to the storage crates.)

lunaris-llamacpp

The only local embed/rerank runtime. LlamaCppEmbedder and LlamaCppReranker load their GGUF eagerly and raise/log a WARN + NoopEmbedder/NoopReranker fallback on a missing or corrupt artifact — there is no auto-download; the MCP server stages GGUFs lazily on first recall, other deployments download them out-of-band and verify against the canonical SHA-256s printed by cargo run -p lunaris-bench --bin stage-models -- --help.

lunaris-extract

With no feature/provider active, NoopExtractor is the fallback (applies() == false). Provider selection at runtime is via LUNARIS_EXTRACT_PROVIDER.

lunaris-verify

The candle-based verify-small (Gemma-3-270M) / verify-large (Gemma-3-27B) tiers from RFC 0006 were deleted in the v0.6 llama.cpp-only cutover — the verifier is remote-only (LUNARIS_VERIFY_PROVIDER) or NoopVerifier, with no in-process model tier.

Integration-test features (never default)

lunaris-recipes / lunaris-storage-moon: moon-it. (pg-it was removed in 0.7.0 with the Postgres backend.) lunaris-conformance: chaos-it. lunaris-bench: budget-it.

Excluded from cargo test --workspace: lunaris-py and lunaris-ts are cdylibs and fail to link under the workspace test runner. Test them with maturin + pytest / napi build + vitest, or via scripts/sdk-real-evidence.sh.

2. Environment variables

All variables below are read by Lunaris::open (or the lunaris-server binary) unless noted. Boolean variables accept 1, true, on (case- insensitive) for “enabled”; anything else (or unset) is “disabled”.

Backend / pipeline selection

The production recall pipeline (GA-1)

Every production surface builds ONE canonical recall root, lunaris_retrieve::production_root(k, graph_enabled):

• graph-OFF: Vector("chunks",k) ∧ BM25("chunks",k) → fuse_rrf(60) → top(k)
• graph-ON: the same chunks legs fused with the fact legs (Navigate("entities",k, fallback "facts") ∧ BM25("facts",k)), then top(k)

Per-surface deltas on top of that shared root:

Rerank is OFF by default on every surface; with it off the bge-reranker GGUF is never loaded. When enabled, the stage runs between RRF fusion and the final top(k) over the top LUNARIS_RECALL_RERANK_TOP_IN candidates. Budget seconds, not milliseconds, for it — the measured cost is p50 1301.3 ms at top_in=60 and 575.6 ms at top_in=30 (capacity §4). It is a quality stage, not a latency-class stage, and turning it on voids the 25 ms p50 recall contract.

Activation boost — on by default, and it changes ranking

Read this before you A/B anything. The boost is on by default on every surface (W1.8 — it was previously applied only on the lunaris-memory-service path, so the same query could rank differently through MCP than through /v1/recall; that divergence is gone). Any benchmark, eval, or regression comparison MUST still state which value it ran with, and both arms of an A/B must run with the same one — the prior is a real ranking input, not a tiebreaker. It is also the first thing to check when recall ordering looks inexplicable in production.

One consequence worth knowing before you read a flamegraph: with the boost on, every recall issues one activation-ledger point read per distinct hit — bounded by the hit set, never by the scope’s size, and pinned by ledger_read_cost_is_one_point_read_per_distinct_hit. Callers that never write reinforcement signals still pay those reads and get an empty ledger back; LUNARIS_ACTIVATION_BOOST=0 removes them entirely.

How much the boost is worth, and for how long. The prior is additive on a hit’s fused score, bounded by BOOST_CAP (0.30, an asymptote — not a value any real record reaches), and it decays with the age of the memory’s most recent reference. Measured for a memory referenced ten times (weighted = 30):

A memory that was never referenced gets exactly 0.0 — the ledger only ever promotes, never demotes, so an unreferenced memory keeps its raw hybrid rank.

Until the fix for F43 landed, this curve clamped negative ACT-R activation to zero, which made the prior read exactly 0.0 for any memory older than weighted² seconds — 9 seconds after a single strong reference, 15 minutes after ten. If you are reading recall traces from an older build, the boost column is expected to be zero almost everywhere; that was a defect (F43), not a tuning choice.

The llama.cpp granite-r2 embedder and bge-reranker-v2-m3 reranker are selected unconditionally when the llamacpp feature is on (default) — there is no LUNARIS_EMBEDDER_BACKEND or LUNARIS_RERANKER_BACKEND variable. Use the env vars below to change the GGUF path or (operators only) redirect the embedder to a remote Ollama endpoint.

Embedder and reranker details

Verifier / extractor providers (remote-only)

A provider that is set but fails to construct (bad URL, missing key) logs a tracing::warn! and degrades to NoopExtractor/NoopVerifier — never a silent backend swap.

Workspace-wide LLM defaults (lunaris-llm, src/config.rs) — consulted only when the per-pipeline variable (LUNARIS_EXTRACT_PROVIDER / LUNARIS_VERIFY_PROVIDER / LUNARIS_REFLECT_PROVIDER) is unset. Precedence: per-pipeline env → workspace env → TOML file → built-in default.

Precedence for a pipeline’s provider/model, highest first: the per-pipeline env var (LUNARIS_EXTRACT_PROVIDER / LUNARIS_EXTRACT_MODEL) → the workspace env var (LUNARIS_LLM_PROVIDER / LUNARIS_LLM_MODEL) → the matching section of LUNARIS_LLM_CONFIG’s TOML → the built-in fallback pair (ollama + gemma3:4b). Env always wins over the file.

Moon storage tuning (lunaris-storage-moon)

Read by the Moon adapter in any embedding process (server, MCP, SDKs).

Supervision / worker pool

Ingest + embedding batching

The embedder batches by token window, not by row count, and the two families of knob are independent: *_BATCH_TOKENS sizes the llama.cpp compute buffer, *_BATCH* sizes how many items the caller hands over at once.

Scope resolution

contextd — the shared local daemon

lunaris-contextd keeps one warm embedder and one Moon connection for all the short-lived hook / MCP / CLI processes on a machine. Everything below tunes how those processes find it and how long they will wait.

Codex hook-adapter budgets

scripts/lunaris-codex-hook-adapter.py is a thin shim that talks to contextd over the socket above. These are its per-phase deadlines, in milliseconds; each one degrades to “inject nothing” rather than delaying the agent.

Hook context injection

What the Claude Code / Codex hook may inject, and the latency budgets it may spend doing it. Every timeout here is a hard budget on a user-visible path — exceeding one degrades to injecting nothing, never to blocking the turn.

The LUNARIS_CODEX_* spellings (LUNARIS_CODEX_CONTEXT_MAX_CHARS, …_CONTEXT_MIN_SCORE, …_POST_TOOL_*) are legacy aliases consulted after the LUNARIS_CONTEXT_* names above. Prefer the unprefixed names; the Codex ones exist so older Codex hook configs keep working.

Recall degradation signal

Logging

There is no LUNARIS_LOG variable — the library/server filter is the standard RUST_LOG; the auxiliary binaries each have their own clap-backed filter var.

HTTP server (lunaris-server)

crates/lunaris-server/src/config.rs — every var has a matching CLI flag that takes precedence.

Plus the --metrics-disabled CLI flag, which removes the /metrics endpoint. The per-command Moon timeout the server inherits is LUNARIS_MOON_OP_TIMEOUT — a storage-layer variable, not a lunaris-server flag (see Moon storage tuning above).

Bearer-token map format (LUNARIS_TOKENS_FILE, D-07):

{
  "<opaque-bearer-token>": { "tenant": "acme",   "scopes": ["ingest", "recall", "forget"] },
  "<another-token>":       { "tenant": "globex", "scopes": ["recall"] }
}

• tenant is the partition scope for the token (typed as Scope, validated against [A-Za-z0-9_\-.]{1,128}) — and the only source of truth for it. Route handlers ignore any scope / tenant field on the request body; every public DTO carries #[serde(deny_unknown_fields)], so a body that contains such a field is rejected (HTTP 422).
• scopes is the verb-permission set — which of ingest / recall / forget this token may call. A request whose route requires a verb not in this list is 403.
• A missing or invalid token is 401.

MCP server (lunaris-mcp)

Every var has a matching CLI flag (clap) that takes precedence. Storage resolution is explicit → contextd-advertised → refuse-to-boot; see MCP Server.

(LUNARIS_MCP_LOG is in the Logging table above.)

Hooks & context injection (lunaris-hook / lunaris-contextd)

LUNARIS_DREAM_CRON and LUNARIS_DREAM_PIGGYBACK appear in the /dream skill docs as v2 stubs but are not read by any code yet — setting them does nothing today.

Bench-only variables

The LUNARIS_EVAL_* family (plus the bench harness knobs) configures the LongMemEval / PersonaMem benchmark rigs only — never a production process. They are documented next to the harnesses: scripts/bench/lme/README.md and scripts/bench/pm/README.md.

Integration-test probes (not for production)

Point these at a dedicated Moon. Never at a store you care about — the fixtures own their instance and clear it.

3. Builder / pipeline toggles (programmatic)

Each opt-in pipeline exposes a handle on Lunaris plus an env-seeded initial state:

The handles are obtained from the Lunaris value after open; see Guides → Consolidation & Verification and Guides → The Graph Pipeline.

4. Storage URL scheme

Lunaris::open(url) / lunaris::open(url) dispatch on the scheme:

There is no schema migration and no role bootstrap to run — per-scope keyspaces, FT indices, GRAPH keys, and MQ topics are created lazily on the first atomic_write per scope.

See also Operations → The Storage Backend.

API Reference (docs.rs)

The exhaustive, type-level API reference is the generated rustdoc — this book covers the how and why; rustdoc covers every type, trait, method, and signature.

• Online (per release): https://docs.rs/lunaris-memory (the umbrella crate is published as lunaris-memory; its library name is lunaris) — built from cargo doc with the documentation feature set (see each crate’s [package.metadata.docs.rs]).
• Locally: cargo doc --workspace --no-deps --open (or make docs-rust).

The lunaris umbrella crate

lunaris re-exports the surface you normally touch. For the common subset, glob-import the prelude:

use lunaris::{EpisodeBuilder, ForgetTarget, Graph, Hit, Keyword, Lunaris, Query, Scope, ScopeSpec, Tree, Vector};
async fn demo() -> Result<(), lunaris::LunarisError> {
use lunaris::prelude::*;
// → Lunaris, ScopedLunaris, Scope, EpisodeBuilder, Query, Hit,
//   Vector, Keyword, Graph, Tree, RetrievalBuilder, ForgetTarget, ScopeSpec,
//   LunarisError, Embedder, HlcClock,
//   Reranker/NoopReranker, Extractor/NoopExtractor,
//   Verifier/NoopVerifier, Consolidator/NoopConsolidator
Ok(())
}

The prelude is intentionally small. Reach into the full re-export list (or the member crates directly) for everything else — extractor/verifier backend structs, the storage concrete (MoonStorage), the recipe types, init_logging, the pipeline handles, etc.

Crate map

lunaris-codegen, lunaris-conformance, and lunaris-bench are internal tooling crates — not part of the public API.

Publishing note. The umbrella crate is published as lunaris-memory (the bare lunaris name on crates.io is taken; the library name stays lunaris, so the import path is unchanged). lunaris-storage-moon depends on moondb from crates.io (version-pinned), so the workspace is crates.io-publishable; the [package.metadata.docs.rs] blocks are wired so docs.rs builds the right feature set.

Error Taxonomy

Every public lunaris API returns Result<_, LunarisError>. LunarisError is one umbrella enum with a sub-enum per subsystem; the HTTP server maps each variant onto a status code (see Protocol → MemoryProtocol 0.1).

Source: crates/lunaris-core/src/error.rs.

LunarisError (umbrella)

#[non_exhaustive] — always include a wildcard arm when matching; new subsystems can be added in a patch release.

Sub-enums

StorageError

ExtractError

Timeout (the extractor model didn’t answer in budget) · GrammarReject(String) (the model’s output failed the constrained-decoding grammar) · Backend(String).

ValidateError

RetrieveError

OperatorFailed(String) (an operator in the retrieval tree errored) · Backend(String).

ConsolError

ActivationUnderflow (ACT-R base-level activation went negative — a calibration bug) · Backend(String).

HTTP mapping (lunaris-server)

A handful of statuses are produced by handler-local validation rather than map_error — these are not LunarisError variants:

The auth / rate-limit middleware emits 401 / 403 / 429 before the LunarisError → status map runs (crates/lunaris-server/src/middleware/error.rs::map_error); that map only covers business-logic errors. map_error also increments lunaris_error_total{kind=…} for every error it handles.

The wire-level error body shape is specified in MemoryProtocol 0.1.

Running the HTTP Server

Reach for lunaris-server when an agent harness — or a non-Rust service — needs to talk to a shared Lunaris memory engine over HTTP/SSE instead of linking the crate. It is the reference implementation of MemoryProtocol 0.1: an axum 0.8 binary exposing the blueprint verbs plus a Prometheus /metrics endpoint.

The crate is lunaris-server; config lives in crates/lunaris-server/src/config.rs. The full env-var / feature-flag matrix is in the Configuration Reference — this page covers operating the binary.

Quick start

cargo build -p lunaris-server          # → target/debug/lunaris-server

LUNARIS_STORAGE=moon://localhost:6380 \
LUNARIS_TOKENS_FILE=/etc/lunaris/tokens.json \
  target/debug/lunaris-server --bind 127.0.0.1:8080

On startup the binary prints its bound address to stderr as LISTENING_ON <addr> (e.g. LISTENING_ON 127.0.0.1:8080) — the conformance subprocess runner parses this; see crates/lunaris-server/src/main.rs. Then probe it:

curl -s localhost:8080/healthz                                  # {"ok":true,"version":"0.2.1"}  (version = CARGO_PKG_VERSION)
curl -s localhost:8080/readyz                                   # {"ready":true,"version":...,"checks":{"ping":"ok","canary":"ok","embedder":"ok"}}
curl -s -H 'Authorization: Bearer <token>' \
     -H 'Content-Type: application/json' \
     -d '{"source":"demo","content":"Alice loves chocolate."}' \
     localhost:8080/v1/ingest

Configuration

Every flag has a matching LUNARIS_* env var (12-factor; CLI flag wins over env). Source: crates/lunaris-server/src/config.rs.

The same LUNARIS_EMBEDDER_DIR / LUNARIS_EMBEDDER_GGUF / LUNARIS_GRAPH_ENABLED / verifier / consolidator env vars that Lunaris::open reads also apply here — see Configuration Reference §2.

The bearer-token map (LUNARIS_TOKENS_FILE)

A JSON object mapping opaque bearer tokens to a tenant id + scope set (CONTEXT.md D-07):

{
  "<opaque-bearer-token>": { "tenant": "acme",   "scopes": ["ingest", "recall", "forget"] },
  "<another-token>":       { "tenant": "globex", "scopes": ["recall"] }
}

• tenant is the partition scope for the token (typed and validated as a Scope) — the only source of truth for it. Route handlers consume the token-bound scope and ignore any scope / tenant field on the request body; every public DTO carries #[serde(deny_unknown_fields)], so a request body that contains such a field is rejected outright (HTTP 422).
• scopes is the verb-permission set for the token — which of ingest / recall / forget it may call. A request whose route requires a verb the token doesn’t carry → 403 Forbidden.
• A missing or invalid token → 401 Unauthorized.

Heads-up on forget under real scopes. In v0.2.x, Lunaris::forget still routes through Scope::dev() internally for its atomic_write / read_as_of / scan_range calls — a forget issued under any non-_dev_ scope silently returns rows_written = 0, rows_deleted = 0 (the Moon SCAN prefix filters everything out). It emits a tracing::warn! on every call. The real per-scope routing — ScopedLunaris::forget(target) with a 403/404 cross-scope contract — is a v0.3 deliverable (RFC 0001 §11.6, CHANGELOG.md “Known issues”). See Forgetting and docs/migration/0.1-to-0.2.md §10.2.

Endpoints (operational view)

The wire spec is MemoryProtocol 0.1; the operational summary:

Liveness vs readiness

Wire them to the matching Kubernetes probes — they answer different questions and have different remedies:

/readyz runs three checks, each bounded at 2 s, and reports them individually in checks:

1. ping — StoragePort::health_check (Moon PING);
2. canary — a KvPut + KvDelete of the fixed reserved key lunaris:__health__:canary in the reserved __health__ scope;
3. embedder — the embedder is configured with a usable dimension. This is a structural check: a probe must never run inference, because a wedged ggml pool cannot be cancelled and the probe itself would wedge.

The canary check is the point of the endpoint. Both production wedges we have hit (the MA1 write-stall, the dashtable recovery crash-loop) answered PING happily while refusing every write, so a PING-only probe kept traffic flowing into a store that could not accept a byte. A canary of timeout is that exact signature. Note that liveness deliberately stays green in that case: restarting the process does not un-wedge the backend, it just adds a cold start to the incident.

Readiness results are cached for 5 s and probes single-flight, so at most one canary write reaches the store every 5 s regardless of probe rate — probe traffic can never become write traffic. lunaris_ready (1/0) exports the last verdict for alerting.

$ curl -s localhost:8080/readyz | jq
{ "ready": true, "version": "0.6.0", "checks": { "ping": "ok", "canary": "ok", "embedder": "ok" } }

Request timeout, concurrency limit and load shedding

Applied to every route (probes included), outside the per-route auth / rate-limit stack:

• a request that exceeds --http-timeout-secs is cut off with 408 and the {error:"request_timeout"} envelope, and counted in lunaris_http_timeout_total. The budget covers producing the response, not streaming its body — an SSE /v1/recall stream is never severed mid-flight;
• a request arriving while --http-concurrency requests are already in flight is shed with 503 + Retry-After: 1 and the {error:"overloaded"} envelope, counted in lunaris_http_shed_total. It is never queued: queueing in front of a slow backend is how a latency blip becomes an OOM.

Order on the request path is CORS → load-shed(concurrency) → in-flight gauge → timeout → auth/rate-limit → handler, so the worst-case backlog is bounded by --http-concurrency × --http-timeout-secs rather than by client patience. Rationale for that order lives in crates/lunaris-server/src/middleware/resilience.rs.

Rate limiting

Per-tenant, applied to every /v1/* request (key = the tenant claim). Exceeded → 429 Too Many Requests with a Retry-After: <seconds> header. Un-authenticated routes (/healthz, /metrics) are not rate-limited.

Metrics

/metrics exposes (Plan 05-05; CONTEXT.md D-25):

Time-series count grows linearly with tenant count (the tokens-file map size), not with traffic. Content-Type is the standard text/plain; version=0.0.4; charset=utf-8.

Deployment notes

• Stateless process. Every byte of durable state lives in the backend; the server holds nothing on disk. Scale horizontally; restarts are free. See Durability & Recovery.
• Graceful shutdown. On SIGTERM/SIGINT the server stops accepting new connections and drains in-flight requests for at most --shutdown-grace-secs (default 30 s) before exiting. The window is a ceiling, not a sleep: an idle server exits in milliseconds. If the window expires the server logs WARN shutdown grace window expired; abandoning in-flight requests aborted_in_flight=<n> (n from the lunaris_http_in_flight gauge) and exits anyway — so a wedged backend can no longer pin the process until the orchestrator escalates to SIGKILL. Set your orchestrator’s termination grace period a few seconds ABOVE --shutdown-grace-secs.
• HTTP-only image. A cargo build --no-default-features -p lunaris build links neither the native embedder nor the reranker stack — useful when the server uses the Ollama HTTP escape hatch (--features embed-remote, LUNARIS_EMBEDDER_OLLAMA_URL) and you want a small image.
• TLS / OAuth. v0 is plain HTTP with opaque bearer tokens; terminate TLS and do OAuth2/OIDC issuance at a reverse proxy. Managed-cloud JWT issuance is a v1 gate (DEPLOY-V1-01).
• Errors. The HTTP status ↔ LunarisError mapping lives in crates/lunaris-server/src/middleware/error.rs::map_error; the full table is in the protocol spec and Error Taxonomy.

See also

• MemoryProtocol 0.1 — the wire spec
• Conformance — certifying a server
• The Storage Backend — Moon setup and its honest limits
• Configuration Reference — every flag/var

The Storage Backend (Moon)

As of 0.7.0 Lunaris ships exactly one StoragePort implementation: Moon, the Redis-compatible substrate. Lunaris::open(url) accepts one scheme, moon://host:port; every retired spelling (postgres://, postgresql://, memory://, sqlite:///path) was removed in 0.7.0 and returns UnsupportedScheme carrying the migration link rather than half-working.

If you are on 0.6.x with a Postgres or SQLite store, migrate before you bump the pin — the exit ramp is lunaris-migrate, built from the v0.6.2 tag. See 0.6 → 0.7.

What Moon provides

The StorageCapabilities report the backend returns still drives capability-gated behaviour (graph mode, native vs client RRF, queue mode). It is no longer a portability mechanism — with one backend it is how the engine learns what this Moon build supports, and it is what the STORE-07 refusal below is derived from.

STORE-07 — no historical KV reads

Moon has no per-key version chain, so read_as_of cannot walk one. supports_historical_kv_reads() returns false and the call refuses rather than silently answering with today’s value — a wrong answer to “what did the agent know at T?” is worse than a named error. Through 0.6.x this was the one capability Postgres/SQLite had that Moon did not; with those backends gone it is a flat limitation of 0.7.0, pinned by lunaris_conformance::storage::read_as_of and the run_as_of_moon_gap test.

Time-travel over search and graph results is unaffected and native.

About the embedding dimension

Moon has no hard vector-dimension limit — FT.CREATE only requires DIM > 0. The adapter creates its chunks (and entities / facts / communities) FT indices at the configured embedder’s dimension: Lunaris::open(url) reads embedder.dim() and calls MoonStorage::connect_with_dim(url, dim), so a 1536-d embedder (OpenAI text-embedding-3) works out of the box. The default is 768-d (granite-embedding-311m-multilingual-r2); max_vector_dim in StorageCapabilities reports whatever dimension the index was actually created at.

Operator footgun. FT.CREATE is idempotent and does not resize an existing index. If a Moon instance already holds a 768-d chunks index and you reopen with a wider embedder, the old index stays and the mismatch only surfaces on the first vector write — drop the stale index (FT.DROPINDEX <name>) first. Wider vectors remain a latency trade-off (more bytes/vector, more distance-compute per query), not a capability boundary.

Moon setup

docker run -d --name lunaris-moon -p 6380:6379 \
  ghcr.io/pilotspace/moon:0.8.5 \
  --shards 1 --protected-mode no --appendonly yes

Two flags are load-bearing:

• --shards 1 is mandatory. A Lunaris ingest is one MULTI/EXEC transaction, and a sharded Moon rejects cross-shard writes — every ingest fails. The image defaults to --shards 0 (auto-detect), so the flag has to be passed explicitly.
• --appendonly yes is what makes the store survive a restart.

There is no schema migration and no role bootstrap. Per-scope keyspaces, FT indices, GRAPH keys, and MQ topics are created lazily on the first atomic_write per scope, so the first write for a new scope is slightly slower and subsequent writes hit the warm index.

Before you trust the data on disk, read Durability & Recovery — the short version is: enable AOF (--appendonly yes --appendfsync always) and ensure a base RDB exists via BGREWRITEAOF (not BGSAVE).

Full production setup — memory limits, backups, health probes, systemd/launchd units — is in Running an external Moon.

See also