A typed-table memory layer for AI agents with hybrid semantic+keyword search, embeddings, and multi-kind memory storage (rules, facts, incidents, tasks, documents).
OpenBrain demonstrates solid definition quality with comprehensive parameter schemas, detailed descriptions, and clear semantic intent. All 11 tools have explicit input schemas with typed parameters and descriptions. Tool names follow verb_noun conventions (capture, search, recall, update, delete, browse, stats). Descriptions are substantive (100-400 chars), explaining WHAT, WHEN, and WHY. However, output schemas are not formally documented in the source, responses are inferred from code logic rather than declared. Error handling is minimal; no recovery guidance or actionable error messages visible. Security considerations (audit trail, session_id tracking) are present but not explicitly gated. Composition is strong: tools chain well (search→recall, capture→supersede), and idempotency is implicit for read operations.
Load top behavioral rules and active tasks for a new session. Returns a curated payload of: - Pinned rules (severity=BLOCKER, up to boot_blocker_cap) - Active patterns (severity=PATTERN, up to boot_pattern_cap) - Open/blocked tasks (up to boot_task_cap) - Active handoff note from the previous session (if any) The payload is token-capped (boot_token_cap) and shrunk in order: tasks → patterns → blockers → handoff body (halving) → drop handoff. Always call boot() first in a new session to prime the agent with context.
List memories by kind, project, and status filters. Returns paginated results (headlines only; use `recall` for full bodies). Filters: - kind: filter by memory type (rule/fact/incident/task/document or null for all) - project: scope to a project (or null for all projects) - status: for tasks, filter by status (open/blocked/done/stale or null for all) - severity: for rules, filter by severity (BLOCKER/PATTERN/DEPRECATED or null for all) - active: for facts, filter by active status (true/false or null for all) - archived: for incidents, filter by archived status (true/false or null for all) - limit: max results per page (1-200) - offset: pagination offset
Store a new memory in OpenBrain. Use this whenever the user, the assistant, or a workflow surfaces something worth remembering across sessions or agents. Pick the right kind: - kind='rule' Behavioral directive ("never push to main", "use uv not pip"). Rules are immutable; modify via `supersede`. Requires severity='BLOCKER' (must follow) or 'PATTERN' (should follow). - kind='fact' Knowledge, decision, observation. Decays over time, reactivates on recall. Use for project context, people, topics. - kind='incident' Bug, error, postmortem. Auto-archives after 90 days idle. - kind='task' Action item with status open/blocked/done/stale. - kind='document' Large handoff spec, architecture doc, or project brief (~60KB max). Use sparingly — max 10 active per project. NOT for everyday capture. The write gate enforces: headline ≤15 words, body ≤400 words (≤15000 for documents). Embeddings are generated automatically. Returns the created memory or a duplicate-hit warning if cosine similarity exceeds the dedup threshold. Always pass `project` to scope memories per-codebase or per-domain.
Output schemas not formally documented. Response structures are inferred from code (e.g., _row_to_dict, _shrink_payload_to_cap) but not declared in tool definitions. LLMs cannot reliably predict what fields to expect from each tool.
No error recovery guidance. Tools lack actionable error messages. E.g., duplicate detection returns a dict but no guidance on what to do next (retry with different headline? merge? abort?). Error responses should tell LLMs what to do.
handoff tool uses overloaded 'action' parameter (set/get/clear) instead of separate tools. This violates single-responsibility principle and forces LLMs to reason about which action to invoke. Should be: set_handoff, get_handoff, clear_handoff.
Inferred effective spec: <=2025-11-25.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | <=2025-11-25 | v2 |
Delete a memory by ref_id. Allowed for all kinds. Soft-deletes facts (sets active=false); hard-deletes all other kinds. Removes the memory from search and boot results. Returns ok=true on success.
Store or retrieve a handoff note for session continuity. Handoff notes are short summaries (≤4000 chars) passed between sessions. They are returned by `boot` in the next session and can be updated or cleared. Use `set_handoff` to store a note for the next session. Use `get_handoff` to retrieve the current note.
Fetch the full body of a memory by ref_id. Use after `search` to retrieve the complete content of a memory. Returns all fields except the embedding vector. Increases the access_count and updates last_accessed_at for facts (used by decay scoring).
Rename a project across all memories. Updates all memories in the old project to the new project name. Returns the count of updated memories.
Hybrid semantic+keyword search across all memory kinds. Performs a weighted blend of: - Vector similarity (cosine distance on embeddings) - Full-text search (trigram + tsvector on headlines) Returns up to `limit` results ranked by hybrid score. Use `recall` to fetch full bodies after search identifies relevant memories. Filters: - kind: filter by memory type (rule/fact/incident/task/document or null for all) - project: scope to a project (or null for all projects) - days: limit to memories created in the last N days (or null for all) The hybrid_weight (0.0–1.0) controls the blend: 0.0 = pure keyword, 1.0 = pure semantic.
Get aggregate statistics for memories. Returns counts by kind, project, status (for tasks), severity (for rules), and active status (for facts).
Mark a rule as superseded by a new rule. Rules are immutable; to replace a rule, create a new one and call `supersede` to link the old rule to the new one. The old rule remains in the audit log but is excluded from `boot` and `search` results. Returns the new rule.
Update headline and/or body of an existing memory. Allowed for all kinds except rules (which are immutable; use `supersede` instead). If the new headline+body produces a different embedding, the memory is re-indexed and checked for duplicates. If a duplicate is found, the update is rejected. Returns the updated memory.
Permission gates not visible. Tools like delete and rename_project are destructive but no authorization checks are documented or visible in code. Should declare required permissions (e.g., 'admin:memory', 'write:project').
Pagination limits not enforced in browse/search. browse accepts limit 1-200 and search accepts limit 1-200, but no guidance on default or recommended values. Should default to 20-50 and document why.