Project memory / Page 42 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/
Searching memory
An agent searches project memory by calling ishoo_find with a few words in text. Ishoo scores every rule, decision and issue by keyword relevance (BM25), ranks records for the files named in files 1.5 times higher, hides replaced history, and returns the best five, each with the file to open.
Asking#
| Give it | What it does |
|---|---|
text | A few words, the way the record would say them: “rebase conflict”, “store remote”, “stale claim”. |
files | The files you're working on. Records in their rule areas rank 1.5 times higher, and so do issues whose landings changed files in those areas. |
history | true brings back repealed rules, superseded decisions and declined, superseded or shelved issues. Use it for “did we try this before?” |
status | Limits which issues match, such as done or open. Rules and decisions are unaffected. |
limit | How many results. Five by default for a search. |
How results are ranked#
Gather
Every numbered paragraph on the rule pages, every decision file on main, and every issue in the store, each with the file to open.
Hide history
Repealed rules, superseded, rejected or deprecated decisions, and declined, superseded or shelved issues drop out, unless
historyis true.Score the words
BM25, the ranking classic search engines use, over each record's address, title and text. Title words count twice, because a record about a thing names it. Little words like “the”, “how” and “what” are ignored.
Favour your files
A record in the rule area of a file you named scores 1.5 times higher. An issue counts as being in the areas its landing changed, so past work on your files rises too.
Exact names first
Search for an address itself, like
DEC-07orlanding.4, and that record comes first.Answer
The best few, one line each: address, kind and status, a one-line summary, and the file.
Looking up one rule or decision#
Give id a rule address or a decision number and ishoo_find shows the record, then everything that cites it: tracked files by line, and issues by id.
ishoo_find id: "landing.4"
landing.4 [rule, in force] Every landing writes a trace record: issue, agent, time, base, commit, files, note, the tests the agent says i… (docs/rules/landing.md)
Cited by (9): docs/decisions/DEC-06.md:26, docs/rules/README.md:14, docs/rules/landing.md:6, src/citations.rs:1, src/citations.rs:39, src/memory.rs:19, DEC-06, MEM-04, MEM-05Writing a good query#
- Use the record's words, not a question. “rebase conflict” finds
landing.3; “what happens when git fails during land” spreads its weight over words every record uses. - Always name your files. The 1.5 times boost is often the difference between the rule for your code and a similar rule for someone else's.
- Search before filing. The agent's instructions say so: an issue that already exists gets a comment, not a twin.
- Ask for history when it's history you want. A declined idea is hidden by default, which is right for “how do I do this?” and wrong for “did we already reject this?”
Why keyword search and not embeddings?
Embeddings answer “what is this text about?” A coding agent needs “which records govern the change I'm making?” Those come apart all the time: a rule about landing and a decision about landing are about the same thing, but only one may apply. Scoping by the files in play and then ranking by the words used is cheap, explainable, and keeps no index that can fall behind the code.
A project holds hundreds to a few thousand records. Scoring them all takes milliseconds, so there's no need for a search engine either. If a project ever outgrows that, the step up is a proper keyword index, not a different kind of search.
Searching without Ishoo
Every record is a plain file: rules in docs/rules/, decisions in docs/decisions/, issues in .ishoo/records/issues/. git grep and rg work on all of them, so an agent or a person can always fall back to text search.