本记为器求序会

1. Install

pip install 'mnemostack[mcp]'

Run a local Qdrant for the vector store:

```bash

tag rule: match your installed qdrant-client - same major, minor within 1

docker run -p 6333:6333 qdrant/qdrant:v1.18.3

Optional: run Memgraph for graph-backed memory:

Setup and usage details

Try it in 30 seconds (Docker)

Fastest way to kick the tyres. No Python install, no manual Qdrant / Memgraph setup.

```bash git clone https://github.com/udjin-labs/mnemostack && cd mnemostack cp README.md examples/notes/ # any markdown will do GEMINI_API_KEY=your-key docker compose -f examples/docker-compose.yml up -d --build

Installation

```bash

tag rule: match your installed qdrant-client - same major, minor within 1

docker run -p 6333:6333 qdrant/qdrant:v1.18.3

Optionally a Memgraph for the knowledge graph:

Quickstart: agent memory over MCP

The fastest on-ramp is the MCP server — it gives Claude Desktop, Claude Code, Cursor, ChatGPT, or another MCP-capable agent durable memory in a few commands. Building an app instead of wiring up an agent? Use the HTTP API or the Python library over the same collection.

Use cases

Agent and chatbot memory (flagship):

• Long-running coding agents that need to survive compaction and session restarts.
• Chat assistants and conversational bots that remember a user's earlier messages, preferences, and decisions across sessions — scope each user's memory with payload filters so one user never sees another's history.
• Personal assistant memory for preferences, recurring tasks, and long-horizon context.
• Multi-agent context sharing through one durable memory backend.
• Session compaction recovery when the useful details no longer fit in the prompt.

Beyond agents — the same engine as a retrieval backend:

• A searchable knowledge base in memory: ingest your docs/notes/FAQ once, then serve hybrid search or grounded answer() (with confidence and source citations) over it from the CLI, HTTP, or library.
• RAG over mixed corpora (code, docs, transcripts) where exact-token and temporal recall beat pure vector similarity.
• Multi-tenant or per-user knowledge stores — payload filters isolate each tenant's data inside every retriever, or enable service-key auth (serve --auth) for a hard, key-resolved tenant boundary with optional per-tenant quotas (see the HTTP API).
• Time-aware search and knowledge bases — "what changed last week", point-in-time graph facts, freshness-weighted ranking.
• Team or project knowledge recall across docs, notes, tickets, and chat history.

CLI quick start

```bash

Environment

Only the providers you actually use need their keys. HuggingFace local-GPU embeddings need no keys at all. mnemostack init writes the same settings as YAML; explicit CLI flags override config/env defaults.

Optional extras

pip install 'mnemostack[huggingface]' # local GPU embeddings pip install 'mnemostack[mcp]' # MCP server pip install 'mnemostack[dev]' # tests + linters

Run a local Qdrant for the vector store:

Optional: synthesize a concise answer

gen = AnswerGenerator(llm=get_llm("gemini")) answer = gen.generate("what did we decide", results) print(answer.text, answer.confidence, answer.sources)

**Count and "list all X" questions** need set completeness, which similarity top-K does not guarantee — the model counts what it sees and undercounts, returning a subset. For those, retrieve a wide candidate pool and enable the two-pass extract-and-aggregate mode:

`list_extract_mode` routes count/list questions through an extract pass (pulls every matching item as JSON) and a finalize pass (formats the list or count); other question categories are unaffected. The extract pass walks the **whole pool you pass in**, in batches of `list_extract_batch_size` (default 40), merging items across batches — so pool order does not decide whether a memory is seen, and the cost is one LLM call per batch plus finalize. An empty extract over a non-empty pool is retried once before abstaining. For guaranteed exhaustiveness on a bounded slice, build the pool from a full scan (`VectorStore.scroll`) filtered to the relevant slice. To evaluate it on your own data, the benchmark harness exposes the same knobs: `benchmarks/locomo_single.py --list-extract --pool 150`.

`list_finalize="verbatim"` skips the finalize LLM pass and assembles the answer deterministically from the extracted items (the count for count questions, the comma-joined items otherwise). Recommended for non-English corpora: an LLM finalize pass can paraphrase or distort items instead of repeating them verbatim. The default `"llm"` keeps the formatting pass.

**Enriching payloads at ingest.** `Ingestor(enrich=callable)` calls your function for every final item (including assembled window chunks) and merges the returned dict into the chunk payload — the mechanism is core, the extractor is yours (content extraction is corpus- and language-specific, so mnemostack ships none). Fail-open: a raising hook logs a warning and the item is indexed without enrichment; `text`/`source`/`offset` and an explicit item timestamp can't be overridden. From the CLI: `mnemostack index docs/ --enrich mypkg.extractors:invoice_fields`. Enriched fields combine with the rest of the stack: scope recall with `filters={"amount": {"gte": 100}}` and show them to the answer LLM with `context_fields=["amount"]`.

ing = Ingestor(embedding=emb, vector_store=store, enrich=invoice_fields)

Already-indexed collections don't need re-embedding to pick up enrichment: `mnemostack index docs/ --enrich ... --refresh-payloads` rewrites the payloads of existing chunks in place (Qdrant `set_payload`, vectors untouched) — only genuinely new chunks pay for embedding.

**Structured payload fields in the answer prompt.** By default the answer context shows each memory's timestamp, source and text. `AnswerGenerator(context_fields=["author", "amount"])` additionally projects the named payload fields into each memory's context line (`author=…`, lists comma-joined, long values truncated; memories without the field render without it). Use it for structured facts the answer needs — who said it, amounts, your own ingest-time enrichments. Note the boundary: projection only changes what the answer prompt *shows* — retrieval ranks by `text`, so content that must be *findable* (image captions and similar) belongs in the text itself, not in a payload field.

**Conversational follow-ups.** "And who wrote that?" carries none of the conversation, so recall misses. `rewrite_followup(query, history, llm)` resolves pronouns and ellipses into a standalone question before recall — mnemostack holds no dialog state, you pass the history (`(question, answer)` pairs or plain lines, oldest first). One LLM call; the prompt instructs the model to return a self-contained question unchanged, and any failure falls back to the original query. To skip the call entirely for queries you already know are standalone, pass `needs_rewrite=callable` — that trigger heuristic is language-dependent, so core ships none (same boundary as `question_classifier`).

standalone = rewrite_followup("а кто это написал?", history, llm) results = recall_flow(recaller, standalone, limit=10, pipeline=pipeline)

**Non-English corpora.** The built-in answer prompts and the question classifier are English; on other languages the extract/finalize passes degrade instead of helping. Both are pluggable:

HTTP server (optional)

If you want mnemostack available to callers that aren't Python — any service written in Node, Go, Rust, or a plain curl from a shell script — install the server extra and expose it over HTTP:

pip install 'mnemostack[server]'
export GEMINI_API_KEY=...
mnemostack serve --provider gemini --collection memory --port 8000

mnemostack serve binds to 127.0.0.1 by default. Use --host 0.0.0.0 only behind your own auth/rate-limit layer.

Endpoints:

curl -s http://localhost:8000/recall \
    -H 'content-type: application/json' \
    -d '{"query": "what did we decide about auth", "limit": 10}' | jq

Response shape (abridged):

{
  "query": "what did we decide about auth",
  "results": [
    { "id": "...", "text": "...", "score": 0.72, "source": "notes/...md", "metadata": {} }
  ],
  "degraded": [],  // components that ACTUALLY fell back, e.g. "retriever:bm25:failed", "reranker:fallback"; empty when healthy
  "notes": [],     // routine signals for stages that did not apply, e.g. "temporal:no_parse" on a date-less query; never a fault
  "tokens_estimate": 512   // estimated text tokens of the returned results
}

The order of results is authoritative — do not re-sort by score: many stages and fallback paths write that number on different scales, and a rerank changes the order without rewriting it. See what score is not.

Pass "include_trace": true in the request body to additionally get a trace object with per-retriever ranked lists, the fused order, and the post-rerank order — useful when debugging why a memory did or didn't surface.

Pass "token_budget": 2000 to cap how much prompt space the results may occupy: the final ranking is cut to the prefix whose total text tokens fit the budget (a hard cap — never overshot, so an oversized top hit yields an empty list rather than a blown prompt). tokens_estimate in the response is the value the budget is enforced against; counting uses a dependency-free heuristic (≈4 chars/token for ASCII, ≈2 for non-ASCII scripts), so leave yourself margin rather than budgeting to the exact context limit. A server-wide default can be set with recall.token_budget in the config file (or MNEMOSTACK_TOKEN_BUDGET); per-request values override it. The same parameter is available on /answer (caps the memories fed to the LLM), on MCP mnemostack_search / mnemostack_answer, on the CLI as --token-budget, and in the library as recall_flow(..., token_budget=...) — where you can also pass an exact token_counter= (e.g. a tiktoken encoder) instead of the heuristic.

Pass "filters": {...} to scope recall by payload fields — exact match ({"tenant": "a"}) or inclusive ranges ({"timestamp": {"gte": "2026-01-01"}}). Filters apply inside every retriever, not as a post-filter on the output: the candidate pool itself is restricted, so top-K stays full and results never include points outside the scope — this is the isolation contract for multi-tenant and per-user memory. Sources that cannot attribute their results to the scope contribute nothing rather than leak. The knowledge-graph retriever attributes its hits where it can: a filter key the hit's own node metadata carries (e.g. index_root) is checked in place, the rest is proven through the hit's vector chunks — a graph file hit (with a recorded root, pinning the probe to its exact document) passes the filter exactly when at least one of its chunks does; entity nodes and anything else without pinnable chunks are still excluded, never leaked. The same filters parameter is available on /answer (the answer is generated only from in-scope memories, including retry sub-recalls), on MCP mnemostack_search / mnemostack_answer, on the CLI as --filters '{"tenant": "a"}', and in the library as recaller.recall(query, filters=...) / recall_flow(..., filters=...).

The /answer endpoint adds { answer, confidence, sources } alongside the memories and carries the same degraded / notes / opt-in trace fields, plus tokens_used — the LLM provider's reported token usage for the generation call that produced the answer (provider-specific semantics; null when the provider reports nothing). If the LLM isn't configured, /answer returns 503 and /recall still works — graceful degradation applies at the HTTP layer too.

Start the server with --retry-on-weak if you want a recall that comes back nearly empty to be paraphrased by the answer LLM and asked again, fusing the rounds by reciprocal rank — so a memory that two phrasings both find outranks one that only a single phrasing did, and a later paraphrase can beat an earlier one. What counts as "weak" is a COUNT (--retry-weak-below, default 1 — only a recall that returned nothing), not a score: fused scores are RRF values encoding rank, not confidence, so a threshold on them would measure nothing. One extra round, at most two paraphrases, and every retry carries the caller's tenant, filters, validity view and budget unchanged. Budget for it accordingly: each variant repeats your recall in full, reranker included, so a weak recall costs up to three LLM calls (one paraphrase plus one rerank per variant) and two extra retrieval rounds — not the single call the name suggests. Two consequences worth knowing before you switch it on: a retried response fuses over several rounds where an unretried one fuses over a single one, so the rank basis behind

Streaming ingest API

When you want to feed items into mnemostack from code — a chatbot that logs every message, a scraper, a daemon tailing a log — use the Ingestor. It handles batching, deduplication, and idempotency for you.

from mnemostack.embeddings import get_provider
from mnemostack.vector import VectorStore
from mnemostack import Ingestor, IngestItem

emb = get_provider("gemini")
store = VectorStore(collection="my-memory", dimension=emb.dimension)
store.ensure_collection()

ing = Ingestor(embedding=emb, vector_store=store, batch_size=64)

stats = ing.ingest([
    IngestItem(text="alice joined acme on 2024-03-01", source="notes/alice.md",
               timestamp="2024-03-01T09:00:00Z"),  # event time — drives temporal recall
    IngestItem(text="alice left acme on 2025-06-15", source="notes/alice.md", offset=100),
])
print(stats)  # IngestStats(seen=2, embedded=2, upserted=2, skipped=0, failed=0)

Guarantees:

• Idempotent. Each item gets a deterministic UUID-shaped content id computed from (source, offset, text). Re-running with the same input is a no-op: Qdrant upsert replaces the point onto itself, and an in-process LRU cache skips even the embedding call for items already seen in this session.
• Batched. Items are embedded in batches of batch_size, so provider HTTP overhead amortises across many items.
• Dated. Every payload records indexed_at (UTC). Pass timestamp= (or metadata={"timestamp": ...}) to set the event time the temporal retriever filters on. With window_size > 1, sliding-window chunks also carry the window's temporal range as window_start_ts / window_end_ts payload keys.

Images in the input (optional)

A memory stack that indexes only text answers "Not in memory" to questions whose answer lived in a photo. If your data contains images, describe them at ingest time and index the description:

from mnemostack.llm import get_llm

llm = get_llm("gemini")                 # or get_llm("ollama", model="llava") with a local vision model
desc = llm.describe_image(photo_bytes, mime_type="image/jpeg")  # one vision call per image
caption = f" [shared a photo: {desc.text}]" if desc.ok and desc.text else ""
item = IngestItem(text=f"{message_text}{caption}", source=..., timestamp=...)

describe_image is fully opt-in — nothing in the ingest or recall paths calls it, and text-only pipelines are unaffected. It works with any provider that has vision support (Gemini; Ollama vision models such as llava, llama3.2-vision, qwen2.5-vl) — providers without it return a normal fail-open error response. The default prompt produces a dense, index-oriented description (objects, any text/signs verbatim, setting, actions); pass prompt= to customize. - Streaming-friendly. ing.stream(item_iter) yields per-batch stats so long feeds can be monitored without waiting for the whole stream to drain. - Graceful. If a single item fails to embed, it is counted as failed but the rest of the batch still lands.

```python

Long-lived feed (e.g. inside a FastAPI or Celery worker)

for item in your_firehose(): ing.ingest_one(IngestItem(text=item.body, source=item.channel, metadata={ "user_id": item.user_id, "ts": item.ts.isoformat(), })) ```

Python API

```python from mnemostack.embeddings import get_provider from mnemostack.vector import VectorStore from mnemostack.recall import Recaller, AnswerGenerator from mnemostack.llm import get_llm

emb = get_provider("gemini") store = VectorStore(collection="my-memory", dimension=emb.dimension) store.ensure_collection()

confidence; re-sorting by it undoes reranking. docs/api-stability.md#what-score-is-not

Pipeline state

The 8-stage pipeline can use a small state store between calls (Q-learning weights, inhibition-of-return history, per-document gravity/hub counters). FileStateStore(path) persists it to a JSON file. HTTP recall applies existing state and can record inhibition-of-return exposure with --auto-record-ior; Q-learning updates only through explicit /feedback calls. CLI/MCP recall still apply existing state but do not collect feedback automatically. For deterministic benchmarks, call build_full_pipeline(enable_stateful_stages=False) so IoR/Q-learning/curiosity state cannot affect scores. For multi-process servers, implement your own StateStore (three methods: get(), set(), update()) backed by Redis or your database.

Record explicit feedback into the same state file used by the HTTP/MCP pipeline

mnemostack feedback <hit-id> --signal clicked --query "what did we decide about auth" \ --source-list vector --source-list bm25

Comparison and benchmarks

On LoCoMo, Mnemostack reaches 82.9% strict accuracy in our evaluation setup. The table below includes our baseline runs and externally reported numbers for context. Results depend on dataset version, configuration, judge model, scoring rules, and query type. Treat externally reported numbers as directional unless they were run with the same harness and settings.

Comparison with reported numbers from other systems

Caveat: different judges, evaluation protocols, and in some cases category cherry-picking. Vendor numbers below are taken at face value from their published material.

Index the notes volume and ask a question over HTTP

docker compose -f examples/docker-compose.yml exec mnemostack \ mnemostack index /data --provider gemini --collection demo

curl -s http://localhost:8000/recall \ -H 'content-type: application/json' \ -d '{"query":"what is this about","limit":5}' | jq

The mnemostack container runs the HTTP API on port 8000 by default. Interactive docs are at [http://localhost:8000/docs](http://localhost:8000/docs). Use `docker compose exec mnemostack mnemostack <cmd>` for CLI-style operations (`index`, `search`, `health`) against the same stack.

Tear down with `docker compose -f examples/docker-compose.yml down -v` (the `-v` wipes Qdrant + Memgraph state).

Prefer Ollama (no cloud key needed)? Run Ollama on the host and pass `--provider ollama` everywhere instead of `gemini`. The endpoint resolves as: `--ollama-host` flag > `MNEMOSTACK_OLLAMA_HOST` env / `embedding.ollama_host` config > the native `OLLAMA_HOST` variable > `http://localhost:11434` — so a client running in a container or VM can reach a remote Ollama daemon directly. An ollama **LLM** follows the same chain and inherits the embedding host by default; set `llm.host` / `MNEMOSTACK_LLM_HOST` only when generation lives on a different box:

Embedding uses the batch `POST /api/embed` endpoint (one request per batch; servers too old for it are detected once and served per-item with a loud warning). The embedding timeout (`--embedding-timeout` / `MNEMOSTACK_EMBEDDING_TIMEOUT`, default 180s) is independent of the short Qdrant liveness timeout — cold loads of larger local models are legitimately slow. Vector dimensions come from the model tables (quantization-suffix aware) or, for unknown models, a one-shot probe of the live model — there is no blind fallback dimension, so a wrong-size collection can't be created.

**Behind an OpenAI-compatible endpoint** (LiteLLM proxy, vLLM, llama.cpp server, an API gateway)? Use the `openai` LLM provider — it speaks `POST {base}/v1/chat/completions`, which all of them accept:

with llm.host: http://gateway:4000 in the config (or MNEMOSTACK_LLM_HOST). Both the base URL and the model name are required — gateways have no meaningful defaults, so a missing one is a loud, actionable error (serve logs it and disables /answer) instead of a silent dial to the wrong place. A base URL already ending in /v1 (the OpenAI SDK convention) works too. Leave the key unset (or set it to none) for keyless vLLM / llama.cpp deployments; embeddings are unaffected and keep their own provider. Redirects are refused outright — a gateway 3xx becomes a normal error instead of carrying the bearer token to another origin. Reasoning models pointed straight at the cloud OpenAI endpoint (o1 family) reject the classic fields; via the SDK, get_llm("openai", token_param="max_completion_tokens", options={"temperature": None}) renames the budget field and drops the fields they refuse (gateways normally translate this themselves).

Reasoning models (qwen3, deepseek-r1 and similar): mnemostack disables thinking by default (think=False in OllamaLLM) — with thinking on, these models spend the whole token budget on thoughts and return empty text, silently degrading reranking, expansion and extraction. Pass get_llm("ollama", think=None) to keep the model's own default, or think=True to force it on models that support thinking. Extra generation options go through options={...} (e.g. {"num_ctx": 8192}).

the classifier's patterns are English too — route question classes yourself:

answer = gen.generate(query, pool, category="count")

Override names: the seven category prompts (`general`, `list`, `count`, `temporal`, `multihop`, `inference`, `adversarial`) plus `list_extract` / `list_finalize`. Required placeholders are validated at construction. mnemostack ships no translations by design — prompt quality is corpus- and domain-specific, so you own the templates.

#### Full stack: 4-source retrieval + 8-stage pipeline + reranker

This is the full runtime configuration. The LoCoMo numbers above are produced by a subset of it: the benchmark loop runs Vector + BM25 retrieval, the 8-stage pipeline, `window_size=3`, query expansion, and top-K 25 — the LLM reranker and the graph retriever are runtime-only features and are not part of the benchmark methodology (see `benchmarks/run_locomo.sh` for the exact reproduction path).

emb = get_provider("gemini") store = VectorStore(collection="my-memory", dimension=emb.dimension)

retrievers = [ VectorRetriever(embedding=emb, vector_store=store), BM25Retriever(docs=bm25_docs), # see "Building a BM25 corpus" below MemgraphRetriever(uri="bolt://localhost:7687"), # optional TemporalRetriever(embedding=emb, vector_store=store), ] recaller = Recaller(retrievers=retrievers) raw = recaller.recall("what did we decide", limit=30)

pipeline = build_full_pipeline(state_store=FileStateStore(default_state_path())) reranked = pipeline.apply("what did we decide", raw) reranker = Reranker(llm=get_llm("gemini"), max_items=20) final = reranker.rerank("what did we decide", reranked)[:10]

`Reranker` is generative: it asks an LLM to return candidate IDs. If you have
a backend that returns numeric relevance scores instead (a local cross-encoder
or a hosted rerank service), use `ScoringReranker`:

scoring_reranker = ScoringReranker(scorer=my_relevance_scorer, max_items=100) final = scoring_reranker.rerank("retention policy", reranked)[:10]

The scorer object only needs `score(query, documents) -> Iterable[float]`.
Scores are relative; no absolute threshold is applied by default. Generative
LLMs can be wrapped as scorers, but dedicated rerank models/services are the
more stable default because they avoid ID-format parsing.

##### Building a BM25 corpus

`BM25Retriever` needs a list of `BM25Doc`. Each doc is the atomic unit BM25 will rank — typically a paragraph or chunk of one of your source files:

docs = [] for i, path in enumerate(Path("my-notes/").rglob("*.md")): text = path.read_text() # chunk however you like — here: 800-char windows for j in range(0, len(text), 800): chunk = text[j : j + 800] if chunk.strip(): docs.append(BM25Doc( id=f"{path.name}:{j}", text=chunk, payload={"source": str(path), "offset": j}, ))

For transcript-like inputs (adjacent user and assistant turns), prefer `MessagePairChunker` so related turns stay in the same chunk. See `mnemostack.chunking`.

If your canonical memory corpus is already stored in Qdrant payloads, build the BM25 corpus from the same collection instead of maintaining a separate markdown export. This keeps exact-token lookup aligned with vector search (IDs, commit hashes, filenames, quoted phrases):

client = QdrantClient(host="localhost", port=6333) bm25 = BM25Retriever.from_qdrant( client, "memory", scroll_filter=Filter( must=[FieldCondition(key="chunk_type", match=MatchValue(value="transcript"))] ), limit=40_000, )

hits = bm25.search("api_key_rotation", limit=5)

You can also call `bm25_docs_from_qdrant(...)` directly if you want to combine Qdrant payload chunks with local `BM25Doc`s before constructing `BM25Retriever`.

For morphologically rich languages or domain-specific normalization, pass a
custom tokenizer/analyzer. The same analyzer is applied to corpus and query
text; the default exact-token behavior is unchanged when omitted.

def analyzer(text: str) -> list[str]: # Normalize only what your corpus needs; preserve IDs, hashes and paths. ...

bm25 = BM25Retriever.from_qdrant(client, "memory", tokenizer=analyzer) ```

If you pre-tokenize BM25Doc objects yourself, pass retokenize=False when constructing BM25/BM25Retriever with the same analyzer. The BM25Retriever.from_qdrant(...) helper does this automatically.