cdeust/Cortex

Keep decisions, fixes and project context between sessions, and inspect what was retrieved.
Runs locally by default. No account, no API key, no server to manage.
---
**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 neuroscience mechanisms · 57 memory tools · 11 lifecycle hooks · a self-curating per-project wiki — all local, all open-source, MIT.**
Install
**Claude Code** — add the marketplace and install the plugin:
Update the same way, one command:
**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:
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.
The first session installs Cortex's runtime into the plugin's data directory (about a minute
on a cold machine; a Mac whose python3 is older than 3.10 also gets a private CPython 3.12),
then shows Cortex ready: , memories; , or Cortex not ready:
with the cause. Semantic search installs in the background; until it lands the same line says
recall is keyword-only.
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 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.
Upgrading from an older plugin identity
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.
The visualization companion, hypermnesia-mcp-viz ,
was renamed the same way:
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