Project memory / Page 41 of 70
This page is one part of The Ishoo manual. The complete manual is a single page, short enough to read in one go: ishoo.app/docs/
Project memory
Long-term memory for a coding agent is a record it can search, kept in the repository: rules for how the code must be written, decisions with their reasons, and every past issue with what landed. Ishoo hands an agent the rules for its files when it claims work and lets it search the rest.
Every session starts with an empty head. The agent knows your project only through what it reads. Chat history ends with the chat, compaction throws most of it away, and a memory file the agent keeps for itself holds fragments without reasons. So a week later the agent asks a question you already answered, or worse, undoes something you settled on purpose.
Ishoo's answer is to keep the project's memory as ordinary files in the project, and to make the right one cheap to find at the moment it matters.
What the memory holds#
| Record | Where it lives | It answers |
|---|---|---|
| Rules | docs/rules/<area>.md on main, one numbered paragraph each, such as landing.3 | How must this be done here, now? |
| Decisions | docs/decisions/DEC-n.md on main | Why is it this way, and what was tried and rejected? |
| Issues | The store, with a readable copy in .ishoo/records/issues/ | Has this been done or tried? What changed, and which tests ran? |
| Landings | The store, one trace file per landing | Who changed these files, when, and why? |
Rules and decisions are code: they're reviewed in diffs, land on main, and travel with every clone. Issues and landings live on the store ref, which syncs on its own. Nothing sits in a database or a service, so a plain git grep always works too.
Push the map, pull the territory#
Ishoo pushes very little into an agent's context, on purpose. When an agent claims an issue and names the files it will touch, the reply names the rule areas for those files. That's the whole push:
Claimed DOCS-07: Manual: upgrade to dopedocs 0.10.1, better look, and deep pages…
Work in .ishoo/worktrees/DOCS-07 (branch ishoo/DOCS-07).
Rules for these files: product (ishoo_rules area:<name>).Everything else the agent pulls when it needs it, with ishoo_find. This is deliberate. Research on coding agents keeps finding the same things: more context makes them worse even when all of it is relevant; a long CLAUDE.md can lower the success rate and raise the cost; and matching by meaning confuses “about the same thing” with “governs this change”. Classic Ishoo pushed up to ten decisions matched by embeddings into every filing. It missed about a third of the decisions that applied, and about one push in eight was right.
What a search looks like#
The agent asks in a few words and names the files it's working on:
ishoo_find text: "rebase conflict" files: ["src/tools.rs"]
landing.3 [rule, in force] On a rebase conflict, abort the rebase, name the files and who landed there recently, and let the agent resolv… (docs/rules/landing.md)
landing.1 [rule, in force] Land is one call: commit what's in the worktree (the note is the message), rebase on main, fast-forward main, … (docs/rules/landing.md)
STOR-05 [issue, done] Store refs from two machines merge line by line, and real conflicts are shown readably (.ishoo/records/issues/STOR-05.toml)
TEAM-06 [issue, done] Decide which classic git machinery comes back, with evidence (.ishoo/records/issues/TEAM-06.toml)
STOR-06 [issue, done] Sync throws away the other machine's newer work when this machine just converted… (.ishoo/records/issues/STOR-06.toml)Each line is an address, what kind of record it is and whether it still holds, one line of summary, and the file to open. Ishoo never pastes whole records into the reply: the agent opens the one or two that matter and reads them in full. Five short lines cost far less context than one long rules file, and the agent sees why each result is there.
What it deliberately doesn't do#
- No embeddings or vector database. Keyword search with the right scope finds what applies; meaning-matching mostly finds what's related. Ishoo adds a second channel only if an evaluation shows keyword search missing records that apply.
- No AI rewriting of memory. Summaries made by a model drift a little each time they're rewritten, and the drift is invisible. Records are only changed by an agent in a landing you can read, and replaced ones stay as history.
- No index. Every search reads the rule pages and decisions on main and the issues in the store as they are now. There is nothing to rebuild, so search can't disagree with the code.
- No extra tool. Memory search is
ishoo_findwithtext. Fewer tools mean fewer wrong choices.
NoteIshoo can't make a model read what it finds. It makes the right record cheap to find, ranks it first for the files in play, and points out text that cites something replaced. The rest of this chapter covers each part: Searching memory, Rules, Rule, decision or issue? and Citation checks.