A semantic memory system with trust-ladder governance, LLM enrichment, and MCP integration for storing, searching, and reviewing memories with provenance tracking.
OpenBrain demonstrates solid tool design with comprehensive schemas, detailed descriptions, and thoughtful governance patterns. All 13 tools have explicit registrations with Zod schemas and descriptions (10 - 200+ chars). Naming follows verb_noun convention (StoreMemory, SearchMemory, etc.). However, several tools lack parameter-level descriptions in the visible schema definitions, and output schemas are not formally documented. Error handling is present but generic (unified envelope). The trust-ladder and lineage concepts are well-explained, but composition could be tighter, compat tools (search, fetch, search_thoughts, etc.) duplicate core functionality without clear differentiation.
Soft-delete a memory by UUID. The memory is marked as deleted but not removed from the database (recoverable — ask the user to restore via the web UI's duplicates view if needed).
List memories newest-first with optional filters for type, source, and tags. Paginated via limit/offset; `count` is the page size and `hasMore` indicates whether another page exists.
Retrieve a specific memory by its UUID, including governance/trust-ladder fields and lineage (derivedFrom: sources it was produced from; derivatives: notes produced from it).
Review an agent-written memory (trust ladder). 'confirm' promotes it to instruction-grade (user_confirmed) — only do this on the user's explicit say-so; 'evidence_only'/'reject'/'restrict_scope'/'mark_stale'/'dispute'/'supersede' adjust its lifecycle. 'supersede' means: this memory (id) replaces the older relatedId.
Preferred semantic search across stored memories, ranked by cosine similarity with optional filters, similarity threshold, and recency blending. Rejected/superseded/disputed memories are excluded unless includeRejected. May return fewer than `limit` results: when a source and a note derived from it both match, the source is collapsed into the derivative's derivedFrom list.
Compat tools (search, fetch, search_thoughts, list_thoughts, thought_stats, capture_thought) have minimal descriptions ('OB1 canonical tool parity: <action> (compat layer)'), under 50 chars, insufficient for LLM tool selection. Descriptions do not explain when to use compat vs. primary tools or what 'OB1 parity' means.
Output schemas are not formally documented in the visible code. The `run()` wrapper returns a generic `ToolResult` envelope with `{content, isError}`, but the actual shape of the JSON inside `content.text` (e.g., fields returned by SearchMemory, RecallMemory) is not declared. LLMs cannot plan downstream calls without knowing what fields to expect.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 66 | <=2025-11-25 | v2 |
Store a new memory with semantic embedding; summary/tags/entities are enriched asynchronously via LLM. Identical content (same fingerprint) returns the existing memory with deduped:true instead of storing twice. MCP writes enter the trust ladder as agent evidence pending review — use ReviewMemory 'confirm' to promote a memory to instruction-grade.
Update a memory's content or metadata. Content changes trigger re-embedding and re-enrichment; a content change to a confirmed/instruction-grade memory demotes it back to pending review (returned as demoted:true) — ask the user to ReviewMemory 'confirm' it again.
OB1 canonical tool parity: capture a new thought (compat layer)
OB1 canonical tool parity: retrieve a specific memory by ID (compat layer)
OB1 canonical tool parity: list thoughts (compat layer)
OB1 canonical tool parity: semantic search across memories (compat layer)
OB1 canonical tool parity: search thoughts (compat layer)
OB1 canonical tool parity: retrieve thought statistics (compat layer)
Error handling is generic: all errors surface as `{error: message}` with `isError: true`. No error categorization (retryable vs. user-fixable vs. fatal), no recovery guidance, and no invalid-value echoing. E.g., if ReviewMemory receives an invalid action, the error should list valid enums: 'Invalid action: got "foo", must be one of: confirm, evidence_only, reject, ...'
Composition: 6 compat tools duplicate core functionality (search vs. SearchMemory, fetch vs. RecallMemory, capture_thought vs. StoreMemory). No clear guidance on which to use. LLMs will waste reasoning cycles choosing between overlapping tools. Consider deprecating compat tools or documenting their specific use cases.
Parameter descriptions in Zod schemas are present but not visible in the provided code excerpt. If any parameters lack descriptions in the actual schema definitions (e.g., `tags` array in StoreMemory), those tools cannot score above 50 for schema. Verify all parameters have non-empty descriptions.