Agent Kernel Gives Any AI Coding Agent Persistent Memory With Just Three Markdown Files
Photo by Photo by Jakub Żerdzicki on Unsplash on Unsplash
The most annoying thing about AI coding agents isn't hallucinations or bad code. It's the amnesia. Every new session, your agent greets you like a stranger: What's this project? What conventions do we use? Why is that one function named like that? You spend ten minutes re-explaining your codebase before any real work happens.
Agent Kernel, an open-source project that's been making the rounds on Hacker News, tackles this with almost aggressive simplicity: three markdown files that persist between sessions and get injected into your agent's context automatically. No vector database, no embedding pipeline, no cloud service. Just files.
How the Three-File System Works
The structure is deliberately minimal. One file holds project context — what the codebase is, the architecture, the non-obvious decisions. One holds working state: current tasks, known bugs, what was in progress when the last session ended. The third holds learned preferences: how you like tests written, your naming conventions, the linter rules the agent kept forgetting.
The genius is that the files are markdown, meaning you can read them, edit them in your editor, and commit them to git alongside your code. Your agent's memory becomes version-controlled. Roll back a bad session? The memory rolls back too.
A Month of Real Testing
We ran Agent Kernel with Claude Code and Cursor on two projects: a React dashboard and a Python data pipeline. Setup took twenty minutes — mostly writing the initial project context file, which the agent can draft itself from a codebase scan.
The payoff showed up by week two. Sessions that used to start with ten minutes of re-explanation now started with the agent picking up exactly where the last one left off. On the Python project, the agent correctly recalled that we'd decided against a particular library for licensing reasons — a detail documented nowhere in the code itself, only in the memory file.
Context usage was the surprise win. Because the files are concise by design, they add maybe 1,500 tokens per session — trivial compared to the alternative of pasting documentation into every prompt.
The Limitations
Agent Kernel's simplicity cuts both ways. It doesn't scale gracefully past a certain point: our React project's memory files grew to a point where we had to prune aggressively, and there's no built-in tooling for managing that. It also can't compete with full retrieval systems for large codebases — if your repo is 500,000 lines, three markdown files won't capture what you need. And everything lives in plaintext, so don't put secrets in there. Someone on your team will commit it somewhere they shouldn't.
Verdict
Agent Kernel won't replace RAG-based memory systems for big teams, but that was never the point. For solo developers and small teams using coding agents daily, it solves the amnesia problem with a solution so simple it feels obvious in hindsight — which is usually the mark of a good tool. It's free, it's git-friendly, and worst case, you're left with three well-organized markdown files documenting your project. That's a pretty safe bet.
