Claude forgets you every time you close the tab. Every architecture decision you explained. Every debugging session where you traced a bug through four layers of abstraction. Every "remember, we decided to use event sourcing, not CRUD" correction. Gone. Next session, you're a stranger to your own tools.
Cortex is a persistent memory engine for Claude built on computational neuroscience. It remembers what you worked on, how you think, what you decided and why — not as a text dump shoved into context, but as a living memory system that consolidates, forgets intelligently, and reconstructs the right context at the right time.
It runs entirely on your machine — a local SQLite database by default (zero setup, no services to install), or PostgreSQL + pgvector when you want it. A 22 MB embedding model, no LLM in the retrieval loop, no data leaving localhost.
36 neuroscience mechanisms · 44 memory tools · 9 lifecycle hooks · a self-curating per-project wiki — all local, all open-source.
Getting Started
Cortex ships as a single-click MCP bundle (.mcpb). Download the latest hypermnesia-mcp.mcpb from Releases, then open it in Claude Desktop — Settings → Extensions installs it in one click.
It runs immediately on the built-in SQLite backend: zero configuration, no database to provision, nothing to set up. Memory persists to a local file under ~/.claude/methodology/. That's the whole install.
Want PostgreSQL + pgvector instead (for very large stores or a shared team database)? It's a single configuration field — see Configuration below. SQLite is the default; PostgreSQL is opt-in.
<details> <summary><strong>More options</strong> (Claude Code plugin, Clone, Docker)</summary>Claude Code plugin (marketplace):
claude plugin marketplace add cdeust/Cortex
claude plugin install cortexThe plugin path also registers the lifecycle hooks (session-start context injection, compaction checkpointing, the autonomous wiki cycle) and the /cortex-setup-project command. If you point the plugin at PostgreSQL, run /cortex-setup-project once — it handles pgvector installation, database creation, the embedding-model download, profile building, codebase seeding, and hook registration.
If you configured the PostgreSQL backend, verify the connection:
python3 -m mcp_server.doctorSeven checks in two seconds: Python, the PG driver, DATABASE_URL, connection, extensions, a writable methodology dir, and the pool-capacity invariant. Exit 0 means the PostgreSQL path is ready. (On the default SQLite backend the PostgreSQL checks report "not set" and can be ignored — SQLite needs no doctor.)
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-platformDocker:
git clone https://github.com/cdeust/Cortex.git && cd Cortex
docker build -t cortex-runtime -f docker/Dockerfile .
docker run -it \
-v $(pwd):/workspace \
-v cortex-pgdata:/var/lib/postgresql/17/data \
-v ~/.claude:/home/cortex/.claude-host:ro \
cortex-runtimePyPI (uvx / pip) — deprecated secondary channel:
uvx hypermnesia-mcp # run the MCP server directly
pip install hypermnesia-mcp # or install into your environmentThe server is published on PyPI as hypermnesia-mcp (registry name io.github.cdeust/hypermnesia-mcp). The supported install paths are the .mcpb bundle and the Claude Code marketplace above; PyPI is kept best-effort for legacy pip / uvx users.
WSL / TLS client-cert / remote PostgreSQL: See deployment scenarios.
</details>Configuration
Cortex needs no configuration to run — the SQLite backend is the default and requires nothing. Two optional settings let you change the storage backend; in the single-click bundle they appear as fields in Claude Desktop's extension settings, and everywhere else they map to environment variables.
| Setting | Env var | Default | What it does |
|---|---|---|---|
| Storage backend | CORTEX_MEMORY_STORE_BACKEND | sqlite* | sqlite runs fully local with zero setup. postgresql uses an external PostgreSQL + pgvector database (set the URL below). auto tries PostgreSQL and falls back to SQLite. |
| PostgreSQL URL | CORTEX_MEMORY_DATABASE_URL | (empty) | Only used when the backend is postgresql or auto. Example: postgresql://user:password@host:5432/cortex. Leave empty to stay on SQLite. Treated as sensitive. |
* The single-click bundle pins the backend to sqlite through the manifest. If you run the server directly (clone / Docker) without setting the variable, the underlying code default is auto — it tries PostgreSQL and falls back to SQLite.
That's the entire surface most users touch. Both backends expose the same 44 memory tools (47 with the optional automatised-pipeline + prd-spec-generator integrations) and the same retrieval contract; PostgreSQL adds server-side PL/pgSQL fusion and HNSW indexing that pays off at very large scale. Every other knob uses the CORTEX_MEMORY_ prefix — see mcp_server/infrastructure/memory_config.py.
Examples
A live, end-to-end run on the SQLite backend (44 tools registered) — store three memories, recall them by meaning, then check the store. The output is taken from the in-process FastMCP client (recall lists trimmed to the top hit). The harness writes with force: true for determinism, and the demo store already held a few earlier memories — so memory_stats totals exceed the three inserted here.
1 — Store a memory. It is stored with a heat score (force: true skips the dedup write-gate to keep the demo deterministic; omit it and a near-duplicate would be gated).
remember({
content: "Cortex stores memory in a local SQLite database by default — zero setup, no PostgreSQL required.",
tags: ["architecture", "decision"],
force: true
})
// → { stored: true, memory_id: 490, action: "stored", heat: 0.796 }2 — Recall by meaning, not keywords. The fused retrieval ranks the relevant memory first.
recall({ query: "how does cortex store memory by default?" })
// → memories[0] = {
// content: "Cortex stores memory in a local SQLite database by default — zero setup, no PostgreSQL required.",
// score: 0.0167, heat: 0.846, tags: ["architecture", "decision"]
// }3 — A different query surfaces a different memory. Stored "Anchored memories survive context compaction with maximum priority."; this recall puts it on top.
recall({ query: "what survives context compaction?" })
// → memories[0] = {
// content: "Anchored memories survive context compaction with maximum priority.",
// heat: 0.565, tags: ["compaction"]
// }4 — Inspect the store. has_vector_search: true confirms semantic search is live on SQLite.
memory_stats({})
// → { total_memories: 14, episodic_count: 8, semantic_count: 6,
// avg_heat: 0.942, has_vector_search: true }You rarely call these by hand: the lifecycle hooks (plugin install) inject the right memories at session start and capture new ones as you work. The tools are there when you want explicit control — anchor to pin an architecture constraint, consolidate to run a maintenance cycle, narrative to get the project's story so far.
What's new
v4.0.0 — the neuroscience model complete (13 new mechanisms). Cortex fills the remaining cognitive-science gaps so memory spans encoding → consolidation → retrieval → forgetting with a grounded mechanism at every stage: source/reality monitoring (C1) with a confabulation gate, recollection-vs-familiarity dual-process retrieval (C2), claim-conflict monitoring (A2), goal maintenance (A1), attentional-salience gating, habituation (E1), fear-extinction inhibitory learning (E2), stress/arousal encoding-gain modulation, a predictive-coding forward model, value/reward-weighted retention, procedural (skill) memory (B1), two-phase NREM/REM sleep consolidation (F1), and cued targeted reactivation (F2). One new MCP tool (recall_skills); each mechanism is cited to published work and exposed as a live system vital. 44 memory tools (47 with upstream integrations).
v3.25.0 — headless wiki-authoring hardened + active forgetting. The headless wiki worker now delegates read-only codebase analysis to your full zetetic specialist roster (architect, engineer, code-reviewer, test-engineer, security-auditor, …) under a hard Write/Edit/Bash deny ceiling that propagates to delegated subagents; it bills a logged-in Claude subscription by default (API key opt-in), and no-ops every Cortex hook in the child process to stop consolidation→authoring recursion and memory pollution. Root-cause fix: a variadic --add-dir had been swallowing the authoring prompt, silently failing every drain with a source root since 3.24. New memory mechanism — active forgetting: two Drosophila dopaminergic circuits (permanent Rac1 trace erosion under chronic interference + transient DAMB retrieval block), shipped with a falsification harness left failing where the model genuinely diverges from biology. Also: Windows cross-platform portability. (Davis & Zhong 2017; Sabandal et al. 2021)
v3.24.0–3.24.1 — MCPB manifest fix + cross-backend recall fix. 3.24.1 fixes recall (and every
…