Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 24 additions & 5 deletions docs/claude-md-sample.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,23 @@ scratch.
| `<team-scope>` | <shared engineering knowledge and work status for the team> |
| `<private-scope>` | <anything that must not reach the wider group> |

`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:<name>", "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
Expand All @@ -30,21 +40,30 @@ Store a memory when starting a task, reviewing a PR or ticket, or parking someth
- `pr:<n>` / `issue:<n>` 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:<name>` plus topic tags:
Store durable findings with the category that fits (`architecture`, `bug-fix`, `debugging`, `performance`,
`security`, `learning`, `tool-usage`), tagged `repo:<name>` 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

Expand Down
Loading