Loading ToolBench
Persistent structured memory for LLM orchestration — Unix-native memory control plane with 21 memory tools for MCP integration
memctl offers 20 well-named memory management tools with consistently strong descriptions and detailed parameter schemas. Tool names follow verb_noun conventions (memory_recall, memory_propose, memory_consolidate) and are specific and action-oriented. All tools have substantive descriptions (100 - 400 chars) explaining WHAT, WHEN, and output format. Input schemas are present and type-complete for all tools. However, output schemas are documented only in tool docstrings, not formally in JSON Schema responses, the code shows 'Dict[str, Any]' return type hints but no structured output schema declarations in the MCP registration layer. Error handling is present in middleware (GuardError, RateLimitExceeded) but recovery guidance is not returned to the LLM in tool responses. A few tools (e.g., memory_loop, memory_eco) have moderately complex parameter relationships that could be documented more explicitly.
Ask contextual questions about mounted folder contents. Retrieve items relevant to a question about a folder.
Deterministic consolidation: cluster and merge similar STM items by type and tag overlap, promoting to MTM. Fully deterministic — no LLM calls.
Compare two items or an item versus one of its revisions. Show structural and content differences.
Toggle eco mode for optimized structural retrieval and FTS discipline. Control FTS query hints and structural suggestions.
Export memory items to JSONL format for backup or migration.
Import memory items from JSONL format. Restore from backup or migrate from another store.
Output schemas not formally declared in MCP registration. Tool docstrings document return types (e.g., 'Returns: inject_text, items, tokens_used, matched') as narrative text, not as structured JSON Schema. This forces LLMs to infer output structure from description text rather than parsing a formal schema, reducing downstream tool chaining reliability.
Error responses do not include recovery guidance. Middleware raises GuardError, RateLimitExceeded, etc., but the code shown does not demonstrate LLM-facing error messages with actionable next steps (e.g., 'Rate limit exceeded. Try again in 60 seconds' or 'Path traversal detected. Use absolute paths only'). Generic HTTP error responses waste agent reasoning cycles.
Inferred effective spec: 2026-07-28+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | B | 72 | 2026-07-28+ | v2 |
| 2026-03-09 | D | 50 | - | v1 |
Structural inspection and summary of folder contents. Auto-mounts, auto-syncs, returns folder tree with descriptions.
Iterative recall-answer loop with convergence detection. LLM proposes, controller enforces bounds. Stops on fixed-point, cycle, or max calls.
Register a folder for structured memory ingestion. Set up a named mount point for folder-based synchronization.
Curate key items: promote STM→LTM or MTM→LTM. Move important findings to long-term memory.
Governed write: propose knowledge with policy enforcement. The LLM proposes, memctl enforces governance rules (secret detection, quarantine, injection classification).
Read items by ID. Retrieve specific items from the store.
Token-budgeted memory retrieval for context injection. PRIMARY tool — returns items formatted for direct insertion into LLM context, respecting a token budget. Use this as the default way to retrieve prior knowledge.
Multi-step best-effort memory retrieval with full cascade transparency. Use this tool for exploratory recall when you need prior knowledge from the memory store and want full visibility into what happened.
Rebuild full-text search index. Repair or optimize FTS5 index after corruption or schema changes.
Administrative reset: clear all data or specific tiers. Irreversible — use with extreme caution.
Interactive full-text search for discovery and exploration. Use for ad-hoc queries and finding related items.
Retrieve memory store statistics: total items, tier distribution, tag frequency, storage metrics.
Synchronize mounted folder: delta-aware ingestion. Detects changes via mtime and SHA-256, skips unchanged files.
Privileged direct write: bypass policy checks. Use only for trusted/administrative operations.
Complex parameter relationships underdocumented. memory_loop accepts both 'llm' (subprocess command) and 'replay' (JSONL trace), mutually exclusive options. memory_eco's 'action' parameter has three modes (on, off, status) but no explicit enum constraint shown in source. Interdependencies are noted in docstrings but not formally in schema constraints.
Destructive operations (memory_reset, memory_write) accept a 'confirm' flag but tool descriptions do not explicitly state the irreversibility or consequences. memory_reset explicitly requires confirm=true, which is good, but memory_write docstring says 'Privileged direct write: bypass policy checks' without warning of permanent storage modification. LLMs may not infer the severity.
Pagination not explicitly supported in memory_search or memory_recall_best_effort. memory_search accepts 'limit' (default 20) but source code shows hardcoded limit=50 in memory_recall's fulltext call, with no cursor or offset parameter. Large result sets could blow context windows; pagination metadata (total, next_cursor) not documented.