Cortex

Local-first, auditable AI memory substrate.

Cortex records what your AI agent does into an append-only, hash-chained event ledger. It derives structured memories from those events, scores them by salience and proof state, and builds context packs that tell the model exactly what it's looking at — including what was excluded, redacted, or flagged as unverified. Every memory carries its truth ceiling: LocalUnsigned, SelfSigned, RemoteSigned. Nothing gets silently promoted.

The problem it solves: LLM sessions are ephemeral. Anything the model learns is gone when the context window closes. Existing solutions (vector databases, fine-tuning) either lose the audit trail or require cloud infrastructure. Cortex is the middle path: durable, inspectable, local-first memory with a policy lattice that prevents an AI from laundering a guess into trusted history.

Trust boundary: Rust owns validation, storage, scoring, and audit. Models propose interpretations and are always bounded by a ceiling.

Install

cargo install crtx          # installs the `cortex` binary
cortex --version
cortex init                 # creates ~/.local/share/cortex/cortex.db + events.jsonl
cortex doctor --strict      # verify the store is healthy

Requires Rust 1.88+ (rust-toolchain.toml pins it; rustup handles upgrades).
Platform notes: binary is cortex on Linux/macOS, cortex.exe on Windows.
See docs/INSTALL.md for upgrade, uninstall, and data-directory details.

Use with Claude Code (or any MCP client)

Add to .claude/settings.json in your project:

Zero-gate mode — AI manages the full memory lifecycle, no confirmation token required:

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["serve"],
      "env": { "CORTEX_MCP_AUTO_COMMIT": "1" }
    }
  }
}

Manual mode — paste the confirmation token once per session (printed to stderr at startup):

{
  "mcpServers": {
    "cortex": {
      "command": "cortex",
      "args": ["serve"]
    }
  }
}

24 tools are available immediately across three tiers (session, supervised, confirmed).
See docs/MCP_GUIDE.md for the full tool reference and parameter schemas.

Autonomous session pattern

session start:  cortex_search("what you're working on")   ← pull relevant memories
                cortex_context()                          ← broader context pack if needed
                … do your work …
session end:    cortex_session_close({events_json: …})    ← index this session
                cortex_session_commit()                   ← auto in zero-gate mode

Memories are searchable from the next session after commit — the same-session gate (ADR 0047) prevents an AI from using its own in-flight work as trusted prior art.

Setting up Cortex via an LLM

Paste docs/LLM_SETUP.md to any capable LLM and it will install, initialize, and configure Cortex for your project autonomously.

Documentation

Architecture decisions: docs/adr/README.md · Design spec: docs/BUILD_SPEC.md

60-second demo

Uses the installed binary. Run from the cortex repo root (for the fixture file) or point SESSION at any session JSON.

cortex init --db /tmp/demo.db --event-log /tmp/demo.jsonl

# Ingest a one-event session (idempotent — safe to re-run).
SESSION="crates/cortex-cli/tests/fixtures/session-minimal.json"
cortex ingest "$SESSION" --db /tmp/demo.db --event-log /tmp/demo.jsonl

# Verify the hash chain end-to-end.
cortex audit verify --db /tmp/demo.db --event-log /tmp/demo.jsonl

# Deterministic reflection via the replay adapter (no LLM, no network).
cortex reflect --trace trc_01ARZ3NDEKTSV4RRFFQ69G5FAW --model replay \
  --db /tmp/demo.db --event-log /tmp/demo.jsonl

Expected output:

cortex init: db = /tmp/demo.db (created)
appended evt_01ARZ3NDEKTSV4RRFFQ69G5FAV
appended_count = 1
audit verify: /tmp/demo.jsonl (1 rows scanned, 0 failures)
{"episode_candidates":[{"summary":"Demo trace: user greeted the cortex CLI.",...}]}

Ollama (optional — local LLM for reflection and semantic search)

ollama serve                  # must be running before any Ollama-backed command
ollama pull llama3.1:8b       # for reflection / cortex run
ollama pull nomic-embed-text  # for semantic embeddings

cortex models list             # verify Ollama is reachable and list loaded models
cortex session close --live-reflect ./session.json   # real reflection via Ollama
cortex memory embed            # enrich memories with Ollama semantic embeddings

Configure in ~/.config/cortex/config.toml (Linux/macOS) or %APPDATA%\cortex\config.toml (Windows):

[llm]
backend = "ollama"

[llm.ollama]
endpoint = "http://localhost:11434"
# Get the digest: ollama show --modelfile llama3.1:8b | grep "^FROM"
model    = "llama3.1:8b@sha256:<64-char-hex-digest>"

[embeddings]
backend = "ollama"

[embeddings.ollama]
model = "nomic-embed-text"

The model ref must be digest-pinned — latest and plain tags are refused. See docs/WIRING_GUIDE.md §16b for the full config reference.

Workspace

13 crates published to crates.io under the crtx-* namespace:

Development

just check           # full quality gate: fmt + clippy + test + deny (mirrors CI)
just test            # cargo test --workspace
just publish-dry-run # verify all 13 crates package cleanly

Requires just (cargo install just).
Without it: cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace && cargo deny check

CI runs Ubuntu + macOS + Windows in parallel via Azure DevOps Pipelines. Every push runs:

• cargo check / clippy / fmt / test / deny
• taudit authority audit (gates on High+ findings)
• Four drills: anchor, v1-to-v2, restore, axiom admission

Contributing

See CONTRIBUTING.md for dev setup, architecture overview, and how to add CLI commands, MCP tools, and migrations.

Security

See SECURITY.md to report vulnerabilities.
Trust model and boundaries: docs/THREAT_MODEL.md.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.