060-ask: conversational synthesis over accumulated knowledge

[ahoward]

Summary

brane ask — ask a question, get an answer synthesized from brane's accumulated knowledge (concepts, edges, episodes). Not just search results — reasoned answers with citations.

Why

brane search and brane memory recall find relevant items by vector similarity, but they don't reason. An agent (or human) asking "how does our auth system work?" wants a synthesized answer drawing from multiple concepts, their relationships, and past episodes — not a ranked list of similarity scores.

Bunny's bny brane ask does this by loading the entire worldview into Claude's context. That won't scale. We use vector search to select relevant context, then hand that focused context to the LLM.

What

CLI

brane ask "how does the auth middleware work?"
brane ask "what do I know about rate limiting?"
brane ask "what changed in the last week?" --after 2026-03-20
brane ask --input design-doc.md "does this conflict with what we know?"

Flags

• --limit <n> — max context items to load (default: 20)
• --after / --before — time range filter on episodes
• --agent <id> — filter by agent
• --input <path> — ask about a file against the knowledge base
• --json / -j — JSON output

Flow

1. Vector search — query concepts + episodes for relevant context (existing infrastructure)
2. Graph enrichment — for matched concepts, pull neighbor edges and connected concepts
3. Build context — assemble relevant concepts, edges, episodes into a prompt
4. LLM synthesis — Claude answers the question using only the provided context
5. Citation — response includes which concepts/episodes informed the answer

Response

Auth uses JWT tokens with 15-minute expiry and refresh rotation.
The AuthService (Entity) depends on UserDB and handles login/logout.
Rate limiting was added to the login endpoint (5 req/min sliding window).

Sources:
  concept #1: AuthService (Entity)
  concept #5: UserDB (Entity)
  edge #1: AuthService → UserDB (DEPENDS_ON)
  episode #1: JWT tokens expire after 15 minutes [auth, debugging]
  episode #3: Rate limiter uses sliding window [architecture, security]

Key Difference from bunny

• Doesn't load everything — uses vector search to select relevant context
• Cites specific concepts/episodes by ID, not markdown file paths
• Scales with graph size (search is O(log n), not O(n))

MCP Tool

ask: { question: string, limit?: number, after?: string, before?: string, agent_id?: string }

Depends On

• 059-digest: consume URLs, files, directories, stdin into knowledge graph #82 (059-digest) — not strictly required, but ask is most useful after digest populates the graph

Acceptance

• Answers natural language questions from graph + episodes
• Citations reference specific concept/episode IDs
• Vector search selects relevant context (not full load)
• Graph enrichment pulls neighbor edges
• Time range and agent filtering work
• --input mode compares a document against knowledge
• MCP tool exposed
• Spike test passes