# 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](INSTALL.md) ·
[Try the examples](docs/EXAMPLES.md) ·
[See how it works](docs/HOW-IT-WORKS.md) ·
[View architecture diagrams](docs/ARCHITECTURE-DIAGRAMS.md) ·
[Explore the macOS app](#native-macos-companion) ·
[Browse the documentation](docs/README.md)

![Memory Cortex memory inspector showing synthetic sample records](apps/macos/MemoryCortex/design-qa/actual-memories-final-v2.png)

_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.

| Surface | Current source candidate |
| --- | --- |
| Deployment modes | Local and self-hosted Cloudflare |
| Local profiles | Exact-only, Ollama, Codex hybrid, OpenAI-compatible |
| MCP tools | 14 memory, provenance, health, and search operations |
| Connector packages | Local files, Gmail, Microsoft Graph, IMAP, JMAP, Slack, Notion, CalDAV |
| MCP clients | Claude Code, Codex, Claude Desktop, Cursor, generic stdio |
| Native companion | macOS menu bar and SwiftUI application source |
| Isolation | Any number of named spaces per installation |
| License | Apache-2.0 |

## How it works

```mermaid
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](docs/HOW-IT-WORKS.md)
or the package-level design in [Architecture](ARCHITECTURE.md).

## Deployment choices

| Profile | Storage | Embeddings | Fact extraction | Memory Cortex inference boundary |
| --- | --- | --- | --- | --- |
| Exact-only | Local | None | None | Local only; no model inference |
| Ollama local | Local | Ollama | Ollama | Local only after software and models are installed |
| Codex hybrid | Local | Local Ollama | Codex CLI/service | Scrubbed extraction input is sent to Codex |
| OpenAI-compatible | Local | Chosen endpoint | Chosen endpoint | Depends on the configured endpoints |
| Cloud | Operator-owned Cloudflare | Configured cloud model | Configured extractor | Selected cloud and model-provider boundary |

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](docs/DEPLOYMENT-OPERATING-MODEL.md).

## Quickstart from source

For profile selection, client registration, backup, update, and uninstall, use
the complete [source-preview installation guide](INSTALL.md). 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:

```sh
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:

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

### Fastest local start: exact-only

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

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

Verify the durable installation:

```sh
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:

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

### Fully local semantic memory with Ollama

Install [Ollama](https://ollama.com/download), then download the default models:

```sh
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:

```sh
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](docs/README.md).

## Agent and client support

| Client | MCP tools | Automatic prompt/session hooks |
| --- | ---: | ---: |
| Claude Code | Yes | Yes |
| Codex CLI | Yes | No |
| Claude Desktop | Yes | No |
| Cursor | Yes | No |
| Generic stdio MCP | Yes | No |

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](docs/MCP-CLIENTS.md) 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.

![Memory Cortex Clean Up comparing two synthetic exact-duplicate memories before a guarded retraction](docs/audits/2026-07-21-ui/14-clean-up-remediated.png)

_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._

```sh
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](apps/macos/MemoryCortex/README.md) and the
[native control-plane decision](docs/ADR-0005-native-macos-control-plane.md).

## 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](SECURITY.md), the [threat model](docs/THREAT-MODEL.md), and the
[deployment operating model](docs/DEPLOYMENT-OPERATING-MODEL.md) 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](docs/acceptance/PHASE-3.2-CONNECTORS.md) before
describing an integration as production-qualified.

Start with the [connector SDK guide](docs/CONNECTOR-SDK.md) and
[connector trust boundary](docs/ADR-0004-connector-trust-boundary.md).

## 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
release-readiness review (document retired from the public tree).

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](docs/PUBLICATION-CHECKLIST.md) and
[release process](docs/RELEASING.md).

## Documentation

- [Documentation map](docs/README.md)
- [Source-preview installation](INSTALL.md)
- [Worked examples](docs/EXAMPLES.md)
- [Architecture diagrams](docs/ARCHITECTURE-DIAGRAMS.md)
- [Native macOS UI audit](docs/UI-AUDIT-2026-07-21.md)
- [Product overview](docs/PRODUCT-OVERVIEW.md)
- [How it works](docs/HOW-IT-WORKS.md)
- [Architecture](ARCHITECTURE.md)
- [Local mode](docs/LOCAL-MODE.md)
- [Deployment operating model](docs/DEPLOYMENT-OPERATING-MODEL.md)
- [Memory-system cutover](docs/CUTOVER-CHECKLIST.md)
- [Migrating from Cortex v4](docs/MIGRATING-FROM-CORTEX-V4.md)
- [Backup and restore](docs/BACKUP-RESTORE.md)
- [Operations](docs/OPERATIONS.md)
- [Troubleshooting](docs/TROUBLESHOOTING.md)
- [FAQ](docs/FAQ.md)
- [Product specification](docs/PRODUCT-SPEC.md)
- [Historical acceptance evidence](docs/acceptance/)

## Contributing and disclosure

Contributions are welcome. Start with [CONTRIBUTING.md](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](SECURITY.md).

Memory Cortex is licensed under the [Apache License 2.0](LICENSE).