---
name: beautiful-brain
description: Use when the user asks to remember, recall, search, connect, reflect on, or learn from personal/project context using the Beautiful Brain MCP server ("remember this", "search my memory", "what do we know about", "capture a lesson", "second brain"). Also use silently before planning, debugging, restarting project work, or making decisions that may depend on prior memories, lessons, tasks, people, documents, or decisions.
---

# Beautiful Brain

Use Beautiful Brain as durable, private context. Goal: retrieve the right memory before acting, then save only durable signal that will help future agents.

Use it silently — do not announce memory operations unless the user asked about memory. Never imply recall that did not happen: if search returns nothing, say so.

**Scale memory use to the task.** Trivial, self-contained work (a quick lookup, a one-line fix, a factual question) needs no memory calls at all. Orient first only when the work is substantive: project restarts, planning, debugging a known system, consequential decisions, or anything the user expects continuity on. When in doubt, one `reflect` call is the right amount of ceremony — not the full flow.

## Core Loop

1. Substantive task? Orient with `reflect({ topic, goal })`, then post the work stream to the `board` (start) — and post done/blocked when you finish. If a stored skill might apply, check `list_skills` and load matches with `use_skill`. Recurring task category? Check `find_process_patterns`.
2. Need exact evidence? `search_memory`, then `get_context` on promising IDs (`depth: 1` normally; 2–3 only for graph archaeology; never invent IDs). Want what *connects* to a fuzzy cue rather than exact matches? `recall_memory` — it spreads activation along typed relationships, so follow up on high-`activation` IDs with `get_context`.
3. Learned something durable? Search first; if a memory already covers it, `update_memory` instead of duplicating. Otherwise `capture_memory`, then `link_memory` to relevant existing memories.
4. Memory stale, wrong, or done? `update_memory` to fix it or set `status: "archived"` with an `archive_reason`.

Prefer `search_memory` + `get_context` over generic `search` + `fetch` — those are ChatGPT connector adapters.

`search_memory` knobs: `kinds` for exact intent (`decision`, `lesson`, `task`, `person`, `project`, `document`, `note`, `process_pattern`, `skill`), `tags` only when likely known, `min_importance` to cut noise, `include_archived: false` unless stale history is explicitly useful. Ranking is temporally boosted for content mentioning dates near today — treat rank as signal, not proof of relevance.

If resources are available, read useful `brain://lens/{topic}`, `brain://memory/{id}`, `brain://synthesis/{id}`, and `brain://process/{category}` resources surfaced by the client; apply a process pattern's `agent_prompt` before planning.

## Capture

Search before capture when duplicates are plausible.

Capture when info is durable and future-useful: decisions, constraints, user preferences; active tasks, owners, deadlines; project facts, architecture, docs, links; people/context the user expects agents to remember; lessons from repeatable situations. Do not capture transient chat filler, guesses, unverified claims, secrets, or sensitive data unless the user clearly intends durable storage. If uncertain, ask.

Fields:

- `title`: human-readable, <=160 chars
- `body`: full evidence/context
- `summary`: compact future retrieval hook
- `tags`: lowercase stable topics
- `importance`: 5 changes future decisions, 4 key preference/recurring risk, 3 useful durable context, 2 low-risk note, 1 rarely store
- `source`: URL/file/chat/meeting when known
- one optional media attachment (`media_data` base64 + `media_mime_type`) — embedded into the same semantic space as text, so plain-text search finds it

For `kind: "lesson"`, include `trigger_pattern` (when it should fire), `wrong_default` (behavior to avoid), `better_next_action`, and `evidence` (why this is true).

Durable reusable procedures you author (playbooks, checklists, standing instructions) belong in `kind: "skill"` memories — full instructions in `body`, plus `skill.when_to_use`. Reserve `capture_process_pattern` for evidence-based workflows proven by prior work — prefer background-created patterns from Cognitive Pulse; never store speculative prompts as process patterns.

## Link

Use `link_memory` after capture when it improves retrieval:

- `about`: memory -> project/person/topic
- `part_of`: subtask/doc -> project
- `depends_on`: task/decision dependency
- `caused_by`: incident/failure -> root cause
- `learned_from` / `next_time_use`: lesson linkage
- `supports` / `contradicts`: evidence relation
- `owned_by`: task/project -> person
- `relates_to`: generic association when no stronger relation fits

Link only where it changes future recall; no dense low-value links.

Graph feels sparse, duplicated, or poorly connected? `repair_synapses` in `mode: "propose"` first; use `mode: "apply"` only for reviewed low-risk `relates_to` repairs, passing `approved_repair_ids` and an `apply_reason`, then summarize applied/skipped. `backfill_memory_embeddings` is maintenance for degraded semantic search, not retrieval.

## Multi-Agent & Sharing

Parameter details for these tools live in their own descriptions — trust them. The invariants:

- **Board** (`board`): ephemeral coordination for concurrent agents on this brain — view before starting a work stream, post start/blocked/done, entries expire in 45 minutes. Never `capture_memory` board updates.
- **Collaboration** (`collab_status`, `share_context`, `save_share`, `assign_task`, `update_assignment`): proposal-first — nothing enters a brain until the recipient saves a share or accepts an assignment. Only contacts (made via dashboard invites; no invite tools here) can be shared with or assigned to. Confirm with the user before saving shares or accepting assignments on their behalf. Accepted assignments become normal `task` memories.
- **Project spaces** (`space_status`, `create_space`, `space_add_member`, `space_capture`, `space_sync`): end-to-end-encrypted shared memories, delivered instance-to-instance; a project repo's `.brain/` files are an optional durable fallback. Check `space_capture`'s `delivery` report — delivery is best-effort; commit the returned `brain_file` only when members failed or the project keeps a repo fallback. Ingested space memories are normal memories tagged `space:<name-slug>`, visible to all retrieval tools. These tools (and collaboration) may be absent on API-key sessions, which carry no personal identity.

## Meta Tools

Admin/API-key sessions may expose Cognitive Pulse tools (`run_cognitive_pulse`, `list_meta_proposals`, `apply_meta_proposal`, `reject_meta_proposal`, `get_meta_run`). Use `mode: "dry_run"` first; never apply or reject proposals silently — summarize risk, affected memories, and reason first.

## Answering

State which memories changed the answer when relevant: title + ID. If search found nothing, say that and proceed from available context. Do not expose unrelated private memory.

Prefer memory over vibes; prefer verified source over memory if they conflict. Surface conflicts and use `contradicts` links if durable. Memory is a snapshot in time — verify against current code/files before acting on it.

## Failure Modes

- Tools missing: discover them via lazy MCP loading first (search for "beautiful brain" or the tool names); only then tell the user to connect the server.
- Search failure: say memory lookup failed; continue from current context only if useful.
- Capture failure: report that nothing was stored and keep the proposed memory text in the reply.
- Ambiguous duplicate: prefer `update_memory` or `link_memory` over a new capture; if unsure, ask or store a task to reconcile.
- Sensitive info: never store secrets, credentials, raw logs, private health/finance/legal data, or third-party PII unless explicitly requested and clearly appropriate.