Persistent memory for Claude Code. Install once, never re-explain your project again.
Claude Code forgets everything between sessions. Your architecture, your preferences, every decision you made yesterday — gone. Cortex is a local MCP server that captures context during your sessions and feeds it back automatically. Your AI starts every conversation knowing exactly where you left off.
Product Page · npm · Issues · Docs
If Cortex is useful to you, a star helps other engineers find it.
Claude Code forgets context between sessions. Every conversation starts from zero. You explain your architecture, your naming conventions, the tech stack, why you chose Turso over PlanetScale — and tomorrow it asks the same questions again. Claude Code loses context when the session ends, completely.
For most engineers, this means 15 to 30 minutes of wasted context-setting every morning. You are paying for a genius contractor who forgets everything overnight. There is no built-in way to give Claude Code persistent memory. Session memory disappears the moment you close the terminal. If you have searched for how to give Claude Code memory that persists across sessions, you have found the right tool.
Cortex is an MCP server that provides context persistence for Claude Code. It runs silently in the background, captures the decisions and preferences that matter, and injects them back at the start of every future session. No manual note-taking, no pasting old conversations, no context files you have to maintain. Your AI coding assistant finally has memory between sessions.
Three ways. Pick one.
Homebrew (macOS)
brew tap ProductionLineHQ/cortex
brew install cortex-memorynpx (any platform)
npx @cortex.memory/cli initcurl
curl -fsSL https://raw.githubusercontent.com/ProductionLineHQ/cortex/main/scripts/install.sh | shAfter install, run cortex init in any project directory. Cortex registers itself as an MCP server with Claude Code automatically.
Cortex runs as a local daemon on your machine. It connects to Claude Code through the Model Context Protocol, the same interface Claude Code uses for all its tool integrations.
┌──────────────┐ MCP Protocol ┌───────────────┐
│ Claude Code │◄───────────────────►│ Cortex MCP │
│ (your IDE) │ read/write tools │ Server │
└──────────────┘ └───────┬───────┘
│
┌───────▼───────┐
│ Quality Gate │
│ (7 rules) │
└───────┬───────┘
│
┌───────▼───────┐
│ SQLite │
│ (local disk) │
└───────┬───────┘
│ optional
┌───────▼───────┐
│ Turso Sync │
│ (multi-machine)│
└───────────────┘
When Claude Code starts a session, it calls the cortex_get_context MCP tool. Cortex returns the relevant memories for the current project:
{
"tool": "cortex_get_context",
"result": {
"project": "my-saas-app",
"memories": [
{
"type": "decision",
"content": "Using Drizzle ORM instead of Prisma — better edge runtime support and no binary dependency",
"importance": 8,
"created": "2025-03-19T14:22:00Z"
},
{
"type": "preference",
"content": "Always use server components by default, only add use client when state or effects are needed",
"importance": 9,
"created": "2025-03-18T09:15:00Z"
},
{
"type": "thread",
"content": "Investigating WebSocket reconnection drops under high load — suspect Cloudflare timeout at 100s",
"importance": 7,
"created": "2025-03-20T16:40:00Z"
}
]
}
}During the session, Claude can save new memories through the cortex_save_memory tool. Every memory passes through a quality gate before being stored — this prevents the database from filling up with noise.
At the end of each session, an AI summarizer reviews the conversation for any important context that Claude forgot to save, and captures those as additional memories.
| Feature | Description |
|---|---|
| MCP Server | 5 tools exposed to Claude Code via the Model Context Protocol |
| 6 Memory Types | Decision, Context, Preference, Thread, Error, Learning — each with its own lifecycle |
| Quality Gate | 7 validation rules block duplicates, sensitive data, and low-quality saves |
| Session Summarizer | AI reviews completed sessions and captures missed context |
| Project Detection | 4-layer strategy (git remote → package.json → directory name → manual) |
| 33 CLI Commands | Full terminal interface for browsing, searching, editing, and exporting memories |
| Web Dashboard | Next.js dashboard on localhost:7433 — search, filter, edit, bulk operations |
| Multi-Machine Sync | Optional Turso-powered sync across your machines (you own the database) |
| VS Code Extension | Memory sidebar, inline context, quick save from the editor |
| Desktop App | Native Electron app with system tray integration |
| Local First | SQLite on your machine. Nothing leaves unless you enable sync |
| Clean Uninstall | cortex uninstall removes everything — database, daemon, config, MCP registration |
Cortex works out of the box with zero configuration. For those who want to customize:
# Show current configuration
cortex config show
# Set custom MCP server port (default: 7434)
cortex config set port 7434
# Set dashboard port (default: 7433)
cortex config set dashboard.port 7433
# Enable multi-machine sync
cortex config set sync.enabled true
cortex config set sync.url libsql://your-db.turso.io
cortex config set sync.token your-turso-auth-token
# Adjust quality gate thresholds
cortex config set quality.minLength 50
cortex config set quality.maxLength 2000
cortex config set quality.similarityThreshold 0.85
cortex config set quality.rateLimit.perSession 50Configuration is stored in ~/.cortex/config.json. Project-specific overrides go in .cortex/config.json in your project root.
# Project management
cortex init # Initialize Cortex in the current project
cortex status # Show daemon status, memory counts, sync state
cortex doctor # Diagnose and fix common issues
# Memory operations
cortex show [project] # Browse memories for a project
cortex search <query> # Full-text search across all projects
cortex add # Manually add a memory
cortex edit <id> # Edit an existing memory
cortex delete <id> # Delete a memory
cortex clear [project] # Delete all memories (with backup prompt)
# Data management
cortex export [project] # Export memories as JSON
cortex import <file> # Import memories from a JSON file
cortex backup # Create a timestamped database backup
# Daemon control
cortex start # Start the background daemon
cortex stop # Stop the daemon
cortex restart # Restart the daemon
cortex logs # View daemon logs
# Sync
cortex sync status # Show sync state
cortex sync push # Push local changes to Turso
cortex sync pull # Pull remote changes
# Utilities
cortex config show # Show configuration
cortex config set <key> <val> # Update a config value
cortex uninstall # Remove Cortex completely (with export option)
cortex --version # Print versionRun cortex help <command> for detailed usage of any command.
Does this send my code to your servers?
No. Cortex runs entirely on your machine. The MCP server listens on localhost only — it is one of the few MCP tools for context persistence that is fully local. Your memories are stored in a SQLite database at ~/.cortex/cortex.db. The only time data leaves your machine is if you explicitly enable Turso sync, and even then, you create the database yourself and own the credentials. We never see your data.
What happens if I uninstall?
Run cortex uninstall. It removes the database, stops the daemon, deletes the config directory, and unregisters the MCP server from Claude Code. Before deletion, it offers to export all your memories to a JSON file. Nothing is left behind. If you installed via Homebrew, also run brew uninstall cortex-memory. Your Claude Code project context across sessions is exported as JSON so nothing is lost.
Does it work with projects that don't use git?
Yes. Cortex uses a 4-layer project detection strategy: git remote URL (most reliable), package.json name field, directory name, or manual assignment via cortex init --name my-project. Git is preferred for consistent project identification but is not required. The goal is to give every project its own persistent memory space regardless of your version control setup.
How is this different from just keeping a notes file?
A notes file requires you to remember to write things down, to organize them, and to paste them into every Claude Code session. Cortex captures context automatically during your normal workflow, validates it through a quality gate, categorizes it by type, and injects it into Claude Code without you doing anything. It also handles deduplication, expiration, importance scoring, and cross-project search — things a text file cannot do.
Will this slow down Claude Code?
No. The MCP server runs as a separate process on localhost. Context injection adds roughly 50 to 100 milliseconds to session startup — the time it takes to read from SQLite and format the response. Memory saves happen asynchronously and do not block your session. The quality gate and summarizer run after your session ends.
Can I see what's been stored?
Yes. Run cortex show to browse all memories for the current project, or cortex search <query> to find specific memories across all projects. The web dashboard at localhost:7433 gives you a visual interface to browse, edit, delete, and export everything. Every memory includes its type, importance score, creation date, and tags. Nothing is hidden.
Teams and engineers using Cortex on production codebases.
| Who | Stack | Memories |
|---|---|---|
| Your project here | — | — |
Using Cortex? Open a PR to add yourself, or share your setup on Twitter/X with #cortexmemory.
We welcome contributions from anyone. See CONTRIBUTING.md for the full guide covering dev setup, repo structure, testing, and PR process.
Quick start for contributors:
git clone https://github.com/ProductionLineHQ/cortex.git
cd cortex
pnpm install
pnpm build
pnpm testThe monorepo has 9 packages: shared, server, cli, dashboard, desktop, electron, vscode, installer, web. Each package has its own README with package-specific details.
Please open an issue before starting work on anything non-trivial. This lets us coordinate and avoids duplicate effort.
MIT — The Production Line
Built by Koundinya Lanka.