Two things bothered me about AI coding agents. First, they forget everything between sessions — ask Claude Code on Monday how to submit a job to my cluster and it figures it out from my scripts, beautifully, then does the exact same work again on Friday. Second, the tools that fix this mostly want my entire session history living in their cloud, in a database I can't open, under a retention policy I don't set.
So I built Peon around a single principle: the memory is yours. It's a local daemon that records your sessions through hooks, consolidates them into typed beliefs with a model you choose, and injects the relevant ones into each new prompt. This post is about what "yours" actually means, because that's the whole point.
Your files. Every belief Peon holds is a line in a plain JSONL file inside your repo. Not a vector database, not a hosted store — a text file you can cat, grep, edit by hand, delete, or git-commit so memory travels with the code. The real-time brain files (decisions, preferences, open questions) are readable markdown. If you want to know what your agent believes about you, you open a file and read it. If a belief is wrong, you delete the line.
Your boundaries. There's a global brain for facts about you (your tools, your conventions, your rules) and a separate child brain per project. You decide where those lines are with a .peon/root marker, so a big subproject can own its memory and a parent directory can never silently swallow it. Injection at session start carries the project's memory plus the inherited global memory, and nothing else.
Your model, or none. Consolidation runs on whatever you configure: OpenRouter, OpenAI, Anthropic. Or point it at a local Ollama and nothing leaves your machine. Or set PEON_AI_MODE=off and there is no model at all — capture becomes deterministic rule-based extraction into readable markdown, retrieval is lexical with recency and importance priors, and episodic recall is verbatim. It's a genuine mode, not a degraded fallback nobody tests; the lexical path is the same one the semantic stack falls back to, so it runs constantly.
Nothing you can't undo. The consolidator can supersede a belief or merge duplicates, but it never hard-deletes. Retired beliefs stay in the file, linked to whatever replaced them, fully recoverable. Every mutation is backed up first. This isn't a slogan — while A/B testing the tool I hit a bug where a stale superseded belief outranked its newer replacement in retrieval. The fix demotes the stale one at rank time. It deletes nothing, because deleting your memory is not a thing this tool is allowed to do.
Does it actually work? I measured it instead of asserting it. 20 questions about my thesis repo, each run in a fresh session twice — memory on, memory off — same model, same tool access, token counts from Claude Code's own transcripts. Memory averaged about 42% fewer tokens and won 12 of 15 clean pairs. But I'll be honest: the token number undersells the tool, because my repo has a well-maintained research log the no-memory arm could just read to reconstruct answers.
The result that actually shows what memory is for was a single question. It asked about a rule my professor set for citing papers. That rule arrived in an email and was discussed in a session — it exists in no file in the repo. The baseline searched, found nothing, and honestly said so. Peon recited the rule, the exceptions, and who to cc. Conversation-borne knowledge has no file to grep. That's the memory you can't get any other way, and Peon keeps it somewhere you control.
The honest caveats, because n=15 on one repo is a pilot, not a benchmark: the questions were picked to have known answers, the repo's docs prop up the baseline, and your numbers will differ. There's an open issue asking people to run the same test on their own repos and post results, including losses. One feature already ships disabled because it measured -2.9% Recall@10. The eval ledger that proves all this is committed to the repo.
Peon is MIT, local-first, plain JSONL, and works with Claude Code, Codex, and any MCP client. npm install -g peon-mem, or read the code: https://github.com/VineetV2/peon-mem
Top comments (2)
I like the JSONL choice here. Agent memory gets risky when the only editor is another agent, because you lose the boring escape hatch. A repo-local file you can grep, diff, and delete is much easier to trust when the memory is wrong.
This is a really interesting approach to agent memory. I especially like the idea of keeping the memory in plain JSONL and giving the developer full control over what gets stored, changed, or removed. The distinction between project-specific and global memory also makes a lot of sense.
The experiment around the professor’s citation rule is particularly compelling—it highlights the kind of context that traditional repo-based retrieval simply can’t recover. I’d be interested to see how Peon performs across different types of projects and larger teams. Great work