Cortex - Project Memory for AI Coding Assistants

Your AI forgets everything between sessions. Cortex gives it a brain.

Every time you start a new AI coding session, you waste 15-30 minutes re-explaining your project. Architecture, past decisions, known bugs, conventions — all gone.

Cortex captures everything automatically and injects it into your next session before you type a single character.

Works with Claude Code | Cursor | Cline | Copilot | Any MCP client

---

Why Cortex?

Without Cortex	With Cortex
"Here's my project structure again..."	AI already knows your architecture
"We decided to use Redis because..."	Decision auto-captured with full context
"The bug was in the auth middleware..."	Bug pattern recorded, never repeated
"Don't touch that file, it's..."	Convention remembered across sessions
15-30 min context loading per session	0 min. Full context injected automatically

---

How It Works

You code with AI  -->  Cortex watches silently  -->  Memory builds automatically
                                                           |
Next session starts  <--  Context injected into CLAUDE.md  <--  Best context selected

Install. Code. That's it. Zero configuration needed.

---

Features

Real-Time Memory Capture

Cortex monitors your AI sessions live — not just at the end:

• Every 1 second — Watches for new messages
• Every 15 seconds — Fast local extraction (no API call)
• Every 20 messages — Deep LLM extraction in background
• On decisions/bugs detected — Immediate capture
• Status bar shows Cortex: Live during active sessions

3-Layer Memory Architecture

Inspired by how human memory works:

Layer 1: Working Memory (hot) — Always injected (~800 tokens)

• Last session summary, recent decisions, open problems
• Auto-injected into CLAUDE.md before every session
• Your AI reads this automatically

Layer 2: Episodic Memory (warm) — Session histories

• One file per session with full context
• Auto-generated Architectural Decision Records (ADRs)
• Searchable via CLI and MCP

Layer 3: Semantic Memory (cold) — Knowledge graph

• Full-text search across all layers
• Vector embeddings (coming in v0.2)

Auto-Generated Decision Logs

Every architectural decision captured with:

• What was decided and why
• Alternatives considered
• Files affected
• Full session context

VSCode Sidebar

• Memory Layers tree view (Working, Episodes, Decisions)
• Memory Health dashboard (0-100 score)
• Token budget tracking
• Live updates during sessions

CLAUDE.md Auto-Injection

<!-- CORTEX:START -->
## Project Memory (auto-managed by Cortex)

### Last Session
Fixed authentication bug in session middleware...

### Recent Decisions
- **Use Redis for sessions**: Latency requirements...

### Open Problems
- Rate limiting not implemented yet

_Last updated: 2026-03-26T10:30:00Z | Tokens: 227/800_
<!-- CORTEX:END -->

Claude Code, Cursor, and Cline read CLAUDE.md natively.

---

Quick Start

1. Install

Search "Cortex Memory" in VS Code Extensions, or:

ext install cortex-dev.cortex-memory

2. (Optional) Add a free API key for smarter extraction

• Get a free Gemini key at aistudio.google.com/apikey
• Run Ctrl+Shift+P → Cortex: Set API Key → paste key

3. Code

Start coding with your AI assistant. Cortex runs silently in the background.

Works without an API key too — basic pattern-matching extraction runs locally.

---

What Gets Captured

Signal	Example	Where It's Stored
Decisions	"Let's go with Redis for sessions"	decisions.md (ADR format)
Bug patterns	"Root cause was a race condition"	Episode + working memory
Architecture	"Refactor auth into its own module"	Episode + decision log
File changes	Every file read, edited, created	Tracked per episode
Session context	What you worked on, what's next	Working memory
Open problems	Unresolved bugs, TODOs	Working memory

---

LLM Providers

Provider	Cost	Setup
Gemini (default)	Free (500 req/day)	Get key at aistudio.google.com/apikey
Anthropic	~$0.01/session	Set cortex.apiKey in settings
Ollama	Free (local)	Install Ollama, set provider to ollama
No API key	Free	Works with basic pattern matching

---

CLI Tool

npm install -g cortex-memory

cortex status              # Memory health score
cortex query "auth flow"   # Search across all layers
cortex export              # Export as single markdown

MCP Server (Cursor, Cline, Zed)

{
  "cortex": {
    "command": "node",
    "args": ["path/to/cortex/dist/mcp/index.js"]
  }
}

Tools: cortex_get_context | cortex_search | cortex_save_memory | cortex_get_decisions | cortex_status

---

Settings

Setting	Default	Description
cortex.llmProvider	gemini	Provider: gemini, anthropic, ollama
cortex.apiKey	—	API key for Gemini or Anthropic
cortex.maxWorkingMemoryTokens	800	Token budget for working memory
cortex.autoInjectClaudeMd	true	Auto-inject into CLAUDE.md

Commands

Command	Description
Cortex: Set API Key	Configure your LLM API key
Cortex: Show Memory Status	Health score, token usage, stats
Cortex: Search Memories	Full-text search
Cortex: Refresh Memory View	Force refresh sidebar
Cortex: Initialize Project Memory	Manual init (usually automatic)

---

Privacy

• 100% local — All data in .cortex/ on your machine
• No telemetry — Zero data collection, zero tracking
• No cloud — Only external call is to your chosen LLM
• Your data — Delete .cortex/ to erase everything
• Git-safe — Auto-added to .gitignore

---

Supported AI Assistants

Assistant	Integration	How
Claude Code	Native	CLAUDE.md injection + session watching
Cursor	MCP	Via MCP server
Cline	MCP	Via MCP server
Copilot	Passive	Reads CLAUDE.md if present
Zed	MCP	Via MCP server
Continue	MCP	Via MCP server

---

FAQ

Does this slow down my editor? No. <200KB bundle. All processing in background.

Does it work without an API key? Yes. Basic extraction works out of the box. API key enables deeper LLM-powered extraction.

How much does Gemini cost? $0. Free tier = 500 requests/day. More than enough.

Can my team share memories? Team sync via git planned for v0.2. You can commit .cortex/ to share now.

---

Contributing

See CONTRIBUTING.md. PRs welcome.

License

MIT

---

Stop explaining your codebase to AI. Let Cortex remember it for you.