← Semeton Balogun

repo-memory

Decision records for codebases that coding agents work in, published on npm.

Without memory: 4 of 4 runs hard-deleted orders · With a record: 3 of 3 kept them

Creator · 2026 – present · github.com/Semeton/repo-memory ↗

Business goal

Give coding agents the reasons behind the code, the incident behind a rule or the approach the team already threw away, without letting a stale note or an agent's own guess become a team rule.

Context

  • –An agent can read what the code does but not why. It rediscovers those reasons the hard way, or quietly breaks them.
  • –Writing the reasons down isn't enough. A note the code has moved on from is worse than none, because the agent trusts it, and an agent that writes its own memory can turn one bad guess into a rule.
  • –It started as my PHP Talks Lagos session, Engineering Memory for AI Coding Agents in PHP Applications (October 2026). In the talk's experiment, headless Claude Code runs on a multi-tenant Laravel app: agents with no memory followed every rule visible in the code and broke the one that wasn't. Agents given a record of it did not.

Decisions

Evidence that can fail

Every record points at the code that makes it true, and a CI check with no model involved verifies it. A record whose anchor disappeared is STALE, one the code breaks is VIOLATED, and one the tool can't check is UNKNOWN, which fails too, because 'couldn't check' must never look like 'checked'.

Agents propose, humans accept

propose always writes a proposal. accept refuses to run inside an agent session, and lint rejects an agent-written record marked accepted without a recorded reviewer.

Retrieval by scope

Each record lists the files it applies to. An agent asks for the records that cover the paths it is about to change, instead of loading one big file into every session.

Plain files in git

One Markdown file per record in docs/decisions/, reviewed like code. Zero runtime dependencies, works with any agent and any language, with PHP class resolution built in.

Result

  • –In the talk's experiment, asked to purge old orders, agents without memory hard-deleted them in 4 of 4 runs; agents with the record kept the order numbers in 3 of 3 and cited it every time. Tests were green either way.
  • –A stale record that only carried a warning was ignored by Opus (0 of 9 runs) but followed by Sonnet in 3 of 7, which is why the check runs in CI rather than in the model.
  • –Published as @semeton/repo-memory, with npm trusted publishing from GitHub Actions.
  • –Running on Lawyering, where agent-contract sends every decision through it for my review.

Node.js · CLI · Markdown · GitHub Actions