diff --git a/docs/claude-md-sample.md b/docs/claude-md-sample.md index 8094138..ab9126c 100644 --- a/docs/claude-md-sample.md +++ b/docs/claude-md-sample.md @@ -11,13 +11,23 @@ scratch. | `` | | | `` | | +`store` needs a `scope`. Reads (`search`, `recall`, `list_recent`, `stats`) cover every scope you can read unless +`scopes` narrows them. `list_scopes` shows the scopes you can use and your access to each. A scope you have no grant on +is reported as "not found", the same as one that doesn't exist. So if a store fails that way, check `list_scopes` +rather than retrying. + Everyone who can read a scope sees everything in it, threads included. If a finding came from somewhere private, store -a version with the private details taken out. +a version with the private details taken out. If a bot that answers in public reads a scope, treat everything in that +scope as public: it may be quoted. ### At the start of a session - When picking work up, or asked "where was I" or "what's left", call `recall` with the relevant topics before answering. Those answers live in earlier sessions, not in this conversation. +- To sweep across every repo, search by status tag rather than by topic: + `search(query="outstanding work", tags=["status:open", "status:blocked", "status:in-review"])`. `tags` matches a + memory with any of the tags. `tags_all` requires every one, so `tags_all=["repo:", "status:open"]` gives one + repo's open work without filtering on the client. - If a status memory names a thread session label, call `whats_new` with that label before carrying on. ### Work status @@ -30,21 +40,30 @@ Store a memory when starting a task, reviewing a PR or ticket, or parking someth - `pr:` / `issue:` when there is one. Write it so it still makes sense in six months: what the work is, where it got to, and what the next action is. +"Fixed the bug" is useless. Name the branch, the file, the decision taken and what remains. **When the state changes, `update` the existing memory. Never store a second one.** Find it by its `repo:`/`pr:` -tags, change the text and swap the `status:` tag. If a duplicate has crept in, delete the stale one. +tags, change the text and swap the `status:` tag. If a duplicate has crept in, delete the stale one. A store that +lies about status is worse than none, because it is believed. + +- **Changing only `tags` or `category` is safe:** the content and its embedding are kept. +- **Changing `content` re-embeds it,** so meaning-based search finds the new text. +- **`update` can move a memory to another scope** (`scope`). This needs write access on both. +- **`delete` is soft:** for 30 days an admin can restore the memory with `scripts/admin.ts restore`, which is not + available through the MCP. ### What I've learnt -Store durable findings with the category that fits, tagged `repo:` plus topic tags: +Store durable findings with the category that fits (`architecture`, `bug-fix`, `debugging`, `performance`, +`security`, `learning`, `tool-usage`), tagged `repo:` plus topic tags: - design decisions and the reasons for them; - constraints that aren't obvious; - traps that cost real time; - what was tried and rejected. -Store the *why*, not the diff. Never store secrets, tokens, credentials or anything from a `.env` file. Don't store -what the repo already records, or session chatter. +Store the *why*, not the diff. Never store secrets, tokens, credentials or anything from a `.env` file: the store is +plaintext in a hosted database that others can read. Don't store what the repo already records, or session chatter. ### Threads