Loading ToolBench
Persistent memory for AI coding agents. Local-first vault with semantic search, 19 MCP tools, and Claude Code hooks. Trust-aware retrieval, provenance tracking, stale detection, fact extraction.
SAME demonstrates strong definition quality with 8 well-named, verb-first tools and comprehensive descriptions. All tools have full input schemas with type definitions and parameter descriptions. Tool names follow verb_noun convention (search_notes, get_note, save_note, etc.). Descriptions are detailed (150-300 chars average) and include usage context and return value documentation. However, output schemas are not formally documented in the source code provided, parameter constraints lack some enforcement details (e.g., top_k max values stated only in descriptions, not schema enums), and error handling guidance is minimal. The codebase shows security awareness (destructive hints on write tools, trust state filtering) but lacks explicit per-tool error recovery guides. Overall, this is a well-designed knowledge-management toolkit suitable for production with minor polish needed on output schema formalization and error guidance.
Find notes that cover similar topics to a given note. Use this to discover related context, find notes that might conflict, or build a broader picture of a topic. Args: path: Relative path of the source note top_k: Number of similar notes (default 5, max 100) Returns list of related notes ranked by similarity.
Read the full content of a note. Use this after search_notes returns a relevant result and you need the complete text. Paths are relative to the vault root. Args: path: Relative path from vault root (as returned by search_notes) Returns full markdown text content.
Check the health and size of the note index. Use this to verify the index is up to date or to report stats to the user. Returns note count, chunk count, last indexed timestamp, embedding model info, and database size. If the user reports problems, suggest they run `same doctor` for diagnostics. For bugs, direct them to: https://github.com/sgx-labs/statelessagent/issues
Re-scan and re-index all markdown notes. Use this if the user has added or changed notes and search results seem stale. Incremental by default (only re-embeds changed files). Args: force: Re-embed all files regardless of changes (default false) Returns indexing statistics.
Log a project decision. Appends to the decision log so future sessions can find it. Args: title: Short decision title (e.g. 'Use JWT for auth') body: Full decision details — what was decided, why, alternatives considered status: Decision status — 'accepted', 'proposed', or 'superseded' (default 'accepted') agent: Optional writer attribution stored in frontmatter (e.g. 'codex')
Output schemas not formally documented. Tool descriptions state return values in prose ('Returns ranked list of matching notes...') but no structured JSON Schema output specification is visible in the source code. LLMs cannot reliably parse prose return types for downstream composition.
Parameter constraints stated in descriptions but not enforced via JSON Schema. E.g., top_k 'default 10, max 100' is written in description text, not as a JSON Schema maxItems/maximum constraint. LLMs cannot guarantee they respect these bounds.
Error handling lacks recovery guidance. E.g., save_note and save_decision (WRITE/DESTRUCTIVE tools) have no documented error responses or suggestions for what to do if indexing fails or path is invalid. Critical for agent safety.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-21 | C | 67 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 11 | - | v1 |
Create or update a markdown note in the vault. The note is written to disk and indexed automatically. Optionally specify source files to enable provenance tracking — SAME will flag this note as stale if sources change. Args: path: Relative path within the vault (e.g. 'decisions/auth-approach.md') content: Markdown content to write append: If true, append to existing file instead of overwriting (default false) agent: Optional writer attribution stored in frontmatter (e.g. 'codex') sources: File paths that this note was derived from (optional) Returns confirmation with the saved path.
Search the user's knowledge base for relevant notes, decisions, and context. Use this when you need background on a topic, want to find prior decisions, or need to understand project architecture. Args: query: Natural language search query (e.g. 'authentication approach', 'database schema decisions') top_k: Number of results (default 10, max 100) Returns ranked list of matching notes with titles, paths, and text snippets.
Search the user's knowledge base with metadata filters. Use this when you want to narrow results by domain (e.g. 'engineering'), workstream (e.g. 'api-redesign'), tags, agent attribution, trust state, or content type. Args: query: Natural language search query top_k: Number of results (default 10, max 100) domain: Filter by domain (e.g. 'engineering', 'product') workstream: Filter by workstream/project name tags: Comma-separated tags to filter by agent: Filter by agent attribution (e.g. 'codex', 'claude') trust_state: Filter by trust state (validated, stale, contradicted, unknown) content_type: Filter by content type (decision, handoff, note, research) Returns filtered ranked list.
search_notes_filtered has 7 optional string parameters (domain, workstream, tags, agent, trust_state, content_type) with no enum constraints. trust_state description lists valid values ('validated, stale, contradicted, unknown') in prose only, should be JSON Schema enum.
Irreversible operations (save_note, save_decision, reindex) lack dry-run or confirmation step. Agents can silently overwrite or reindex without warning. No idempotent hints visible.
Tool registration in internal/mcp/server.go not fully visible in provided excerpt. Cannot verify tool annotation fields (readOnlyHint, destructiveHint, idempotentHint) are properly set on all tools, though 'Risk' field in spec suggests they may be declared.