mnemostack
Durable hybrid memory for AI agents: vector + BM25 + temporal + graph recall, exposed through MCP, HTTP, and Python.
Install / Use
claude mcp add udjin-labs -- npx -y github:udjin-labs/mnemostackIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Our assessment of mnemostack
mnemostack scores 72/100 on our quality scale, 858th of 947 AI & Machine Learning skills we index.
Its MCP Server is 80 KB long, well organised into 68 sections with 33 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so mnemostack is actively maintained.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
mnemostack compared with similar skills
All 4 of these similar skills score higher than mnemostack; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| mnemostack (this skill)by udjin-labs | 72 | 10 | today | MCP Server |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install mnemostack?
- Run
claude mcp add udjin-labs -- npx -y github:udjin-labs/mnemostack. The install tabs above show the steps for each supported agent. - Which AI agents does mnemostack work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is mnemostack safe to use?
- It is Apache-2.0-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is mnemostack still maintained?
- The repository was last updated today, so mnemostack is actively maintained.
Skill content
View source on GitHubmnemostack
Self-hosted memory and retrieval for agents and applications.
mnemostack keeps context beyond a session, retrieves relevant evidence, and gives you controls for maintaining and operating that memory. Ingest notes, messages, documents, or application events; search them with configurable hybrid retrieval; track when facts were valid and whether their sources still support them. Run it inside your application or as a service with a separate tenant for each consumer.
The Python SDK, CLI, HTTP API, and MCP server are interfaces to the same memory and retrieval components. Agent integrations decide when to capture or recall context; mnemostack provides the backend and its controls.
What you can do with it
| Your task | What mnemostack provides | Start here |
| --- | --- | --- |
| Keep context across sessions | File indexing and streaming ingestion, deterministic chunk IDs, structured markdown, and enrichment hooks | Ingestion |
| Find evidence that fits the question | Vector, lexical, temporal, and optional graph retrieval; fusion, ranking, reranking, and token budgets | Retrieval design |
| Maintain facts as they change | Invalidation, validity intervals and as_of reads, source metadata, and citation resolution against current files | Memory lifecycle |
| Understand a missed result | Per-retriever and per-stage traces, explicit fallback tags, and RecallTrace.loss_report(expected_ids) | Diagnosis and feedback |
| Operate memory for different consumers | Service-key scopes, tenant isolation across vector/graph/learning state, quotas, metering, export, and offboarding | Service operations |
These capabilities have different activation points. The memory model and boundaries distinguish shipped interfaces, optional settings, and SDK components that your application assembles.
Start with your own context
- OpenClaw memory: retain existing notes and connect recall through the companion plugin or an existing recall entry point. The companion adds retrieved context to the agent prompt; ingestion remains a separate operation.
- One personal archive, several agents: index a messenger export once and let your authorized agents query the same backend. The two-local-client walkthrough rehearses shared reads; access from different PCs needs a protected connection to that backend. It does not configure automatic messenger capture or synchronization.
- Local memory for a Hermes agent: use a local mnemostack backend through the agent's memory integration. The separate
hermes-mnemostackprovider is listed in the integration roadmap; its installation and capture behavior belong to that integration, not to the core quickstart. - Workplace infrastructure: serve multiple applications or agents from one deployment, with a separate tenant for each consumer. Use service-key authentication to enforce ownership. Sharing the infrastructure does not imply sharing their context.
The same interfaces also support document RAG, code search, personal knowledge bases, and time-aware application retrieval.
<a id="quickstart-agent-memory-over-mcp"></a>
Quickstart: index, retrieve, inspect
Follow the local quickstart to index one synthetic message with Ollama and Qdrant, retrieve its fact and filename, and optionally generate an answer or connect an MCP client. It keeps one collection and embedding model throughout. The explicitly tested full_reorder setting is a configuration workaround for the selected LLM, not a change to the default reranker.
Choose the interface your application needs after the first retrieval works. Connecting tools alone does not make an agent capture messages or query memory automatically.
Status: Actively developed. See the API stability guide for stable contracts versus experimental components, and CHANGELOG.md for release changes.
Upgrading to 3.0: Qdrant 1.20+ is required. The lexical and
qdrant_bm25 text-search modes and recall.text_search_fields were removed.
For server-side BM25, upgrade Qdrant, run mnemostack text-index with your
collection configuration, and set recall.text_search: native_bm25.
See the 3.0.0 changelog for Python API removals
and the new LLM options environment variable.
Why hybrid memory?
A useful memory query may depend on an exact identifier, a paraphrased decision, a date, or a relationship. Configurable retrieval sources let you combine these signals instead of relying on a single nearest-vector lookup. Traces and source evidence help you check whether the configured path found what your application needed.
Use cases
Use mnemostack when retaining context also requires retrieving, updating, or operating it: agent memory across restarts, a personal archive queried by several clients, grounded answers over documents, or a service with isolated consumers. Choose the corpus, ownership boundary, and ingestion path explicitly. The memory model explains how those choices relate.
<a id="three-ways-to-use-mnemostack"></a>
Interfaces
| Interface | Use it when | Entry point | | --- | --- | --- | | Python SDK | Your application owns ingestion and composes retrieval components | Python API, streaming ingest | | CLI | You import, query, inspect, or maintain a corpus from scripts or a terminal | Local quickstart, CLI reference | | HTTP API | Applications in any language need a running memory service | HTTP server, deployment | | MCP | An agent client needs memory tools in its existing tool protocol | MCP guide, host integrations |
SDK composition is explicit: Recaller.recall() does not automatically build the serving surfaces' full ranking pipeline. CLI search/answer, HTTP, and MCP use the shared recall_flow() chain with their configured components. See defaults and composition.
Architecture
Mental model
Your application or agent keeps its current working context. mnemostack keeps the corpus you explicitly ingest and returns selected evidence when called. Qdrant holds vectors and payloads, optional Memgraph holds temporal relationships, and the ranking state store holds feedback separately from the corpus. An integration decides what to write, when to query, and how to use the results.
Retention, retrieval, and correction are separate actions: storing a fact does not guarantee it will rank first, and marking it stale does not erase it. That separation lets you inspect recall, preserve historical validity, and choose explicit removal policies.
How it works, in one paragraph
Configured retrievers collect candidates from vector, lexical, temporal, and optional graph sources. Reciprocal Rank Fusion combines their ranked lists. The ranking pipeline can adjust the result using exact tokens, freshness, and feedback state; graph resurrection and LLM reranking add further configured steps. The serving chain cuts the final result to the requested limit and optional text-token budget. Answers are an additional LLM synthesis step over retrieved evidence. The response order is authoritative: score is not calibrated confidence and need not sort the response. See the score contract.

Where mnemostack fits
mnemostack is an independent memory and retrieval layer. You can embed its components in an application, expose them through a service, or connect an agent integration. Alongside retrieval, it provides explicit memory lifecycle operations and service controls. Your application still owns conversation state, ingestion decisions, domain-specific extraction, and any automatic policy for reconciling conflicting facts.
Design
See ARCHITECTURE.md for module behavior and the recall chain, the memory model for capabilities and boundaries, and deployment for persistence and operations.
Storage, index, and retrieval layers
- Corpus and indexes: Qdrant stores vectors and payloads; lexical retrieval can use an in-process corpus or configured Qdrant-native text search. Memgraph is optional.
- Retrieval and ranking: configured sources feed fusion and the ranking chain. A token budget bounds returned memory text using the configured counter; it is not a bound on the whole prompt or answer.
- Lifecycle and evidence: idempotent ingest, pruning, invalidation, validity views, and citation resolution give explicit controls over stored information.
- Service operations: authentication and tenant scopes govern consumers; quotas, metering, diagnostics, export, and offboarding support operators.
Pipeline state
Explicit feedback updates Q-learning and exposure state. HTTP exposure/access recording are opt-in; access reinforcement is a bounded bonus, not automatic forgetting. CLI and MCP can use existing state and accept explicit feedback. FileStateStore uses flock so processes on the same host can share a local POSIX state file. Multi-host deployments, network filesystems, and high-write workloads need a suitable shared store or restricted stateful writes; see state persistence.
Graceful degradation
A failed retriever can leave results from other sources, and a failing LLM reranker can leave the pre-rerank order. Inspect degraded together with notes: entries present only in degraded identify actual faults. Request include_trace on HTTP/MCP to inspect the stages. A plausible answer alone does not demonstrate that every component worked.
Query expansion is an exception: misconfiguration or a provider failure before retrieval surfaces as an error. The architecture guide describes the contract.
Comparison and benchmarks
On LoCoMo, Mnemostack reaches 82.9% strict accuracy in the evaluation setup below. These runs measure the specified retrieval-and-answer configuration, not the complete current service: the runtime LLM reranker is excluded, and tenant operations, integrations, and lifecycle policies are not benchmarked by these figures. 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.
Benchmarks
Full LoCoMo runs use the official SNAP-Research dataset (10 samples / 1986 QA) from a clean state. Across the tables below: Strict = exact match, Combined = strict + partial. Counts in cells are correct / total.
Some LoCoMo cat_5 questions have empty ground-truth answers. Under the current scorer, these are counted
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
