Canonical: https://agent-personalizer.aunysillyme.dev/docs/how-it-works/

Read the source: [docs/tiers.md](https://github.com/aunysillyme/agent-personalizer/blob/main/docs/tiers.md)

# How it works

Instructions to an AI live in five places. Each has one job and prevents one failure. Put a rule in the wrong tier and it either decays, drifts, or gets ignored. Put it in the right one and it holds.

Read bottom-up. Tier 1 is the most present, tier 5 the most durable. Install levels select the files you receive; these tiers explain where the resulting instructions belong.

Tier | What | Prevents | 

1 | Style in the system prompt | rules decaying over a long chat | 

2 | One always-loaded home file | the AI not knowing where anything is | 

3 | Session-start injection | a tool's own instructions beating yours at the moment of decision | 

4 | One owning document per rule | the same rule drifting in five copies | 

5 | Memory with a status on every fact | the AI treating its own guess as your ruling | 

A word on the stories below: each is one setup's experience of what held and what did not. They explain why the tiers are shaped this way. They are not measurements, and placing a rule in a tier puts it in front of the model; it does not make the model obey. Instruction precedence differs by host and model.

## Tier 1: style in the system prompt

What. How the AI writes back to you: length, structure, punctuation, what to lead with. Not what it knows. Not what it does.

Where. The one slot your AI keeps in front of it every single turn. Claude Code calls it an output style. Chat apps call it custom instructions or a system prompt. If the app has no slot, the top of the home file is the next best place.

Prevents. Decay. A style stated once in a message fades after twenty turns. A style in the system prompt is re-sent on turn two hundred exactly as on turn one, so it cannot fade for lack of presence (it can still be ignored).

Story. A user corrected the same formatting habit, in words, more than thirty times across two months. Every correction held for a session and vanished. Moving the same sentence into the system-prompt slot ended it in a day. The rule had not changed. Its tier had.

## Tier 2: one always-loaded home file

What. `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, whatever your AI reads first. It says who you are (by pointing at `USER.md`), where your notes live, and which document owns which rule.

Where. The root of the project or folder the AI works in. Some AIs also read a global one in your home directory.

Prevents. The AI not knowing where anything is. Without a home file it re-derives your setup every session, wrongly.

Story. A home file grew to 40 KB of rules, restated from documents that lived elsewhere. Three of those restatements went stale within a month and the AI followed the stale copies with full confidence, because the home file is the first thing it reads. The fix was not a shorter file. It was a file of pointers: one line per rule, naming the document that owns it.

Rule inside the tier. The home file carries pointers, or a generated block, never a hand-maintained copy. A `[hook: name]` or `[owner: path]` tag on a one-line rule tells the AI where the full text lives. The block between the render markers is the one exception: it is a generated snapshot of `USER.md`, `LEARNED.md` and `rules/`, regenerated by `render/render.cjs` and compared by `--check`, so it has one owner and a drift detector. What this tier forbids is a second copy you maintain by hand.

## Compact mode and file budget

Use `--compact` on the installer or renderer to save `compact: true` in `.agent-personalizer.json`. Re-renders and `--check` use that preference. Set it to `false` to return to full rules. For Claude, agents, Gemini and Hermes file targets, each non-injected rule becomes its title, universal `In practice:` line and a link to the full rule. Levels 1 and 2 link to the version-pinned public rule; level 3 links to the editable local rule. Rules marked `inject: true` stay in full. ChatGPT and prompt targets are unchanged. A custom rule needs an `In practice:` line for compact mode.

The four file targets have a 20,000-character warning budget for the whole rendered file, including text outside the generated block. Hermes may truncate context files above roughly that size. A warning leaves the file intact and exits 0; renderer `--strict` exits 1 and writes nothing when a file or ChatGPT box exceeds its budget.

## Tier 3: session-start injection

What. The handful of rules that must win at the moment of decision, injected in full at the start of every session. Not pointers. Full text.

Where. A session-start hook (Claude Code and Gemini CLI both support `SessionStart` hooks; see [hooks/README.md](https://github.com/aunysillyme/agent-personalizer/blob/main/hooks/README.md)). For AIs without hooks, a block you paste at the top of the first message, or a saved prompt that starts every session.

Prevents. A tool's own instructions beating yours by default. Installed skills, plugins and tool descriptions each say "use me." A rule that says "use the other one first" loses that argument if it is only stated in a document the AI may or may not have opened. Injection makes sure your rule is at least in the room; it does not settle the argument on every host.

Story. Thirty-two installed skill packages for one crawling service each instructed the AI to use that service. The user's rule said a different, free tool was the default. The rule lived in the home file as a pointer. The AI picked the paid service every time, because at the moment of choice thirty-two voices said one thing and one pointer said another. Injecting the full routing rule at session start fixed it. Prose in a document does not win that argument; a contract present in context does.

Rule inside the tier. Injected contracts are few, and each carries its story. Ten is a lot. Every one costs tokens every session.

## Tier 4: one owning document per rule

What. Every rule has exactly one document that owns it. Everything else points there. Canon is read on demand, when the task needs it.

Where. Your notes folder. A `protocols/` or `rules/` directory. Each file names what it owns.

Prevents. Drift. A rule hand-stated in five places drifts in five places, and the five copies disagree silently until one of them is quoted back at you as your own ruling.

Story. A routing rule was corrected in its owning document. Four days later, four other surfaces still carried the old version, and the AI quoted one of them to the user as if her own decision had been the reverse. A drift detector had been green the whole time, because it checked that each surface matched the rule as last recorded, not that each surface matched the owner. Restating canon is how it drifts. Link down instead.

Rule inside the tier. If you find yourself pasting a rule's text into a second file by hand, stop and write a pointer, or let the renderer generate the copy and check it. Pasted copies you cannot check (a chat app's instruction box) are re-pasted after every change; nothing can detect a stale paste for you.

## Tier 5: memory with a status on every fact

What. What the AI remembers about you across sessions: preferences, corrections and project facts. agent-personalizer ships this tier as `LEARNED.md`: each entry has an origin (`said` or `inferred`), an approval status (`confirmed`, `proposed` or `declined`) and optional short evidence.

Where. `LEARNED.md` in the installed folder owns the shared entries. Your AI's own memory remains in its app. The renderer puts confirmed entries and a declined "Never ask again" list into personal AI instructions and the session-start contract. Proposed entries render nowhere.

Prevents. The AI treating its own guess as your ruling. An inference written down without a status reads, next session, like something you decided.

Story. A memory file said the user preferred a certain tool. The user had never said so; an earlier session had inferred it from one choice. Three sessions built on it. The status field exists so the next session can tell the difference between "she said" and "I guessed." When the user rejects an entry, mark it `declined` and keep the correction in its evidence rather than silently overwriting it.

Rule inside the tier. Ask before keeping an entry as confirmed. A no is recorded as declined and never asked again. Re-render after an entry changes; `--check` catches an unrendered edit. The digest of past messages is temporary evidence, separate from the entries: `learn --forget` removes it, and uninstall keeps `LEARNED.md` once it holds anything you wrote. See [learning.md](https://agent-personalizer.aunysillyme.dev/docs/learning/).

## How the tiers relate

```
tier 1  style        every turn        system prompt slot
tier 2  home file    every session     pointers to owners
tier 3  contracts    every session     full text, few, with stories
tier 4  canon        on demand         one owner per rule
tier 5  memory       across sessions   facts with a status
```

A rule moves DOWN the tiers as it proves durable: a correction becomes a memory fact, a memory fact that keeps mattering becomes a rule in canon, a canon rule that keeps losing arguments becomes an injected contract. Nothing starts at tier 3.
