cortex

module

v1.3.0 Latest Latest Go to latest Published: Jun 23, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/lleontor705/cortex

Links

Open Source Insights

README ¶

Installation • Agent Setup • Benchmarks • Architecture • Recommendations • Contributing

cortex /ˈkɔːr.tɛks/ — 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, vector search, and temporal reasoning. One Go binary. Zero cloud dependencies.

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

Why Cortex?

	Cortex	Mem0	Zep/Graphiti	claude-mem
Single binary	Go	Python + Neo4j/Qdrant	Python + Neo4j	TS + Python + ChromaDB
Knowledge graph	SQLite-native	Neo4j (cloud)	Neo4j (cloud)	No
Vector search	Ollama (local) or OpenAI	Qdrant/Pinecone	Neo4j vectors	ChromaDB
Temporal reasoning	Built-in	No	Graphiti	No
Privacy	100% local	Cloud option	Cloud option	Local
Agent lock-in	None (MCP)	LangChain-centric	Python SDKs	Claude only
Setup	`go install`	pip + docker	pip + docker	npm + bun + uv

Quick Start

# Install
brew install lleontor705/tap/cortex    # macOS / Linux
go install github.com/lleontor705/cortex/cmd/cortex@latest  # all platforms

# Setup your agent
cortex setup claude-code   # or: opencode, gemini-cli, codex

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

Setup for VS Code, Cursor, Windsurf, and other MCP clients

Agent	Setup
VS Code (Copilot)	`code --add-mcp '{"name":"cortex","command":"cortex","args":["mcp"]}'`
Cursor	Add to `.cursor/mcp.json`
Windsurf	Add to MCP config

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

Migrating from Engram?

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

100% API-compatible. All 14 Engram MCP tools work identically. Cortex adds 8 more. Full migration script: 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 + auto-embedding
4. Entities auto-extracted (files, URLs, packages, symbols)
5. Agent relates observations via knowledge graph (mem_relate)
6. Next session: agent searches memory -> FTS5 + vector + graph boost

Features

Memory Engine

Full-Text Search (FTS5) with BM25 ranking and topic key lookup
Vector Search via Ollama (local, free) or OpenAI — hybrid FTS5 + cosine similarity with RRF fusion
Knowledge Graph with typed edges (references, relates_to, follows, supersedes, contradicts) and BFS traversal
Temporal Reasoning — search as-of a specific date, edges with validity windows
Importance Scoring — base + typeBonus + accessBonus + recencyBonus + edgeBonus - agePenalty, clamped [0.0, 5.0]

Intelligence

Entity Linking — auto-extract files, URLs, packages, symbols from observations
Memory Consolidation — find and merge duplicate topic keys across sessions
Project DNA — auto-generate structured project summaries (decisions, patterns, gotchas)
Auto-Archival — periodically soft-delete old low-importance observations

Developer Experience

Interactive TUI — 12-screen BubbleTea terminal UI with search, graph viewer, health dashboard
Health Check — cortex doctor validates DB, FTS5, graph, vectors, and orphan detection
Batch Reindex — cortex reindex generates embeddings for all observations
Agent-Agnostic — works with any MCP client: Claude Code, Cursor, Gemini CLI, Codex, VS Code, OpenCode, Windsurf, Antigravity

Benchmarks

Evaluated on LOCOMO (ACL 2024) — 1,986 questions across 10 long-term conversations:

Search Mode	single-hop	multi-hop	temporal	vs baseline
FTS5 only	0.002	0.001	0.000	—
+ Ollama (local, free)	0.025	0.016	0.026	12-16x
+ OpenAI (cloud)	0.026	0.016	0.037	13-37x

F1 token overlap on retrieval. Cortex finds relevant memories — the agent's LLM generates answers on top.

Provider	Cost	Privacy	Latency	Best for
Ollama	$0	100% local	~90ms	Default (recommended)
OpenAI	~$0.02/1M tok	Cloud	~200ms	Max temporal quality
None	$0	Local	<1ms	Quick start, keywords only

Full methodology and reproducibility: docs/BENCHMARKS.md | Provider guide: docs/RECOMMENDATIONS.md

MCP Tools (22)

14 Core Tools (Engram-compatible)

Tool	Purpose
`mem_save`	Save observation with What/Why/Where/Learned format
`mem_search`	Full-text search with filters + optional graph expansion
`mem_context`	Recent session context aggregation
`mem_session_summary`	End-of-session comprehensive save
`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

8 Cortex-Exclusive Tools

Tool	Purpose
`mem_relate`	Create typed relationship between observations
`mem_graph`	Traverse knowledge graph (BFS, depth 1-10)
`mem_score`	Get/recalculate importance score
`mem_search_hybrid`	FTS5 + vector search with RRF fusion
`mem_search_temporal`	Search as-of a specific date
`mem_consolidate`	Find duplicate topic keys for merging
`mem_project_dna`	Generate structured project summary
`mem_archive`	Soft-delete observation

CLI

cortex setup [agent]           # Install agent integration
cortex search <query>          # Search memories
cortex save <title> <content>  # Save a memory
cortex tui                     # Launch interactive terminal UI
cortex doctor                  # Health check (DB, FTS5, graph, vectors)
cortex reindex [--project P]   # Generate vector embeddings
cortex gc [--days N]           # Garbage collect archived observations
cortex serve                   # Start HTTP REST API (port 7438)
cortex mcp [--tools=PROFILE]   # Start MCP server (stdio)
cortex stats                   # Memory statistics
cortex export [--project P]    # Export to JSON
cortex import --from-engram    # Import from Engram database
cortex migrate <up|down>       # Manage database migrations

Configuration

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

search:
  default_limit: 20
  embedding_provider: ollama    # ollama | openai | none

memory:
  auto_archive_days: 90
  min_archive_score: 0.1

lifecycle:
  enable_auto_archive: true

Environment variable overrides: CORTEX_DATABASE_PATH, CORTEX_SEARCH_EMBEDDING_PROVIDER, etc.

Architecture

cmd/cortex/           CLI entry point
internal/
  app/                Dependency wiring (config -> DB -> stores -> MCP)
  mcp/                22 MCP tool handlers
  http/               REST API server (17 endpoints)
  tui/                BubbleTea terminal UI (12 screens)
  embedding/          Ollama + OpenAI embedding service
  domain/
    memory/           Observation CRUD, dedup, topic key upsert
    graph/            Knowledge graph with BFS traversal
    scoring/          Importance scoring formula
    temporal/         Temporal edge validity + contradiction handling
    dna/              Project DNA generation
    entity/           Entity extraction (files, URLs, packages, symbols)
    lifecycle/        Auto-archival service
  store/
    sqlite/           Observation store + vector store
    search/           FTS5 search + graph neighbor expansion
    graph/            Edge store with temporal filtering
    scoring/          Importance score store
    session/          Session lifecycle store
    entity/           Entity link store
  migration/          Version-tracked SQL migrations (001-009)
bench/                Benchmark harness (LOCOMO, DMR, LongMemEval)

Full architecture details: 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
Benchmarks	LOCOMO/DMR results, methodology, reproducibility
Recommendations	Embedding provider guide, performance tuning
Plugins	Claude Code hooks + OpenCode TypeScript plugin
Comparison	Cortex vs Engram vs claude-mem
Contributing	Contribution workflow + standards

License

MIT

Built on the foundation of Engram
Enhanced with knowledge graph, vector search, temporal reasoning, and project DNA
for the next generation of AI coding assistants.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
bench
common Package common provides shared utilities for benchmark evaluation.	Package common provides shared utilities for benchmark evaluation.
dmr Package dmr implements the Deep Memory Retrieval benchmark runner for Cortex.	Package dmr implements the Deep Memory Retrieval benchmark runner for Cortex.
locomo Package locomo implements the LOCOMO benchmark runner for Cortex.	Package locomo implements the LOCOMO benchmark runner for Cortex.
longmemeval Package longmemeval implements the LongMemEval benchmark runner for Cortex.	Package longmemeval implements the LongMemEval benchmark runner for Cortex.
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/dna Package dna generates Project DNA — a structured summary of a project's key decisions, patterns, tech stack, and gotchas extracted from observations.	Package dna generates Project DNA — a structured summary of a project's key decisions, patterns, tech stack, and gotchas extracted from observations.
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.
embedding Package embedding provides text-to-vector embedding for Cortex.	Package embedding provides text-to-vector embedding for 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.
ollama Package ollama manages the Ollama process lifecycle for Cortex.	Package ollama manages the Ollama process lifecycle for Cortex.
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 BubbleTea terminal UI for Cortex.	Package tui implements the BubbleTea terminal UI for Cortex.
update Package update provides passive version checking against GitHub releases.	Package update provides passive version checking against GitHub releases.
testutil Package testutil provides testing utilities for Cortex tests.	Package testutil provides testing utilities for Cortex tests.