Claude Cortex

License: MIT Python 3.9+ CI ChromaDB

Auto-capture + structured semantic recall for AI coding agents.

The memory system Claude Code should have had. One install. Zero config. Your AI remembers everything.

What it does

1. Captures — hooks into Claude Code's session lifecycle and records every conversation, tool use, and decision automatically
2. Indexes — pipes captured content into a local ChromaDB vector store in real-time, classified by topic
3. Recalls — provides semantic search + temporal knowledge graph via MCP tools, so your AI finds relevant context instantly

No cloud. No API keys. No subscriptions. Everything runs on your machine.

Install

pip install claude-cortex
cortex init
cortex install

That's it. Restart Claude Code and you have persistent memory.

What cortex install does

1. Registers as a Claude Code plugin — hooks into SessionStart, PostToolUse, SessionEnd, and PreCompact
2. Registers an MCP server — exposes 10 tools (search, KG, status) to your AI agent

From source (development)

git clone https://github.com/codebloodedai/claude-cortex.git
cd claude-cortex
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cortex init
cortex install

Quick start

# Mine existing files into the cortex
cortex mine ~/my-project --region myproject

# Search your memory
cortex search "authentication flow"

# Check what's stored
cortex status

# Knowledge graph
cortex kg stats
cortex kg query "Rudy"
cortex kg timeline "project-x"

How it works

The Cortex Structure

Concept	What it is	Example
Region	Top-level domain	myproject, health, trading
Cluster	Topic within a region	auth, database, api-design
Trace	One chunk of stored memory	A paragraph from a conversation
Synapse	Cross-region connection	Links auth in project A to auth in project B

Memory Stack

Layer	Size	When
L0 — Identity	~50 tokens	Every session
L1 — Critical facts	~120 tokens	Every session
L2 — Topic recall	On demand	When topic mentioned
L3 — Deep search	On demand	When explicitly needed

Your AI wakes up with ~170 tokens of context. Not 10,000. Just enough to know who you are and what matters.

Auto-Capture Pipeline (Claude Code Hooks)

Four hooks fire automatically during every Claude Code session:

SessionStart
  → session-start.py fires
  → Loads L0 + L1 from cortex → injected as system message
  → AI starts with relevant context, zero manual effort

PostToolUse (Write | Edit | Bash)
  → post-tool-use.py fires
  → Captures operation to ~/.cortex/captures/{session}.jsonl
  → Fast: local file write only, no ChromaDB during session

PreCompact
  → pre-compact.py fires
  → Injects cortex context before context window compression
  → Critical state survives compaction

SessionEnd
  → session-end.py fires
  → Reads all captured observations
  → Classifies each by topic (keyword matching against clusters)
  → Vectorizes and stores as traces in ChromaDB
  → Builds session summary trace
  → Update knowledge graph
  → Ready for next session

MCP Tools

When connected to Claude Code, these tools are available:

Tool	Description
cortex_status	Cortex overview — traces, regions, clusters
cortex_search	Semantic search with optional filters
cortex_add_trace	Store content into region/cluster
cortex_delete_trace	Remove a trace by ID
cortex_kg_query	Query entity relationships
cortex_kg_add	Add temporal fact
cortex_kg_invalidate	Mark fact as no longer true
cortex_kg_timeline	Chronological entity history
cortex_kg_stats	Knowledge graph overview
cortex_reconnect	Force reconnect

Configuration

# ~/.cortex/config.yaml
region: default
store_path: ~/.cortex/store

clusters:
  - name: code
    description: Code changes, architecture, debugging
    keywords: [function, class, bug, fix, refactor, api]
  - name: decisions
    description: Architecture choices, strategy
    keywords: [decided, chose, strategy, plan, design]
  - name: general
    description: Everything else
    keywords: []

vs. existing tools

	claude-cortex	claude-mem	MemPalace
Auto-capture	Yes	Yes	No
Structured recall	Yes	Basic	Yes
Knowledge graph	Yes	No	Yes
Real-time indexing	Yes	No	No
MCP tools	10+	3-4	29
One install	Yes	Yes	Yes
License	MIT	AGPL	MIT

claude-cortex combines the best of both: automatic capture from session hooks + structured semantic recall with a knowledge graph. One tool, not two.

Credits

Storage engine inspired by MemPalace (MIT). Auto-capture architecture inspired by claude-mem. Built from scratch by CodeBloodedAI.

License

MIT — do whatever you want with it.