Cortex

A local memory and project-ops layer for coding agents.

Coding agents forget everything the moment a session ends. Cortex gives them a memory that persists — and gives you one place to see, steer, and audit the work across every project they touch.

It runs entirely on your machine: one Node process, one SQLite file, no external services, no data leaving your laptop. It works with Claude Code and Codex out of the box.

Your agent → the Cortex hub on localhost:4317 → a memory that gets smarter every session, a command center, and an evening brief of what actually happened.

Contents: What it does · How it compares · How it works · The memory lifecycle · Quickstart · Connect your agent · Using the system · The dashboard · Autonomy tiers · CLI reference · Deploy · Security

What it does

🧠 Memory that survives sessions. As your agent finishes work, Cortex quietly captures the things worth keeping — a fix and how it was verified, a research finding, a blocker, a task that changed state. Generic "done!" chatter is thrown away. What's left is deduplicated, linked to related records with typed provenance, and ranked so the next session recalls the relevant past, not all of it — packed to fit a token budget you control.

🎛️ A command center. A dark web dashboard that puts blocked work, unresolved questions, and recent activity first. Search across projects with explained scores, inspect the token pack, browse tasks and the activity log, run a database audit, and explore an interactive graph of how your records connect.

🌆 An evening brief. One command (cortex eod) turns the day's raw records into a report: what got done (with evidence), what needs your eyes, what's queued for tonight — as text, JSON, or a rendered HTML page, optionally pushed to Telegram. An optional agent layer rewrites each item into plain English and adds a short "story of the day"; if that fails for any reason, the deterministic SQL report stands untouched.

🩺 A portfolio doctor. Cortex watches every project the hub knows about and tells you which are active, stalled, or quietly abandoned — with a per-project lifecycle you can set (active, waiting, maintenance, archived) so the noise stays down.

🎚️ Autonomy tiers. Each project carries a dial — watch, plan, assist, auto — that says how much autonomy an orchestrator may take with it, and a pin (CORTEX_NEVER_AUTOPILOT) that locks protected repos at watch forever. Cortex itself never launches agents; it is the policy and memory surface an external runner reads.

Related MCP server: Muninn

How it compares

There are several polished commercial memory layers for AI agents. They're good products — the honest difference is where your data lives and what the tool is for:

(Competitor details checked August 2026 — pricing and self-host options move fast; check their sites for current terms.)

Pick a paid platform when you're building a product that needs memory for thousands of end users, managed scaling, and SLAs.

Pick Cortex when the memory is for you and your coding agents: your codebase context never leaves your laptop, there's no per-request bill, it works offline, and you get the project-ops layer (tasks, briefs, autonomy tiers) that generic memory APIs don't try to be.

How it works

Cortex is a single local process. Your agents talk to it three ways — session hooks, an MCP server for mid-session calls, and a plain HTTP/CLI interface — and everything lands in one SQLite database that the dashboard, the evening brief, and the portfolio doctor all read.

flowchart LR
    CC["Claude Code"]
    CX["Codex"]

    subgraph HUB["Cortex hub · localhost:4317"]
      direction TB
      CAP["Capture policy<br/>dedup + quarantine + normalize"]
      DB[("SQLite<br/>node:sqlite")]
      LINK["Typed links (provenance)"]
      IDX["Full-text index<br/>(porter-stemmed)"]
      RANK["Ranking engine"]
      CAP --> DB
      DB --> LINK
      DB --> IDX
      RANK --> DB
    end

    WEB["Web command center"]
    EOD["Evening brief"]
    TG["Telegram"]

    CC -->|"hooks: recall / capture"| CAP
    CC -.->|"MCP tools, mid-session"| CAP
    CX -->|"CLI / HTTP API"| CAP
    HUB --> WEB
    HUB --> EOD
    EOD -.->|"daily report / needs you"| TG

No external dependencies for storage or search. The database is Node's built-in node:sqlite (that's why it needs Node ≥ 25) and search is a deterministic local ranker — no vector database, no embedding API, no keys. If you want a semantic arm in the ranking, set CORTEX_EMBEDDINGS=1 and Cortex blends embedding cosine similarity (via a local Ollama model, nomic-embed-text by default) with the keyword score — still fully local.

The memory lifecycle

Every session is a loop: recall relevant context at the start, capture durable takeaways at the end. The signal survives; the chatter doesn't.

sequenceDiagram
    participant A as Agent
    participant H as Cortex hook
    participant P as Capture policy
    participant DB as SQLite

    rect rgb(30,40,55)
    Note over A,DB: Session start
    A->>H: SessionStart
    H->>DB: recall ranked context (token-budgeted)
    DB-->>A: compact project brief
    end

    Note over A,DB: ...work happens...

    rect rgb(45,35,50)
    Note over A,DB: Session stop
    A->>H: Stop (full transcript)
    H->>P: any durable takeaways?
    P->>P: discard chatter · dedup · normalize
    P->>DB: store fix / research / blocker / task change
    DB->>DB: link to related records + index
    end

What gets captured

Generic completion chatter ("Done!", "Let me know if you need anything else") is discarded before it ever reaches the database.

How recall ranks results

Search needs no API key. Its deterministic score blends four signals, so a verified older fix can still outrank recent noise:

score  =  lexical relevance          (does the text match?)
        + typed graph proximity       (is it linked to what you're touching?)
        + record quality              (verified > unverified, fix > chatter)
        + recency decay               (newer counts more, but doesn't win alone)
        ─────────────────────────────
        then packed to fit your token budget

Two more guards keep the brief honest: an off-topic filter drops records that name another project and never this one, and a Supersedes: [m:id] marker in any new decision cleanly retires the one it reverses instead of letting both rank forever.

Quickstart

Five minutes, four steps. The only requirement is Node.js ≥ 25 (Cortex uses the built-in node:sqlite module — no database to install, nothing to compile).

1. Get the code and install:

git clone https://github.com/gsl0001/Cortex.git cortex
cd cortex
npm install

2. Set a write token. This is just a password you make up — anything long and random. Cortex refuses to save anything until it exists:

export CORTEX_TOKEN="$(openssl rand -hex 24)"

On Windows: setx CORTEX_TOKEN "any-long-random-string", then open a new terminal.

3. Build the dashboard and start the hub:

npm run web:build
npm start

4. Open http://127.0.0.1:4317 — that's your dashboard. It will be empty; that's normal. It fills up as your agents work.

The server only listens on your own machine. Nothing is sent anywhere.

Next: connect your agent so sessions start feeding it.

Connect your agent

Claude Code

Install the hooks into any project you want remembered:

node src/cli.js claude install --project /path/to/your/project

From then on, Claude recalls compact project context at the start of a session and Cortex captures durable takeaways when it stops — automatically.

Mid-session recall (MCP)

Hooks cover session boundaries. To let an agent search or save memory during a session, start the server (npm start) and register the MCP server in the project's .mcp.json:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["/absolute/path/to/cortex/src/mcp.js"],
      "env": {
        "CORTEX_URL": "http://127.0.0.1:4317",
        "CORTEX_TOKEN": "${CORTEX_TOKEN}",
        "CORTEX_AGENT": "claude-code"
      }
    }
  }
}

Use the absolute path to src/mcp.js in your Cortex checkout — your agent launches this from your project's directory, not Cortex's.

Six tools are exposed: memory_search, memory_get, memory_remember, memory_recall_task, memory_update_task, memory_lesson. The session brief cites records by id ([m:42]); memory_get pulls the full record on demand, so the brief itself can stay a compact stub index.

Codex uses the same CLI and HTTP API.

Using the system

A typical end-to-end flow, from zero to a self-improving memory:

flowchart LR
    S1["1 · Start the hub<br/>npm start"] --> S2["2 · Connect a project<br/>claude install"]
    S2 --> S3["3 · Work normally<br/>fix, verify, ship"]
    S3 --> S4["4 · Session ends<br/>Cortex captures the fix"]
    S4 --> S5["5 · Next session<br/>it recalls what matters"]
    S5 --> S3
    S5 -.-> S6["6 · Evening: cortex eod<br/>the day, in one report"]

1. Start the hub once — it stays running and serves the dashboard at localhost:4317.

2. Connect a project: node src/cli.js claude install --project ~/code/myapp. Now every Claude Code session in that repo recalls context on start and captures durable takeaways on stop.

3. Work normally. Fix a bug and verify it. You don't do anything special — Cortex watches the session boundaries.

4. The session ends and Cortex stores the fix plus how it was verified, throwing away the surrounding chatter.

5. Next session, it remembers. Your agent opens with a brief: recent fixes, open blockers, and relevant research — ranked and trimmed to a token budget.

6. Search or track work anytime — from the dashboard or the CLI:

# "How did we solve this before?"
node src/cli.js search --project ~/code/myapp --query "auth redirect loop"

# See the current project brief the agent would receive
node src/cli.js brief --project ~/code/myapp

# Capture a task, then let a human or agent pick it up
node src/cli.js task add --project ~/code/myapp --title "Rate-limit the export endpoint" --type chore --priority high
node src/cli.js next-task --project ~/code/myapp --claim --agent claude-code

7. End the day with one report. node src/cli.js eod --html reports/eod/today.html --notify builds the evening brief — done work with evidence, a verify queue, what's blocked, tonight's open items — and can ping it to Telegram. Schedule it (see scripts/eod-brief.ps1 for a Windows Task Scheduler example) and you get a daily digest for free.

The dashboard

The web command center (dark, keyboard-friendly) is organized around what needs attention first:

Autonomy tiers

Cortex does not launch agents. What it holds is the policy: a per-project dial that says how much autonomy an external orchestrator (your own runner, a cron job, a night-shift script) may take, readable over the same HTTP API as everything else.

Every project starts at watch — a newly-seen repo is never autonomous by default. Set a tier from the dashboard's Control Center or POST /api/v1/projects/tier.

The pin. Set CORTEX_NEVER_AUTOPILOT to a comma-separated list of absolute paths (production repos, anything that moves money) and those projects are pinned at watch — a floor no setting write can raise. Entries are normalized like project paths themselves, so a subdirectory or mixed-separator spelling of a protected repo still collapses onto the pin. See SETUP.md for details.

CLI reference

Run node src/cli.js with no arguments for the full, always-current list.

node src/cli.js search --project . --query "close fill" --max-tokens 1500
node src/cli.js task add --project . --title "Fix login redirect" --type bug --priority high
node src/cli.js audit --all --json

Deploy with Docker

docker build -t cortex .
docker run -d \
  -e CORTEX_TOKEN="your-long-random-token" \
  -p 4317:4317 \
  -v cortex-data:/data \
  cortex

The image builds the web UI, binds 0.0.0.0 (so port-mapping works), and stores the database on the /data volume. Because it binds beyond loopback, the server requires CORTEX_TOKEN and refuses to start without it. Put it behind a reverse proxy with TLS if you expose it beyond localhost.

Configuration

Only CORTEX_TOKEN is required. Everything else has a sensible default — see .env.example for the common knobs (CORTEX_DB, CORTEX_HOST, CORTEX_PORT, CORTEX_NEVER_AUTOPILOT) and SETUP.md for the full setup, agent adapters, notifications, and the autonomy-tier details.

Security model

• Loopback by default. The server only binds a public interface when you opt in (CORTEX_ALLOW_REMOTE=1), and even then refuses to start without a token.

• Writes are default-deny. Every POST/PATCH/DELETE is rejected until CORTEX_TOKEN is set — even on localhost.

• Reads are gated off-loopback. When bound beyond loopback, read endpoints require the token too — not just writes.

• Captured text is quarantined. Session captures that look like prompt injection ("ignore previous instructions…", and a broad family of phrasings) are flagged on the way in, so a poisoned transcript can't smuggle instructions into a future session's brief.

• Autonomy is pinned, not promised. Repos listed in CORTEX_NEVER_AUTOPILOT are locked at the watch tier — no API write can raise them.

• Treat CORTEX_TOKEN like an SSH key. The hub schedules local CLI jobs (transcript distillation, the evening digest), so treat a leaked token as more than read access. Keep the hub on loopback unless you front it with an authenticating reverse proxy over TLS.

Development

npm test            # backend suite (node:test) — 348 tests
npm run web:test    # web UI tests (vitest) — 51 tests
npm run web:build   # production build

Back up

Stop the server, copy the SQLite file, restart, and rebuild the index:

cp ~/.cortex/cortex.sqlite ~/.cortex/cortex.backup.sqlite
node src/cli.js index rebuild

License

MIT — see LICENSE.