cortex

Persistent memory for AI coding agents
Knowledge graph • Importance scoring • Entity linking • Vector search

Installation • Agent Setup • Architecture • Plugins • Contributing

---

cortex /ˈkɔːr.tɛks/ — neuroscience: the outer layer of the brain responsible for memory, attention, perception, and cognition.

Your AI coding agent forgets everything when the session ends. Cortex gives it a brain — with a knowledge graph.

Built on the foundation of Engram, Cortex adds knowledge graph relationships, importance scoring, entity linking, auto-archival, and optional vector search while maintaining full API compatibility. Drop-in replacement — migrate in one command.

A Go binary with SQLite + FTS5 full-text search + Knowledge Graph, exposed via CLI, HTTP API, MCP server, and TUI. Works with any agent that supports MCP — Claude Code, OpenCode, Gemini CLI, Codex, VS Code (Copilot), Antigravity, Cursor, Windsurf, or anything else.

Agent (Claude Code / OpenCode / Gemini CLI / Codex / VS Code / Antigravity / ...)
    ↓ MCP stdio
Cortex (single Go binary)
    ↓
SQLite + FTS5 + Knowledge Graph + Importance Scoring

Quick Start

Install

# macOS / Linux
brew install lleontor705/tap/cortex

# go install (all platforms)
go install github.com/lleontor705/cortex/cmd/cortex@latest

Windows, pre-built binaries, Docker → docs/INSTALLATION.md

Setup Your Agent

Agent	One-liner
Claude Code	cortex setup claude-code
OpenCode	cortex setup opencode
Gemini CLI	cortex setup gemini-cli
Codex	cortex setup codex
VS Code	code --add-mcp '{"name":"cortex","command":"cortex","args":["mcp"]}'
Cursor / Windsurf / Any MCP	See docs/AGENT-SETUP.md

Full per-agent config, Memory Protocol, and compaction survival → docs/AGENT-SETUP.md

That's it. No Node.js, no Python, no Docker. One binary, one SQLite file.

Migrating from Engram?

cortex import --from-engram --path ~/.engram/engram.db

Full migration script (uninstalls Engram, migrates data, reconfigures agents) → scripts/migrate-from-engram.sh

How It Works

1. Agent completes significant work (bugfix, architecture decision, etc.)
2. Agent calls mem_save → title, type, What/Why/Where/Learned
3. Cortex persists to SQLite with FTS5 indexing + importance scoring
4. Entities auto-extracted (files, URLs, packages, symbols)
5. Agent relates observations via knowledge graph (mem_relate)
6. Next session: agent searches memory, gets relevant context + graph connections

Key Features

Core Memory (Engram-Compatible)

• Full-Text Search (FTS5) — Lightning-fast search across all observations
• Session Tracking — Automatic session management with context aggregation
• Topic Keys — Upsert semantics for evolving observations (architecture decisions, etc.)
• Passive Capture — Extract learnings from agent output automatically
• Deduplication — SHA-256 content-based deduplication