Cortex: a local, cited memory layer for Claude, Cursor and other MCP clients

The problem Cortex targets: assistants that start from zero

Every assistant you connect to begins with no knowledge of your preferences, past decisions or vocabulary. You re-explain the same context in every new session. Cortex's stated goal is to compile a model of you once and serve it to those tools, so the assistant reasons with your judgment loaded in rather than asking for it again.

The audience is narrow and specific: people who already keep notes (the README names Obsidian and generic local notes folders), who have an export of chat history from ChatGPT, Claude, Perplexity or Notion, and who use at least one MCP client such as Claude Desktop, Cursor, Windsurf or Zed. If you use one assistant in a browser tab and keep no notes, there is nothing for Cortex to compile.

The project is trace-cortex/cortex-app, MIT licensed, written primarily in Python with a SwiftUI front end. The last push to the default branch was on 2026-08-26, which is recent enough that the repository is not dormant.

How the operating model is built: layers, graph and a sleep-time pass

Sources flow in through a review inbox, and you approve what becomes memory. Approved items land as typed, layered memory in a SQLite store that carries full-text search plus sqlite-vec vectors. The README lists seven layers: voice, preferences, decisions, facts, episodic, entities and topics. Deterministic extractors build them, with an optional LLM condenser layered on top.

Retrieval is the part worth reading closely. It walks what the README calls a trust-aware knowledge graph with bounded multi-hop recall, and offers a personalized-PageRank mode that surfaces what is connected to the query rather than what is lexically near it. Hops are budgeted and carry provenance, which is the mechanism behind the project's cite-or-abstain claim: an answer either points at source memory or declines.

The consolidation pass runs while you are away. The README describes it as bounded and deterministic: it resolves only contradictions that clear deterministic safety rules, source memory stays authoritative, and every decision is logged. It also pre-warms verified hot-context packs so the next agent request is served from a checked cache. That design choice trades freshness for predictability. If your notes change while the pass runs, the pre-warmed pack can lag until the next pass, and the README does not describe a manual trigger for re-warming.

The Contextual Memory Protocol and the per-session delta channel

CMP is the delivery format. It fits a model-calibrated SMP envelope using a token-aware knapsack, meaning the packer selects the subset of memory that fits a token budget instead of sending everything. Retrieval fuses BM25, sqlite-vec KNN, temporal and intent signals, reranks on-device, and cites or abstains.

The per-session delta channel is the more interesting constraint. The README states it never re-sends what an agent already holds, and that this is enforced by invariants with measured savings. In practice this means the first request in a session is expensive and later ones are cheap, so a client that opens a fresh session per turn gains nothing from the delta channel. The README points to docs/CMP_PROTOCOL.md for the invariants; that document is where you should look before relying on the savings claim in your own setup.

Packs are sha256-addressed and replayable, and the model itself lives as plain Markdown plus a rebuildable index. That combination is what makes vendor portability credible: the derived index can be thrown away and rebuilt, while the Markdown remains readable without Cortex installed.

Installing Cortex on macOS and connecting a first tool

The README gives a four-step install for the packaged app: download the latest DMG from the releases page, open it and drag Cortex into Applications, launch it (the build is Developer ID signed and notarized, so it opens without a Gatekeeper warning), then point it at a notes folder or import chats, review the first memories, and connect a tool. The app checks for updates on its own.

Building from source is documented separately. The macOS app builds with the script in the macos directory, and the Python engine needs Python 3.11 or later:

./macos/build.sh

python3 -m venv .venv && source .venv/bin/activate
pip install -r backend/runtime-requirements.txt
python3 -m pytest backend/tests

After installing the runtime requirements, the test suite runs against the backend. The README also documents a deterministic offline retrieval-quality gate, which is useful as a baseline before you change any retrieval settings:

python3 scripts/retrieval_eval.py

If you run the backend outside the packaged app, copy .env.example to .env. The packaged app generates its own API token; the example file expects you to supply one:

CORTEX_API_KEY=replace-with-a-long-random-token
CORTEX_DB_PATH=./backend/data/Cortex.vault/index.sqlite
CORTEX_PORT=8766

The engine binds to 127.0.0.1 on port 8766 by default, and the vault path defaults to ./backend/data/Cortex.vault. Keep CORTEX_ALLOW_INSECURE_DEV_TOKEN at 0 unless you are deliberately running development scripts with the sample dev-local-key token, because that flag exists precisely to accept a known-insecure token.

Where Cortex is the wrong tool

The README documents a macOS 13 or later app. There is no Windows, Linux, iOS, Android or browser client described, and the repository layout is consistent with that: a macos directory holding a SwiftUI app, and a backend directory holding the FastAPI engine. If your team is not on Macs, this project is not a candidate today.

The second limitation is the extraction path. The .env.example file states that if ANTHROPIC_API_KEY is unset, Cortex uses deterministic local extraction, and that the default embedding provider is a deterministic hash embedding with OpenAI available for higher recall. Deterministic extraction is predictable and offline, but it is also the weaker option by the project's own framing, since the alternative embedding provider is described as improving recall. You are choosing between quality and staying fully offline.

Third, the trust model assumes you actually review. Memory enters through an approval inbox, and the safety rules in the consolidation pass only resolve contradictions that clear deterministic checks. If you bulk-import and never approve, you get an inbox, not a model. The documentation also does not describe a rollback for a consolidation decision beyond the fact that decisions are logged.

How Cortex differs from running a notes MCP server

The obvious alternative is a plain notes MCP server: expose an Obsidian vault or a folder of Markdown files over MCP and let the assistant read files directly. That approach has real advantages. It has no database, no consolidation pass, no packing step, and nothing to approve. If your notes are already well organized, a file-reading MCP server may be all you need.

The difference in approach is what happens between the files and the model call. A file server returns whatever the assistant asks for. Cortex builds typed layers, walks a knowledge graph with budgeted hops, packs a token-bounded envelope, and cites or abstains. That machinery exists to answer questions a flat file listing handles badly: what did I decide about this last quarter, how do I usually phrase this, which topics connect to this one. It also exists to cut token cost through the delta channel.

You pay for that with a review step, a SQLite index that must be rebuilt when it drifts, and a macOS-only app. A file server has none of those costs and none of those capabilities. The honest split is that flat files suit retrieval of things you already know you wrote, while Cortex targets retrieval of things you have forgotten you wrote.

Maintenance, licence and the cost of upgrading

Cortex is MIT licensed, so you can read, modify and redistribute the source, including in commercial settings, provided the licence notice is preserved. That is a permissive arrangement with few strings. It is not legal advice, and if you plan to ship a modified build you should read the LICENSE file in the repository rather than this summary.

The upgrade path is the part to think about. The packaged app checks for updates on its own, and releases are cut frequently: v0.2.0-24 arrived on 2026-07-11, the day after v0.2.0-23, which itself followed v0.2.0-17 on 2026-07-07. Build numbers in that range suggest rapid iteration on a 0.2.x line, which means the storage schema and the CMP envelope are both moving. Because the SQLite index is described as rebuildable from the Markdown vault, a schema change should be recoverable, but the README does not document a migration procedure or a downgrade path.

Local backups have their own cost. The .env.example file sets CORTEX_BACKUP_RETENTION_COUNT to 20 and CORTEX_BACKUP_RETENTION_DAYS to 0, with the comment that count pruning is enabled by default while age pruning is opt-in because users may depend on older recovery archives. If you raise the count, you are trading disk space for recovery depth, and the file gives no guidance on sizing.

Optional cloud sync exists as an end-to-end-encryption design for multi-device use, opt-in and account-based, with data staying local unless enabled. The README links to docs/ACCOUNTS_ENCRYPTION_DESIGN.md, and the word design matters: read that document before treating sync as a shipped feature.

Editorial conclusion

Adopt Cortex if you work on macOS with MCP-capable assistants and want your notes and chat history turned into cited, inspectable memory you can erase in one act. Do not adopt it if you need Windows, Linux, iOS, Android or a browser client, or if you want a hosted service rather than a local engine on 127.0.0.1:8766. Before committing, verify two things in your own copy: that the packaged app generates its own CORTEX_API_KEY, and that your notes folder is small enough for the deterministic extraction path to finish before you connect a tool.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. trace-cortex/cortex-app on GitHub