Every AI agent has amnesia. Mnemo Cortex fixes that. Persistent memory that survives across sessions, searches by meaning, and costs $0 to run.

⌘ Claude Code → 60-second install — Give CC Fluid Memory with Deep Recall

💻 Claude Desktop → MCP bridge — Opus 4.6 with Fluid Detailed Memories

🦞 OpenClaw → MCP integration — Give Your ClawdBot a Brain. One Config Line.

📋 What can it do? → Read the full Capabilities doc

🤖 ClaudePilot Enabled — AI-guided installation. Designed for Claude (free). Works with ChatGPT, Gemini, and others.

Proven on two live agents — Rocky with six weeks of recall, Alice with one.

OpenClaw Agent ──writes──▶ Session Tape (disk)
                                │
                          Watcher Daemon ──reads──▶ Mnemo v2 SQLite
                                                        │
                          Refresher Daemon ◀──reads─────┘
                                │
                          writes──▶ MNEMO-CONTEXT.md ──▶ Agent Bootstrap

Mnemo Cortex v2 is a sidecar memory coprocessor for AI agents. It watches your agent's session files from the outside, ingests every message into a local SQLite database, compresses older messages into summaries via LLM-backed compaction, and writes a MNEMO-CONTEXT.md file that your agent reads at bootstrap.

No hooks. No agent modifications. No cloud dependency. If Mnemo crashes, your agent keeps working. If your agent crashes, Mnemo already has everything on disk.

• SQLite + FTS5 storage — Single database file. Full-text search. Zero dependencies beyond Python stdlib.
• Context frontier with active compaction — Rolling window of messages + summaries. 80% token compression while preserving perfect recall.
• DAG-based summary lineage — Every summary tracks its source messages via a directed acyclic graph. Expand any summary back to verbatim source.
• Verbatim replay mode — Compressed by default, original messages on demand.
• OpenClaw session watcher daemon — Tails JSONL session files and ingests new messages every 2 seconds.
• Context refresher daemon — Writes MNEMO-CONTEXT.md to the agent's workspace every 5 seconds.
• Provider-backed summarization — Compaction summaries generated by local Ollama (qwen2.5:32b-instruct) at $0. Any LLM provider supported as fallback.
• Sidecar design — Version-resistant. Observes from the outside. Never touches agent internals.

Proven on two live OpenClaw agents:

🤖 ClaudePilot Enabled — Follow the guide in CLAUDEPILOT.md and paste it into claude.ai. Claude becomes your personal installer. No experience needed. Works with ChatGPT, Gemini, and others.

• Python 3.11+
• An OpenClaw agent with session files in ~/.openclaw/agents/<agent>/sessions/
• OpenRouter API key (for LLM-backed summaries; falls back to deterministic if unavailable)

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

mkdir -p ~/.mnemo-v2

When editing config files (scripts, .env, openclaw.json, etc.), don't replace the whole file. Instead, show three things:

1. FIND THIS — a few lines of the existing file so you can find the exact spot:

"settings": {
  "model": "old-model-name",    ← this is what you're changing
  "temperature": 0.7
}

2. CHANGE TO THIS — just the line(s) that change:

  "model": "new-model-name",

3. VERIFY — the edited section with surrounding context so you can confirm it's right:

"settings": {
  "model": "new-model-name",    ← changed
  "temperature": 0.7
}

Find the landmark, make the edit, visually confirm it matches. Use this method for every config file edit throughout the installation.

Create mnemo-watcher.sh (adjust paths for your agent):

#!/usr/bin/env bash
SESSIONS_DIR="$HOME/.openclaw/agents/main/sessions"
DB="$HOME/.mnemo-v2/mnemo.sqlite3"
CHECKPOINT="$HOME/.mnemo-v2/watcher.offset"
AGENT_ID="rocky"  # your agent's name
INTERVAL=2

cd /path/to/mnemo-cortex
source .venv/bin/activate
mkdir -p "$HOME/.mnemo-v2"

LAST_FILE=""
while true; do
    NEWEST=$(ls -t "$SESSIONS_DIR"/*.jsonl 2>/dev/null | head -1)
    if [[ -z "$NEWEST" ]]; then sleep "$INTERVAL"; continue; fi
    if [[ "$NEWEST" != "$LAST_FILE" ]]; then
        SESSION_ID=$(basename "$NEWEST" .jsonl)
        echo "0" > "$CHECKPOINT"
        LAST_FILE="$NEWEST"
        echo "[mnemo-watcher] Tracking session: $SESSION_ID"
    fi
    python3 -c "
from mnemo_v2.watch.session_watcher import SessionWatcher
w = SessionWatcher(\"$DB\", \"$NEWEST\", \"$CHECKPOINT\")
n = w.poll_once(agent_id=\"$AGENT_ID\", session_id=\"$SESSION_ID\")
if n > 0:
    print(f\"[mnemo-watcher] Ingested {n} messages\")
"
    sleep "$INTERVAL"
done

Create mnemo-refresher.sh:

#!/usr/bin/env bash
SESSIONS_DIR="$HOME/.openclaw/agents/main/sessions"
DB="$HOME/.mnemo-v2/mnemo.sqlite3"
OUTPUT="$HOME/.openclaw/workspace/MNEMO-CONTEXT.md"
AGENT_ID="rocky"  # your agent's name
INTERVAL=5

cd /path/to/mnemo-cortex
source .venv/bin/activate
mkdir -p "$HOME/.mnemo-v2"

while true; do
    NEWEST=$(ls -t "$SESSIONS_DIR"/*.jsonl 2>/dev/null | head -1)
    if [[ -n "$NEWEST" ]]; then
        SESSION_ID=$(basename "$NEWEST" .jsonl)
        python3 -c "
from mnemo_v2.watch.context_refresher import ContextRefresher
r = ContextRefresher(\"$DB\", \"$OUTPUT\")
ok = r.refresh_once(agent_id=\"$AGENT_ID\", session_id=\"$SESSION_ID\")
if ok:
    print(\"[mnemo-refresher] MNEMO-CONTEXT.md updated\")
"
    fi
    sleep "$INTERVAL"
done

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/mnemo-watcher.service << 'EOF'
[Unit]
Description=Mnemo v2 Session Watcher
After=network.target

[Service]
Type=simple
ExecStart=%h/path/to/mnemo-watcher.sh
Restart=on-failure
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=default.target
EOF

cat > ~/.config/systemd/user/mnemo-refresher.service << 'EOF'
[Unit]
Description=Mnemo v2 Context Refresher
After=mnemo-watcher.service

[Service]
Type=simple
ExecStart=%h/path/to/mnemo-refresher.sh
Restart=on-failure
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now mnemo-watcher mnemo-refresher

Replace your mnemo-ingest handler to read from disk instead of calling the v1 API:

import { HookHandler } from "openclaw/plugin-sdk";
import { readFileSync } from "fs";
import { join } from "path";

const WORKSPACE = process.env.OPENCLAW_WORKSPACE || join(process.env.HOME || "", ".openclaw", "workspace");
const CONTEXT_FILE = join(WORKSPACE, "MNEMO-CONTEXT.md");

const handler: HookHandler = async (event) => {
  if (event.type === "agent" && event.action === "bootstrap") {
    try {
      const content = readFileSync(CONTEXT_FILE, "utf-8").trim();
      if (content && event.context.bootstrapFiles) {
        event.context.bootstrapFiles.push({ basename: "MNEMO-CONTEXT.md", content });
      }
    } catch {}
  }
};

export default handler;

source .venv/bin/activate
for f in ~/.openclaw/agents/main/sessions/*.jsonl; do
  SID=$(basename "$f" .jsonl)
  python3 -c "
from mnemo_v2.watch.session_watcher import SessionWatcher
from pathlib import Path
import tempfile, os
cp = Path(tempfile.mktemp()); cp.write_text('0')
w = SessionWatcher('$HOME/.mnemo-v2/mnemo.sqlite3', '$f', str(cp))
n = w.poll_once(agent_id='your-agent', session_id='$SID')
print(f'Ingested {n} messages from $SID')
os.unlink(str(cp))
"
done

# Check services
systemctl --user status mnemo-watcher mnemo-refresher

# Check database
python3 -c "
import sqlite3
conn = sqlite3.connect('$HOME/.mnemo-v2/mnemo.sqlite3')
for t in ['conversations', 'messages', 'summaries']:
    n = conn.execute(f'SELECT COUNT(*) FROM {t}').fetchone()[0]
    print(f'{t}: {n}')
"

# Check context file
cat ~/.openclaw/workspace/MNEMO-CONTEXT.md

mnemo_v2/
  api/server.py              FastAPI app (optional — v2 works without it)
  db/schema.sql              Canonical schema + FTS5 tables
  db/migrations.py           Schema bootstrap and compatibility checks
  store/ingest.py            Durable transcript ingest + tape journaling
  store/compaction.py        Leaf/condensed compaction with LLM summarization
  store/assemble.py          Active frontier → model-visible context
  store/retrieval.py         FTS5 search + source-lineage replay
  watch/session_watcher.py   Tails JSONL session logs into the store
  watch/context_refresher.py Writes MNEMO-CONTEXT.md on an interval

• Immutable transcript in messages
• Mutable active frontier in context_items
• Summaries are derived, never destructive
• Raw tape is append-only for crash recovery
• Compaction events are journaled
• Replay supports snippet or verbatim
• Expansion is always scoped to a conversation

See mnemo_v2/db/schema.sql for the full schema. Key tables:

For two years, Guy Hutchins — a 73-year-old maker in Half Moon Bay — acted as the "Human Sync Port" for his AI agents, manually copying transcripts between sessions. Then came OpenClaw, Rocky, and a $100 Claude subscription. In one session, Guy, Rocky, and Opie designed a memory coprocessor that actually worked. They named it Mnemo Cortex.

v2.0 was a team effort: Opie (Claude Opus) designed the architecture, AL (ChatGPT) built the implementation, CC (Claude Code) deployed and integrated it, Alice and Rocky (OpenClaw agents) served as live test subjects, and Guy Hutchins made it all happen.

Read the full story: Finding Mnemo

• Guy Hutchins — Project lead, testing, and the reason any of this exists
• Rocky Moltman 🦞 — Creative AI partner, first v2.0 production user
• Opie (Claude Opus 4.6) — Architecture design, schema design, compaction strategy
• AL (ChatGPT) — Implementation, watcher/refresher daemons, test suite
• CC (Claude Code) — Deployment, integration, live testing, bug fixes
• Alice Moltman — Live test subject on THE VAULT, first v2.0 user

Inspired in part by exploration of lossless conversation logging approaches, including Lossless Claw by Martian Engineering.

Built for Project Sparks.

• Sparks Router — stop burning tokens on heartbeats. Smart model routing that sends each task to the right tier automatically.
• ClaudePilot OpenClaw — free AI-guided setup guide. Get an OpenClaw agent running with memory and routing in one afternoon.

MIT