What a static instruction file is genuinely good at
AGENTS.md, CLAUDE.md and their equivalents are read at the start
of a session and injected into the model's context. That gives them four real strengths,
and none of what follows is an argument against using one.
- Deterministic. The same text reaches the agent every time. No retrieval step can fail to surface it.
- Reviewable. It lives in the repository, so a change to how your agents behave arrives as a diff someone approves.
- Versioned with the code. Check out an old branch and you get the instructions that matched it.
- Cheap. No server, no index, no moving parts.
For conventions, architecture notes, build commands and house style, that is the correct tool and it needs no replacement.
Four things it structurally cannot do
These are not gaps you can close by writing a longer file. Each one is a property of the format rather than of any particular file's contents.
1. It does not know what happened yesterday
A file is written ahead of time by a person. It cannot contain the decision you reached at 4pm, the fix that finally worked after three that did not, or the migration you were halfway through when the session ended. Every new session starts from the same fixed text and none of your accumulated working state.
2. It cannot rank
Every line in the file costs the same share of the context budget every session, whether it has ever been useful or not. There is no mechanism by which a paragraph that keeps saving people rises, or one that has never once been relevant falls away. The file only grows, and growing is the failure mode: the more you add, the more each individual line is diluted.
3. It stops at the repository boundary
What your teammate discovered this morning is not in your file unless somebody wrote it there, in your repository, by hand. Neither is anything learned in a different repository, or the runbook that lives in a wiki, or the reason a config value is what it is.
4. It cannot hold a secret
A connection string in a checked-in file is a leaked credential, and no amount of care changes that. So the one category of context an agent most often needs and most often lacks is the category the format can never carry.
What the other layer is for
Dynamic context is the answer to those four, and it decomposes into more than "memory". Firekeep separates them because they have different lifetimes and different rules.
Session state
What you were doing, the plan, the decisions and the files touched — so an interrupted session can be resumed rather than reconstructed.
Long-term memory
What was learned, retrieved by relevance and re-ranked by whether the sessions that used it went on to succeed.
Corpus
Documents your team already wrote — runbooks, wikis, exports — chunked and searchable alongside everything else.
Vault
Credentials, encrypted at rest and fetched by key, so the thing that must never be in a file is not in a file.
The ranking point is the one that is easiest to miss and hardest to copy. Retrieval by similarity alone returns what looks like your query; it has no opinion about whether that memory has ever helped anyone. Firekeep records the outcome of the sessions a memory was used in and lets that adjust where it ranks next time, so the store gets more useful as it is used rather than merely larger.
They are not alternatives
This is the part most comparisons get wrong, and Firekeep is a straightforward example of why: installing it writes to your instruction file. The static layer is where an agent is told when to reach for the dynamic one — recall before starting non-trivial work, write down a fix the moment it lands, open a decision board rather than guessing.
A tool description alone does not produce that behaviour; the instruction has to reach the layer the runtime always reads. So the two layers are complementary by construction. The question is never which to use. It is only which facts belong in which.
A working rule. If it will still be true in six months and applies to everyone who touches this repository, it belongs in the file. If it became true this week, came from one person's session, or would be a credential leak in a diff, it belongs in the other layer.
Where Firekeep sits
Firekeep is a self-hosted server your coding agents check in with. It holds the four dynamic layers above on one Linux host you control, and every capability is exposed as an MCP tool, so any MCP-capable client can use it — with configured adapters for Claude Code, Codex, Kiro and OpenCode. It is free and complete for one person.