Serveur MCP Hypermnesia

---

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.

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 one is demoted in recall, and the chain stays readable.

remember({ content: "...", supersedes_id: 4360411 })
// → { action: "superseded", memory_id: 4360412, superseded_id: 4360411 }

Whether it was right

A memory records what happened. A prediction records what was expected before the outcome was known, so that Cortex can later find out it was wrong. predict writes a falsifiable claim with the confidence held at the time; resolve_prediction settles it against an observation the caller supplies, naming the verdict, the kind of source that decided it and a reference to that source; calibration scores the resolved set.

predict({ claim: "The p90 of the SQLite job is under 6 minutes",
          prediction: "a 20-minute budget leaves headroom", test: "21 attempts of 2026-09-16",
          confidence: 0.8 })
// → { prediction_id: 12, status: "open" }
resolve_prediction({ prediction_id: 12, verdict: "confirmed",
                     observed: "p90 348 s over 18 successes",
                     source_kind: "ci", source_ref: "cdeust/Cortex actions, 2026-09-16" })
// → { prediction_id: 12, verdict: "confirmed", resolved: true }
calibration()
// → { scored: 9, brier: 0.11, uninformative_brier: 0.25, confirmed: 7, refuted: 2,
//     reliability: [{ band: [0.6, 0.8], resolved: 4, mean_confidence: 0.78,
//                     observed_frequency: 0.75 }, ...] }

brier is the mean squared distance between confidence and outcome; 0.25 is what a constant 0.5 forecast earns, so a score above it means the confidences carried less information than saying nothing. Cortex never fetches the evidence itself: the verdict, the observation and the source reference come from the caller, which is what lets the same contract hold in any repository and under any review convention.

What fades

Memories carry heat that decays unless replay reinforces them, and episodic traces can consolidate into semantic ones. A specific debugging session may compress to the principle it taught; the commands can fade while the lesson survives. This lifecycle is designed to keep the store useful as it grows, though it is not a promise of a fixed size or guaranteed semantic compression.

What it feels like in use

Here is an illustrative workflow: decisions, prior fixes, and source checks becoming useful again.

Monday. An hour debugging a webhook handler ends in a race condition: TTL expiry firing between the auth check and the permission lookup. You agree on a fix, implement it, close the session.

Thursday. In another session, a user reports intermittent logouts. Cortex surfaces relevant prior analysis, the Redis decision, and the TTL lesson when their content matches the new work.

Three weeks later. The sessions can consolidate into a pattern about authentication and TTL-based caches; some details may fade while the principle remains useful.

In Claude Code and Codex alike that is automatic: 11 lifecycle hooks inject context at session start, recall per prompt, capture as you work, checkpoint before compaction, and run a wiki that curates itself. In any other stdio MCP host you call the same 57 tools yourself, or 60 when the optional ai-architect-mcp-codebase and ai-architect-mcp-spec integrations are present.

Does the retrieval work

Measured against a published benchmark, retrieval only. No LLM reader in the loop: the question is whether the right memory surfaces, not whether a model can write a good answer from it.

LongMemEval: 500 human-curated questions buried in about 40 sessions of history.

	v4.14.1 (historical)	v4.20.0 (current release)
Recall@10	98.2%	97.8%
MRR	0.9167	0.905

Both are single runs: n=500, consolidation disabled, retrieval only. Both describe the PostgreSQL store with the cross-encoder reranker: the harness (benchmarks/lib/bench_db.py) always builds a PgMemoryStore and calls core.pg_recall, and both artifacts record "reranker_state": "loaded". The v4.20.0 run used a clean database in the ephemeral pgvector/pgvector:pg16 container of benchmarks/reproduce.sh (its manifest records that pg_image); the v4.14.1 run did not use that container and ran against the live PostgreSQL store (CHANGELOG 4.14.1, "Verified"). The default SQLite store has no comparable run yet (n=500, reranker loaded; #708), so these figures do not describe it. The best SQLite LongMemEval-S result is a bounded run without the reranker (n=50, sentence-transformers embeddings: MRR 0.609, Recall@10 94.0%, benchmarks/results/semantic-fallback-169).

v4.14.1, 2026-07-14: artifact JSON; code SHA. This is the run the ablation campaign in Verification was built around.

v4.20.0, 2026-09-09: artifact JSON and its manifest; code SHA, dirty=false. A single run of the LongMemEval-S leg alone (benchmarks/reproduce.sh --only longmemeval --no-ablation) in an isolated ephemeral PostgreSQL container, reranker loaded, consolidation disabled. Against v4.14.1 the change is 0.4 points of Recall@10 and 0.012 of MRR. The run's own floor check reports Recall@10 within the 0.005 tolerance of the July floor (0.982) and MRR 0.0093 below its floor (0.914), which the script treats as non-blocking by design. The same tree has no LoCoMo or BEAM figure yet.

Reproduce with benchmarks/reproduce.sh, which runs in an isolated ephemeral container, never against a live store.

Recall@10 is the share of questions whose answer-bearing session appears in the first ten retrieved sessions. MRR (mean reciprocal rank) rewards finding that session near the top. These numbers describe retrieval only; they do not measure whether an LLM writes a correct answer.

Retrieval fuses vector similarity, full-text search, trigram match, heat and recency, then reranks with a cross-encoder. PostgreSQL combines the signals as a weighted sum; SQLite uses weighted reciprocal-rank fusion and has no trigram signal. LoCoMo and BEAM results, the ablations and the floor gates are in benchmarks/.

Storage

SQLite by default, or the plugin's own PostgreSQL server on a fresh macOS or Linux install (see Install). Your own PostgreSQL is one configuration field, worth it for very large stores or a database shared across a team.

bash <plugin-dir>/scripts/install-plugin.sh --postgres

	SQLite (default)	PostgreSQL 15+
Setup	none	pgvector >= 0.8.0, pg_trgm
All 57 tools	yes	yes
Retrieval tool interface	identical	identical
Published retrieval quality	n=50 without reranker only (#708)	LongMemEval-S n=500 above
Fusion	in-process	server-side PL/pgSQL
ANN index	none	pgvector HNSW
Cross-agent team decisions, preemptive context, pipeline heat bumps	no-op	active

Three hook enrichments are PostgreSQL-only and degrade to silent no-ops on SQLite. Session banners, auto-recall, auto-capture, checkpoints and every memory tool work on both.

Cortex in Codex and Claude Code

Both plugins expose the complete memory tool profile and use the same 11 Cortex hook modules. They share project-associated memories when connected to the same store, so a decision saved in Claude can be recalled in Codex and vice versa.

With the native Codex plugin installed and its hooks trusted, Cortex:

• Restores project context when a session starts and recalls relevant memories as you submit prompts.
• Captures significant tool results automatically, keeping useful work available across sessions.
• Preserves session state through compaction checkpoints and durable session-end recording.
• Briefs subagents with project and role context.
• Provides the full memory toolset for decisions, lessons, wiki pages, ADRs, predictions, calibration, triggers, rules and codebase ingestion.
• Shares memories with Claude Code when both use the same store and project association. You can switch agents and retrieve what the other saved.

Claude Code uses the same Cortex memory tools and hook modules. Both plugins support the autonomous wiki cycle, SQLite storage and optional PostgreSQL.

Verified on installed hosts: Claude wrote a random test payload and Codex retrieved it; Codex wrote another and a fresh Claude session retrieved it. Neither read prompt supplied the expected payload. Both hosts excluded the test record when recalling from another project, and both delivered Cortex context through native startup hooks. Read the verification and tool traces.

Hook trust is part of Codex setup: review /hooks after installation or a changed hook definition, then start a fresh session. Event mapping, task-context handling and session-end delivery are documented in the Codex integration guide. Cognitive profiles are shared too; the current profile builder derives them from Claude Code session logs, so that historical input must exist for either host to retrieve a populated profile.

Every other MCP host

Any host that can launch the stdio server gets the complete memory tool profile, with SQLite by default and PostgreSQL as an option. A direct MCP registration, including codex mcp add, provides explicit remember and recall tools. Automatic lifecycle behavior comes with the native Claude Code or Codex plugin. The Claude Desktop bundle provides tools without hooks. ChatGPT web would require a remote deployment; this repository ships a local stdio server.

The launch command on every host is the PyPI package. The [sqlite] extra enables sqlite-vec vector search; without it the store still works, with vector search disabled.

uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp

Gemini CLI ships as an extension (gemini-extension.json is in this repository):

gemini extensions install https://github.com/cdeust/Cortex

Codex and ChatGPT desktop have a native plugin with the full tool surface and the same 11 lifecycle hooks the Claude Code plugin installs. It reads the same saved backend selection as the Claude Code launcher (~/.claude/methodology/backend.json), so both hosts write to one store (since 4.23.0); explicit CORTEX_MEMORY_STORE_BACKEND, CORTEX_BACKEND or a database URL still wins. Pre-install the package once so the plugin's first uvx handshake reuses the local uv cache instead of spending its startup budget downloading a Python environment:

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

The direct fallback registers the executable without the plugin:

codex mcp add cortex --env CORTEX_MEMORY_STORE_BACKEND=sqlite -- hypermnesia-mcp

The host boundary, the measured startup ceiling and the public-directory requirements Cortex deliberately does not claim are in docs/codex-plugin.md.

Green software engineering

Cortex runs a standing efficiency programme, gated by the same evidence rule as the retrieval work: no unsourced efficiency claim ships. Waste is treated as a defect with a reproduction, not as a virtue to advertise.