Mnemo Cortex

A local-first cognitive coprocessor for AI agents: active memory, semantic recall, and cross-agent sharing with no cloud.

Stars
★ 161
Last updated
1d ago
License
MIT
Primary language
Python

At a glance

How it runs
Self-hosted serviceMCP serverCLI
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
Python 3.11+SQLite FTS5Ollama (recommended)Node.js 18+ (only for MCP-bridge integrations)Shell / CLINetwork accessLocal filesystemMCP Server
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.

  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

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\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?

Pros
  • 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)
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Good
75/ 100 5-point scale 3.8 / 5
This review covers the source as of Nov 08, 2026. The project has shipped 1 stable release(s) since, which have not been re-reviewed. The score and verdict describe the reviewed version only. Recent releases ↓
Trust 22/29
Reliability 8/14
Adaptability 15/18
Convention 15/18
Effectiveness 10/13
Verifiability 5/8
Why each dimension lost points
Trust22 / 29 · 3.8/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability15 / 18 · 4.2/5

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.

Convention15 / 18 · 4.2/5

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.

Effectiveness10 / 13 · 3.8/5

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.

Verifiability5 / 8 · 3.1/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision d351dcb0e2cb New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/mnemo-cortex.svg)](https://followagents.com/en/agents/mnemo-cortex)
<a href="https://followagents.com/en/agents/mnemo-cortex"><img src="https://followagents.com/badge/mnemo-cortex.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. 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 ↗
  2. 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 ↗
  3. 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?
The software is MIT-licensed and free. Running compaction and embeddings on local Ollama models costs $0. If you configure OpenAI/Google/Anthropic/OpenRouter as your reasoning or embedding provider, you supply the API keys and pay their usage. The project is donation-funded overall.
Can ChatGPT connect directly?
Not via standard local MCP (ChatGPT has no stdio transport). The project ships a bearer-authenticated, tenant-pinned, rate-limited, audit-logged two-route gate that a Custom GPT calls through Actions. Plus tier or higher is required, and full custom MCP save+recall in the main ChatGPT app needs Business/Enterprise. The Mnemo server itself never faces the internet.
Why does recall return 'No chunks'?
The most common cause is an embedding model name that no longer matches the provider's current model (Ollama: nomic-embed-text; Google: gemini_embedding_001; text-embedding-004 was shut down in January 2026). Fix the embedding setting in your config.
Is it production-proven?
Per the README, it has been the daily production memory of a five-agent fleet (CC, Opie, Dreamer, Rocky, Cody on Claude Code, Claude Desktop, Hermes, and Codex CLI) since March 2026, with ~10,000 memories, ~7,000 verified facts, and 84 versions in five months. These figures are author-reported and not independently verifiable.
Do agents see each other's memories? What about privacy?
Deployment is configurable: shared (cross-agent search and dreaming for the whole fleet), isolated (per-agent or per-customer stores with zero bleed), or hybrid (shared internal, isolated customer-facing). All data stays in a local SQLite database you control, with no telemetry or third-party services, and you can read or delete it anytime.
Is Mnemo Cortex open source?
Yes. The source code is on GitHub (GuyMannDude/mnemo-cortex) under the MIT licence.
Is Mnemo Cortex still maintained?
Yes. The latest commit on GitHub is from 2026-11-19, within the last 30 days. The latest release is v4.28.4 (2026-11-12).
Who makes Mnemo Cortex?
Mnemo Cortex is published on GitHub by the account GuyMannDude. FollowAgents has not verified which person or company is behind that account.
What is Mnemo Cortex's official website?
The project's GitHub repository lists https://projectsparks.ai as its website. That link is set by the repository owner; the source code itself is on GitHub (GuyMannDude/mnemo-cortex).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts