udjin-labs/mnemostack

> Self-hosted hybrid memory & retrieval for AI apps.
mnemostack is a durable retrieval layer over your own Qdrant (and optional Memgraph): semantic, keyword (BM25), temporal, and graph recall, fused with Reciprocal Rank Fusion and refined by an 8-stage ranking pipeline — with payload filters for multi-tenant isolation, optional LLM answer synthesis (confidence + citations), and an ingest path that enriches and projects structured fields. One recall(query) call, usable as a Python library, an HTTP service, or an MCP server.
**Flagship use case — durable memory for AI agents.** Long-running agents hit the same wall: context gets compacted, sessions restart, useful decisions disappear, and the next run pays the re-orientation tax again. mnemostack gives them a persistent memory layer to query when the context window is not enough — durable, searchable, scoped, and explainable, not just embedded and hoped for.
The same engine backs other retrieval-heavy work: RAG over mixed corpora, multi-tenant or per-user knowledge stores, and time-aware search backends — anywhere pure vector similarity falls short on its own.
**Status:** Actively developed — public API is stable; new functionality lands additively in minor releases. Breaking changes are rare and called out in CHANGELOG.md.
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.
1. Install
Run a local Qdrant for the vector store:
Optional: run Memgraph for graph-backed memory:
2. Start the MCP server
Claude Desktop config example:
Claude will then be able to call mnemostack_search, mnemostack_answer, and graph tools.
3. Store memory
Index a folder of notes, docs, transcripts, or project context:
--recreate drops the existing collection, so it asks for confirmation first; pass --yes to skip the prompt (required in scripts/CI — non-interactive runs without it exit with code 2).
For a running app or assistant, use the streaming Ingestor API shown below to store messages as they arrive.
4. Recall memory
From an agent, ask a memory-style question and let the MCP tools retrieve the right facts.
From the shell, test the same collection directly:
Why hybrid memory?
Vector search answers "what sounds similar?" Real retrieval over a growing corpus needs to answer "what actually matters for this query?" — which takes exact matches, semantic similarity, relationship tracking, recency, user/project scope, and feedback from past recalls. Mnemostack uses hybrid retrieval so recall is reliable instead of embedding roulette. (Agent memory is the most demanding version of this problem, which is why it's the flagship use case.)
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.
Three ways to use Mnemostack
1. **MCP server — for agent users.** Start mnemostack mcp-serve, connect your agent, and use memory tools from the chat/runtime you already use.
2. **HTTP API — for app developers.** Run mnemostack serve and call /recall, /answer, /feedback, the memory write/lifecycle endpoints (/memories, /invalidate, /triples), /health, /metrics, or /docs from any language.