I built a persistent memory layer for AI coding agents (and it fits in a markdown file)

Aravind Raghu — Wed, 08 Jul 2026 02:47:39 +0000

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?

DEV Community: Aravind Raghu