name: brian-retrieval description: When and how to retrieve context from Brian before responding. Call get_context before answering domain questions, at conversation start, or when prior context would improve the answer.

brian-retrieval

When and how to retrieve context from Brian before responding.

When to use

Any conversation where prior context would improve the answer. Specifically:

• Domain-specific questions about the user's work, projects, or decisions
• References to past work ("as we discussed", "my project", "our approach")
• The opening of any new conversation when Brian is connected
• Any task where the user's preferences, instructions, or history are relevant

The cost of an unnecessary retrieval is negligible. The cost of a missed retrieval is a confabulated or stale answer. When in doubt, retrieve.

How to retrieve

Call get_context with a query relevant to the current topic.

Query construction

Specific queries outperform vague ones. The scoring formula rewards keyword overlap — query terms that match memory content and tags score highest.

Good queries (noun-focused, specific):

• "user's tech stack and deployment environment"
• "Q2 fundraising goals and investor contacts"
• "Brian MCP session indexing architecture"

Bad queries (vague, verb-heavy):

• "what does the user work on"
• "tell me about their project"
• "recent stuff"

Limit calibration

• Default (20): Most conversations
• Broad reconstruction (40-50): Start of conversation, multi-topic catchup, user says "remind me where we are"
• Narrow lookup (10): Specific fact retrieval, single-topic question

How retrieval works

Brian uses hybrid scoring: keyword matching + vector semantic similarity.

Scoring formula:

• Keyword match: up to 4 points (% of query terms found in memory content and tags)
• Salience: up to 2 points (memory's importance rating)
• Pinned bonus: +3 (pinned memories always surface)
• Recency: up to 1 point (linear decay over 30 days)
• Type priority: +1 for truth and instruction types
• Vector similarity: up to 3 points (semantic match via embeddings)

Practical implication: Pinned truth and instruction memories dominate retrieval. Recent memories get a boost. Tags directly improve recall — they're scored as keywords.

Space scoping

When a space is active, retrieval is scoped to that space only. Memories from other spaces are not returned. The active space is reported in the retrieval response footer.

If the user appears to be working in a different domain than the active space, flag it. Use set_space to switch. After switching, call get_context again to load context for the new space.

To search across all spaces, the user must clear the active space (set_space with empty string or "all").

Applying context

Never narrate the retrieval. Do not say "based on my memories", "I can see from Brian that...", or "according to what's stored". Treat retrieved context as naturally known — the same way a colleague recalls shared history without explaining how they remember it.

When results are thin

If retrieval returns sparse or irrelevant results for a domain the user is clearly working in, flag this. Suggest seeding the memory graph for that topic. Do not silently proceed as if you have good context when you don't.

Conflict handling

If two retrieved memories contradict (e.g. two truths with different values for the same fact), surface the conflict explicitly with timestamps. Do not silently pick one. The user needs to resolve which is current.

Technical limits

• Retrieval fetches up to 200 memories from the database before scoring
• Top N are returned (controlled by limit parameter)
• If fewer memories exist than the limit, all are returned (no error)
• Vector similarity search additionally returns up to 10 semantically similar memories
• Results from both keyword and vector scoring are merged and deduplicated

Soul querying (Brief 11)

Every Brian tool response ends with a micro router marker:

---SOUL-ROUTER---
tool: <tool_name>
v: <soul_version>
audit: <tool_invocations row uuid>
---END---

The full soul guidance is not pushed into the response — it's queryable. Fetch it on demand.

Canonical query pattern

• Tool souls: fetch_tool_soul({ tool_name: "<name>" }) — returns the full soul JSON. Tool souls live in the Edge runtime filesystem (one JSON per tool); this MCP tool reads from there.
• Schema souls (Brief 5, not yet built): will use the same filesystem pattern.
• Space souls (Brief 10): retrieved automatically when the space is active — pinned truth memory inside each space. No separate fetch needed.

When to query a tool soul

• First use of a tool in a session.
• Unexpected tool behaviour or debugging.
• The v in the router differs from what you saw earlier in this session for the same tool (a new soul version shipped — fetch the new guidance).
• Before calling a mandatory-query tool: start_session, close_session, set_space, create_space, extract_memories. Their portfolio_impact entries carry invocation-time triggers directives that you need to act on.

When to ignore

Routine repeat use within a session after you've already been shaped by the soul. The router is a receipt, not a prompt.

Interpreting portfolio_impact

Each soul's portfolio_impact entries declare what happens when the tool fires:

• triggers — act now. Fire a follow-up write, call, or user prompt.
• constrains — shape the response. Apply the rule to what you return.
• flags — surface to the user. Don't act silently.
• activates — begin a pattern for the session (e.g. three-layer writes).
• scopes — inherit context automatically (session_id, space_id).

How souls evolve

Tool souls evolve via Git. A soul edit lands as a file change + commit; the router's v bumps the next time the tool fires. Historical soul content is recoverable via git show <commit>:supabase/functions/mcp/souls/<tool>.json. No DB migration, no per-user seeding.

Space souls (the only soul type still stored as memories) evolve via update_memory({supersede: true}). The update_memory guard fires on direct in-place edits; use the supersede path to create a new version with superseded_by linking back to the old row.