Mnemo Cortex

What does this agent do, and when should you use it?

Mnemo Cortex is a self-hosted cognitive coprocessor that gives AI agents persistent, local, cross-agent memory. It watches agent session files from the outside (JSONL for OpenClaw and Claude Code), ingests every message into a local SQLite database, and applies rolling LLM-backed compaction via a local Ollama model (default qwen2.5:32b-instruct) for roughly 80% token reduction. The system runs as an API server (default http://localhost:50001) and connects to clients — Claude Desktop, LM Studio, AnythingLLM, OpenClaw, Agent Zero, Hermes — through MCP bridges; ChatGPT is served through a hardened two-route REST gate instead of MCP. Core components include tiered smart notes versus session logs, a structured facts store with a confidence ladder and authority tiers, nightly cross-agent 'dreaming' synthesis, The Librarian workspace document index (SQLite FTS5), the encrypted USB-courier Cortex Stick, the Disco-Bus agent messaging system, and a tamper-evident Memory Ledger. According to the README, it has run since March 2026 as the production memory of a five-agent fleet, holding about 10,000 memories and ~7,000 verified facts across 84 shipped versions.

After mnemo-cortex start, the API server listens on port 50001; mnemo-cortex watch --backfill starts a session watcher that tails JSONL session files and auto-ingests messages every 2 seconds (no hooks or agent changes needed). Saves are tiered at write time: Tier 1 smart notes are classified by the reasoning model into one of eight categories (topology, current_state, doctrine, incident, identity, relationship, decision), while Tier 2 holds raw session logs excluded from default recall. Recall runs semantic vector search and a BM25 keyword lane (SQLite FTS5) in parallel; since v4.22 it also matches misspelled proper names via consonant-skeleton keys. Structured facts are stored as (entity, attribute, value) triples with an automatic verified→high_probability→false confidence ladder and four MCP tools: mnemo_fact_save, mnemo_fact_get, mnemo_fact_query, and mnemo_fact_demote. The nightly dreaming pipeline map-reduces each agent's recent memories into themes, then merges them cross-agent into a shared brief. mnemo-cortex health verifies the server, database, compaction model, and per-agent recall; mnemo-cortex stick sync carries deltas between two machines via an optionally AES-256-encrypted USB stick.

1. A solo developer running multiple agents (Claude Code, Claude Desktop, Codex CLI, Hermes) who wants Agent A to recall what Agent B learned
2. A user working across two desks who syncs agent memory via the encrypted Cortex Stick USB courier — no cloud, VPN, or account
3. Local-LLM users (LM Studio, Open WebUI, Ollama, AnythingLLM) who want persistent semantic memory at zero API cost
4. A ChatGPT Plus subscriber who wants a Custom GPT with memory they own, accessed through a private gate rather than an exposed server
5. Users who need exact facts (names, settings, identifiers) rather than fuzzy semantics — served by the structured facts store and the BM25 lexical lane
6. Multi-agent teams wanting overnight cross-agent dream synthesis plus the Lane Protocol session workflow

How do you install or deploy this agent?

Prerequisites: Python 3.11+, optionally Ollama (recommended for local reasoning and embeddings), Node.js 18+ only when running an MCP-bridge integration. Install from source:

bash

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 .

This registers the mnemo-cortex CLI (alias mnemo). For non-interactive install (LLM agents or CI):

bash

./robot-install.sh

The script emits a single JSON object on stdout (ok, steps, etc.) with progress on stderr; sandbox runs are supported via MNEMO_INSTALL_DRY_RUN=1 and path overrides. A dedicated macOS guide exists (docs/install-macos.md); Windows is natively supported as of v4.4.1.

How do you use this agent?

Five-step flow:

bash

mnemo-cortex init      # Interactive wizard: reasoning/embedding models, bind address, port; writes ~/.agentb/agentb.yaml
mnemo-cortex start     # Detached start; server listens on http://localhost:50001
mnemo-cortex health    # 14-point health check; use mnemo-cortex doctor for deeper diagnostics

Enable auto-capture:

bash

mnemo-cortex watch --backfill

Or set export MNEMO_AUTO_CAPTURE=true in your shell profile so the watcher starts with the server. Then connect a client: Claude Code via integrations/claude-code/; Claude Desktop via a drag-and-drop .mcpb bundle; LM Studio, AnythingLLM, OpenClaw, Agent Zero via a one-line MCP config; ChatGPT via Custom GPT Actions against the two-route gate (Plus tier or higher). Direct API example:

bash

curl -s -X POST http://localhost:50001/context \
-H "Content-Type: application/" \
-d '{"prompt": "what happened today", "agent_id": "YOUR-AGENT-ID", "max_results": 5}'

Recommended companions: a forked mnemo-plan brain repo pointed at via the BRAIN_DIR env var, and the THE-LANE-PROTOCOL.md operating ritual.

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ