mnemo-cortex

Mnemo Cortex

Set up Mnemo Cortex — local-first persistent memory — so the agent can save, recall, and search across sessions.

When to Use

• The agent needs memory that survives session restarts (decisions, fixes, ruled-out approaches)
• Multiple agents on the same machine should share or query each other's memories
• The user wants memory that runs locally with no recurring cost
• The user already has Mnemo Cortex running and wants to wire this agent to it

When Not to Use

• The user only needs in-session context (the model's context window is enough)
• The user is committed to a hosted memory service (Mem0, supermemory) and doesn't want a local server
• The user wants vector embeddings only — Mnemo's value is the combination of FTS5 + embeddings + brain files; pure embedding workflows have lower friction with Mem0 or supermemory

Workflow

1. Ask the user whether Mnemo Cortex is already running. If unsure, run curl http://localhost:50001/health to check.
2. Ask the user which host the agent is running in (Claude Code, Claude Desktop, OpenClaw, LM Studio, AnythingLLM, Agent Zero, Ollama Desktop). The integration path differs by host.
3. Pick a path below.
4. Verify with a save + recall round-trip in a fresh session.
5. (Recommended) Set up a brain repo using the mnemo-plan template so the agent has project state to read at session start.
6. Tell the user about THE-LANE-PROTOCOL.md — the six-step session ritual that turns Mnemo from a tool you have into a tool you use every session.

Path 1: No server running yet

git clone https://github.com/GuyMannDude/mnemo-cortex.git
cd mnemo-cortex
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .

mnemo-cortex init                   # interactive wizard: pick model providers
mnemo-cortex start                  # listens on http://localhost:50001
mnemo-cortex health                 # verify

Then continue with Path 2.

Path 2: Server already running, connect this agent

Pick the host's integration guide and follow it:

Each integration registers the same MCP tools: mnemo_save, mnemo_recall, mnemo_search, mnemo_share, plus 5 Developer's Passport tools by default.

Verify

In a fresh session of the host:

Use mnemo_save to remember that I tested the install today.

Then in a separate session:

Use mnemo_recall to find what I told you to remember.

If the recall surfaces what you saved, the chain is wired. If the model agrees but no tool fires (no tool-call indicator in the chat), the model probably doesn't support tool calling — switch to a tool-capable model (Qwen3 any size, GPT-4/4o, Claude 3.5+, Mistral 7B v0.3).

Common Failures

• "Mnemo Cortex unreachable" — server isn't running or MNEMO_URL is wrong. Check with curl http://localhost:50001/health.
• Model narrates a fake save ID without invoking the tool — model isn't tool-capable. Switch models. See each integration's "Gotchas" section.
• Memory saved but not recallable — usually a different MNEMO_AGENT_ID between save and recall. Same agent_id reads its own memories by default; cross-agent search requires mnemo_share toggled on.

After Setup

Read THE-LANE-PROTOCOL.md (~5 min). The install is the easy part — the protocol is what makes Mnemo pay off in practice.

References

• Project: https://github.com/GuyMannDude/mnemo-cortex
• Brain repo template: https://github.com/GuyMannDude/mnemo-plan
• Operating practice: THE-LANE-PROTOCOL.md
• Workflow guide: SESSION-GUIDE.md
• Monitoring: MONITORING.md