Loading ToolBench
Local-first MCP memory layer for coding agents across Claude Code, Codex, Cursor, Cline, Windsurf, and other MCP-compatible hosts.
sessionmem demonstrates strong definition quality with comprehensive, LLM-optimized descriptions and well-structured schemas. All 13 tools have descriptions ranging from 150-450 characters, which fall within the production baseline (p10=34, p90=392). Input schemas use Zod with proper type definitions and descriptions for all parameters. The server implements semantic memory patterns effectively with clear WHEN TO CALL / WHEN NOT TO CALL guidance. However, output schemas are not explicitly documented in the visible code, and some tools show inferred implementation rather than explicit registration. Tool naming follows verb_noun conventions consistently (retrieve, store, batch, list, get, forget, ingest, handle, reset, stats, summarize, fetch, startup). The compositions are well-designed for memory management workflows. Main gaps: output schema documentation is missing, error handling guidance is generic, and some tools (fetch_memories, startup_inject_memories) are conditionally registered fallbacks with limited visibility into their actual invocation paths.
Persist multiple memory units in a single call. Semantically equivalent to calling storeMemory repeatedly, but preferred at session end when storing several new decisions/facts together. WHEN TO CALL: At session end, once per session, to persist all new decisions/facts/summaries discovered during this session in one go. Preferred over storeMemory for bulk writes. WHEN NOT TO CALL: For a single memory (use storeMemory). If you already called storeMemory/batchStoreMemory once this session and have only a couple new items — use storeMemory for the remainder.
Fallback memory retrieval for hosts that do not support MCP resources. Call this instead of accessing the sessionmem:// resource URI directly when the host lacks resource support. Semantically equivalent to retrieveMemories — returns stored memories ranked by relevance to the query. Read-only; no side effects. WHEN TO CALL: At session start and mid-session when you need to retrieve context and the host does not support MCP resources. Do not call if the host supports MCP resources — use the sessionmem:// resource URI or retrieveMemories tool instead. Parameter `query`: natural-language description of what context you need to recall (e.g. 'API design decisions', 'database schema choices').
Delete a memory by ID. Irreversible. WHEN TO CALL: When a memory is outdated, incorrect, or no longer relevant to future sessions. WHEN NOT TO CALL: Casually — this is permanent.
Fetch a single memory by ID. Use this when you have a specific memoryId (e.g. from a prior retrieveMemories call or from the CLI) and want the full record. WHEN TO CALL: When you have a specific memory ID and want to inspect or review the full content, or when updating/deleting a memory. WHEN NOT TO CALL: For context loading (use retrieveMemories). For bulk browsing (use listMemories).
Output schemas not documented. While input schemas are well-defined via Zod, the return types for all tools lack explicit documentation. LLMs cannot plan downstream operations or extract specific fields without knowing what fields each tool returns.
ingestSessionEvents has incomplete schema documentation. The input parameter 'events' is described as 'Array of session events to ingest' but the structure of each event element is not defined. LLMs cannot construct valid event objects without knowing the required/optional fields.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 68 | 2026-07-28+ | v2 |
Run the session-end pipeline: auto-summarize ingested session events and apply light retention pruning. This is called automatically by the Claude Code SessionEnd hook; invoking it manually signals an explicit session close.
Manually push raw session events (e.g. user messages, tool calls) for later auto-summarization by the SessionEnd pipeline. Useful when an agent wants to record mid-session context that wasn't captured by the automatic PostToolUse hook. WHEN TO CALL: Mid-session when you want to record a key decision, discovery, or outcome explicitly so it feeds the SessionEnd auto-summarizer. Do NOT call at the very end of the session — let the SessionEnd hook call it automatically instead. WHEN NOT TO CALL: For every turn (feeds noise). Prefer storeMemory/batchStoreMemory for decisions that should be memories immediately.
List all memories for the current project, ordered by creation time (newest first). Useful for auditing, but do NOT use for context loading — use retrieveMemories instead. WHEN TO CALL: To browse the full store when debugging, exporting, or curating existing memories. Not recommended for every session. WHEN NOT TO CALL: As a substitute for retrieveMemories at session start. Returns all memories unranked — wasteful for loading context.
Zero out the access counters on all memories for the current project. These counters feed the retrieval ranking boost for frequently-accessed memories, so resetting them is useful after a major codebase shift or to suppress stale popularity. WHEN TO CALL: Rarely — only after a major project reset or when old access patterns are no longer meaningful.
Semantically search stored memories and return the top matches ranked by a weighted combination of relevance, recency, and importance. Read-only; no side effects. WHEN TO CALL: (1) At the start of every session — pass the current task or file as the query to pre-load relevant context. (2) Mid-session whenever a new topic, file, or decision area arises that may have prior context. Do NOT call on every user turn. WHEN NOT TO CALL: If you already retrieved memories for this topic this session. Use getMemory if you have a specific memoryId. Use listMemories only to audit the full store, not for context loading. Returns up to `limit` results (default 20). `mode='auto'` is the standard startup path; `mode='on-demand'` signals an explicit mid-session lookup. `depth='deep'` runs a broader semantic sweep at higher latency — use when the topic is unfamiliar. Phrase `query` as what you need to recall, not what you are about to do. NOTE: this tool updates access-pattern counters on the memories it returns (used to boost frequently-recalled memories in future ranking), so it is NOT side-effect-free despite being a lookup.
Fallback startup-injection for hosts that do not support MCP prompts. Call this once at the very start of a session instead of relying on the automatic sessionmem startup prompt when the host lacks prompt support. Injects the top relevant memories for the current project into the working context. No parameters required. WHEN TO CALL: Once per session start, before any user task work begins, when the host does not surface MCP prompts automatically. Do not call if the host already surfaces the sessionmem startup prompt — calling both duplicates injected context. Note: access counts are incremented on retrieval.
Return memory statistics for the current project: count, total token size, embedding version mismatch count, and other diagnostics.
Persist a single memory unit to the local SQLite store. Accepts decisions, facts, architectural choices, warnings, and session summaries. NOT idempotent — each call creates a new record even with identical content. Writes to disk immediately. WHEN TO CALL: After any significant decision, discovery, or conclusion that should be available in a future session. Good candidates: technology choices, non-obvious constraints, bug root-causes, architectural decisions, key facts about the codebase. WHEN NOT TO CALL: For trivial observations, transient state, or content that duplicates what was just retrieved. Do not store entire files or full conversation transcripts. `kind` categories: 'decision', 'fact', 'summary', 'warning', 'preference'. Write `content` to be self-contained — it must be useful without any surrounding conversation context. `importance` 1-10 (10 = most critical); directly affects retrieval ranking in future sessions. RESPONSE may include `warningCodes`: 'session_write_limit_warning' (this session has stored many memories — stop storing trivia and prefer batchStoreMemory) and 'redaction_partial_failure' (a redaction rule errored; the write still succeeded). Treat them as advisory signals, not errors.
Explicitly run the session auto-summarizer over ingested session events without waiting for the SessionEnd hook. Useful for testing or mid-session snapshots.
startup_inject_memories tool lacks input schema definition in visible code. The inputShape is an empty object {}, but the description claims 'No parameters required.' This is valid but creates ambiguity about the fallback path.
Error handling descriptions are missing recovery guidance. While tool descriptions explain WHEN to call, error responses return generic JSON-stringified results without actionable guidance. E.g., 'Error: ...' in fetch_memories and startup_inject_memories does not tell the LLM what to do next (retry, ask user, or abandon).
Conditional tool registration (fetch_memories, startup_inject_memories) are fallback tools with limited direct visibility. Tool invocation paths through FallbackToolRegistrar cannot be verified in actual MCP tool registration calls; these are inferred from code inspection.
stats tool has minimal description (55 chars). The description 'Return memory statistics for the current project: count, total token size, embedding version mismatch count, and other diagnostics.' lacks WHEN TO CALL guidance. Does the agent call this before or after bulk operations? Is it for debugging only?