README
mnemos
Local-first memory for coding agents that keeps project, workspace, and global context separate.
Mnemos plugs into Claude Code and other MCP hosts, rewrites stale facts instead of appending forever, and compacts raw agent history into durable memory.
Quick start · MCP setup · Codex · Website
What Mnemos Is
Mnemos is a local-first memory layer for coding agents. The v1 target is straightforward:
- safe scoped memory for solo agent workflows
- persistent local storage that survives restarts
- MCP compatibility for Claude Code, Claude Desktop, generic MCP hosts, and documented Codex setup
- biomimetic memory modules under the hood so retrieval stays compact and adaptive instead of append-only
This is not a hosted memory platform, team memory system, or remote sync product in v1.
Public Beta
Mnemos is now in broad public beta. The core engine and onboarding control plane are ready for real coding-agent usage, and the intended setup path is:
pip install "mnemos-memory[mcp]"mnemos ui- Choose a provider and review the local SQLite path
- Apply Claude Code, Cursor, or Codex config from the UI
- Run the built-in smoke check before daily use
If you are coming from an env-var or hand-edited MCP config setup, use the UI's Import Existing Setup action first.
Manual env-var setup is still supported for advanced users, but it is no longer the primary onboarding path. This beta is meant for real users and real workflows, but it is still a beta: use it, stress it, and report where setup, retrieval quality, or host behavior breaks down.
Quick Start
pip install "mnemos-memory[mcp]"
mnemos ui
What the control plane gives you:
- canonical config in
mnemos.toml - optional project override in
.mnemos/mnemos.toml - guided host setup for Claude Code, Cursor, and Codex
- health checks, smoke checks, and a light memory viewer with chunk details
Inspectability entry points:
mnemos inspect <chunk-id>for raw JSON inspection from the CLImnemos inspect <chunk-id> --query "..." --current-scope project --scope-id <repo>to explain why a memory is relevant to a taskmnemos_inspectfor MCP-native hosts- the control plane Memory panel for scope, provenance, revision history, and graph context
Feedback review loop:
- record a retrieval outcome with
mnemos-cli feedback helpful|not_helpful|missed_memory --query "..." [--chunk-id <id>] - review the highest-signal misses or bad recalls with
mnemos-cli feedback-list --event-type missed_memoryormnemos-cli feedback-list --event-type not_helpful - export events for offline eval work with
mnemos-cli feedback-export --format jsonl --output feedback-events.jsonl
For advanced/manual setup, see docs/MCP_INTEGRATION.md.
Why Use This Instead Of Built-In Claude Memory?
Claude Code already has built-in memory. Mnemos is narrower and more explicit:
- repo, workspace, and global memory stay scoped instead of blending together
- retrieval is inspectable, so you can see why a memory came back
- recall and curator form a repeatable workflow instead of silent accumulation
- everything persists in one local SQLite database
What curator is supposed to keep:
- stable repo conventions and tooling expectations
- environment and deployment constraints
- recurring bug causes and the real fix
What curator should skip:
- timestamps and command echoes
- one-off task status
- repetitive "still debugging" style chatter
If you want "memory exists somewhere in the background," Claude's built-in path may be enough. If you want scoped, local, inspectable continuity across coding sessions, Mnemos is the point.
See the side-by-side writeup at docs/demos/claude-code-continuity.md.
Why The Architecture Is Different
Most agent memory tools either keep too much raw transcript or append contradictory facts forever. Mnemos uses a different design: