Skip to content

docs: expand the CLAUDE.md sample's shared-memory guidance - #9

Merged
springfall2008 merged 1 commit into
mainfrom
docs/claude-md-sample-scopes
Nov 9, 2026
Merged

springfall2008 merged 1 commit into
mainfrom
docs/claude-md-sample-scopes

Conversation

@springfall2008

Copy link
Copy Markdown
Owner

Why

The sample CLAUDE.md in docs/claude-md-sample.md lacked guidance that agents need in practice. One gap showed up today: an agent tried to store into a scope its token had no grant on, got Scope '…' not found, and fell back to local notes without knowing why.

What

  • Scopes:
    • store needs a scope.
    • Reads 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 reads as "not found". If a store fails that way, check list_scopes rather than retrying.
    • If a bot that answers in public reads a scope, treat everything in it as public.
  • Start of session: a cross-repo sweep by status tag. Also an example of the new tags_all filter (feat(search): add a tags_all filter that requires every tag #8) that gets one repo's open work without filtering on the client.
  • Work status:
    • What a useful status memory names: branch, file, decision and what remains.
    • Why a stale status memory is worse than none.
    • What changing tags, category or content does on update, and moving a memory between scopes.
    • delete is soft. Restoring is shell-only, through scripts/admin.ts restore.
  • Findings: the category list. Also the reason for never storing secrets: the store is plaintext in a hosted database that others can read.

The sample is docs only and still uses placeholders throughout.

🤖 Generated with Claude Code

Add scope behaviour (store needs a scope, reads cover all readable scopes,
list_scopes, an ungranted scope reads as "not found"), a status-tag sweep
with a tags_all example, a public-bot warning, what update and delete do,
the categories list, and why secrets must never be stored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@springfall2008
springfall2008 merged commit bfd0063 into main Nov 9, 2026
1 check passed
@springfall2008
springfall2008 deleted the docs/claude-md-sample-scopes branch November 9, 2026 19:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant