mnemos-memory

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:

1. pip install "mnemos-memory[mcp]"
2. mnemos ui
3. Choose a provider and review the local SQLite path
4. Apply Claude Code, Cursor, or Codex config from the UI
5. 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 CLI
• mnemos inspect <chunk-id> --query "..." --current-scope project --scope-id <repo> to explain why a memory is relevant to a task
• mnemos_inspect for 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_memory or mnemos-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: