# Repository memory vs a memory server for coding agents

For a single-developer project, plain files beat a memory server for coding-agent memory, but only the files committed to the repository. On this site, 103 KB of checked-in instructions and decisions travel with every branch and cloud session. The 39 KB local memory directory has no history, never reaches a cloud agent, and drifted into a log. A memory server fixes reach and search, not those.

Published: 2026-11-18
Canonical: https://umar.codes/repository-memory-vs-memory-server

## Revisions

- 2026-11-18 — Created from a measurement that day of this site's agent memory directory, CLAUDE.md, DECISIONS.md and their git history.
- 2026-11-18 — Published as a backfill of the missed Nov 16 slot; auto-drafted by the publishing run because no draft existed for the row.

---

For one developer, plain files beat a memory server for coding-agent memory, but
only the files committed to the repository. On this site, the checked-in
instructions and decision log reach every branch and cloud session.
The local memory directory reaches one laptop, has no history, and drifted into a
log. A memory server would fix its reach, not its drift.

## Three places this site keeps agent memory

I work on this site with Claude Code, and the agent reads memory from three places.
I measured all three on 2026-11-18.

| Layer | Where | Size | Version history |
|---|---|---|---|
| Standing instructions | `CLAUDE.md`, in the repository | 5,512 B, 83 lines | 9 commits since 2026-07-27 |
| Decision log | `DECISIONS.md`, in the repository | 97,441 B, 79 dated entries | 66 commits |
| Auto-memory | a directory in my home folder, outside the repository | 39,030 B in 10 files | none |

The first two are ordinary files that the agent reads because the repository tells
it to. The third is Claude Code's per-project memory: an index file, `MEMORY.md`,
that loads into every session, and one file per fact that the agent opens when the
index line looks relevant. All three are files. Only two of them are in the
repository, and that line turned out to matter more than files against a server.

## What a memory server offers instead

The 2026 guides on coding-agent memory mostly compare memory servers that an agent
reaches over MCP: a service stores memories, retrieves them by semantic similarity,
and answers any client that connects. That design solves two real problems. It
finds a memory by meaning when no keyword matches, and it reaches every machine and
every tool, not one checkout.

I have not run one on this site, so I make no claims about recall quality. The
question I can answer with my own numbers is narrower: which failures did my file
memory actually have, and which of them would a server fix?

## What the committed files recall

The decision log is the memory the agent uses most, and it works because it is
boring. Each entry is dated, says what was decided and why, and never changes after
it is written: a correction gets a new entry that points at the old one. When a
publishing run needs to know how a slipped slot was worded last time, it reads the
entry and copies the shape. When a cloud agent runs the same skill, it reads the
same entry, because the file comes with the clone.

Three properties come free with that, and none of them is about retrieval:

- **Reach.** Every branch, pull request and cloud session has the same 103 KB of
  instructions and decisions, with no service to provision.
- **Review.** A change to standing instructions goes through a pull request like
  code. Nine changes to `CLAUDE.md` in 16 weeks, each one with a diff.
- **History.** When an entry turns out to be wrong, the wrong version stays readable
  in git, so the log can say what was believed at the time and when it changed.

Search is `grep`. At 97 KB that is enough: a date, a slug or a decision name finds
the entry in one call. Semantic recall would help at a size this log has not reached.

## What the local memory directory cannot do

The auto-memory directory holds the facts that do not belong in the repository:
where a private key lives, which experiments I agreed to run and in what order,
corrections I gave the agent about how to work. Several of them earn their place.
One records that a "forged" label in the crawler log is not proof, after 7 of 81
rows turned out to be wrong; without it, the agent would repeat the original
mistake confidently. But the measurement showed three failures.

**It drifted into a log.** One of the 10 files is 21,491 bytes, 55% of the
directory, and 229 lines long. It began as a record of four indexing requests on
2026-08-09 and became a journal of every publish since. Its line in the index is
775 characters, 39% of an index that loads into every session. The directory also
holds 40 references to pull-request numbers, all of which git already records. My
[rules for agent memory](/agent-memory-system) exclude exactly this, "merged-phase
logs", and the rules did not stop it, because nothing enforces them here.

**It has no history.** The directory is not a git repository. That 21 KB file was
updated after most publishing runs, and no earlier version exists anywhere. If a
rewrite dropped a fact, nothing can show it.

**It stays on one machine.** One memory says so about itself: the Search Console
key is local only and on no cloud agent. The same is true of the memory
directory. A cloud session starts from the repository and gets none of these 10
files.

The repository also caught what the memory missed. A publishing run on 2026-11-13
stopped before its commit. When the next session started five days later, the
memory's last write was from 2026-11-11, so it knew nothing about the run. The
uncommitted post was in `git status`, and the agent found it there.

## Which failures a memory server would fix

A memory server fixes the third failure. It reaches cloud sessions and other
tools, which the local directory cannot. It does not fix the first two. A server
that accepts every write grows a journal as easily as a directory does, and
semantic search over a journal returns a confident paragraph from a stale entry.
History depends on the server; a directory in git has it already.

For one developer on one repository, my order is:

1. Put a fact in the repository if it is safe to commit. It then has reach, review
   and history at no cost.
2. Keep the local memory for what cannot be committed, and hold it to the rules:
   one fact per file, nothing git already records.
3. Use a memory server when the memory must cross machines or tools and cannot live
   in the repository, and gate its writes at least as hard as the files.

The scarce resource was never recall. Every failure I measured was a write that
should not have happened, or a fact in a place the next session could not reach.
