How to Give Claude Code Persistent Memory with Cortex
Claude Code forgets everything between sessions. Cortex fixes that with 6 memory types, a quality gate, and zero cloud dependency. Here is how to set it up in under 2 minutes.
Koundinya Lanka
AI & Future
You spend 45 minutes explaining your project architecture to Claude Code. The monorepo structure. The naming conventions. The reason you chose Drizzle over Prisma. The deployment pipeline that took three days to get right. Claude nails the session -- every suggestion is contextually perfect. Then you close the terminal. The next morning you open a new session and Claude has no idea who you are.
This is the amnesia problem, and every developer using AI coding assistants hits it. Claude Code, Copilot, Cursor -- they are all stateless by default. Every session starts from zero. You end up repeating yourself, re-explaining decisions, and watching your AI assistant make the same mistakes you corrected yesterday.
Cortex solves this. It is an open-source persistent memory layer for Claude Code that captures decisions, preferences, errors, and context during your sessions and automatically injects them back at the start of new ones. Local-first SQLite, zero telemetry, MIT licensed. Here is how to set it up.
Installation: Two Minutes, Three Commands
# Install via Homebrew (macOS)
brew tap ProductionLineHQ/cortex
brew install cortex-memory
# Or via npx (any platform)
npx @cortex.memory/cli init
# Then just open Claude Code -- Cortex is active
claudeThat is it. Cortex creates a SQLite database at ~/.cortex/cortex.db, starts a background daemon, and registers itself with Claude Code via the Model Context Protocol. No accounts, no API keys, no cloud services. Everything runs on your machine.
How It Works: The Session Lifecycle
- 1
Session Start: Context Injection
Claude Code calls Cortex's get_memories tool. Cortex retrieves the top-ranked memories for your current project and injects them into context with importance scoring and type labels. Claude starts the session already knowing your architecture, preferences, and open threads.
- 2
During the Session: Memory Capture
As you work, Claude can save important decisions, discovered bugs, and learned patterns via the save_memory tool. Every save passes through a 7-rule quality gate that blocks duplicates, generic commentary, and sensitive data like API keys.
- 3
Session End: Automatic Summarization
Optionally, Cortex's AI summarizer reviews the session transcript and extracts memory candidates that were missed during the session. These go into a review queue -- you approve or reject them before they become permanent memories.
- 4
Next Session: Full Context Restored
When you open Claude Code again, Cortex injects the accumulated project knowledge. Claude remembers why you chose that ORM, what the deployment quirks are, and which bugs have workarounds. No re-explaining required.
The Six Memory Types
Not all context is created equal. A decision about your database architecture has a different lifecycle than a bug workaround that will be irrelevant after the next patch. Cortex uses six distinct memory types, each with its own persistence and importance characteristics.
0
Permanent
Architectural and technical choices. Why you chose Drizzle over Prisma. Why the API uses edge runtime.
0
Permanent
Coding conventions and working style. Server components by default. Never use gray-400 on light backgrounds.
0
Configurable
Project state and configuration. Database URLs, deployment targets, environment setup.
0
Until Fixed
Known bugs and workarounds. Buffer not defined in edge runtime -- use WebCrypto instead.
0
Until Resolved
Active investigations. WebSocket reconnection drops under load -- suspect Cloudflare timeout.
0
Permanent
Technical discoveries. Astro env files load at build-time only -- use getSecret() for runtime.
The Quality Gate: Why Most Memory Systems Fail
The naive approach to persistent memory is to save everything. This fails spectacularly. Within a week your context window is full of noise: session summaries, meta-commentary about what Claude just did, vague observations like 'the code works now.' Cortex prevents this with a 7-rule quality gate that every memory must pass before being stored.
- 1
Length Check
Content must be 50 to 2000 characters. No one-liners, no novels. The reason field must be at least 10 characters explaining why this memory matters.
- 2
Banned Phrase Filter
50 generic phrases are automatically rejected: 'user asked me to,' 'as requested,' 'everything looks good,' 'let me help you.' These are process commentary, not memories.
- 3
Sensitive Data Blocker
Regex patterns detect AWS keys, GitHub tokens, Stripe keys, JWTs, private keys, and credit card numbers. Extensible with custom patterns via config.
- 4
Quality Score
Evaluates specificity and technical density. Memories with version numbers, library names, and concrete details score higher. Vague language gets rejected.
- 5
Duplicate Detection
TF-IDF cosine similarity comparison against all existing memories. If the new memory is 85% or more similar to an existing one, it is blocked.
- 6
Rate Limiting
50 memories per session, 200 per day per project. Prevents runaway saves during long sessions.
- 7
Reason Validation
Every memory requires a reason explaining why it matters. This forces intentionality and makes review easier later.
Key Insight
The quality gate is the single most important design decision in Cortex. Without it, memory systems drown in noise within days. With it, every memory that makes it through is genuinely useful six months later.
33 CLI Commands for Full Control
Cortex gives you a full CLI for managing memories outside of Claude Code sessions. Search, edit, export, review stale memories, check daemon health, and manage multi-machine sync -- all from your terminal.
# Browse memories for current project
cortex show
# Search across all projects
cortex search "database migration"
# Review memories that haven't been checked in 90+ days
cortex review
# Export everything to JSON
cortex export > backup.json
# Health check
cortex doctor
# Open web dashboard
cortex dashboard # localhost:7433Optional: Multi-Machine Sync via Turso
By default, Cortex is entirely local. But if you work across multiple machines -- a desktop and a laptop, for example -- you can enable sync via Turso. You create your own Turso database, provide your own credentials, and Cortex syncs memories across machines every 30 seconds. We never see the database. You own the credentials and the data.
# Enable multi-machine sync
cortex config set sync.enabled true
cortex config set sync.turso_url libsql://your-db.turso.io
cortex config set sync.turso_auth_token your-token
# Check sync status
cortex sync statusPro Tip
If you only use one machine, you do not need sync at all. Cortex works perfectly as a local-only tool. The sync feature exists for people who switch between machines during the day.
Privacy by Design
AI Memory Approaches
Cloud-based AI memory: Your code context uploaded to third-party servers. API keys potentially exposed. No control over data retention. Vendor lock-in.
Cortex: SQLite on your machine. MCP server binds to localhost only. Zero telemetry. Sensitive data blocked by default. cortex uninstall removes everything with optional JSON export.
Cortex is MIT licensed, open source at github.com/ProductionLineHQ/cortex, and published on npm as @cortex.memory/cli. If you want to give Claude Code the memory it should have had from the start, the install takes two minutes and the first session will convince you.
Action Checklist
0 of 7 complete
Koundinya Lanka
Founder & CEO of TheProductionLine. Former Brillio engineering leader and Berkeley Haas alum. Builder of Cortex.
Enjoyed this article? Get more like it every week.