Cortex - Project Memory for AI Coding Assistants

March 25, 2026 · View on GitHub

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

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.