name: brian-sessions description: When and how to manage Brian sessions for tracked work. Covers start_session, close_session, list_sessions, auto-linking, and session summary artifacts.

brian-sessions

When and how to manage Brian sessions for tracked work.

When to start a session

Not every conversation needs a session. Start one when:

• The work is substantive and traceable (planning session, document draft, product decision)
• The user explicitly wants the session indexed ("let's work on...", "I want to plan...")
• The topic is coherent enough to warrant its own summary document
• The conversation will last more than a few exchanges on a focused topic

Do not start sessions for quick Q&A, lookups, or casual conversations.

How to start

Call start_session with a specific, descriptive topic.

Good topics (findable, descriptive — becomes the summary document title):

• "energy model — SA-VIC interconnector scenario"
• "Brian MCP welcome experience v2 design"
• "Q2 investor update draft"

Bad topics (vague, generic):

• "model review"
• "working session"
• "planning"

The session ID is generated as: session_{YYYYMMDD}_{topic_slug} (slug is lowercase, max 40 chars, hyphens for spaces).

What happens when a session is active

Once start_session is called, all subsequent store_memory and store_document calls automatically inherit session_id and exchange_id. Claude does not need to pass these manually. This is the primary mechanical reason to start a session — it creates automatic linkage across everything stored in that conversation.

The exchange counter increments automatically on the server side.

Only one session at a time

start_session fails if a session is already active. It returns an error: "session X is already active. Close it first with close_session."

If you need to switch topics, close the current session first, then start a new one.

When to close

Call close_session at the natural end of a focused work block:

• User says they're done for the day
• The conversation has reached a natural conclusion
• The topic is shifting to something unrelated

Do not close prematurely. If the user is pausing and will likely continue, do not close. The session can span multiple exchanges over an extended period.

Do not forget to close. An unclosed session means the next start_session will fail. If a previous session was left open (e.g. conversation was abandoned), close it before starting a new one.

What close_session produces

When close_session is called, the backend:

1. Queries all memories tagged with the session ID
2. Groups them by type: intent, state, outcome, document, truth, event, preference, instruction, snapshot
3. Builds a markdown summary with metadata (topic, space, start time, close time, exchange count, memory count)
4. If Google Drive is connected: uploads summary to Sessions/{YYYY-MM}/ folder as a text file
5. If no Drive: stores summary as a memory-only document in the structured field
6. Writes the summary as a document memory with tags ["document", "session-summary", sessionId] and salience 0.8
7. Closes the session record and clears the active session

The summary document is a valuable artifact — it becomes retrievable in future get_context calls and appears in the welcome block's "Last Session" section.

Drive path for summaries

Session summaries are saved to Sessions/{YYYY-MM}/ in Google Drive. This is not configurable via close_session — the path is hardcoded on the server.

Session state

There is no list_sessions tool. To check if a session is active, attempt start_session — if it fails with "already active", a session is open. Or check the welcome block which references the last session.

If a session was abandoned

If a previous session was never closed (e.g. the conversation ended without close_session):

1. The session is still marked "active" in the database
2. start_session will fail until it's closed
3. Call close_session with the old session's ID to close it — the summary will still be generated from whatever memories were stored during that session
4. Then start a fresh session for the new work