MCP Tools Reference

BrainLayer exposes 8 MCP tools — 3 core (search/store/recall) + 5 knowledge graph (digest/entity/expand/update/get_person).

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: Chunk ID and related existing memories.

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

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.

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 still work as backward-compat aliases.

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