| name | grapha-knowledge |
| description | Use when work in this repo needs to persist or recall symbol annotations (ownership, invariants, role) or concept bindings (business term → code). |
Grapha — durable knowledge
Two persistent layers Grapha maintains on top of the graph:
- Annotations — short, agent-written notes attached to a symbol by ID/USR. Future agents read them via
get_symbol_context and can save the cost of re-deriving the same context.
- Concepts — business/product terms bound to one or more code symbols, with aliases. Lets agents resolve "the room invitation flow" to actual symbols without rediscovering them every session.
Annotation tool map
| Task | MCP tool | CLI fallback |
|---|
| Add or replace an annotation | mcp__grapha__annotate_symbol | grapha symbol annotate "<symbol>" "<note>" --by <agent> |
| Read context including annotation | mcp__grapha__get_symbol_context | grapha symbol context "<symbol>" |
| Inspect one note (CLI-only short form) | — | grapha symbol annotation "<symbol>" |
| Verify after sync | mcp__grapha__get_symbol_context (look at annotation field) | grapha symbol context "<symbol>" --fields annotation |
Annotation daemon and sync (CLI only)
These are project-management actions, not query tools:
grapha annotation serve --port 8080 — standalone local LAN annotation service. Does not require grapha index or a project path.grapha annotation list — local annotation records and project identity.grapha annotation sync — pull/merge/push against the configured service.grapha annotation sync --server http://HOST:8080 — one-off override.
Sync resolves the service address from --server, then GRAPHA_ANNOTATION_SERVER, then project grapha.toml, then global Grapha config. Records are project-scoped by default; older branch-specific rows remain readable. Set [repo].name in grapha.toml when syncing non-Git copies that should share one project identity.
When to record an annotation
Compact, factual, expensive-to-rediscover. Good candidates:
- Ownership and business role.
- Invariants the type promises but doesn't enforce in code.
- Cross-module coupling that isn't visible from one file.
- Migration state ("this is the new path; old
XLegacy is being removed in 2026Q3").
- Non-obvious dependencies or side effects.
Don't annotate guesses, obvious restatements of the symbol name, or task-local scratch.
Concept tool map
| Task | MCP tool | CLI fallback |
|---|
| Resolve a business term to code scopes | mcp__grapha__search_concepts | grapha concept search "<term>" |
| Inspect a stored concept | mcp__grapha__get_concept | grapha concept get "<term>" |
| Bind a concept to one or more symbols | mcp__grapha__bind_concept | grapha concept bind "<term>" <symbols...> |
| Add aliases to an existing concept | mcp__grapha__add_concept_alias | grapha concept alias "<term>" <aliases...> |
| Remove a concept | mcp__grapha__remove_concept | grapha concept remove "<term>" |
When to bind a concept
When the user uses a domain term (e.g., "room invitation", "checkout funnel", "audit log") and you've identified the symbols that implement it, bind once so the next session can resolve the term in a single call instead of re-searching. Add aliases for common variants the team uses.
search_concepts falls back through stored bindings → localization → assets → symbol heuristics, so even an un-bound term often resolves usefully — but a binding is still the cheapest path.
Tips
- Annotations are keyed by Grapha ID / Swift USR, so they survive renames at the language level (the ID tracks the declaration).
- Concept bindings are additive —
bind_concept with new symbols extends the binding rather than replacing it. To replace, remove and rebind.
- After bulk imports of annotations or concepts, run
grapha annotation list (or for concepts, search-then-get) to confirm shape before relying on the data.
