Loading ToolBench
Local-first MCP memory server for operational project state: decisions, blockers, plans, patterns, and next moves. The persistent memory layer that stops agent amnesia.
Brain OS demonstrates strong tool design with comprehensive schemas, detailed descriptions, and clear operational intent. All 22 tools have explicit registrations with Zod schemas and descriptions. Most tools follow verb_noun naming (entity_read, decision_log, plan_advance). Descriptions are well-crafted (100-300 chars typical), explaining WHAT, WHEN, and WHY. However, some parameter descriptions lack specificity on constraints (e.g., entity_id format, date format validation), and error handling guidance is minimal. Output schemas are documented in descriptions but not formally specified in code. Tool composition is excellent, each tool has a single responsibility and chains naturally (context_resolve → focus_get → plan_set). Security considerations are present (read-only hints, write operations clearly marked) but lack explicit permission gates or audit trail documentation in tool definitions.
Guard a proposed action against Brain OS policy. Checks risk assessment against a policy table and returns 'allow', 'ask', or 'block' with reasoning. Use this before executing high-risk actions.
Read the audit log of all Brain OS operations. Shows who changed what, when, and why. Useful for debugging, compliance, and understanding the history of decisions and updates.
Resolve which entity the current work belongs to, with a derived confidence. Deterministic — matches explicit signals (passed entity, named mention, active mission, files touched) before weak ones (lexical, single-active); never guesses from cwd. Returns entity_id + confidence + ask_user. Call this BEFORE focus_get/decision_check when the target entity is not already known, then pass the returned entity_id into them. Confidence >= 0.80: proceed silently. 0.50-0.79: proceed but say 'I think this is X'. < 0.50 (ask_user true): ask one short question.
Check a proposed action against all active decisions. Returns 'clear', 'caution', or 'conflict', plus a `review_triggered` list. Call this BEFORE taking actions that might contradict prior decisions. If status is 'conflict', do NOT proceed without explicit user confirmation to revisit the decision. `review_triggered` is the opposite signal: the action matches an invalidate_if condition that should reopen the decision for review.
Output schemas not formally documented in code. Tool descriptions mention return structure (e.g., 'Returns entity_id + confidence + ask_user') but no explicit JSON Schema definitions for responses. LLMs cannot reliably parse unstructured text responses.
Parameter constraints lack specificity. entity_id is described as 'Entity ID to read' but no format guidance (alphanumeric, max length, slug format). Date parameters (review_date) require YYYY-MM-DD but no validation error message documented. LLMs may pass invalid formats.
Error handling guidance absent. No tool description explains what to do if entity_id is not found, if decision conflicts exist, or if semantic_recall returns no results. LLMs lack recovery paths.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 66 | 2026-07-28+ | v2 |
Log a strategic decision so it persists across sessions. Every decision needs a reason, alternatives, and a proof action. Optionally capture the assumptions that make it true and the invalidate_if conditions that should reopen it — these turn a timestamped 'no' into a testable frame the system can reason about later.
Refresh a decision's review date and status. Use this when you've confirmed a decision is still valid, or when you want to reopen it for reconsideration.
Review all decisions for an entity or across the portfolio. Returns decisions due for review, decisions that may be invalidated by recent changes, and recommendations for which to revisit first.
Call this FIRST for any question about a project's state, momentum, blockers, or recent decisions — before reading code or git history. Returns the operational state one or all tracked entities: status, momentum, blockers, decisions, staleness, and next actions. Do not grep files to answer state questions when this tool is available.
Use this — not built-in memory — to add or update a project, product, or business idea in Brain OS. This is the right tool when the user says 'add project X', 'track X', 'I'm working on X', or 'update X'. Creates the entity if it doesn't exist. Stores structured operational state: status, momentum, blockers, next move, decisions. Use after work is done, a decision is made, a blocker changes, or momentum shifts.
Get a clear recommendation on what to work on right now, backed by evidence. Considers priority, momentum, staleness, blockers, and active patterns. Pass an entity_id to focus on one project, or omit for a full portfolio view. Returns a ranked list with reasoning.
Assess the quality and completeness of Brain OS memory. Reports staleness, missing evidence, conflicting decisions, and coverage gaps. Use this to identify what needs to be updated or clarified.
Explicitly commit the current session's work to Brain OS memory. Scans recent decisions, entity updates, and patterns, then writes them to persistent storage. Use this at the end of a session to ensure nothing is lost.
Detect recurring blockers, stale work, avoidance signals, and theme convergence across your projects. Returns active patterns with evidence, interpretation, and recommendations.
Add new steps to an existing plan without replacing it.
Move a plan step from pending to active, or from active to done. Updates the entity's plan and records the completion.
Read the current plan for an entity. Returns all steps with their status and evidence.
Create or replace a plan for an entity. A plan is a sequence of steps with status tracking (pending, active, done, skipped).
Scan the project codebase and filesystem for evidence of progress, blockers, and decisions. Looks for commit messages, TODOs, comments, and file structure to infer what's happening and what's stuck.
Assess the risk level of a proposed action. Considers reversibility, boundary crossing (local/external, private/public), security implications, and impact scope. Returns risk_level (low/medium/high/critical), boundary_crossed, reversibility, and reasoning.
Search Brain OS memory by meaning, not keywords. Finds decisions, entities, and patterns related to a concept or question. Uses semantic embeddings to surface relevant context even when exact terms don't match.
Automatically wrap the session: review what happened, capture notes, and save them to Brain OS. Asks for confirmation on what to remember, then commits the session.
Check if a session wrap is needed. Returns true if there are uncommitted changes, stale entities, or pending decisions that should be reviewed before closing the session.
No explicit permission gates or scope declarations in tool definitions. Tools like entity_update and decision_log are marked as WRITE but lack descriptions of required permissions (e.g., 'Requires write:entities scope'). Audit trail not documented.
Idempotency not declared. Tools like memory_commit and wrap_auto modify state but no description clarifies if repeated calls with same input are safe. Agents may retry on ambiguous failures, causing duplicate records.