Portfolio • Case Study 04
Memory Agent
What is it?
Persistent memory for coding agents. Every session starts knowing what was done, where it stopped and which mistakes not to repeat, without the agent having to remember to ask.
Problem framing
Coding agents start every session from nothing. I was re-explaining the same project, the same decisions and the same mistakes to Kiro, Claude Code, Codex and Cursor, sometimes in the same day. Memory had to carry across sessions and across tools, or the agent would keep relearning what it already knew.
Remembering everything is its own failure. A memory that never updates keeps a decision you’ve since reversed, and an agent will follow it confidently. So the problem had two halves: keep what matters, and know when something has been replaced.
Research through use
The first version gave the agent memory tools and used hooks to nudge it into calling them. It worked when the agent remembered to, which wasn’t reliably. Using it every day surfaced the real lessons:
- Tools get skipped. Memory the agent has to ask for is memory it forgets to ask for, so the second version takes memory out of the agent’s hands entirely.
- Don’t rebuild the host. An audit found three subsystems re-creating what Kiro already provides: session lifecycle, always-loaded instructions and per‑turn triggers. Every one of them was where the defects lived.
- Simpler beats clever. About fifty scoring mechanisms decided what to discard when a tier filled, and the instrument meant to tune them couldn’t be trusted. Plain limits and least-recently-seen replaced them.
- Measure, then fix. Stale to-dos had filled 42 of the 60 short-term slots, pushing real memories out before they could recur. Items that drop out of focus now go straight to the subconscious; the session summary already records them.
- Cost. Laying each consolidation prompt out for caching cut cache-weighted input tokens by about 41% on a five-chunk session.
Solution as a system
The second version works at the harness level. A small background service reads the session logs the IDEs already write, records each finished turn and redacts secrets, with no model and no network. The agent never has to remember to use it.
Then it dreams. When a session goes idle, and again overnight, a model consolidates what happened into four tiers modeled on human memory: working, short-term, long-term, and a subconscious that keeps everything. A new memory is added, reinforces or extends one already known, or supersedes it; a superseded memory gets an end date and moves to the subconscious rather than being deleted. A lesson that recurs in two sessions becomes a standing rule. And forgotten isn’t gone: the subconscious is searched once per session, and a memory that comes up again is brought back.
After every dream it rewrites a short brief where each IDE already loads context, so the next session opens with the rules, where you left off and the newest lessons. Anything that didn’t fit is named by subject for a single read-only recall tool, wired into Kiro, Claude Code and Cursor. No tool call can change memory, and recalled memory reaches the agent as data, not instructions.
Designing the product
With no screen to design, the product is what the agent reads, how it asks, and how it behaves when something breaks. Each of those was a design decision.
- A brief, not a search. The brief loads at session start with no tool call, capped at 5,000 characters globally and 7,000 per workspace, about 3k tokens together. It holds standing rules, where you left off, the newest lessons and decisions, and preferences. Anything cut is listed by subject, ready to pass to recall.
- Plain time, resolved in code. Recall takes “yesterday” or “last Friday”. Models are unreliable at date arithmetic, so phrases resolve in code, and anything outside the grammar fails loudly with the supported list rather than a guess.
- Honest when it’s behind. If the service is down, recall leads with a warning that names the cause and the restart command. If sign-in has expired, the brief says memory is behind, and new work is still recorded for later.
- The model proposes; code decides. Every change the model suggests is applied mechanically. Unknown memories and malformed changes are rejected, never guessed, with at most six new memories per chunk.
- Merges you can check. Two lessons merge only if their rules say the same thing. On the live store, true duplicates’ rules overlapped 1.00, and distinct lessons the model grouped by topic 0.03 to 0.19. A dry run shows tonight’s merges and changes nothing.
- Light, supervised, private. The always-on service uses about 30 MB. Each dream runs as its own process, peaks around 170 MB and exits; one that stalls for 10 minutes is stopped and resumes from its last chunk. Capture needs no model and no network, and nothing but the dream calls a model.
Each IDE gets the brief where it already reads: a steering file in Kiro, a marked block in CLAUDE.md for Claude Code, a rules file in Cursor and a marked block in AGENTS.md for Codex. In a git repo, brief files are excluded, so they’re never committed.
Takeaway
The best memory is the one the agent doesn’t have to think about. Moving memory from a tool the agent calls to a brief the IDE loads did more than any scoring rule.
And forgetting is not deleting. A replaced decision keeps its end date and its link to what replaced it, so the agent follows the current answer and I can still see why it changed.