Multi-project brain MCP server: write-gated decisions, lessons, and memory edges, pinned to one project per server instance.
mai-mcp demonstrates strong schema completeness and domain-specific naming. All 11 tools have explicit JSON Schema definitions with typed parameters and descriptions. Tool names follow verb_noun patterns (mai_search, mai_remember, mai_link). However, descriptions vary in quality: some are excellent (mai_remember at ~180 chars with clear prerequisites), others are terse (mai_recall at ~60 chars). Parameter descriptions are generally present but inconsistent in depth. Error handling guidance is minimal, tools lack recovery hints for common failure modes. Output schemas are not documented in the tool definitions themselves, forcing LLMs to infer result structure. The write-gated architecture (mai_search prerequisite for mai_remember/mai_lesson_add) is well-designed but underdocumented in descriptions.
Links in either direction, with linked record kind and ID.
Branches, worktrees and recent commits with file stats and decisions; filter by paths/keywords.
Commit metadata/file stats by hash (≥7 chars). patch:true reads a bounded live diff; never stored.
Trace a decision ID from search/recall: decision → session → commits → files → graph nodes.
Add a durable rule (lesson); similar lessons reinforce, not duplicate. Needs a prior mai_search this session + a structured citation (see error for format).
Link memories; lesson→graph_node/applies_to needs note and exact extends citation.
Output schemas not documented. Tool definitions lack return type documentation, forcing LLMs to infer result structure. mai_search, mai_timeline, mai_edges, and mai_git_context return complex nested objects (decisions with citations, sessions, links) but provide no schema guidance.
Sparse error recovery guidance. Tools lack actionable error messages. E.g., mai_remember requires 'a prior mai_search/mai_recall this session' but does not specify what error is returned if this prerequisite is violated, or how the LLM should recover.
Inconsistent description depth. mai_recall (60 chars) and mai_edges (55 chars) are below the 100-char baseline for discovery. Descriptions lack WHEN/WHY context. E.g., mai_recall does not explain when to call it vs mai_search.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
Session-start context: recent sessions, valid decisions and commits.
Log a durable decision (short headline). Requires a prior mai_search/mai_recall this session + a structured citation (see error for format).
Propose retracting a decision. Agents MUST pass propose:true — it files an operator review candidate and retracts nothing. Direct retraction is operator-only (dashboard/CLI).
Unified search over decisions, lessons, and plan/spec pointers (path:line). Call BEFORE proposing or writing — it mints the write-gate token your write needs.
Sessions, decisions and commits over N days, chronologically.
Citation schema complexity underdocumented. mai_remember and mai_lesson_add require oneOf citation objects (supersedes/extends/novel) with nested required fields. Descriptions do not explain the citation model or provide examples of valid structures.
No pagination guidance for list-like tools. mai_search, mai_timeline, and mai_git_context accept 'limit' but do not document max values, whether results are truncated, or how to fetch additional pages. LLMs may request unbounded results.