Memory Cortex

Durable, inspectable memory for Codex, Claude Code, and MCP agents.

Your agents remember. You keep the evidence.

Memory Cortex carries decisions, preferences, and project knowledge across sessions without turning memory into an opaque vector dump. Every saved fact keeps provenance and version history. Run it locally, use Ollama offline, reuse an existing Codex login for fact extraction, or self-host it in your own Cloudflare account.

Public source preview: Build and run the CLI and macOS companion from source today. The npm packages and a Developer ID-notarized Mac download are not published yet.

Install from source · Try the examples · See how it works · View architecture diagrams · Explore the macOS app · Check release readiness · Browse the documentation

The native memory inspector shows provenance, version history, correction, and retraction using synthetic sample records.

Why Memory Cortex

Chat history is temporary. Giant instruction files become stale. Raw vector search can return a passage without explaining whether it is current, trusted, or even from the right project.

Memory Cortex gives an agent a governed memory layer:

• Remember across sessions. Deliberate memories and approved source facts remain available through MCP.

• Inspect the evidence. Facts retain source identity, authority, confidence, revisions, corrections, and retractions.

• Choose the boundary. Run model-free exact search, fully local Ollama, local storage with Codex extraction, compatible model endpoints, or a self-hosted Cloudflare composition.

• Automate without hiding control. Claude Code hooks can retrieve context and queue scrubbed session material automatically; inferred facts remain reviewable.

• Keep contexts separated. Every MCP process is bound to one space outside the tool payload. A tool call cannot choose another space.

What is included

These are source inventory facts, not adoption or benchmark claims.

How it works

flowchart LR
  Sources["Approved sources and agent sessions"] --> Gate{"Secret and policy gate"}
  Gate -->|"Suspected secret"| Quarantine["Sanitized quarantine record"]
  Gate -->|"Accepted"| Ingest["Chunk, index, and optionally extract"]
  Ingest --> Review["Lower-authority review queue"]
  Review -->|"Promote"| Ledger["Append-only fact ledger"]
  Manual["Deliberate user memory"] --> Ledger
  Ledger --> Search["Exact and semantic projections"]
  Search --> MCP["Space-bound MCP tools"]
  MCP --> Agents["Codex, Claude, and other MCP clients"]
  App["macOS companion"] --> Ledger

A complete normalized source crosses the secret gate before chunking, persistence, embedding, or model extraction. Provider output is untrusted and must match source evidence before it can become a review candidate.

Corrections do not silently overwrite history. They append a new version. Retractions append a tombstone. Exact and semantic matches remain separately labeled so callers can tell what kind of retrieval produced a result.

Read the visual walkthrough in How Memory Cortex works or the package-level design in Architecture.

Deployment choices

This table describes Memory Cortex's own storage, embedding, and extraction paths. A connected MCP client has a separate data boundary. For example, a hosted Codex or Claude client may send prompts, tool calls, and returned memory content to its provider under that client's configuration and terms.

Cloudflare is optional. Local installations use direct stdio MCP, private SQLite and filesystem state, and no Memory Cortex network listener.

The safe production pattern is one public codebase and private live installations. Databases, configuration, resource receipts, backups, and credentials stay outside Git. Production clients and schedulers point at a versioned installed runtime, never a disposable source checkout. See the deployment operating model.

Quickstart from source

For profile selection, client registration, backup, update, and uninstall, use the complete source-preview installation guide. The commands below are the shortest exact-only path.

Requirements

• macOS or Linux

• Node.js 22.13 through 22.x

• pnpm 10.32.1 through Corepack

From a checkout:

corepack enable
pnpm install --frozen-lockfile
pnpm build
mkdir -p dist-pack
pnpm --filter memory-cortex pack --pack-destination ./dist-pack
export CLI_TARBALL="$PWD/dist-pack/memory-cortex-1.0.0.tgz"

Until npm publication, run the packed source artifact with:

npx --yes --package "$CLI_TARBALL" memory-cortex --help

Fastest local start: exact-only

Exact-only needs no model, cloud account, or API key:

npx --yes --package "$CLI_TARBALL" memory-cortex init local \
  --install-id personal \
  --profile exact-only \
  --space Personal \
  --yes

Verify the durable installation:

npx --yes --package "$CLI_TARBALL" memory-cortex verify local \
  --install-id personal
npx --yes --package "$CLI_TARBALL" memory-cortex doctor local \
  --install-id personal

Reload the selected MCP client, then try:

Remember that my deployment label is Copper Finch.
What is my deployment label?

Fully local semantic memory with Ollama

Install Ollama, then download the default models:

ollama pull embeddinggemma:latest
ollama pull qwen3.5:4b
npx --yes --package "$CLI_TARBALL" memory-cortex init local \
  --install-id personal \
  --profile ollama-local \
  --space Personal \
  --yes

After the models are present, this profile uses only loopback Ollama services.

Local storage with Codex extraction

For an existing Codex CLI user:

ollama pull embeddinggemma:latest
codex login status
npx --yes --package "$CLI_TARBALL" memory-cortex init local \
  --install-id personal \
  --profile codex-hybrid \
  --space Personal \
  --yes

Storage and embeddings remain local. Memory Cortex reuses the Codex CLI login for fact extraction and does not ask for an OpenAI API key. Scrubbed extraction input still leaves the machine, so this is not an offline profile.

Cloud provisioning, compatible endpoints, folder consent, backup, restore, upgrade, and uninstall are covered in the operator guides.

Agent and client support

The installer can register Claude Code and Codex automatically. It prints complete stdio configuration for other supported clients. Automatic lifecycle memory is currently a Claude Code integration; Codex and other clients receive the full explicit MCP tool surface.

See MCP clients for exact capability and registration details.

Native macOS companion

The Apple-silicon source build provides a menu-bar extra and a full SwiftUI window. Its primary navigation is Home, Memories, Decisions, and Clean Up. Sources, System, and Privacy remain available as secondary routes or Settings surfaces, but are hidden from the everyday sidebar until they can complete a useful user job.

Users can search memories, inspect source and version history, promote review candidates, append corrections, retract current facts, and resolve exact duplicates through a guided keep A / stop using B workflow. Cleanup first shows both memories, then an append-only retraction preview, then a separate destructive confirmation. These are different and Remind me in 30 days are saved locally for that installation. The app uses the same governed core writer as MCP; Swift never opens the databases directly.

The current source tree also owns one GUI process and one canonical app window. A duplicate direct launch asks the existing process to activate, then exits before another helper process or app UI starts.

Clean Up explains why a pair was flagged, lets the user choose what remains current, and previews the append-only change before a separate confirmation.

cd apps/macos/MemoryCortex
./script/build-app.sh
./script/verify-app.sh
./script/run-app.sh --use-live-installations

Building and verification are isolated from durable installations. Source launch is deliberately different: the explicit flag acknowledges that the app will discover and can change the current account's live installations. The run helper refuses to start while another Memory Cortex GUI is already running.

The source build targets macOS 14 or newer on Apple silicon. It is ad-hoc signed for local testing. Developer ID signing, notarization, Intel support, and public binary distribution are separate release gates.

Read the macOS build guide and the native control-plane decision.

Security and credentials

• Suspected secrets are quarantined before indexing or extraction, but no detector can recognize every possible secret format.

• Cloudflare provisioning tokens are accepted only through a masked TTY and held in process memory for the provisioning operation. They are rejected in arguments, environment variables, config, journals, and logs.

• Long-lived local credentials live in macOS Keychain or Linux Secret Service. Worker secrets live in Cloudflare's encrypted secret facilities.

• Backups contain memory and must be protected, but exclude credential-vault values and local model files.

• Third-party connectors are trusted same-user code. The current connector host is not an operating-system sandbox.

• Hash chains are verifiable integrity evidence, not a claim that a compromised host is tamper-proof.

• Retraction and append-only history are not hard erasure.

Do not deliberately store passwords or tokens as memories. Read Security, the threat model, and the deployment operating model before using private sources.

Connectors

The repository includes provider and local connector packages plus a standalone authoring SDK, mock host, conformance runner, and clean-room examples.

Connector source exists at different qualification levels. A synthetic harness does not prove a live provider account, permission model, throttle behavior, or outage path. Check the connector acceptance record before describing an integration as production-qualified.

Start with the connector SDK guide and connector trust boundary.

Project status

The repository is being prepared as a public source preview. The local and Cloudflare compositions, package source, native app source, tests, and operator documentation are present. Historical acceptance records preserve the exact evidence and limitations observed at each engineering checkpoint.

The source preview is not ready to publish yet. The safest release path is a fresh, one-commit snapshot in a new public repository, not changing the visibility of this private development history. That snapshot still needs a full scan, a fresh-clone build and test, green hosted CI, and repository rules before the source-preview verdict can change to GO. See the current release-readiness review.

Separate gates remain closed for npm publication, a notarized Mac download, independent provider/account qualification, and general-availability support. One green release surface never waives a red one. See the publication checklist and release process.

Documentation

• Documentation map

• Source-preview installation

• Worked examples

• Architecture diagrams

• Current release-readiness review

• Native macOS UI audit

• Product overview

• How it works

• Architecture

• Local mode

• Deployment operating model

• Memory-system cutover

• Migrating from Cortex v4

• Backup and restore

• Operations

• Troubleshooting

• FAQ

• Product specification

• Historical acceptance evidence

Contributing and disclosure

Contributions are welcome. Start with CONTRIBUTING.md and run the complete local gate before opening a pull request. Use synthetic data only.

Do not open a public issue for a vulnerability. Use GitHub's private vulnerability reporting flow described in SECURITY.md.

Memory Cortex is licensed under the Apache License 2.0.