Design Goals
Cortex is the product of a small number of explicit design goals. They are worth stating up-front because most of the architecture is downstream of them.
1. Local-first
Section titled “1. Local-first”All data lives on the local machine. The default storage is a directory and a SQLite database; both are owned by the user, both are easy to back up, both work offline.
Why: AI memory tends to drift toward hosted services. That is a poor fit for the kind of work that benefits from persistent memory in the first place — notes about clients, drafts, decisions, half-formed thoughts. Local-first removes the trust question.
2. Append-only at the edge
Section titled “2. Append-only at the edge”Capture is dumb. Anything that wants to write to Cortex appends a raw event to an inbox directory. No parsing, no schema enforcement, no foreign-key lookups. The capture path cannot fail because it has almost nothing to do.
Why: Reliability under load. Events arrive from session hooks, from manual captures, from meeting ingest, from external pipelines — sometimes concurrently. Pushing parsing into a separate normalize step means capture never blocks, and a malformed event never breaks the inbox.
3. Atomic records, stable IDs
Section titled “3. Atomic records, stable IDs”The normalize step turns raw events into records: small, self-contained markdown files with a YAML frontmatter, a stable ID, and a known scope. A record is addressable, citable, and dedupable.
Why: AI clients work better with structured handles than with prose. A record ID is something a client can reference, attach to an answer, supersede, or follow. Free text is something it has to re-read.
4. Filesystem-first storage
Section titled “4. Filesystem-first storage”Records live as files on disk in a PARA layout. The SQLite database is a sidecar — it indexes the filesystem rather than owning the data.
Why: Filesystems are the universal interface. Records can be edited by hand,
backed up by git, synced by anything that syncs files, inspected with cat,
and recovered from disk even if the database is corrupted. The database
accelerates queries; it does not gate access to the data.
5. MCP as the AI surface
Section titled “5. MCP as the AI surface”Cortex exposes its operations to AI clients through MCP, not through a client-specific API. Any model that speaks MCP gets the same surface.
Why: AI tooling is fragmenting fast. Building a Claude integration, a Codex integration, and a Cursor integration is a losing battle. MCP is the rare standard that several major clients have actually adopted — aligning with it once costs less than chasing the integrations.
6. Hooks at the lifecycle boundaries
Section titled “6. Hooks at the lifecycle boundaries”Cortex binds into AI client lifecycle events — SessionStart, PreCompact, Stop — rather than asking the user to drive memory operations manually.
Why: The user should not have to remember to capture. The right moments to read or write memory are exactly the moments where the client already raises events; Cortex just listens.
7. Distillation, not deletion
Section titled “7. Distillation, not deletion”Cortex accumulates. It does not aggressively prune. Instead, a periodic distillation step rolls many small records into higher-level summaries, leaving the originals in place.
Why: Raw records carry provenance and detail. Summaries carry signal. Both are useful at different time horizons. Throwing away detail to save space is a false economy when the storage costs are pennies and the retrieval quality is the actual constraint.