Claude-Cortex: Giving Claude Code a Long-Term Memory

Here's the thing about Claude Code: it's incredibly capable in the moment. It can refactor an entire codebase, debug a production issue, build a deployment pipeline. But the moment you close the session, everything it learned is gone. Next time you open it, you're starting from zero.

No memory of your architecture decisions. No recall of that tricky bug you fixed last week. No awareness of your coding preferences. Every session is Groundhog Day.

I noticed this after about 50 sessions. I was re-explaining the same project structure, the same server topology, the same deployment patterns. Every. Single. Time. I was wasting 10–15 minutes per session on context that should have been persistent.

// the solution: structured markdown files

claude-cortex is embarrassingly simple in concept. It's a structured directory of Markdown files that Claude Code reads at session start and updates at session end. No database. No server. No API keys. Just files.

// why markdown

I tried other approaches. SQLite with vector embeddings. A custom API. Even considered using a dedicated memory service. They all failed the same test: complexity. If the memory system itself becomes something you need to maintain, debug, and keep running, you've added a dependency that will eventually break.

Markdown files:

• Work everywhere (any OS, any editor, any cloud storage)
• Are human-readable and editable
• Diff cleanly in git
• Sync via Dropbox, iCloud, Git, anything
• Will never have a breaking API change
• Can be grepped, searched, and processed with standard tools

// how i actually use it

My MEMORY.md has grown to over 200 lines (I need to trim it). It indexes 10+ projects, infrastructure configs, behavioral rules, and research references. When Claude Code starts a session, it reads this file and knows:

• All my projects, their stacks, and their current state
• My infrastructure layout and device roles
• My coding preferences (immutability first, no `any` types, TDD mandatory)
• Past incidents and how they were resolved
• Integration details (API endpoints, database configs, tunnel setups)

The session continuity is the killer feature. At the end of every session, Claude records what was done and what's next. The next session picks up exactly where the last one left off. No re-explanation needed.

// incident runbooks save hours

Every time I fix a non-trivial bug, it becomes an incident file. SSH outage on my VPS? There's an incident-server-ssh-2026-04.md documenting exactly what happened, what the root cause was and how it was fixed. Next time something similar happens, Claude already knows the playbook.

This has saved me hours. Literally hours. Problems that would have required re-debugging from scratch are now fixed in minutes because the runbook is right there in memory.

npx claude-cortex init my-project — GitHub — MIT licensed.