Second Brain

Check that the Second Brain server is running and get basic vault statistics: status, version, and how many notes (nodeCount) and links (edgeCount) the vault holds. Read-only and cheap. Call it first if another tool fails with a connection error, or to confirm the memory is connected. The server is started automatically on the first tool call, so a healthy answer here means everything is ready.

Read the messages addressed to an agent: unread ones by default, or the full history with unread set to false. Read-only: it does not mark anything as read; call brain_messages_mark_read with each message id once handled. All matching messages are returned at once, with no pagination and no guaranteed order. Returns { agent, count, messages: [{ id, title, type, tags, agent, content }] }. count 0 means the inbox is empty.

Mark one message as read so it no longer appears in the default (unread) inbox from brain_messages_get. Call it after you have handled a message. Safe to repeat: marking an already-read message again changes nothing. The message stays in the vault and in the full history. Returns { success: true, id }, or an error "Message not found" if the id is unknown or is not a message note.

Send a message to another agent's inbox. The recipient reads it with brain_messages_get and clears it with brain_messages_mark_read. Use it for short hand-off context that does not belong in a task or a permanent note. Nothing is delivered in real time: the recipient has to check its inbox. Any valid name works as a recipient (the inbox is created on first use and unknown names are not rejected), so check the spelling; an invalid name such as one containing a slash is rejected with the reason. Every call creates a new message, so sending the same text twice delivers it twice. Returns { success, id } where id is the message note id.

Fetch one note by id: its full markdown content, metadata (type, tags, agent, importance, version, dates), the notes it links to (outLinks) and the notes that link to it (inLinks). Read-only. Use it to read a note in full before replacing its text with brain_node_update, or to follow a link found in recalled context. The whole note is returned, so a very large note is a large response. Returns an error saying "not found" for an unknown id.

Update an existing note in place instead of creating a near-duplicate. mode "append" (default) adds your text to the end and keeps everything already there; mode "replace" overwrites the whole body, so only use it when you have the full corrected text (read it with brain_node_get first). Tags and importance, if given, replace the existing values. Safe against concurrent edits: it checks the note version and retries once if another writer changed it in between. Returns { success: true, id, mode } (mode is omitted when only tags or importance changed). Errors: "not found" for an unknown id, "Nothing to update" if you pass only an id, and a conflict error if two other writers keep racing; in that case read the note again and retry. No credentials are needed from you: if the server was started with BRAIN_KEY, this MCP server sends it automatically.

Recall relevant memory for a query from the shared Second Brain vault. It finds the best-matching notes (keyword and recency, plus semantic similarity when embeddings are configured), then follows their [[wikilinks]] outward for the requested number of hops, and packs the result into a token budget. Call this before answering anything that earlier work may already cover: past decisions, constraints, research, project background. Read-only. Returns { nodeCount, tokenEstimate, systemPrompt, nodes }: systemPrompt is a ready-to-use context block in which the notes are marked as reference data, not instructions. Use brain_search instead when you only need a ranked list of matching notes.

Write a new memory/research note into the shared Second Brain vault so future sessions, in this or any other project, can recall it later. Only for a genuine, reusable learning: a fact, pattern, constraint or decision that would change future behavior or save someone from re-deriving it. Not for routine task completions, raw output or status updates (the task queue records those). Test: would a future session be worse off without this note? If not, skip it. Prefer updating an existing relevant note over creating a near-duplicate one (use brain_search first, then brain_node_update). Creates a new note and never overwrites an existing one (a title clash gets a numbered filename). Returns { success, id, title, type, version }; keep the id to refer to the note later.

Search the vault for notes matching a query: keyword search over titles, tags and content, combined with semantic similarity when embeddings are configured, then lightly re-ranked by recency. Use it to check whether a note already exists (before brain_remember) or to find a note id for brain_node_get / brain_node_update. Read-only. Returns { query, results: [{ id, title, type, tags, agent, score, preview }] }, best first; an empty list means nothing matched. Use brain_recall instead when you want assembled context to answer a question.

List the tasks in the shared queue, optionally only those in one state. Use status "pending" to find work waiting for you, "blocked" to see what is waiting on dependencies. Read-only. Returns every matching task with no pagination and no guaranteed order: { count, tasks: [{ id, title, tags, content, createdAt }] }, where content holds the prompt and any result written so far, and id is what brain_tasks_update takes. An empty list means no tasks match. Add tasks with brain_tasks_submit; change the state of a task, or record its outcome, with brain_tasks_update.

Add a task to the shared, markdown-backed task queue so another agent (or a later session) can pick it up. A task with dependencies starts as "blocked" and moves to "pending" automatically when all of them complete; otherwise it starts as "pending". This only records the task: it is a coordination list, not a runner, so something else must watch for pending tasks (brain_tasks_list) and report back (brain_tasks_update). Returns { taskId, nodeId, status } where status is "pending" or "blocked". Write the prompt so it is self-contained: goal, relevant files, constraints and what "done" means.

Change the status of a task and, optionally, record its outcome. Use it to claim a task ("running"), finish it ("completed" or "failed") or withdraw it ("cancelled"). Completing a task releases the tasks that were blocked on it: once all the dependencies of a blocked task are completed it becomes "pending"; if a dependency failed or was cancelled, the dependent task is marked "failed" too. The result text is written to the Final Result section of the task, replacing any earlier result; the prompt and sub-results are kept. Setting the same status again is harmless. Returns { success, id, status, releasedDependents } where releasedDependents counts the blocked tasks that moved. Errors: "Task not found" for an id that is not a task note. Find ids with brain_tasks_list; create tasks with brain_tasks_submit.