Nocetta defines 6 tools with complete input schemas and detailed descriptions. All tools follow verb_noun naming (memory_search, memory_remember, etc.). Descriptions are comprehensive (200-400 chars) and include examples. Input schemas use Zod with proper type definitions and field descriptions. However, output schemas are not formally documented, responses are shaped via helper functions (shapeHit, shapeBelief, shapeWorklist) but the LLM cannot see the structure. Error handling is present but minimal (throws Error with message text). No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels (READ_ONLY vs WRITE). Parameter descriptions are strong but some lack explicit constraints (e.g., max_results lacks min/max bounds).
Check for stale anchors: scan the repo for nodes whose anchors no longer match the current code/docs, and report them with their new locations (if found) or as missing. Drift is a read-only diagnostic — it never modifies the store. Example: {} (no arguments).
Capture a durable fact so a future session recalls it here. kind is "claim" (a fact about code), "value" (a decision or convention), "entity" (a thing and its aliases) or "lore-fact" (a fact about docs/plans). A fact about code or a doc should be anchored so it detects its own staleness: pass artifact_path plus symbol_name (the exact symbol name in that file, e.g. "foo") or heading (the exact markdown heading). Only claim and lore-fact anchor; value and entity are always unanchored — an anchor passed with them is refused. Give a one-line summary when the fact isn't already one line; body should read as a lead sentence then **Why:**/**How to apply:** for anything with rationale, with [[wikilinks]] to related nodes. Unknown or ambiguous anchor names are refused with the candidates — fix the name and retry; a body containing secrets is refused outright and nothing is written. Conflict and duplicate advisories come back as warnings: they are advice, the write still happened. A duplicate advisory means the store already holds this belief — supersede the named node instead of keeping both, or drop the write. Example: {"body":"foo returns the number one","kind":"claim","artifact_path":"src/foo.ts","symbol":"foo"}.
Retire a node: mark it as no longer current (valid-to is set to now). The node stays in history, never deleted. Find the id with memory_search first. Example: {"id":"<id from memory_search>"}.
The recall surface: call it BEFORE editing code to pull up what memory knows about the files you are about to touch, or to answer a question from stored facts. files_in_play are repo-relative paths; they match memories by their code/doc anchors. keyword is a free-text query over memory bodies. Give at least one of the two — a call with neither refuses. Results are ranked and current-only (superseded and retired facts are never served), one JSON object per line: id, kind, authority, score, anchor locators, body. After you act on a result, your next call can pass used_ids — the ids from a prior result you actually used — so nocetta learns which memories earn their keep; it never changes what this search returns. Example: {"files_in_play":["src/auth/login.ts"]} or {"keyword":"why is retry capped at 3"}.
Output schemas not documented. Responses are shaped via helper functions (shapeHit, shapeBelief, shapeWorklist) but the LLM cannot see the structure. LLMs need documented return types to plan downstream calls and extract fields correctly.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint). Tools clearly declare risk levels (READ_ONLY vs WRITE) in comments but do not expose them via MCP tool annotations. Agents cannot distinguish safe from destructive operations without reading descriptions.
Numeric parameter bounds missing. max_results accepts positive integers but lacks explicit min/max constraints (e.g., 1 - 1000). Unbounded numbers let LLMs pass absurd values.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 65 | 2026-07-28+ | v2 |
Correct a belief: writes a new node that supersedes old_id — the old node is never deleted, it stays in history, and recall resolves to the new one. Find the id with memory_search first. kind defaults to the old node's kind. Example: {"old_id":"<id from memory_search>","body":"foo now returns 42"}.
The repair surface: list nodes that need attention — stale anchors, conflicts, duplicates, or nodes that have drifted. Each entry is a node id, kind, scope, anchor locator, and a brief reason. Use memory_supersede or memory_retire to fix them. Example: {} (no arguments).
Error handling lacks recovery guidance. Errors throw raw Error messages (e.g., 'give files_in_play or keyword') but do not categorize as retryable/user-fixable/fatal or suggest next steps. LLMs need actionable error responses.
No confirmation step for destructive operations. memory_retire and memory_supersede modify state irreversibly but lack dry-run or confirmation patterns. Agents can accidentally corrupt memory.