Open source · MIT · v4.24.0 · hypermnesia-mcp

You don’t manage memory.
Cortex does.

Persistent memory for Claude Code, Codex, Gemini CLI and any stdio MCP host — built on computational neuroscience, not guesswork. Memory that learns, consolidates, forgets intelligently, and surfaces the right context at the right time. 36 cited neuroscience mechanisms. 57 MCP tools. 11 lifecycle hooks. Native AST call-graph via ai-architect-mcp-codebase. 97-paper bibliography. 97.8% Recall@10 on LongMemEval-S (v4.20.0, PostgreSQL store with the reranker). No GPU.

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

Local-first — SQLite by default. PostgreSQL 15+ with pgvector + pg_trgm optional for larger corpora.

Cortex in 90 seconds. Silent. Generated from cdeust/Cortex at v4.24.0 (); every figure it prints is read from site-facts.json.
What the film says, scene by scene
  1. What an agent learned in one session is gone in the next. Cortex keeps decisions, fixes and project context between sessions.
  2. The memory stays on your machine. A local SQLite file by default, or PostgreSQL + pgvector if you prefer. No LLM in the retrieval loop.
  3. What gets in: a novelty check. Unattended capture: must pass the novelty check. Nearest neighbours: compared with the five closest memories. Near-duplicate: merges with the memory it repeats. Decisions and errors recorded deliberately bypass the gate.
  4. Can it be checked? Every memory is graded at write time, locally, with no network call. “verified” means its references resolve locally, not that the claim has been proven true.
  5. When it turns out wrong. Corrections supersede rather than overwrite: the old memory is demoted in recall, and the chain stays readable.
  6. What fades. Memories carry heat that decays unless replay reinforces them. An episode may compress to the principle it taught. Not a promise of guaranteed semantic compression.
  7. Recall: five signals, no LLM. Fused: vector similarity, full text, trigram match, heat, recency. Then: reranked by a cross-encoder. On SQLite: no trigram signal: four signals. Model: no LLM in the retrieval loop.
  8. Measured on a public benchmark. LongMemEval-S: 500 questions buried in about 40 sessions of history. Retrieval only. Recall@10: 97.8%. MRR: 0.9046. questions, a single run: 500. Measured on v4.20.0, 9 September 2026, on PostgreSQL, consolidation disabled. The default SQLite store has no comparable run yet.
  9. Cortex. 57 MCP tools, 11 lifecycle hooks, all local. Claude Code and Codex share Cortex memory. $ claude plugin marketplace add cdeust/Cortex $ claude plugin install hypermnesia-mcp $ claude --init-only

Sources: Sources: README, docs and code of cdeust/Cortex at the v4.24.0 tag (caf8fee). Benchmark artifact: benchmarks/results/repro/20260909-v4.20.0-longmemeval-s. Figures: ai-architect.tools/site-facts.json.

// plugin · hypermnesia-mcp-viz · v3.3.0

hypermnesia-mcp-viz (Cortex Viz) — six reading angles, one memory store

A separate, read-only companion, formerly cortex-viz, for Claude Code, Codex, Gemini CLI and other stdio MCP hosts. Reads Cortex's shared PostgreSQL store read-only (the Trace view also works without it, from session transcripts and git); it never writes memories. Renders Graph, an anatomical 3D brain view (MNI152-registered cortical mesh), Trace, Knowledge, Wiki, and Board — filterable by domain, emotion, consolidation stage.

/plugin marketplace add cdeust/Cortex then /plugin install hypermnesia-mcp-viz@cortex-plugins (same marketplace as Cortex).

97.8% Recall@10 on LongMemEval-S. Measured on the release tree.

Tested against published academic benchmarks with retrieval-only metrics — no LLM reader in the evaluation loop. Current figures: the v4.20.0 release, measured on 9 September 2026, as published in the Cortex README. They describe the PostgreSQL store with the cross-encoder reranker; the default SQLite store has no comparable run yet. The committed ablations do not establish that the 36 mechanisms improve retrieval, collectively or individually.

97.8% Recall@10 · LongMemEval-S
0.9046 MRR · LongMemEval-S
500 Questions · LongMemEval-S
97 Paper bibliography
BenchmarkScoreNotes
LongMemEval-S (ICLR 2025) · v4.20.0, 2026-09-0997.8% R@10, 0.9046 MRRLatest release with a published figure. 500 questions, ~115K tokens, single clean run — 19.4 points above the paper best (78.4%). Artifact
LongMemEval-S (ICLR 2025) · v4.14.1, 2026-07-1498.2% R@10, 0.9167 MRRHistorical. Same settings (n=500, single run, retrieval only), run against the live PostgreSQL store, not the isolated container. Artifact
LoCoMo (ACL 2024)not measured on v4.20.0No current-release figure yet; none is claimed here.
BEAM-100K (ICLR 2026)not measured on v4.20.0No current-release figure yet; none is claimed here.

All benchmarks use retrieval-only metrics. They do not measure whether an LLM writes a correct answer from the retrieved memories.

Memory is invisible.

You don’t manage memory. Cortex does. Every lifecycle stage is automatic.

Session start

Hot memories, anchored decisions, and team context inject automatically. No manual recall needed.

During work

PostToolUse hooks capture significant actions. Decisions auto-detect and protect from forgetting. File edits prime related memories via spreading activation.

Session end

A “dream” cycle runs automatically: decay old memories, compress verbose ones, consolidate episodic into semantic knowledge (CLS).

Between sessions

Memories cool naturally (Ebbinghaus forgetting curve). Important ones stay hot. Protected decisions never decay.

Retrieval pipeline

Signals fused server-side on PostgreSQL (in-process on SQLite, which has no trigram signal), then reranked client-side via FlashRank.

SignalSourcePaper
Vector similaritypgvector HNSW / sqlite-vecBruch et al. 2023
Full-text searchtsvector + ts_rank_cd / FTS5Bruch et al. 2023
Trigram similaritypg_trgmBruch et al. 2023
Thermodynamic heatEbbinghaus decay modelEbbinghaus 1885
RecencyExponential time decay—

Cortex pairs with sister projects.

Cortex is the brain — persistent memory across sessions. Codebase intelligence lives in ai-architect-mcp-codebase. All install as independent Claude Code plugins, each in its own marketplace; all three speak to each other via the same MCP layer.

Memory

hypermnesia-mcp (Cortex)

This page. 57 MCP tools, 11 hooks, 36 neuroscience mechanisms, 97-paper bibliography. SQLite default, PostgreSQL + pgvector optional. Stores what you decided, why, and surfaces it back.

  • remember / recall
  • get_causal_chain · navigate_memory
  • open_visualization — provided by hypermnesia-mcp-viz (Cortex Viz)
  • seed_project
Code intelligence

ai-architect-mcp-codebase in development

Cross-platform Rust MCP server. Indexes codebases in 11 languages into a property graph, resolves call chains across files, detects functional communities (Leiden-class), traces processes from entry points, builds hybrid BM25 + sparse TF-IDF + RRF search.

  • 27 MCP tools, 3,500+ tests, v0.15.0
  • 10 pipeline stages, one MCP tool per stage
  • Read-only: never writes code, opens PRs, or runs CI
  • /plugin install ai-architect-mcp-codebase@ai-architect-mcp-codebase-marketplace

Specialization

Each agent writes to its own topic in Cortex. Engineer’s debugging notes don’t clutter tester’s recall.

Transactive memory

Decisions auto-protect and propagate (Wegner 1987). When engineer decides “use Redis over Memcached,” every agent sees it next session.

Briefing

SubagentStart hook extracts task keywords, queries prior work, fetches team decisions, and injects as context prefix.

Code-aware

Cortex integrates AST symbols from ai-architect-mcp-codebase. Symbols imported by two projects literally sit between them on the map.

36 cited neuroscience mechanisms. Zero GPU.

Every mechanism from computational neuroscience, implemented as pure server-side inference. No black-box magic — every constant cites its source. The mechanisms are implemented and inspectable; the committed ablations do not establish that they improve retrieval.

★

Five-signal retrieval fusion

Vector similarity, full-text search, trigram matching, heat, and recency — a weighted sum computed server-side on PostgreSQL, weighted reciprocal-rank fusion without the trigram signal on SQLite, then a cross-encoder rerank.

✨

Surprise momentum

Test-time learning from Titans (Behrouz et al., NeurIPS 2025). Retrieval surprise modulates memory heat via EMA.

⚖

LTP / LTD / STDP

Long-term potentiation strengthens accessed memories. Long-term depression weakens neglected ones. Spike-timing-dependent plasticity adjusts Hebbian connection weights.

⚙

Coupled neuromodulation

Dopamine, norepinephrine, acetylcholine, serotonin — with cross-channel coupling (Doya 2002, Schultz 1997). Modulates encoding strength and retrieval priority.

◉

Microglial pruning

Stale memories pruned during consolidation. Homeostatic plasticity and adaptive decay preserve important facts while cleaning noise.

◆

Knowledge graph

Causal discovery builds a directed graph with Hebbian weights, facilitation/depression, and release probability. Navigate via Successor Representation BFS.

♦

Cognitive profiling

Extracts your 12D reasoning signature — thinking style, entry patterns, blind spots, cross-domain bridges — and pre-loads it every session via EMA updates.

♻

Sleep compute

Dream replay, interference resolution, CLS (episodic-to-semantic transfer), and engram competition. Background consolidation runs at session end.

☼

Neural visualization

Interactive force-directed graph via the read-only cortex-viz companion. Node size encodes importance, heat is shown on a data-only scale, quality arcs show reliability.

57 MCP tools. Organized by function.

From simple remember/recall to knowledge-graph traversal and cognitive profiling. All via natural language in Claude Code.

Memory

Store & retrieve

  • remember
  • recall
  • recall_hierarchical
  • consolidate
  • checkpoint
  • forget
  • anchor
  • rate_memory
  • validate_memory
Navigation

Graph & profiling

  • navigate_memory
  • get_causal_chain
  • detect_gaps
  • drill_down
  • detect_domain
  • explore_features
  • query_methodology
  • memory_stats
Advanced

Wiki & automation

  • narrative
  • get_project_story
  • assess_coverage
  • create_trigger
  • add_rule
  • sync_instructions
  • seed_project
  • unified_search

Five layers. Zero I/O in business logic.

Clean Architecture with strict inward-pointing dependencies. Retrieval fusion runs server-side on PostgreSQL, in-process on SQLite.

LayerResponsibilityKey detail
CorePure business logicZero I/O, imports only shared/
InfrastructureAll I/OSQLite / PostgreSQL, embeddings, file system
HandlersComposition roots57 MCP tool handlers wiring core + infrastructure
HooksLifecycle automation11 hook modules shared by the native Claude Code and Codex plugins; in Claude Code they run on SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SessionEnd, Notification, SubagentStart
SharedPure utilitiesPython stdlib only

How a memory and a decision move through these layers, in six diagrams, with every claim linked to the v4.22.0 source.

97-paper bibliography. The zetetic standard.

Every algorithm, constant, and threshold traces to a published paper, a measured ablation, or a documented engineering source. Nothing is guessed.

Retrieval

Information retrieval

  • Bruch et al. “Fusion Functions” (2023)
  • Collins & Loftus “Spreading Activation” (1975)
  • Joren et al. “Sufficient Context” (2025)
Encoding

Neuroscience — encoding

  • Friston “Cortical Responses” (2005)
  • Bastos et al. “Predictive Coding” (2012)
  • Doya “Metalearning” (2002)
  • Schultz “Prediction & Reward” (1997)
Plasticity

Plasticity & maintenance

  • Hebb (1949), Bi & Poo (1998)
  • Turrigiano “Self-Tuning Neuron” (2008)
  • Tse et al. “Schemas & Consolidation” (2007)
  • Wang et al. “Microglial Pruning” (2020)
  • Ebbinghaus Memory (1885)
  • … 97 papers total, see the release-tree bibliography
Consolidation

Consolidation

  • Kandel “Molecular Biology of Memory” (2001)
  • McClelland et al. “CLS” (1995)
  • Frey & Morris “Synaptic Tagging” (1997)
  • Josselyn & Tonegawa “Engrams” (2020)
  • Borbely “Two-Process Sleep” (1982)
Navigation

Retrieval & navigation

  • Behrouz et al. “Titans” (NeurIPS 2025)
  • Stachenfeld et al. “Predictive Map” (2017)
  • Ramsauer et al. “Hopfield Networks” (2021)
  • Kanerva “Hyperdimensional Computing” (2009)
Team

Team & preemptive

  • Wegner “Transactive Memory” (1987)
  • Zhang et al. “LLM Collaboration” (2024)
  • Bar “The Proactive Brain” (2007)
  • Smith & Vela “Context-Dependent” (2001)
  • McGaugh “Amygdala Modulates” (2004)
  • Adcock et al. “Reward-Motivated” (2006)

Ways to install.

Marketplace plugin, standalone MCP, setup script, or manual. Each gives you persistent memory for Claude Code.

Option A — Claude Code Marketplace (recommended)

> /plugin marketplace add cdeust/Cortex
> /plugin install hypermnesia-mcp

Cortex ships as its own independent marketplace — no combined monorepo install. The same marketplace also carries the read-only hypermnesia-mcp-viz (Cortex Viz): /plugin install hypermnesia-mcp-viz@cortex-plugins. The former cortex plugin is a deprecated shim. Restart your Claude Code session, then run /cortex-setup-project. It verifies the store, builds cognitive profiles from session history, seeds the codebase, imports conversation history, and runs a first consolidation, without asking questions. The plugin install registers the hooks; claude --init-only installs the runtime and the embedding model before the first session.

Option B — Standalone MCP (no plugin)

> claude mcp add hypermnesia-mcp -- uvx --from "hypermnesia-mcp[sqlite]" hypermnesia-mcp

Adds Cortex as a standalone MCP server via uvx. No hooks, no skills — just the 57 MCP tools. Requires uv installed. The same command works in Codex, Gemini CLI and other stdio MCP hosts; Codex also has a native plugin (codex plugin add hypermnesia-mcp-codex@cortex-codex-plugins) with the same 11 lifecycle hooks, sharing one memory store with Claude Code; the old neuro-cortex-memory package is deprecated on PyPI.

Option C — Clone + setup script

$ git clone https://github.com/cdeust/Cortex.git
$ cd Cortex
$ bash scripts/setup.sh        # macOS / Linux
$ python3 scripts/setup.py    # Windows / cross-platform

The opt-in PostgreSQL path. setup.sh installs PostgreSQL + pgvector (Homebrew on macOS, apt/dnf on Linux), creates the database and schema, downloads the embedding model (~100 MB). setup.py expects PostgreSQL to be running already; with CORTEX_MEMORY_STORE_BACKEND=sqlite it skips PostgreSQL and uses the SQLite store. Restart Claude Code after setup.

Configuration

VariableDefaultWhat it controls
DATABASE_URLempty — SQLite store, no PostgreSQL connectionPostgreSQL connection string; when set, it wins over the SQLite default
CORTEX_RUNTIMEauto-detectedcli (strict) or cowork (SQLite fallback)
CORTEX_MEMORY_DECAY_FACTOR0.95Per-session heat decay rate
CORTEX_MEMORY_HOT_THRESHOLD0.7Heat level considered “hot”
CORTEX_MEMORY_WRRF_VECTOR_WEIGHT1.0Vector similarity weight in fusion
CORTEX_MEMORY_WRRF_FTS_WEIGHT0.5Full-text search weight in fusion
CORTEX_MEMORY_WRRF_HEAT_WEIGHT0.3Thermodynamic heat weight in fusion
CORTEX_MEMORY_DEFAULT_RECALL_LIMIT10Max memories returned per query

73 settings in total at v4.24.0. See mcp_server/infrastructure/memory_config.py in the repo for the full list.

What gets installed

MCP server57 tools for memory, retrieval, profiling, navigation, wiki
SessionStart hookInjects anchors + hot memories + team decisions + checkpoint
UserPromptSubmit hookAuto-recalls relevant memories based on the user’s prompt
PostToolUse hooksAuto-captures significant actions; primes related memories via spreading activation
SessionEnd hookRuns the dream cycle: decay, compress, CLS based on activity
PreToolUse hooksDecision and dependency gates before Edit / Write
Notification hookSaves a checkpoint around context compaction
SubagentStart hookBriefs spawned agents with prior work + team decisions
SkillsWorkflow guides (invoke via /cortex-*)

Skills

CommandWhat it does
/cortex-rememberStore a memory with full write gate
/cortex-recallSearch memories with intent-adaptive retrieval
/cortex-consolidateRun maintenance (decay, compress, CLS)
/cortex-explore-memoryNavigate memory by entity/domain
/cortex-navigate-knowledgeTraverse the knowledge graph
/cortex-debug-memoryDiagnose memory system health
/cortex-profileView cognitive methodology profile
/cortex-setup-projectBootstrap a new project
/cortex-importImport memories from other memory systems
/cortex-recall-globalSearch knowledge shared across projects
/cortex-remember-globalStore knowledge that applies to every project
/cortex-wiki-authorWrite ADRs, specs and notes into the project wiki
/cortex-automateCreate prospective triggers

Runs locally. No data leaves your machine.

MCP over stdio, database on localhost, visualization on 127.0.0.1.

PracticeDetail
SQL / query safetyAll queries parameterized; dynamic columns via safe identifier binding
Network behaviorEmbedding and reranking model downloads on first use only; cortex-viz binds 127.0.0.1
Data flowNo external data exfiltration; embeddings computed locally
Input validationPydantic validation on all MCP tool inputs; length limits enforced
Secrets management.env / credentials in .gitignore

A numeric third-party audit score is not currently published for this release tree — this table lists verifiable engineering practices instead of an unsourced grade.

Free & open source

MIT licensed. 6,788 tests passing. 97-paper bibliography. Pairs with ai-architect-mcp-codebase (Rust codebase intelligence). Give your agent a brain.

Part of the engagement journey · Exhibit 02

Where Cortex fits in an engagement

Persistent memory is one of the instruments wired in during Claude Code activation — the 57 MCP tools above ship as part of that stage, then keep running through the paid pilot and the rollout you operate yourself.

Stage Exhibit 02 · Claude Code activation