Mnemo Cortex
A local-first cognitive coprocessor for AI agents: active memory, semantic recall, and cross-agent sharing with no cloud.
- Source repo
- GuyMannDude/mnemo-cortex
- Stars
- ★ 161
- Last updated
- 1d ago
- License
- MIT
- Primary language
- Python
- FA score
- 75/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · Claude.aiChatGPT (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo developer running multiple agents (Claude Code, Claude Desktop, Codex CLI, Hermes) who wants Agent A to recall what Agent B learned
- Not a fit if
- Teams wanting a zero-deployment hosted cloud memory
- Users needing OpenAI cloud connectors to reach a self-hosted MCP directly
- Users unwilling to maintain a local server process
- Website
- projectsparks.ai ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-19latest release v4.28.4 (2026-11-12)
- Source review
- 75/100 · Good
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.
- A solo developer running multiple agents (Claude Code, Claude Desktop, Codex CLI, Hermes) who wants Agent A to recall what Agent B learned
- A user working across two desks who syncs agent memory via the encrypted Cortex Stick USB courier — no cloud, VPN, or account
- Local-LLM users (LM Studio, Open WebUI, Ollama, AnythingLLM) who want persistent semantic memory at zero API cost
- A ChatGPT Plus subscriber who wants a Custom GPT with memory they own, accessed through a private gate rather than an exposed server
- Users who need exact facts (names, settings, identifiers) rather than fuzzy semantics — served by the structured facts store and the BM25 lexical lane
- Multi-agent teams wanting overnight cross-agent dream synthesis plus the Lane Protocol session workflow
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pip install -e
- Environment variables
BRAIN_DIR- Config files
~/.agentb/agentb.yaml- Runtime
- Python 3.11+ · Node.js 18+
- Install notes cover
- Windows · macOS
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\activatepip install -e .
This registers the mnemo-cortex CLI (alias mnemo). For non-interactive install (LLM agents or CI):
bash
./robot-install.shThe 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 diagnosticsEnable auto-capture:
bash
mnemo-cortex watch --backfillOr 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?
- Only memory system claiming cross-agent overnight dreaming — map-reduce compaction of each agent's memory into a shared brief so all agents wake up knowing what the others did
- Fully local-first: no telemetry, no cloud dependency, single-file SQLite storage, and $0 compaction/embedding via local Ollama models
- Multi-lane recall: semantic vectors + BM25 keyword lane (SQLite FTS5) + phonetic name matching; author's test shows 11/11 exact hits versus 8/11 with vectors alone
- Structured facts with a confidence ladder, authority tiers (probe/declared/open), tamper-evident Memory Ledger, and a demote endpoint for wrong memories
- Rich operational tooling: per-platform install guides, robot-install non-interactive setup, health/doctor diagnostics, Disco-Bus agent bus, The Librarian document index (~107K files, ~17s full rebuild)
- Requires a continuously running local server process (default 127.0.0.1:50001) that you must keep alive via systemd/launchd/Task Scheduler yourself
- Depends on local Ollama models for compaction and embeddings (qwen2.5:32b-instruct, nomic-embed-text); embedding model-name drift is a documented failure mode causing empty recall
- ChatGPT cannot use standard MCP — a custom hardened gate is required, and OpenAI plan tiers restrict functionality (read-only custom MCP connectors on Plus)
- Authority tiers are currently an audit trail plus honor system; enforcement that actually blocks agent writes is not yet implemented
- Personal/small-team project by a self-described non-developer; the documented timeline (2026 dates) and long-term maintenance cannot be independently verified
How does this agent compare with similar options?
The README explicitly compares against OpenClaw's native Active Memory plugin (2026.4.10): that plugin is single-agent, per-workspace scratchpad storage, while Mnemo is a centralized SQLite + embeddings memory bus that survives resets and machine moves — the two stack rather than compete. It also self-positions against Mem0, Zep, and Letta, which store memory per agent, whereas Mnemo dreams across all of them (author's claim). For ChatGPT, instead of exposing a standard MCP server over HTTPS, it ships a hardened two-route gate — a deliberate design contrast with typical self-hosted MCP servers.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mnemo Cortex This agent | 75 · Good | Self-hosted serviceFree | ★ 161 | 1d ago | Python | Codex · Claude Code · Claude.ai |
| Compartment | 73 · Some gaps | CLIFree | ★ 473 | 3d ago | Python | Codex · Claude Code |
| Remnic Agent Memory | 73 · Some gaps | CLIFree + model costs | ★ 235 | today | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| Emulo | 76 · Good | Agent plugin / skillFree + model costs | ★ 306 | 1mo ago | HTML | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows local deployment, tenant isolation, tool permission prompts, and a ChatGPT gate with authentication, rate limits, body caps, auditing, and secret-file guidance. The gate exposes two operations and pins a tenant. Scores are reduced because the sample does not fully show MCP permission scope or per-endpoint authorization in the core service; users still make deployment choices, and USB sync rollback details are limited despite conflict preservation claims.
CI configuration covers pytest, wheel smoke, and Docker boot, while guides include health checks and troubleshooting. Scores are reduced because the README says the default bind is loopback while the macOS guide says initialization defaults to 0.0.0.0; the sample does not resolve this configuration conflict. Dependency ranges are broad, and security fixes are stated to apply only to the latest release.
Documentation covers many MCP clients, Windows/Linux/macOS, shared and isolated deployments, and explicit exclusions including ChatGPT gate constraints. Scores are reduced because the many client and model support claims leave some compatibility boundaries for users to verify, and trigger guidance is mostly limited to the sampled skill instructions.
The documentation has a clear index, cross-platform installation guides, troubleshooting, known limitations, an MIT license, and a security reporting path. Scores are reduced because the skill version is 0.1.0 while the package is 4.28.4, and the sample cannot fully reconcile README release/date claims with the snapshot version. Single-maker maintenance and latest-release-only security support are disclosed, but the publisher identity is not independently verified here.
The product combines persistent memory, semantic and lexical retrieval, structured facts, and cross-agent sync, with concrete setup and usage examples. Scores are reduced because performance and scale figures are primarily publisher-reported and cannot be independently established from this static sample; users still bear model-service, setup, and maintenance costs.
Configuration, API behavior, security controls, installation steps, and several feature claims can be compared across the code and documentation samples; the guides also tell users to verify actual tool calls and distinguish speculation from facts. Scores are reduced because many performance, scale, uniqueness, and usage claims are self-reported, the CI file shows configured workflows rather than results for this revision, and fact/inference labeling is not consistent throughout.
- The README and macOS guide disagree about the default bind address after initialization. Check the actual configuration and avoid network exposure without authentication.
- The ChatGPT gate requires a public HTTPS endpoint; its security boundary depends on a separate gate token, tenant pinning, and correct proxy configuration.
- Scheduled fact seeding can overwrite later corrections; update the seed file whenever the corresponding fact changes.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v4.28.4 v4.28.4 — Anthropic provider on Sonnet 5.5; Claude Desktop bundle rebuilt (reinstall it)
Release notes excerpt
Anthropic provider (PR #25, thanks @SamHofmannOfficial). The setup wizard's Anthropic default is now claude-sonnet-5-5 (claude-sonnet-4-5-20250929 retires 2026-11-30), and AnthropicReasoning.generate no longer raises KeyError when a reply starts with a thinking block. Claude Desktop bundle rebuilt on bridge 2.40.1 — reinstall if you use it. The one-click mnemo-cortex.mcpb had not been rebuilt since July and still carried bridge 2.17.0. That means it was missing the wiki_search security fix announced in v4.28.1 (GHSA-h2jf-xmmf-2w8p). If you installed the bundle before 2026- …View on GitHub ↗ -
v4.28.1 v4.28.1 — SECURITY: wiki_search no longer runs a shell (GHSA-h2jf-xmmf-2w8p)
Release notes excerpt
Security fix — MCP bridge 2.40.1. The read-only wiki_search tool built a shell command string with the query inside double quotes; $(...) and backticks expand there, so a search term shaped that way ran commands as the bridge user. CVSS 3.1 7.8 (local stdio; needs a wiki directory to exist and the host to invoke the search with attacker-chosen text). The Mnemo server itself is unaffected. grep now receives its arguments directly with no shell (wiki-search.js). wiki-search.test.js covers eight injection shapes plus option- and path-shaped queries. Behaviour is otherwise unchanged. …View on GitHub ↗ -
v4.27.0 v4.27.0 — SECURITY: no wildcard CORS, foreign origins and hosts refused without auth
Release notes excerpt
Problem. GHSA-682p-grrx-wrwg (high, reported 2026-08-20 by kasparovabi). The server shipped cors_origins: ["*"] by default, and the default auth posture is none. A browser on the same machine is a loopback client, so any web page the user visited could read /facts, /sessions, transcripts and dreams, write facts, pause capture, and plant trajectories — the loopback peer check never saw a difference. A DNS-rebinding page did the same with no Origin header at all. Deployments with auth_token or scoped tokens were not affected (the token is the gate, and a page cannot attach it). …View on GitHub ↗
FAQ
Does Mnemo Cortex cost anything to use?
Can ChatGPT connect directly?
Why does recall return 'No chunks'?
Is it production-proven?
Do agents see each other's memories? What about privacy?
Is Mnemo Cortex open source?
Is Mnemo Cortex still maintained?
Who makes Mnemo Cortex?
What is Mnemo Cortex's official website?
Thanks — we use this to improve the page.