Cortex

Cortex

[](https://github.com/dereksantos/cortex/actions/workflows/test.yml) [](go.mod) [](LICENSE)

A coding harness with a continuous learning loop. Cortex owns the coding loop (cortex code / cortex repl / cortex run) and runs Think and Dream in the background between turns. Small local models do the continuous integration work; a frontier model can be invoked at query time and receive pre-computed context.

> Status: Experimental. The core capture → store → retrieve → inject > pipeline works and is in daily use on the author's machine, but Cortex > is a research-grade tool, not a polished product. Pre-DAG-protocol > baselines record ABR 0.586 (recorded in docs/eval-journal.md); the > DAG ops landing under audit slice K + the eval migration under E are > what move that upward. Small Ollama models (≤3B params) have measured > below the floor for insight extraction — llama3.1:8b or larger, or > ANTHROPIC_API_KEY, is recommended. Expect rough edges, breaking > changes, and bugs that may require reading code to diagnose.

What Cortex Does

Cortex performs continuous context integration as part of its own coding loop — observing events as they happen, reconciling new information against existing knowledge, and surfacing relevant context on the next turn. It runs as a single binary; the REPL hosts the long-lived process and drives the background cognition (Think, Dream) on its idle hook. Decisions, patterns, and corrections are stored through fast mechanical retrieval (Reflex) backed by an asynchronous agentic loop (Reflect, Resolve, Think, Dream).

The role sits within the framework of cognitive architectures for language agents (CoALA) and is closely related to sleep-time / background-agent patterns (Letta) and memory-evolution approaches (A-Mem). Two architectural commitments shape Cortex's particular implementation:

Inverse activity gradient on background processing. Think runs while you're actively working at reduced budget, doing only what spare cycles allow. Dream runs while you're idle and grows with idle time, capped at a configurable maximum. This refines the binary active/idle split common in sleep-time approaches with a smooth response to host activity. Both modes are bounded by design.

Mechanical foreground with a latency target. Reflex aims to keep retrieval on the critical path fast — --study `, or edit the written config by hand.

Config is layered: ~/.cortex/config.json (user — set once) is inherited by every project, and a project may override per-role in its own .cortex/config.json. API keys are referenced by env-var name (key_env) and never written to disk.

Two ways to get set up

• Hand it to your agent. Point Claude Code, Cursor, or whatever agent you

already use at this section. The config schema is small and the cortex setup flags are deterministic, so it can wire everything up for you.

• Let Cortex set itself up. cortex setup --free && cortex init && cortex repl

gives you a working free agent immediately. From inside the loop, ask it to refine its own setup — it has shell access and the cortex setup command, so it can detect models, edit ~/.cortex/config.json, and switch backends itself.

cortex install exists as a compatibility verb (it now just ensures .cortex/ is initialized and reports local LLM availability — no external editor / hook wiring is done).

Multi-Agent / CI Setup

Cortex's capture and search paths work as standalone CLI tools. Any external process can drive them, which is enough to give multiple agents a shared context pool over the same .cortex/ directory.

go build -o bin/cortex ./cmd/cortex
./bin/cortex init                                                 # one-time per project
./bin/cortex capture --type=decision --content="Use PostgreSQL"   # record an event
./bin/cortex ingest                                               # drain journal → DB
./bin/cortex search "database"

The journal (.cortex/journal//) uses per-segment flock for cross-process capture safety; storage hydrates from JSONL projection files. Concurrent writers may hit brief locks under heavy parallel writes. cortex init does not require any external editor / IDE installation.

Cognitive Architecture

Cortex uses five cognitive modes, inspired by how humans process information:

| Mode | Type | Speed | Purpose | |------|------|-------|---------| | Reflex | Mechanical | # Entity relationships (was: graph)

### Memory ops

```bash
cortex capture --type=decision --content="..."   # Record an event from the CLI
cortex forget                                # Mark context as outdated
cortex journal {ingest|rebuild|replay|verify|show|tail|migrate}

Evals

cortex eval              # Run a scenario or suite
cortex measure           # Measure prompt quality for small context windows
cortex calibrate         # Recompute per-op p50 cost hints from dag_traces.jsonl

Project Structure

cortex/
├── cmd/cortex/          # CLI entry point
├── internal/            # Private implementation
│   ├── capture/         # Fast event capture (<20ms target)
│   ├── cognition/       # Five cognitive modes
│   ├── storage/         # SQLite + search
│   ├── processor/       # Async event processing
│   ├── journal/         # Append-only event log (source of truth)
│   ├── eval/v2/         # v2 eval runner + unified cell_results.jsonl sink
│   └── eval/benchmarks/ # Wrapped benchmarks (SWE-bench, NIAH, LongMemEval, MTEB)
└── pkg/                 # Public API
    ├── cognition/dag/   # DAG engine + op registry
    ├── cognition/       # Mode interfaces
    ├── config/          # Configuration
    ├── events/          # Event types
    └── llm/             # LLM providers (Anthropic, Ollama, OpenRouter)

Configuration

Cortex stores data in ~/.cortex/ (global, project registry) and .cortex/ (per-project, captured events + embeddings + queue).

Coding-harness models (repl / code) are configured by cortex setup, which writes a small JSON config:

{
  "backend": { "type": "openrouter", "endpoint": "https://openrouter.ai/api/v1", "key_env": "OPENROUTER_API_KEY" },
  "models": {
    "code":  { "model": "qwen/qwen3-coder:free" },
    "study": { "model": "openai/gpt-oss-20b:free" }
  }
}

Resolution is layered, lowest to highest precedence: ~/.cortex/config.json (user) → ./.cortex/config.json (project) → CORTEX_BACKEND env. A project inherits the user config and overrides only what it pins — field by field, so overriding code.model keeps the inherited endpoint and key. Auth is resolved at call time from key_env (an env-var name, the portable default) or key_service (a macOS keychain item); the secret is never written to config.

Background cognition (capture/analyze, Think/Dream) is a separate subsystem selected via the ANTHROPIC_API_KEY env var (set → Anthropic; unset → Ollama):

• Ollama: local inference at http://localhost:11434. Free. Recommended models: llama3.1:8b for analysis and nomic-embed-text for embeddings. Smaller models have measured below the task floor; the configured ollama_model in .cortex/config.json must actually be pulled or the REPL's background cognition will silently produce zero insights.
• Anthropic: set ANTHROPIC_API_KEY. Uses claude-haiku-4-5 for analysis. Embeddings still go through Ollama (nomic-embed-text); there is no Anthropic embedding fallback.
• No LLM: capture and search still work; Reflect/Dream and insight extraction are skipped.

Current Status

Active development. See [ROADMAP.md](ROADMAP.md) for the full breakdown and [docs/simplification-audit.md](docs/simplification-audit.md) for the in-flight simplification-to-cortex-only work.

Key metrics from cognitive evaluation:

• Reflex latency <20ms — design target, not yet reliably pinned in

real-world sessions

• Pre-DAG-protocol baseline ABR = 0.586 (recorded in

docs/eval-journal.md)

Known Limitations

• Embedding bootstrap is brittle. cortex reembed requires existing embeddings; events captured before nomic-embed-text is pulled don't get backfilled. Pull the embedding model before the first capture.
• Background cognition fails silently on missing models. If the configured ollama_model isn't pulled, the REPL's ingest goroutine still drains events but Think/Dream produce zero insights and zero embeddings. Check cortex status --system if insights aren't appearing.
• Provider selection is env-driven, not config-driven. The REPL must inherit ANTHROPIC_API_KEY in its environment to use Anthropic; restart it after exporting the key.

Documentation

• [CLAUDE.md](CLAUDE.md) - Developer guide for AI assistants
• [ROADMAP.md](ROADMAP.md) - Development status and gaps
• [docs/abstract.md](docs/abstract.md) - Implementation paper with evaluation results
• [docs/context-evolution.md](docs/context-evolution.md) - Theoretical foundations
• [docs/product.md](docs/product.md) - Detailed product documentation
• [docs/eval.md](docs/eval.md) - Evaluation methodology
• [docs/simplification-audit.md](docs/simplification-audit.md) - Current simplification work

Development

go build ./cmd/cortex    # Build
go test ./...            # Run tests
go fmt ./...             # Format code

Testing uses standard library only—no testify or external assertion libraries.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dereksantos
• Source: dereksantos/cortex
• License: MIT

Install and usage instructions live in the source repository linked above.