cortex

module
v0.2.7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 31, 2026 License: MIT

README

Cortex Logo

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

CI Release License Go Report Card

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

New in Cortex

  • Knowledge Graph — Relate observations with typed edges (references, relates_to, follows, supersedes, contradicts). Traverse with BFS up to depth 10.
  • Importance Scoring — Automatic scoring based on access patterns, recency, graph connections, observation type, and age. Formula: base + accessBonus + recencyBonus + edgeBonus + typeBonus - agePenalty, clamped to [0.0, 5.0].
  • Entity Linking — Auto-extract files, URLs, packages, and symbols from observation content via regex.
  • Auto-Archival — Periodically soft-delete old observations with low importance scores. Configurable thresholds.
  • Vector Search — Optional hybrid search combining FTS5 with embedding similarity via RRF fusion (requires cortex_vectors build tag).
  • HTTP REST API — 17 JSON endpoints for observations, sessions, search, graph, and scoring.

MCP Tools (19 total)

Core Tools (Engram-Compatible)

Tool Purpose
mem_save Save observation with What/Why/Where/Learned format
mem_search Full-text search with filters
mem_context Recent session context aggregation
mem_session_summary End-of-session comprehensive save (mandatory)
mem_get_observation Full content by ID
mem_save_prompt Save user prompt for context
mem_update Update observation by ID
mem_suggest_topic_key Stable key for evolving topics
mem_session_start Register session start
mem_session_end Mark session complete
mem_capture_passive Extract learnings from agent output
mem_delete Soft or hard delete
mem_stats Memory system statistics
mem_timeline Chronological drill-in around observation

Cortex-Exclusive Tools

Tool Purpose
mem_relate Create typed relationship between observations
mem_graph Traverse knowledge graph from an observation
mem_score Get/recalculate importance score
mem_archive Archive an observation (soft-delete)
mem_search_hybrid Hybrid FTS5 + vector search with RRF fusion

Full tool reference → docs/ARCHITECTURE.md

Cortex vs Engram

Feature Engram Cortex
FTS5 Search ✅ ✅
Session Tracking ✅ ✅
Topic Keys ✅ ✅
Passive Capture ✅ ✅
MCP Compatibility ✅ ✅ (100%)
Knowledge Graph ❌ ✅
Importance Scoring ❌ ✅
Auto-Archival ❌ ✅
Entity Linking ❌ ✅
Vector Search ❌ ✅ (optional)
HTTP REST API ✅ ✅

Full comparison (including vs claude-mem) → docs/COMPARISON.md

CLI Reference

Command Description
cortex setup [agent] Install agent integration
cortex serve Start HTTP REST API (default: 7438)
cortex mcp [--tools=PROFILE] Start MCP server (stdio)
cortex tui Launch terminal UI
cortex search <query> Search memories
cortex save <title> <content> Save a memory
cortex timeline <obs_id> Chronological context (--before/--after)
cortex context [project] Recent session context
cortex stats Memory statistics
cortex export [--project P] Export to JSON
cortex import --from-engram Import from Engram database
cortex import --from-json Import from JSON file
cortex migrate <up|down|status> Manage database migrations
cortex version Show version

Configuration

Cortex reads from cortex.yaml with env var overrides (CORTEX_<SECTION>_<KEY>):

database:
  path: cortex.db
  pragma:
    journal_mode: WAL

search:
  default_limit: 20
  vector: false       # Enable with cortex_vectors build tag

memory:
  auto_archive_days: 90
  min_archive_score: 0.1

lifecycle:
  enable_auto_archive: true

Full config reference → docs/ARCHITECTURE.md

Documentation

Doc Description
Installation Homebrew, go install, binaries, Docker
Agent Setup Per-agent configuration + Memory Protocol
Architecture Design, scoring formula, graph, API, schema
Plugins Claude Code hooks + OpenCode TypeScript plugin
Comparison Why Cortex vs Engram vs claude-mem
Contributing Contribution workflow + standards

License

MIT

Built on the foundation of Engram — enhanced with knowledge graph, importance scoring, entity linking, and vector search for the next generation of AI coding assistants.

Directories

Path Synopsis
cmd
cortex command
internal
app
cli
config
database
Package database provides SQLite connection management with optimized pragmas.
 Package database provides SQLite connection management with optimized pragmas.
domain
Package domain defines the core domain models and business rules for Cortex.
 Package domain defines the core domain models and business rules for Cortex.
domain/entity
Package entity implements entity extraction and linking for Cortex.
 Package entity implements entity extraction and linking for Cortex.
domain/graph
Package graph provides business logic for managing relationships between observations in the knowledge graph.
 Package graph provides business logic for managing relationships between observations in the knowledge graph.
domain/lifecycle
Package lifecycle implements auto-archival and lifecycle management for Cortex.
 Package lifecycle implements auto-archival and lifecycle management for Cortex.
domain/memory
Package memory provides the business logic layer for observation management.
 Package memory provides the business logic layer for observation management.
domain/observability
Package observability provides metrics and quality evaluation for the Cortex memory system.
 Package observability provides metrics and quality evaluation for the Cortex memory system.
domain/scoring
Package scoring implements the importance scoring business logic for Cortex.
 Package scoring implements the importance scoring business logic for Cortex.
domain/search
Package search provides FTS5-based full-text search business logic for Cortex.
 Package search provides FTS5-based full-text search business logic for Cortex.
domain/session
Package session provides business logic for session management.
 Package session provides business logic for session management.
domain/temporal
Package temporal provides temporal graph semantics and evolution tracking for the knowledge graph in Cortex.
 Package temporal provides temporal graph semantics and evolution tracking for the knowledge graph in Cortex.
http
Package http implements the REST API server for Cortex.
 Package http implements the REST API server for Cortex.
mcp
Package mcp implements the Model Context Protocol server for Cortex.
 Package mcp implements the Model Context Protocol server for Cortex.
migration
Package migration provides a database migration framework for SQLite.
 Package migration provides a database migration framework for SQLite.
project
setup
Package setup installs Cortex integrations for AI coding agents.
 Package setup installs Cortex integrations for AI coding agents.
store/bundle
Package bundle provides the Stores struct that bundles all store dependencies.
 Package bundle provides the Stores struct that bundles all store dependencies.
store/entity
Package entity implements the SQLite entity link store for Cortex.
 Package entity implements the SQLite entity link store for Cortex.
store/graph
Package graph implements the SQLite graph store for Cortex.
 Package graph implements the SQLite graph store for Cortex.
store/prompt
Package prompt implements the SQLite prompt store for Cortex.
 Package prompt implements the SQLite prompt store for Cortex.
store/scoring
Package scoring implements the SQLite scoring store for Cortex.
 Package scoring implements the SQLite scoring store for Cortex.
store/search
Package search implements the SQLite search store for Cortex.
 Package search implements the SQLite search store for Cortex.
store/session
Package session implements the SQLite session store for Cortex.
 Package session implements the SQLite session store for Cortex.
store/sqlite
Package sqlite implements the SQLite memory store for Cortex.
 Package sqlite implements the SQLite memory store for Cortex.
sync
Package sync provides git-friendly memory synchronization via compressed chunks.
 Package sync provides git-friendly memory synchronization via compressed chunks.
tui
Package tui implements the terminal user interface for Cortex.
 Package tui implements the terminal user interface for Cortex.
update
Package update provides passive version checking against GitHub releases.
 Package update provides passive version checking against GitHub releases.
Package testutil provides testing utilities for Cortex tests.
 Package testutil provides testing utilities for Cortex tests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.