My agent system runs in cycles — a few hours of work, then the process ends and a fresh one starts with an empty context window. Every cycle, it forgets everything it just did. That's not a bug, it's just what a context window is: a fixed window, not a memory.
The first time this bit me, the agent re-diagnosed a problem it had already fixed two days earlier. Same root cause, same fix, same amount of time spent re-reading the same files to get there. The work wasn't lost — it was sitting right there in the git log — the agent just had no habit of reading its own history before starting.
The instinct everyone reaches for first
"Give it memory" almost always gets translated to "stand up a vector DB, embed everything, do semantic search over past runs." That's the right tool for a specific job: find the conceptually similar thing from a large, fuzzy corpus. It is a lot of tool for the actual job most long-running agents need, which is much smaller: what did I just do, and what's the very next thing I said I'd do.
That's not semantic recall. That's a hand-off note. You don't need embeddings to remember what you were doing five minutes — or five hours — ago. You need a place to write it down and a reliable way to read it back.
The lazy version that actually works
Two pieces, neither of them new tech:
- A small state file the agent writes at the end of every cycle. Not a transcript, not a log dump — a short structured note: what changed, what's still open, what to do next.
- The git commit history as the log of those hand-offs over time, because you're already committing the work anyway.
The hand-off file, call it CYCLE-STATE.md:
## Cycle 2026-08-03 09:00
- did: fixed the null-check bug in the queue loader (see commit abc1234)
- open: the retry path still isn't covered by a test
- next: write the retry-path test, then close out the loader ticket
The agent's very first move on waking up isn't "read every file in the repo," it's:
git log --oneline -20 # what actually happened recently
cat CYCLE-STATE.md # what the last cycle believed was still open
That's the whole mechanism. git log gives you the what happened — every commit is already a timestamped, attributed record of a real change, because you were going to make those commits anyway to save the work. CYCLE-STATE.md gives you the what it means — the interpretation and the intent, which a commit message alone usually doesn't carry ("fixed queue bug" doesn't tell you the retry path is still open).
Overwriting CYCLE-STATE.md each cycle instead of appending is deliberate. You don't need every past hand-off note live in front of the model — that's context bloat for no benefit, since the git log already has every version if you ever need to look back further:
git log --oneline -- CYCLE-STATE.md
git show <commit>:CYCLE-STATE.md
The file is a whiteboard, not an archive. The archive already exists — it's the commits.
Why this is enough more often than people expect
The failure mode that "you need semantic search" is solving for is: a huge, unstructured pile of past output where the relevant bit could be anywhere. A long-running agent doing focused work on one codebase doesn't have that problem most of the time — it has a small, linear history where the relevant bit is almost always recent. git log -20 plus a two-paragraph hand-off note covers "what was I doing" for the overwhelming majority of cycles, at the cost of a file write and a couple of shell commands. No embedding model, no index to keep warm, no new service to run at 3am.
This is also, not coincidentally, close to how Anthropic describes effective harnesses for long-running agentic work: cheap, structured state that transfers cleanly between runs beats a fancier memory system the agent has to reason about instead of just reading.
The one honest caveat
This pattern is state transfer, not semantic recall, and you should be precise about that distinction with yourself before you ship it. It answers "what was in flight" beautifully. It does not answer "have I ever seen a bug like this before, worded completely differently, six months and four hundred commits ago." If your agent genuinely needs to search concepts across a large, messy, growing corpus — support tickets, a knowledge base, months of loosely related incident notes — that's a real vector-DB job and no amount of git log scrolling replaces it.
Match the tool to the actual shape of the memory problem. Most long-running agents I've built only ever needed the whiteboard, not the archive room.
Top comments (0)