Let CI Fail: Building Persistent Memory and Checks for Coding Agents

Multi-session coding agents often ask repeated questions because key decisions live only in closed chat windows. A frontend engineer solved this with a file protocol — not by making the agent smarter, but by turning context into files in the repo and using CI checks to enforce maintenance.

The Problem: Decisions Vanish After Session Reset

The pattern is simple: on Monday you tell the agent registration uses phone numbers because most users don't have email; on Thursday a new session opens, the agent sees no email-related logic in the code, and reasonably asks — "Should registration use email or phone number?" No one did anything wrong, but the decision and its rationale are trapped in a chat window that no longer exists. Worse, sometimes the agent doesn't ask and just implements the already-rejected approach.

Developers who use coding agents daily probably write a "mini-brief" at the start of each session: this is a small shop, registration uses phone numbers, don't touch the pricing code because it's been fixed twice, checkout flow is stuck on the failed-payment page design. But you forget different pieces each time, and the one you forget happens to be the one that causes trouble. The author, a React and React Native engineer who uses Claude Code and Codex daily, had a direct requirement: the last five minutes of a session should produce a file, not a memory.

The Solution: Not a Smarter Agent, but a Set of Files

The set is called Fragment. It doesn't run anything — just a few plain-text files in the repo. The core is docs/AGENT-PROTOCOL.md (the rules, one file, both humans and agents read it), CLAUDE.md and AGENTS.md (three lines each, pointing to the protocol file, never a second copy), docs/STATE.md (the board, read first, write after), and scripts/docs-check.sh (checks whether the above files are still true).

STATE.md has a dedicated section: "Decisions already made — don't ask again." Phone number instead of email, and why, all written here. The next session reads it before speaking.

This differs from the common "memory file" approach: many tools store memory as vector databases or persistent memory, but the author chose to turn decisions into plain files in the repo that can be version-controlled and reviewed. The agent doesn't need to understand a database — reading Markdown is enough. This also means humans can edit, diff, and roll back at any time, with no black-box memory.

CLAUDE.md and AGENTS.md are conventional filenames gradually forming in the coding-agent space: the former is auto-read by tools like Claude Code as project instructions, the latter is often recognized by agents like Codex. They are essentially prompt files at the repo root that agents auto-load at session start. Fragment compresses them into three-line pointers, responsible only for directing the agent to docs/AGENT-PROTOCOL.md, avoiding the drift that comes from duplicating the same rules. This "single source of truth" approach is the prerequisite for the file protocol to stay consistent.

The Check Mechanism: Files Rot Within a Week

The author tried the "maintain a single notes file" approach and it failed after about five days: one session forgot to update, the next session trusted the stale board, and the mini-brief loop returned. What really matters is the check script. docs-check.sh fails CI when: a session changed docs without leaving a log trace; links are broken or docs aren't indexed; the board hasn't changed in a week; work is marked done but the checkbox isn't ticked and no command is recorded.

It doesn't care about your code or language — it only checks whether the "story" is still true. Repo-specific rules live in local files, sourced in by the shared check script — updating the check logic never touches those local rules. This design separates the check layer from business rules, making upgrades and reuse easy.

CI (continuous integration) is the pipeline code-hosting platforms run automatically on every push or merge request, typically for tests and builds. Wiring docs-check.sh into CI means: any commit triggers a documentation-consistency check, and failures block merges. This differs from running locally — local checks rely on people remembering to run them, while CI checks are enforced by the platform and can't be skipped. The author's "unskippable engineering constraint" refers precisely to this: turning memory maintenance from personal discipline into a merge gate.

Real Results: One Real Incident Caught in 74 Minutes, a Second Person Naturally Adopting the Process

Fragment was extracted from a private repo, not designed first and implemented later. Two people, two operating systems, two different agents, 25 commits in 18 hours. Two things surprised the author.

The check script caught a real incident 74 minutes after being wired into CI: a file was renamed via GitHub's web interface. A perfectly reasonable cleanup action, but the rename broke three rules at once — a dangling index link, an unlisted file, and a skipped session log. CI turned red within minutes. No one was negligent; the web interface simply couldn't see an index it didn't know about.

The second person adopted the ritual without being taught: all seven of his commits showed the same three-file shape — index, board, actual work. No shared session, no reminder — he just read the same protocol file and converged on the same actions. This suggests the file protocol is somewhat self-explanatory, though the sample is tiny and insufficient to prove generalizability.

What It Doesn't Prove

The author himself lists the limitations: n=2, both production repos run by him; concurrency beyond two people untested, as the two took turns; Fragment doesn't prove it prevents bugs — it prevents context loss and re-arguing already-decided matters. Tests and code review still determine whether code is correct. The full work log (with commit SHAs) is in CASE-STUDY.md.

n=2 is a statistical term for sample size, referring to an observation based on only two people and two repos. With such a small sample, any conclusion like "the second person naturally adopted the process" can only be treated as a case signal, not generalizable evidence. The author proactively flags this to distinguish "what I observed" from "what I can prove." In engineering writing, clarifying sample boundaries is more valuable than exaggerating universality, and it leaves room for larger-scale validation later.

How to Try It

In Claude Code, run npx skills add hematenergi/fragment --skill fragment, or paste the installation prompt from the website into whatever agent you use. The first run of the check script will fail — that's the feature; it's an adoption checklist. Work through items until it turns green. The author is Dany, an independent engineer in Indonesia, GMT+7, open to remote contract work.

Fragment's value isn't in inventing a new concept, but in moving "agent memory" from chat windows into the repo and using CI to turn memory maintenance into an unskippable engineering constraint. This is more durable than any single prompt trick, and more controllable than making the agent smarter. The cost: you need to maintain a board and a check script, and build the discipline in your team of reading the protocol at session start and writing state at session end. For developers collaborating with coding agents daily, this may be one of the lowest-cost context-persistence solutions available today.