Cortex

Your coding agent forgets you every time you close the session. 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, your agent is a stranger to its own tools.

Cortex is a cross-platform persistent memory engine for AI coding agents, built on computational neuroscience. Codex, Gemini CLI, Claude Code, and any local stdio MCP host can use the same remember/recall, knowledge-graph, consolidation, and wiki tools. Claude Code's plugin adds automatic capture and injection hooks; other hosts use the same memory through explicit tool calls.

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 · 52 memory tools · 9 lifecycle hooks · a self-curating, continuously-groomed 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.

Claude Cowork works the same zero-setup way: the sandboxed environment is detected automatically (CLAUDE_ENVIRONMENT=cowork) and Cortex uses the local SQLite store — no PostgreSQL required.

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.

Claude Code plugin (marketplace):

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

Upgrading from the cortex plugin? The plugin was renamed hypermnesia-mcp in v4.15.0 (a community-directory name collision with an unrelated cortex plugin): claude plugin uninstall cortex && claude plugin install hypermnesia-mcp — your memories and configuration are untouched, storage paths do not change.

Upgrading from cortex-viz@cortex-plugins? Its Claude Code marketplace identity was renamed to hypermnesia-mcp-viz, first published in cortex-viz v3.1.0 (the rename commit itself was never tagged as v3.0.0 — that version number was pinned here for six days without a matching release; see cortex-viz's CHANGELOG). Run claude plugin uninstall cortex-viz@cortex-plugins, then claude plugin marketplace update cortex-plugins, then claude plugin install hypermnesia-mcp-viz@cortex-plugins. The retained cortex-viz@cortex-plugins item is a frozen, nonfunctional migration shim: it only prints this notice and exposes no MCP server or tools. The repository remains cdeust/cortex-viz; only its marketplace plugin identity changed.

Claude tool allowlists, hooks, skills, and agents must migrate both composed 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.

That is the whole install — zero configuration, no PostgreSQL, no system packages. The postInstall provisions Python dependencies and selects the local SQLite store (~/.claude/methodology/memory.db); the store schema auto-creates on first use. The embedding model is not downloaded at install time — it fetches lazily on first use (~100 MB, one-time; see PRIVACY.md) and runs fully offline afterwards. The plugin path registers all lifecycle hooks (session-start context injection, per-prompt auto-recall, auto-capture, compaction checkpointing, the autonomous wiki cycle) and the /cortex-setup-project command.

An existing PostgreSQL install is never downgraded: the installer detects a configured DATABASE_URL, a prior PostgreSQL backend marker, or a reachable local cortex database and keeps using it across plugin updates.

Upgrading the plugin to PostgreSQL (optional):

bash <plugin-dir>/scripts/install-plugin.sh --postgres   # <plugin-dir> = the installed plugin root

In one line: PostgreSQL adds connection-pooled concurrency (two psycopg_pool latency classes), server-side PL/pgSQL WRRF fusion, and pgvector HNSW ANN indexing — worth it for very large stores or a shared team database (see Under the Hood); the memory tools and retrieval contract are identical on both backends. After upgrading, run /cortex-setup-project once — it handles pgvector setup, database creation, the embedding-model pre-cache, profile building, codebase seeding, and hook registration.

What SQLite mode does not do (honest disclosure): the WRRF fusion runs in-process instead of server-side, without HNSW ANN indexing (fine at personal-store scale, slower at very large scale); and three PostgreSQL-only hook enrichments degrade to silent no-ops — cross-agent team-decision injection (agent_briefing, plus the banner's Team Decisions section), file-based preemptive context (preemptive_context), and pipeline symbol heat-bumps (pipeline_impact_bump). Session-start banners, auto-recall injection, auto-capture, checkpoints, and all 52 memory tools work on both backends.

Verify any install:

python3 -m mcp_server.doctor

The check list is backend-aware: on SQLite it verifies Python, the store opens, a writable methodology dir, and the pool-capacity invariant; on PostgreSQL it additionally checks the PG driver, DATABASE_URL, connection, and extensions. Exit 0 means ready.

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

Docker:

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-runtime

PyPI (uvx / pip) — best-effort hook-free compatibility:

uvx hypermnesia-mcp          # run the MCP server directly
pip install hypermnesia-mcp  # or install into your environment

The server is published on PyPI as hypermnesia-mcp (registry name io.github.cdeust/hypermnesia-mcp). Claude Code remains the primary integration because it adds the lifecycle hooks; PyPI is the best-effort hook-free stdio compatibility channel for Gemini CLI, Codex CLI, and other MCP hosts.

WSL / TLS client-cert / remote PostgreSQL: See deployment scenarios.

Use with other MCP hosts

The MCP server is host-agnostic: any host that can launch a stdio process gets the full tool surface — remember, recall, the wiki, navigation, consolidation, all 52 tools — on the default local SQLite store. What is not portable are the 9 lifecycle hooks, which are Claude Code plugin machinery. The server itself does not import or require those hooks at startup.

What works where (honest matrix):

…