← All posts

The Chronicle of the Tower: How Our Coding Agents Learned to Remember

AI agentsKnowledge managementSREGit

A shared memory for a team’s coding agents: markdown in git, review through merge requests, no new database

Four animal familiars in cloaks measure a glowing chronicle with a ruler, an unfinished tower in the window

Update, October 2026. The search described below has changed: results are ranked, partial matches are shown, and pages can carry aliases. How we measured it first, and what the measurement found, is the next tale: The Chronicle Learns to Search.

In the previous tale the builders of the tower got one Book: a single repository with the tools for every familiar (Claude Code, Codex, Kiro, Antigravity). The construction started again.

And then we noticed the next problem. The familiars had tools. They had no memory.

🌅 Every morning starts from zero

A familiar is a wonderful worker with one flaw: every morning it wakes up knowing nothing about yesterday.

Yesterday it spent two hours finding out why the gate server refuses to give a builder a key. It found the reason. The builder said “nice”, closed the session and went home.

This morning another builder, on the other side of the scaffolding, asks his familiar the same question. And the familiar goes digging for the same two hours.

What the team knew was lying in three places:

  • 📜 Scattered: in the archive of scrolls, in tickets, in merge request threads and in the heads of the builders
  • 🎒 Local: what a familiar found stayed in the pocket of one builder
  • 🕸 Stale: the wiki written for humans, which nobody had time to maintain

So the goal for this tale is one sentence:

What the familiar of one builder found today, the familiar of every builder knows tomorrow morning.

And one constraint: markdown in git and review through merge requests. No new database, no new SaaS.

🧭 Three travellers

I did not invent this. Three travellers came by the tower and each told a story.

The first traveller (Andrej Karpathy, “LLM Wiki”) said: knowledge is worth compiling once. Keep the raw sources untouched, let the model write and maintain the wiki pages on top of them, and give the model a schema file with the rules of an editor. A new source updates the pages it touches. A good answer becomes a new page. And from time to time somebody looks for contradictions and stale pages.

The second (mem0, “The State of Agent Wikis”) said: four different teams arrived at the same architecture. Markdown in git, a schema file for the model, compilation at ingest. And one more thing, the one I liked most: a wiki is not yet a memory. The wiki holds what is written in the documents. The memory holds what the team learned in practice: decisions, rejected options, things that did not work.

The third (Cerebras, “How We Built Our Knowledge Base”) said: at the scale of a company this becomes a platform, with thousands of questions a day. We are not a company of that size, so we took one thing from them and postponed another. Took: the same shape for every record (symptom, cause, fix, systems). Postponed: vectors and rerankers, for as long as plain search copes.

Inside the Chronicle: raw sources, wiki pages, AGENTS.md and memory

📚 What we built: the Chronicle

Next to the Book of tools there is now a second repository. The Chronicle.

  • 🗃 raw/ - sources as they are, never edited
  • 📖 wiki/ - pages about our systems, written and maintained by the familiars
  • 🧠 memory/ - what we learned in practice: findings, decisions, incidents
  • 📐 AGENTS.md - the schema: rules for the familiar when it acts as an editor
  • 🛠 a small CLI and five skills: look up, capture, ingest, lint, start a task

And one more piece outside of it: a compass in every repository. An AGENTS.md next to the code that says why this repo exists, which commands matter, where the traps are and what it depends on.

The scrolls for humans (the wiki, the tickets) stay where they were, as the source of truth for humans. The familiar reads them live through an MCP server, we do not copy them.

This is how the pieces connect, from the marketplace to the project repos. The interactive version lets you follow each flow step by step: https://devops01ua.github.io/agent-knowledge-sample/architecture.html

How the pieces connect: the Book, the laptop, the Chronicle and the other repos

A runnable sample of the Chronicle (the schema, a few records, the skills, the CLI and the gatekeeper) lives here: https://github.com/devops01ua/agent-knowledge-sample (tag article-1 is the state described in this tale; the next tale moved main further)

🐾 The path of one finding

Let’s follow one finding from the night it was found to the morning everyone knows it.

The path of one finding in eight steps

1. The compass. A builder runs one command in a repo, once. The repo gets its AGENTS.md and joins the catalogue.

2. Sync before search. Before every search the familiar pulls the fresh Chronicle. Nothing is injected into the session at the start, so the context stays clean, and a colleague’s finding is available right after the merge.

3. Search by words and fields.

acme-kb sync
acme-kb search gitops token --in-repo platform

Every word is a separate condition, quotes mean an exact phrase. You can filter by type (finding, decision, incident, wiki) and by status.

4. The answer names its source. The familiar reads two or three pages, not more, and ends the answer with a footer:

source: F-2026-09-16-001 (verified) · wiki/systems/gitops-install (2026-09-16) · owner: platform-team

The footer tells you whether the fact was observed or only assumed, and how old it is. An answer without a footer is an answer from the model’s imagination.

5. Capture by schema. When a session digs something up, the familiar proposes to write it down, and does it only after the builder says yes.

# memory/findings/F-2026-09-16-001.md
---
id: F-2026-09-16-001
type: finding
status: open
severity: medium
repos: [platform]
systems: [gitops-server]
summary: "The GitOps server cannot issue API tokens for SSO users; use the CLI session (24h, refreshable) or a local read-only account"
symptom: "generate-token fails with 'account does not exist' although the user is logged in"
root_cause: "API keys exist only for local accounts; SSO identities are not accounts"
fix: "Personal use: SSO login, the CLI refreshes the session. Long-lived: a local account with get-only permissions"
evidence: [platform a1b2c3d, configs/gitops/server.yaml]
author: a-builder
agent: claude-code
confidence: verified
updated: 2026-09-16
expires: 2027-03-15
---

Three rules sit in this file. The summary is one sentence you can act on. confidence: verified is allowed only when somebody actually saw it happen. And every record has expires, 180 days by default, because knowledge about infrastructure rots.

One record and what its fields answer

6. A minute of review. The capture opens a merge request. A colleague checks four things:

  • you can act on the summary
  • there is evidence: a commit, a merge request or a file
  • the confidence is honest
  • there are no secrets

That minute protects the whole team from a confident lie in the Chronicle.

7. Status and lifetime. A record is open, fixed, accepted-risk or superseded, and it changes status the same way it was born, through a merge request. An open record past its expires date shows up as a warning.

Statuses of a record and its expiry

8. The gatekeeper again. CI runs on every merge request, with nothing but python and git on the runners:

  • the frontmatter schema
  • dead links between pages
  • required sections on system pages
  • expired open records (a warning)
  • secrets in the diff

The gatekeeper catches the form. Contradictions between pages are still found by a human with a familiar, once a month.

What CI, a colleague and the monthly ritual check

🔁 The plan and what came out of it

The first plan was written in one evening. Five things in it did not survive.

  • The plan was for one tribe of familiars. There are four, so the skills and the compass had to work for all of them
  • The index was supposed to be written by the familiar and kept in git. Now it is generated locally, because every merge request was fighting over it
  • Lint was supposed to be a nightly familiar in CI. The mechanical checks stayed in CI, the semantic ones are done by hand
  • One shared log file for everyone became one file per record. A shared file that everybody appends to is a merge conflict factory
  • The agent instruction file was supposed to import AGENTS.md. It is now a symlink to it, one file for every familiar

⚠️ Honestly about the limits

Three things are not closed yet.

Most of the findings are still open: the problems are described, not fixed. A chronicle of known problems is useful, but it is not the same as a tower without them.

The freshness of the Chronicle depends on a manual ritual once a month. Rituals get skipped.

And the search finds exact words only. Ask for nightmode and it will not see the records about night mode. There is no ranking either. For our size it is enough, and the day it stops being enough we will know what to take from the third traveller.

⚡ Epilog

The tower is still not up to the sky. But a familiar that wakes up in the morning now has something to read.

For the builders it came down to two habits. Ask the familiar “how do we do this here” before starting. And say “capture this” when you dig something up.

And BYOA? The gatekeeper has met them. They did not have a compass.