hypermnesia-mcp

Memory for AI coding agents that you can hold accountable. Keep decisions, fixes and project context between sessions, and inspect what was retrieved. Runs locally by default. No account, no API key, no server to manage.

---

Sovereign is what it is today. Everything runs on your machine: a local SQLite file by default, or PostgreSQL + pgvector if you prefer. No LLM in the retrieval loop, and nothing leaves localhost unless you configure an integration that does. Your project's memory is a file you own and can delete.

Claude Code and Codex share Cortex memory. Both native plugins provide the same memory tools and 11 lifecycle hook modules for automatic capture, recall and project context. Use either agent on a project and keep its memory when you switch. Verified with real Claude and Codex sessions on macOS. The same stdio MCP server also supplies memory tools to Claude Desktop, Claude Cowork and other local MCP hosts.

Eco-responsible is what we are aiming at. Work that never reaches a datacenter is work nobody has to power, and an agent that finds the right context first time re-reads fewer files. We hold that intent to the Green Software Foundation's SCI method, and we publish no CO₂ or energy figure, because we have not measured one. What we do and do not claim ↓

36 implemented, inspectable neuroscience-inspired mechanisms · 57 memory tools · 11 lifecycle hooks · a self-curating per-project wiki — all local, all open-source, MIT.

The committed ablations do not establish that these 36 mechanisms improve retrieval collectively or individually. Published neuroscience references explain their design; retrieval benefits require measurements in Cortex. See Verification.

Install

Claude Code — add the marketplace and install the plugin:

claude plugin marketplace add cdeust/Cortex
claude plugin install hypermnesia-mcp
claude --init-only

claude --init-only runs the plugin's Setup hook, which installs Cortex's runtime (base dependencies, semantic search and its embedding model) before your first session. It prints nothing and exits 0 even when the install fails (Claude Code discards a Setup hook's output), so to watch the progress and get a failing exit code, run scripts/init_plugin.py from the installed plugin instead (its path is installPath in claude plugin list --json).

Update the same way, one command, then initialise again:

claude plugin update hypermnesia-mcp
claude --init-only

Claude Desktop — download hypermnesia-mcp.mcpb from Releases and open it, or use Settings → Extensions. The bundle carries the tools but no hooks; the MCPB format has none.

Claude Cowork is detected automatically (CLAUDE_ENVIRONMENT=cowork) and uses the local SQLite store. No PostgreSQL required.

For Codex, install the native plugin for memory tools and automatic hooks:

uv tool install "hypermnesia-mcp[sqlite]"
codex plugin marketplace add cdeust/Cortex
codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins

Open /hooks in Codex to review and trust the Cortex hooks, then start a fresh session. Changed hook definitions require renewed trust after an update. The plugin uses the same saved backend selection as Claude Code; both hosts share memory when they use the same configuration root and store. Codex setup details.

Other stdio MCP hosts (Gemini CLI, Cursor, Windsurf, VS Code) launch the same server and get the same tools. See launch commands. WSL, TLS client certificates and corporate proxies are covered in deployment scenarios.

Cortex's dependencies live in the plugin's data directory, one directory per locked dependency set (sets/<key>), so an update that does not change the locked dependencies (most releases: 21 of 29 from v4.9.0 to v4.23.5) finds its set installed. A background job removes the sets no installed version references; it makes no network call. When a set is missing (the first session after an install, or after an update that changes the locked dependencies, when claude --init-only did not run first), no hook installs: SessionStart says Cortex is installing its dependencies (about 2 minutes, about 5 with semantic search); memory is available when it is done, the Edit/Write guards let edits through and say that the Cortex gate is inactive until then, and the MCP server installs the set in the background; the next session (or the same one, once done) shows Cortex ready: <store>, <n> memories; <how recall ranks>. claude --init-only (or python3 scripts/init_plugin.py, which shows progress) installs everything before the first session; only with it does that session start ready. To work without Cortex, offline or not, run claude plugin disable hypermnesia-mcp@cortex-plugins.

On macOS and Linux (glibc 2.36 or later, x86_64 or arm64: Ubuntu 24.04 and 26.04, Debian 12 and later; not Ubuntu 22.04 or RHEL 9), claude --init-only on a fresh install also gives the plugin its own PostgreSQL server with pgvector and pg_trgm: pinned, sha256-checked binaries (about 13 MB on macOS, 40 MB on Linux, where they bundle their libraries; pgvector is compiled by Cortex's CI, with build provenance attested) on 127.0.0.1, with no Homebrew or system PostgreSQL needed. Its data lives in ~/.claude/methodology/managed-pg/, so uninstalling the plugin never deletes your memories. It becomes the store only after it has started and its schema exists; if it cannot start (a Linux distribution with glibc older than 2.36, for example) the SQLite store is used, as it is on Windows, and the session start says why (SQLite fallback: ...). A store already on that server is never switched to SQLite: Setup fails and names the cause. The Codex plugin on the same account attaches to the same server. An existing SQLite store is not moved (ADR-1114).

Otherwise the first use creates a local SQLite store under ~/.claude/methodology/. Models are downloaded once when needed and then run offline. The embedding and reranking model files are both fetched on first use. Optional integrations, remote PostgreSQL, and OTLP telemetry use the network only when explicitly configured. PRIVACY.md lists the exact scope.

An existing PostgreSQL setup is kept: a configured database_url option (or DATABASE_URL), or the backend marker install-plugin.sh --postgres writes, always wins over the plugin's own server and the SQLite default. An install that ran before on the local cortex database with nothing configured keeps it: on its first launch Cortex moves to SQLite only when nothing listens on localhost:5432 and no PG* variable configures PostgreSQL, records the choice, and prints it. A fresh install never connects to a database nothing configured.

Upgrading from an older plugin identity

The plugin was renamed hypermnesia-mcp in v4.15.0, after a community-directory collision with an unrelated cortex plugin. Memories, configuration and storage paths are untouched.

claude plugin uninstall cortex
claude plugin install hypermnesia-mcp

The visualization companion, hypermnesia-mcp-viz, was renamed the same way:

claude plugin uninstall cortex-viz@cortex-plugins
claude plugin marketplace update cortex-plugins
claude plugin install hypermnesia-mcp-viz@cortex-plugins

The retained cortex-viz@cortex-plugins entry is a frozen shim that only prints this notice and exposes no server or tools.

Allowlists, hooks, skills and agents must migrate both composed tool names: mcp__plugin_cortex-viz_cortex-viz__open_visualization becomes mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__open_visualization, and mcp__plugin_cortex-viz_cortex-viz__get_methodology_graph becomes mcp__plugin_hypermnesia-mcp-viz_hypermnesia-mcp-viz__get_methodology_graph.

Keep context useful

Across sessions, agents need to remember decisions, bring prior fixes back when a similar problem returns, and show you which sources support a memory so you can correct it. Cortex keeps that context available while making its status visible.

Cortex does this with local quality checks: what is written, whether its references resolve, what happens when a decision changes, and what can fade over time.

What gets in

The remember handler and automatic capture check for exact replays after hardening and redaction. Matching domain, directory, agent topic, source, write class, capture origin, and global/team flags produce reason: "exact_duplicate" with the existing memory id. Forced writes retain this check; explicit supersedes_id corrections retain their atomic supersession path. Benchmark rows are isolated, and memory-replica block replicas keep their path identity. Direct store inserts do not use this handler check. Consolidation supersedes existing exact duplicates within that scope and preserves their rows and protection flags. This differs from the optional normalized-text maintenance pass. Near-duplicate curation uses the thresholds in core/curation.py; deliberate writes bypass the novelty threshold and can be stored separately when curation does not merge them.

// Illustrative project decision:
remember({ content: "Keep session state in Redis so TTL expiry is handled consistently." })
// → { stored: true, action: "stored" }

Deliberate writes can be refused as exact replays; novelty alone does not reject them. Unattended capture must also pass the novelty check, which keeps automatic capture from burying the memories you meant to keep.

Whether it can be checked

Every memory is graded at write time, locally, with no network call. The grade is not a confidence score: it is whether the claims carry references that resolve on this machine.

// → provenance: { grade: "unverifiable",
//                 reason: "dead_refs: deps/numpy/_core/_multiarray_umath.cpython-313-darwin.so",
//                 hint: "1 of 9 checkable reference(s) could not be resolved" }

That memory named a file that no longer existed, so it was stored and labelled unverifiable instead of being silently presented as verified. Rewritten against paths that resolve, the same memory grades verified. A recalled memory tells you which kind it is; a verified grade still means that the references resolve locally, not that the claim has been independently proven true.

When it turns out wrong

Corrections supersede rather than overwrite. The new memory records what it replaces, the old