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. 52 MCP tools. 9 Claude Code hooks. Native AST call-graph via ai-architect-mcp-codebase. 97-paper bibliography. 97.8% Recall@10 on LongMemEval-S (v4.20.0). No GPU.
> /plugin install hypermnesia-mcp
Local-first — SQLite by default. PostgreSQL 15+ with pgvector + pg_trgm optional for larger corpora.
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).
State-of-the-art recall. 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.
| Benchmark | Score | Notes |
|---|---|---|
| LongMemEval-S (ICLR 2025) · v4.20.0, 2026-09-09 | 97.8% R@10, 0.9046 MRR | Current release. 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-14 | 98.2% R@10, 0.9167 MRR | Historical, same protocol. Artifact |
| LoCoMo (ACL 2024) | not measured on v4.20.0 | No current-release figure yet; none is claimed here. |
| BEAM-100K (ICLR 2026) | not measured on v4.20.0 | No current-release figure yet; none is claimed here. |
All benchmarks use retrieval-only metrics. High retrieval MRR bounds downstream QA regardless of reader model.
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, then reranked client-side via FlashRank.
| Signal | Source | Paper |
|---|---|---|
| Vector similarity | pgvector HNSW / sqlite-vec | Bruch et al. 2023 |
| Full-text search | tsvector + ts_rank_cd / FTS5 | Bruch et al. 2023 |
| Trigram similarity | pg_trgm | Bruch et al. 2023 |
| Thermodynamic heat | Ebbinghaus decay model | Ebbinghaus 1885 |
| Recency | Exponential 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.
hypermnesia-mcp (Cortex)
This page. 52 MCP tools, 9 hooks, 36 neuroscience mechanisms, 97-paper bibliography. SQLite default, PostgreSQL + pgvector optional. Stores what you decided, why, and surfaces it back.
remember/recallget_causal_chain·navigate_memoryopen_visualization— provided by hypermnesia-mcp-viz (Cortex Viz)seed_project
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.
- 26 MCP tools, 1,200+ tests, v0.11.1
- 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 a paper.
WRRF retrieval fusion
Vector similarity, full-text search, trigram matching, heat decay, temporal proximity, entity density, emotional resonance, access frequency, and consolidation state — fused server-side.
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.
52 MCP tools. Organized by function.
From simple remember/recall to knowledge-graph traversal and cognitive profiling. All via natural language in Claude Code.
Store & retrieve
- remember
- recall
- recall_hierarchical
- consolidate
- checkpoint
- forget
- anchor
- rate_memory
- validate_memory
Graph & profiling
- navigate_memory
- get_causal_chain
- detect_gaps
- drill_down
- detect_domain
- explore_features
- query_methodology
- memory_stats
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.
| Layer | Responsibility | Key detail |
|---|---|---|
| Core | Pure business logic | Zero I/O, imports only shared/ |
| Infrastructure | All I/O | SQLite / PostgreSQL, embeddings, file system |
| Handlers | Composition roots | 52 MCP tool handlers wiring core + infrastructure |
| Hooks | Lifecycle automation | Claude Code hooks on SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SessionEnd, Notification, SubagentStart |
| Shared | Pure utilities | Python 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.
Information retrieval
- Bruch et al. “Fusion Functions” (2023)
- Collins & Loftus “Spreading Activation” (1975)
- Joren et al. “Sufficient Context” (2025)
Neuroscience — encoding
- Friston “Cortical Responses” (2005)
- Bastos et al. “Predictive Coding” (2012)
- Doya “Metalearning” (2002)
- Schultz “Prediction & Reward” (1997)
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
- 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)
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 & 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 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. This handles database creation, embedding model download, cognitive profile building from session history, codebase seeding, conversation import, and hook registration. Zero manual steps.
Option B — Standalone MCP (no plugin)
Adds Cortex as a standalone MCP server via uvx. No hooks, no skills — just the 52 MCP tools. Requires uv installed. The same command works in Codex, Gemini CLI and other stdio MCP hosts; the old neuro-cortex-memory package is deprecated on PyPI.
Option C — Clone + setup script
$ cd Cortex
$ bash scripts/setup.sh # macOS / Linux
$ python3 scripts/setup.py # Windows / cross-platform
Installs SQLite by default; optionally PostgreSQL + pgvector (Homebrew on macOS, apt/dnf on Linux) for larger corpora, creates the database, downloads the embedding model (~100 MB). Restart Claude Code after setup.
Configuration
| Variable | Default | What it controls |
|---|---|---|
| DATABASE_URL | SQLite (default store) / postgresql://127.0.0.1:5432/cortex | Backend connection string |
| CORTEX_RUNTIME | auto-detected | cli (strict) or cowork (SQLite fallback) |
| CORTEX_MEMORY_DECAY_FACTOR | 0.95 | Per-session heat decay rate |
| CORTEX_MEMORY_HOT_THRESHOLD | 0.7 | Heat level considered “hot” |
| CORTEX_MEMORY_WRRF_VECTOR_WEIGHT | 1.0 | Vector similarity weight in fusion |
| CORTEX_MEMORY_WRRF_FTS_WEIGHT | 0.5 | Full-text search weight in fusion |
| CORTEX_MEMORY_WRRF_HEAT_WEIGHT | 0.3 | Thermodynamic heat weight in fusion |
| CORTEX_MEMORY_DEFAULT_RECALL_LIMIT | 10 | Max memories returned per query |
73 settings in total at v4.21.0. See mcp_server/infrastructure/memory_config.py in the repo for the full list.
What gets installed
| MCP server | 52 tools for memory, retrieval, profiling, navigation, wiki |
| SessionStart hook | Injects anchors + hot memories + team decisions + checkpoint |
| UserPromptSubmit hook | Auto-recalls relevant memories based on the user’s prompt |
| PostToolUse hooks | Auto-captures significant actions; primes related memories via spreading activation |
| SessionEnd hook | Runs the dream cycle: decay, compress, CLS based on activity |
| PreToolUse hooks | Decision and dependency gates before Edit / Write |
| Notification hook | Saves a checkpoint around context compaction |
| SubagentStart hook | Briefs spawned agents with prior work + team decisions |
| Skills | Workflow guides (invoke via /cortex-*) |
Skills
| Command | What it does |
|---|---|
| /cortex-remember | Store a memory with full write gate |
| /cortex-recall | Search memories with intent-adaptive retrieval |
| /cortex-consolidate | Run maintenance (decay, compress, CLS) |
| /cortex-explore-memory | Navigate memory by entity/domain |
| /cortex-navigate-knowledge | Traverse the knowledge graph |
| /cortex-debug-memory | Diagnose memory system health |
| /cortex-profile | View cognitive methodology profile |
| /cortex-setup-project | Bootstrap a new project |
| /cortex-import | Import memories from other memory systems |
| /cortex-recall-global | Search knowledge shared across projects |
| /cortex-remember-global | Store knowledge that applies to every project |
| /cortex-wiki-author | Write ADRs, specs and notes into the project wiki |
| /cortex-automate | Create prospective triggers |
Runs locally. No data leaves your machine.
MCP over stdio, database on localhost, visualization on 127.0.0.1.
| Practice | Detail |
|---|---|
| SQL / query safety | All queries parameterized; dynamic columns via safe identifier binding |
| Network behavior | Embedding model download on first run only; cortex-viz binds 127.0.0.1 |
| Data flow | No external data exfiltration; embeddings computed locally |
| Input validation | Pydantic 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.
Where Cortex fits in an engagement
Persistent memory is one of the instruments wired in during Claude Code activation — the 52 MCP tools above ship as part of that stage, then keep running through the paid pilot and the rollout you operate yourself.