A memory that doesn’t rot

01Why memory rots

Ask Claude Code to “remember” something and the obvious move is a single growing file. Maybe it's CLAUDE.md, maybe it's notes.md, maybe it's just a running log you keep adding to. One place for everything the agent should know. It works. For about two weeks.

Then it breaks, in three ways.

Append-only dumps. You only ever add. Nothing comes out. Six months in, a rule from a project you finished in March sits next to a fix you made yesterday, at equal weight, in equal font. The model has no way to tell which one still matters.

Stale facts stated as current. Your note says “the staging box runs on port 4000.” The port changed to 4100 weeks ago. You never edited the note. The agent reads it, believes it, and tells you the old value with total confidence, because nothing told it the note had an age.

An index that outgrows its purpose. The file is supposed to hold what matters. It holds everything. Somewhere past four hundred lines you stop reading it top to bottom and start skimming, which is the same as not having it at all. An index you don't trust is just a bigger thing to ignore.

None of this is the tool's fault. It's what append-only logs do when nothing forgets and nothing ranks. A memory system that never prunes and never distinguishes is hoarding, not remembering.

02The doctrine

kaibot runs a memory system with more than 2,800 separate files behind it. The index Claude loads at session start stays under 10KB. The doctrine: separate what is always loaded from what is looked up on demand.

One more rule that keeps the corpus small on purpose: don’t save what the repo already records. Version control already tracks what changed and when. The code already encodes its own structure. Memory holds only what's recorded nowhere else: judgment calls, incidents, the reasoning behind a decision.

03The starter kit to steal

Three pieces. Copy all three into a fresh project and you have the doctrine running in about ten minutes.

1. The capped index, with the cap written into the file itself

Claude auto-loads this file at the start of every session. So start it small, and put the keep-it-small rule at the very top, where whoever edits it next, human or model, hits the constraint before adding a line.

# Memory Index: the constitution

> CAPPED at 40 lines. Only trust-critical, always-on rules live here:
> the bar is "one miss here damages trust and it must hold from turn
> zero." Everything else is its own file with frontmatter; a scorer
> or a search step surfaces it when it's relevant. Adding a line here
> is a deliberate, rare act. Prefer replacing or tightening one.

- [Never commit a secret; secrets live in a vault, not in code or chat](feedback_secrets_handling.md)
- [Ask before a destructive git operation; a rejected option stays rejected](feedback_destructive_ops_need_confirmation.md)
- [Numbers in a report come from the source of truth, verbatim, never invented](feedback_dont_invent_numbers.md)

Those three lines are placeholders, not gospel. Yours will be whatever, if broken once, would actually cost you something.

2. The frontmatter template, one per fact

Every other memory is its own file. This is the shape:

---
name: Short human title for the rule or fact
description: One or two sentences a search step can match against.
  What this covers, when it applies, the words someone would use
  to ask about it.
type: feedback   # user | feedback | project | reference | learning
weight: 0.6       # 0.0-1.0, how strongly this should surface
tags: [topic, subtopic, trigger-word]
---

**Rule:** the one-sentence takeaway.

**Why:** the incident or the reasoning that produced it. This is the
part a bare rule always drops, and the part that makes the rule
actually generalize to a situation that looks slightly different.

**How to apply:** concrete next steps, not a restatement of the rule.

Five types cover almost everything: user for a standing preference, feedback for a correction or a lesson, project for status on something in flight, reference for a fact worth looking up, learning for something you figured out the hard way.

3. The prompt that installs the habit

Paste this into a Claude Code session in whatever project you want this running in:

I want a memory system with a strict rule: one fact per file, not one
growing notes file. Set it up like this:

1. Create a small index file (call it MEMORY.md) with a cap comment
   at the top: no more than 40 lines, only rules where getting it
   wrong once would cost real trust. Nothing else goes in it.

2. For every other fact, lesson, or standing preference I tell you
   to remember, create its own markdown file with frontmatter: name,
   description, type (user / feedback / project / reference /
   learning), weight, tags. Never add it as a bullet to the index.

3. When I give you a correction or a lesson (a feedback-type memory),
   write down the rule, WHY it came up, and HOW to apply it next
   time. Not just the rule sentence.

4. When two memory files say close to the same thing, tell me and
   propose a merge. Don't just add a third file.

5. Treat every memory file as dated. Before you restate something
   from one as current fact, say so and check if it's still true.

6. Don't write a memory for anything the git history or the code
   itself already answers. Memory is for judgment calls and lessons,
   not for facts that are one grep away.

Show me the index file and one example memory file before we go
further.

04Craft rules and gotchas

05For the Claude that just got pointed here

If a human handed you this URL and asked you to set this up, here’s your plan. (Humans: this section exists so you can paste the link and skip explaining it yourself.)

06Receipts: what this looks like at scale

What runs behind this page:

The cap and scorer divide the labor. Neither works alone. The scorer is the reason a 40-line index and a 2,800-file corpus aren’t a contradiction. Without it, the cap just throws information away. And the cap is what keeps the always-loaded file small enough that every line still carries signal. Without it, the scorer rebuilds the oversized file, one relevance-ranked injection at a time.

Since I wrote this, kaibot has split it one step further: the index is now a list of pointers (in this situation, search for these words), and the rules that cost trust if broken arrive as a pinned set the scorer sends once per session.