MCP Tools Reference

The agent-facing MCP server is BrainBar on /tmp/brainbar.sock. It defines 17 tools (brain-bar/Sources/BrainBar/MCPRouter.swift, toolDefinitions), each with ToolAnnotations.

A session boots into a core palette of 5, not all 17: brain_search, brain_store, brain_recall, brain_expand, and expand_palette — with short descriptions, so the boot payload stays small. Call expand_palette (or set BRAINLAYER_MCP_PROFILE=full on the server) to expose the rest with their full descriptions. Calling a gated tool before expanding returns an error telling you to expand. brain_backup_vacuum_into is callable regardless of profile.

Tool	Type	Core
`brain_search`	read	●
`brain_store`	write	●
`brain_recall`	read	●
`brain_expand`	read	●
`brain_entity`	read
`brain_get_person`	read
`brain_tags`	read
`brain_digest`	write
`brain_update`	write
`brain_enrich`	write
`brain_subscribe`	write
`brain_unsubscribe`	write
`brain_ack`	write
`brain_backup_vacuum_into`	write
`brain_maintenance_rebuild_trigram`	write
`brain_supersede`	destructive
`brain_archive`	destructive

The per-tool sections below document the main eight. For the remaining nine (brain_tags, brain_enrich, brain_supersede, brain_archive, brain_subscribe, brain_unsubscribe, brain_ack, brain_backup_vacuum_into, brain_maintenance_rebuild_trigram), MCPRouter.toolDefinitions carries the authoritative schema and description.

Which schema are these tables? They document the Python library handlers under src/brainlayer/mcp/, whose parameter sets are wider than what BrainBar puts on the wire. For what an agent can actually send, MCPRouter.toolDefinitions is authoritative. Known divergences are called out inline below.

brain_search

Unified semantic search — pass query, file_path, chunk_id, or filters. Auto-routes to the right view.

Parameter	Type	Required	Description
`query`	string	No*	Search query (semantic + keyword)
`file_path`	string	No*	File to get timeline/history for
`chunk_id`	string	No*	Chunk ID for surrounding context
`project`	string	No	Filter by project
`content_type`	string	No	Filter: `ai_code`, `stack_trace`, `user_message`, etc.
`num_results`	integer	No	Max results (default: 5, max: 100)
`source`	string	No	Filter: `claude_code`, `whatsapp`, `youtube`, `all`
`tag`	string	No	Filter by enrichment tag
`intent`	string	No	Filter: `debugging`, `designing`, `implementing`, etc.
`importance_min`	integer	No	Minimum importance (1-10)

*At least one of query, file_path, or chunk_id typically used; filters apply when relevant.

Returns: Markdown with matched chunks, context, or timeline depending on input.

Annotations: readOnlyHint: true

brain_store

Persist a memory (idea, decision, learning, mistake, etc.) for future retrieval. Auto-type and auto-importance from content.

Parameter	Type	Required	Description
`content`	string	Yes	The memory content to store
`type`	string	No	Memory type: idea, mistake, decision, learning, issue, todo, bookmark, note, journal (auto-detected if omitted)
`project`	string	No	Project to scope the memory
`tags`	array[string]	No	Tags for categorization
`importance`	integer	No	Importance score 1-10 (auto-detected if omitted)
`entity_id`	string	No	Link memory to a KG entity

Issue type supports lifecycle tracking: status (open→in_progress→done→archived), severity (critical/high/medium/low), and code references (file_path, function_name, line_number).

Returns: An explicit outcome word plus, on success, the chunk ID and related existing memories.

STORED, DUPLICATE, MERGED, DEFERRED — all four are success. Do not re-store. DEFERRED means the write is queued and will be persisted.
REJECTED, ERROR — nothing was stored. Both return no status field and no chunk_id. REJECTED means the request as sent cannot succeed; ERROR is worth one retry.

Once a row is committed the handler can no longer answer REJECTED or ERROR, so a durable write is never reported as "nothing was stored" (#725).

Annotations: write (readOnlyHint: false, destructiveHint: false)

Use when: An agent discovers something worth remembering for future sessions.

brain_recall

Proactive retrieval — current context, sessions, session summaries. Mode defaults to "context".

Parameter	Type	Required	Description
`mode`	string	No	`context` (default), `sessions`, `session_summary`, `operations`, `plan`, `summary`, `stats`
`session_id`	string	No	For session_summary mode
`project`	string	No	Filter by project
`days`	integer	No	Days back for sessions (default: 7, max: 365)
`hours`	integer	No	Hours back for context (default: 24)
`limit`	integer	No	Max sessions (default: 20, max: 100)

Returns: Structured summary of recent activity, session list, or session-level analysis.

Annotations: readOnlyHint: true

Use when: Starting a conversation, reviewing sessions, or understanding current state.

brain_digest

Ingest raw content (transcripts, docs, articles, conversation blocks). Runs entity extraction, relation extraction, sentiment analysis, and action item detection.

Parameter	Type	Required	Description
`content`	string	Yes	Raw content to digest
`source`	string	No	Source label (default: `digest`)
`project`	string	No	Project to scope
`participants`	array[string]	No	Known participants for entity linking

Returns: Digest summary with extracted entities, relations, sentiment, action items, decisions, and questions.

Use when: Ingesting meeting transcripts, long documents, or conversation logs. Batch 5-10 messages for short chat — don't call per-message.

brain_entity

Look up a known entity in the knowledge graph. Returns entity type, relations, and evidence chunks.

Parameter	Type	Required	Description
`query`	string	Yes	Entity name or search query
`entity_id`	string	No	Direct entity ID lookup
`entity_type`	string	No	Filter by type: person, company, project, golem, technology, concept

Returns: Entity details (type, metadata), relations to other entities, and linked chunks.

Annotations: readOnlyHint: true

Use when: Looking up people, projects, or concepts in the knowledge graph.

brain_expand

Expand a chunk_id with N surrounding chunks for full context. Useful when a search result is truncated and you need the surrounding conversation or code.

Parameter	Type	Required	Description
`chunk_id`	string	Yes	Chunk ID to expand around
`radius`	integer	No	Number of chunks to include on each side (default: 3)
`project`	string	No	Scope to a project

On the BrainBar wire the parameters are chunk_id (required), before (default 3), and after (default 3) — there is no radius and no project.

Returns: The target chunk plus N preceding and N following chunks in order.

Annotations: readOnlyHint: true

Use when: A search result is a fragment and you need the full surrounding context — e.g., the full function body, the full conversation turn, or the full stack trace.

brain_update

Update, archive, or merge existing memories.

On the BrainBar wire, brain_update only changes importance and tags. It takes chunk_id (required), importance, tags — no action, no content, no merge_chunk_ids, and it does not edit content. To replace content, store new content with brain_store; to hide a chunk, use brain_archive or brain_supersede. The action/merge form below is the Python library handler.

Parameter	Type	Required	Description
`action`	string	Yes	`update`, `archive`, or `merge`
`chunk_id`	string	Yes	Target chunk ID
`content`	string	No	New content (re-embeds if changed). For `update` action.
`tags`	array[string]	No	New tags. For `update` action.
`importance`	integer	No	New importance. For `update` action.
`merge_chunk_ids`	array[string]	No	Chunk IDs to archive (kept chunk = `chunk_id`). For `merge` action.

Returns: Confirmation of the action taken.

Use when: Preferences change ("actually Sundays work now"), deduplicating similar memories, or soft-deleting outdated information.

brain_get_person

Look up a person by name — returns entity details, recent interactions, preferences, and related memories. Optimized for real-time lookups (~200-500ms).

Parameter	Type	Required	Description
`name`	string	Yes	Person's name
`project`	string	No	Scope to a project

Returns: Person entity with metadata, recent chunks, relations, and preferences.

Use when: Need quick context about a person before a meeting, during a conversation, or for personalization.

Aliases

Old brainlayer_* names are still handled by the Python library handlers under src/brainlayer/mcp/. They are not served by BrainBar, which is the agent transport — so an agent connected over /tmp/brainbar.sock cannot call them. New wiring should use brain_*.

brain_search aliases: brainlayer_search, brainlayer_context, brainlayer_stats, brainlayer_list_projects, brainlayer_file_timeline, brainlayer_operations, brainlayer_regression, brainlayer_plan_links, brainlayer_think
brain_store alias: brainlayer_store
brain_recall aliases: brainlayer_recall, brainlayer_current_context, brainlayer_sessions, brainlayer_session_summary