MNEMONIC

Memory that learns what matters.

MNEMONIC is a local-first memory system for AI agents. It builds a persistent, queryable knowledge graph from agent interactions and runs fully offline — no cloud dependency.

Unlike vector databases or simple memory logs, MNEMONIC builds a structured graph of decisions, errors, and outcomes — allowing agents to learn what actually works over time.

Instead of losing context every run, your agent builds memory as it works:

Demo

1. Store a memory

mnemonic_store(
    content="We decided to use SQLite for storage",
    event_type="decision",
    project="mnemonic"
)

2. Query memory

mnemonic_query("What database are we using?")

Result:

• Returns the stored decision
• Includes related context from the knowledge graph
• Prioritizes memories that previously led to successful outcomes

3. Visualize the graph

This is one of MNEMONIC's core features — a live view of how memory evolves over time.

Run:

python -m mnemonic.ui.daemon

Then open http://localhost:7437.

You'll see:

• Connected memories
• Relationships between decisions, errors, and lessons
• A live view of how the system "thinks"

4. Real-world workflow

Agent → stores decisions + errors → builds graph → queries → improves over time

Each interaction compounds:

• Better recall
• Better decisions
• Fewer repeated mistakes

Example

An agent fixes a bug, stores the solution, and the next time a similar error appears:

• It recalls the previous fix
• Applies it instantly
• Avoids repeating the same mistake

No prompt engineering. No retries. Just memory.

Use Cases

• Long-running coding agents that need persistent memory across sessions
• AI assistants that improve by remembering past decisions
• Debugging systems that track errors and successful fixes
• Autonomous workflows that get better with each run

Why MNEMONIC

• Local-first: your data never leaves your machine
• Structured memory: not just embeddings, but relationships
• Designed for agents: built for real autonomous workflows

Three Competitive Edges

• Edge 1: Outcome-Aware Retrieval — XGBoost reranker trains on retrieval-to-outcome signal (Phase 7)
• Edge 2: Compositional Recall — synthesizes derived insights across memory clusters (Phase 6)
• Edge 3: Query-Type Routing — each query type gets optimised retrieval physics (Phase 3)

Requirements

• Python 3.11+
• pip install -e ".[dev]"
• Models download automatically on first use and are stored at ~/.mnemonic/models/

Claude Desktop quickstart

1. Install

pip install -e ".[ui]"
mnemonic-init      # merges mcpServers.mnemonic into claude_desktop_config.json
mnemonic-ui        # optional: start the Graph UI daemon (http://localhost:7437)
mnemonic-doctor    # optional: read-only health check

mnemonic-init is safe to re-run: it parses the existing config first, writes a timestamped .bak-* backup, merges atomically, and refuses to run while Claude Desktop is open.

2. Paste the Agent Contract v2 into Custom Instructions

MNEMONIC's Desktop workflow relies on the agent knowing it must call mnemonic_workspace(...) once per session and pass cwd=... on every mnemonic_store. That behaviour is defined by the Agent Contract v2 in CLAUDE.md (the ## Agent Contract (v2) section). Claude Desktop needs to see it.

Source of truth: CLAUDE.md, the whole ## Agent Contract (v2) section up to (but not including) the next ## heading.

Three equally valid ways to get it:

• Option A — let the installer print it. mnemonic-init reads CLAUDE.md at runtime and echoes the contract between two banner lines in its output:

  === PASTE THE FOLLOWING INTO CLAUDE DESKTOP ===
  Settings → Profile → Custom Instructions (or the Knowledge pane
  of the Project you want MNEMONIC wired up in):
  
  ## Agent Contract (v2)
  ...
  

  Copy everything from ## Agent Contract (v2) to the blank line immediately before the installer's final "Done. Restart Claude Desktop..." line.

• Option B — extract directly from CLAUDE.md. Open the file, select from the ## Agent Contract (v2) heading to the line immediately before the next top-level ## Research Sources heading, copy, paste.

• Option C — one-liner to copy to clipboard (Windows PowerShell):

  (Get-Content CLAUDE.md -Raw) `
    -replace '(?s).*?(^## Agent Contract \(v2\).*?)(\r?\n## Research Sources.*)','$1' `
    | Set-Clipboard

  Equivalent on macOS:

  awk '/^## Agent Contract \(v2\)/{f=1} /^## Research Sources/{f=0} f' CLAUDE.md | pbcopy

Where to paste it in Claude Desktop:

1. Open Claude Desktop.
2. Click your avatar (bottom-left) → Settings.
3. Profile tab → scroll to "What personal preferences should Claude consider in responses?" — this is the Custom Instructions box.
4. Paste the whole ## Agent Contract (v2) … section.
5. Save.

Alternative: if you only want MNEMONIC behaviour in one specific project, paste the contract into that Project's Knowledge pane instead of global Custom Instructions.

3. Restart Claude Desktop, then sanity-check

Fully quit Claude Desktop (File → Quit — not just Close Window) and relaunch it. Start a fresh chat and ask:

"What is AGENT_CONTRACT_VERSION?"

If the answer is 2, the paste landed. If it's 1 or "I don't know," verify you're in the right Profile / Project and try again.

4. Use MNEMONIC

In any new chat, tell Claude:

"I'm working in C:\Users\you\code\your-repo." (use the absolute path to your repo)

Claude calls mnemonic_workspace(<path>) once to confirm the workspace, echoes a single-line confirmation, then passes cwd=<same path> on every subsequent mnemonic_store call — so every memory carries full git provenance (branch, commit_sha, dirty, file_paths).

Start mnemonic-ui in a second terminal if you want to watch memories land in the graph in real time.

Run MCP Server (manually, or under Claude Code)

python -m mnemonic.mcp.server

For Claude Code CLI:

claude mcp add mnemonic -- python -m mnemonic.mcp.server

Launch Graph UI

pip install -e ".[ui]"
mnemonic-ui

Opens an interactive graph visualization at http://localhost:7437.

Run Tests

pytest tests/ -v

Security & Privacy

MNEMONIC is local-first by design.

• No telemetry. Nothing is reported back to MNEMONIC or any third party.
• No external API calls during runtime. All inference — embeddings, reranking, outcome scoring — runs on-device via ONNX Runtime.
• Models downloaded once from HuggingFace Hub (BAAI/bge-small-en-v1.5, cross-encoder/ms-marco-MiniLM-L-6-v2) on first use, then cached locally at ~/.mnemonic/models/.
• All data lives at ~/.mnemonic/ — the SQLite database, model cache, and any logs. Nothing leaves your machine.

To report a vulnerability, see SECURITY.md. Do not open public issues for security reports.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, code standards, and the PR workflow.

License

MIT License — see LICENSE.