Every AI coding session starts blank.
You open Cursor. You open Claude. You paste your architecture doc.
You re-explain your folder structure. You describe your patterns again.
Then the context window fills up and you start over.
For small projects, annoying. For large codebases, it's a real productivity
killer.
The insight
The problem isn't the AI. It's that there's no persistent, structured
summary of your codebase that travels with the repo.
So I built one.
What Cortex does
Cortex maintains a single file — CORTEX_MEMORY.md — committed directly
to your repo. It summarizes every source file: what it does, its key
functions, dependencies, and gotchas.
On each session, it only re-summarizes changed files using SHA-256
hash diffing. Everything else is cached. So after the first run, it's
fast and cheap.
You paste the file into any AI assistant. It understands your whole
codebase instantly.
How it works
pip install cortex-agent
cortex init
cortex run
# CORTEX_MEMORY.md is generated
Each file gets a structured summary:
src/auth/jwt.py
Purpose: Handles JWT token generation, validation, and refresh.
Key functions: generate_token, validate_token, refresh_token
Dependencies: python-jose, datetime, os
Notes: Tokens expire in 24h. Refresh tokens use a separate secret key.
On the next run, if jwt.py hasn't changed — no API call. Free.
If it changed — one targeted API call to re-summarize just that file.
The staleness problem (and how I solved it)
The hardest part wasn't summarization. It was keeping the memory fresh.
Options I considered:
- File watcher — too noisy, expensive (LLM call on every save)
- Git hooks — only fires on commit, misses mid-session changes
- Manual — nobody does it consistently
Solution: hash check on session start.
On every cortex run:
- SHA-256 hash all source files
- Compare against stored hashes from last run
- Re-summarize only mismatches
- Prune entries for deleted/renamed files
- Write updated memory + hashes
Simple, reliable, cheap.
Token limits (alpha is conservative)
I deliberately set tight defaults to prevent surprise bills:
| Limit | Default |
|---|---|
| Per-file budget | 2,000 tokens |
| Per-session budget | 10,000 tokens |
| Max file size | 100 KB |
| Max files per run | 50 |
At these limits, a session costs ~$0.003 on GPT-4o mini.
1,000 users × 10 sessions/day = ~$15/day total.
Works with any AI tool
No lock-in. Cortex generates plain markdown. Paste it into:
- Cursor
- Claude
- ChatGPT
- Copilot Chat
- Anything
What's next
- MCP server integration (auto-inject into Cursor/Claude Code)
- Multi-model support (Claude, local models via Ollama)
- Failure memory — storing what didn't work and why
Try it
GitHub: https://github.com/aravindr-res01/cortex
Would love feedback — especially from anyone working on large codebases
where context limits are a real pain. What would make this actually fit
into your workflow?
Top comments (1)
"Every AI coding session starts blank" is the frustration that shaped half my workflow — and I'm not even a developer. My caveman version of Cortex: every project I build keeps a hand-maintained markdown file of rules, gotchas, and "what worked last time," and every session starts by feeding it to the AI. It's crude, but it turned repeated mistakes into one-time mistakes. Markdown being the format is the underrated part — I can read it, doubt it, and fix it, which is exactly what I can't do with opaque memory.
One question from that experience: when I correct a stale note by hand, my edit survives because I'm the only writer. In Cortex, if the file changes and gets re-summarized, do human corrections to the memory survive the next run — or does the regeneration overwrite them? That's the detail my workflow would live or die on.