cortex

Claude Cortex

A Claude Code plugin that gives Claude improved memory, context intelligence, and session observability. Three modules working together:

Module	Language	What it does
Brainiac	Python	Semantic knowledge graph with local embeddings, auto-linking, and intent-aware retrieval
Cortex	TypeScript	Hook processor that tracks sessions + MCP server with 5 dashboard tools
ContextScore	Python	7-dimension context quality scoring with snapshot/recovery

Built on research from A-MEM (NeurIPS 2025), MAGMA (2026), SmartSearch (Derehag et al. 2026), LCM (Ehrlich 2026), and Anthropic Harness Design (2025).

Install as Claude Code Plugin

# From your project directory:
claude plugin add github:Peaky8linders/claude-cortex

# Or clone and install manually:
git clone https://github.com/Peaky8linders/claude-cortex.git
cd claude-cortex
pip install -e .                    # Python dependencies (brainiac + contextscore)
cd cortex && npm install && npm run build  # TypeScript dependencies (cortex engine + MCP server)

After install, the plugin auto-registers:

• 7 hooks — session tracking, context snapshots, compaction recovery
• 14 slash commands — /learn, /hypothesis, /cortex-status, /review-and-ship, etc.
• 5 MCP tools — token timeline, activity map, quality heatmap, graph explorer, unified dashboard
• 3 agents — cortex-advisor (haiku), graph-maintainer (haiku), work-evaluator (sonnet)

What You Get

Persistent Memory Across Sessions

Claude forgets everything between sessions. Cortex doesn't. Use /learn at the end of a session to capture patterns, decisions, and solutions into a knowledge graph. Next session, Claude automatically searches the graph and applies what it learned.

Session Dashboard (MCP Tools)

Query your session in real-time via 5 MCP tools:

Tool	What it shows
cortex_token_timeline	Minute-by-minute token usage with spike detection and cost estimates
cortex_activity_map	Gantt-like timeline of which hooks, skills, and tools fired
cortex_quality_heatmap	7-dimension radar chart of context quality (semantic relevance, redundancy, economics, etc.)
cortex_graph_explorer	Interactive force-directed graph visualization (JSON for terminal, HTML for browser)
cortex_dashboard	Unified session dashboard — KPIs, charts, cost breakdown, and knowledge graph in one page

Context Compaction Survival

When Claude's context window compacts, critical decisions and patterns are lost. Cortex snapshots them before compaction and re-injects them after — lossless context management.

Autonomous Workflows

Level	Command	What it does
L3	/run-tasks	Execute task YAML with generator-evaluator pattern and sprint contracts
L4	/ralph-start	Autonomous loop with dual quality gate and optional context resets
L5	/auto-research	Structured experiment runner with /hypothesis tracking and eval loops

Generator-Evaluator Pattern

Inspired by Anthropic's harness design research: separating work production from assessment is more effective than self-evaluation.

• work-evaluator agent independently grades output across 5 weighted dimensions (correctness, architecture, completeness, safety, craft)
• Sprint contracts align generator and evaluator on testable success criteria before coding begins
• Dual quality gate combines graph health (30%) + work output quality (70%) into a composite score; halts at < 40
• Context reset strategy (--reset-strategy reset) provides clean-slate iterations with structured handoffs for long-running tasks

Slash Commands