Brain · Ask the brain

Find the brain entry that answers the question

Ask the brain searches a tracked repository's .claude/brain/ and docs/ markdown. The lightweight desktop uses lexical BM25 ranking without a model download or API key. Every hit names the file, heading and line. Optional vector ranking names its provider, and synthesis runs only when you request it.

For: the engineer who knows the brain answered this once and cannot name the file, and the owner who sets the cross-client boundary and the token caps

What it does, and why it helps

Type a question. RepoOps searches the repository's .claude/brain/ and docs/ markdown and ranks the chunks with Okapi BM25. The lightweight installer leaves out the optional local embedding libraries, so lexical retrieval works offline without a model download. A configured hosted embedding provider can add vector ranking and receives the text it embeds. Development or archive builds can include local embeddings. The Vector chip says whether vector ranking actually ran. Each hit shows the path, heading, line and snippet; opening it takes you to the cited source.

Three other things answer on the same box, and each says which one did. A counting, trend or existence question is answered by SQL over the metadata ledger and the card offers Show the SQL, because a wrong count is a confident integer with no error signal. A question about your own spend is resolved by the metric registry over the aggregates the cost tabs already compute, and when no value is defined the card reads RepoOps cannot resolve that number with the reason, never a plausible figure. Only the Synthesize this answer button calls a model, on your own Anthropic key, and its answer carries numbered citations back to the hits.

Ask the brain searches the same markdown the Brain library lists. A hit carries its file, heading and line, but no owner, review state or verification date; for those, open the Brain library under Memory (Memory, then Brain library, on the desktop app or at repoops.ai/team/brain-library), which groups the documents by kind (architecture, service and dependency maps, runbooks, decisions, known errors, incident histories, patterns) and shows each one's owner or not recorded, its last verification and whether that date came from the page or its last commit, its sources and whether a person reviewed the revision it holds now, whether it changed after that review, or whether it is a proposal or stale. The hosted library reads the published brain, which keeps no commit dates, so a page without a verified date in its frontmatter reads unknown there. Decisions and Errors are brain pages of their own, the Wiki tab renders the generated wiki with each claim citing the source file it describes, and Citation rot, under Brain health, checks every night that each citation in the brain still resolves, so a broken reference is reported there, not on the hit.

The pain. The reasoning is written down. It is in one of four files, none of them the one you have open, and the word you remember is not the word the author used. So you re-derive the decision, and the brain gets one more entry that says the same thing.

The point of view. An answer without a citation is a claim. Retrieval should hand you the file, the heading and the line and let you read the source, and it should say plainly when a number came from SQL, from a resolver, or from a model.

What gets easier. Recovering a decision you cannot name. The hit row is usually enough to pick which file to open, and the deep link lands on the heading rather than the top of a long page.

When it helps. A repository whose brain and docs are real markdown on disk, and a question whose words would plausibly appear in the prose. Newly accepted brain entries are searchable at once, because the read is working-tree first.

Its limits. It ranks prose. For a specific structural fact, Brain links answers better than text search. The file budget is 2,000 markdown files per tree, so the brain tree and the docs tree get 2,000 each, and sessions may take at most a quarter of the brain share. A file is read in 500 KB windows rather than truncated, up to a 4 MB ceiling. A fleet-wide or multi-repo scope searches the prose only; the fleet event rows are indexed for a single-repo scope. Synthesis is the only part that can be wrong in the way a model is wrong.

Understand it in 30 seconds

30.1 s, captions on. Narration: Microsoft Zira Desktop (provisional voice; an approved narration source is pending).Transcript

Read the narration

0:00 You know the brain answered this once.
0:02 Nobody can name the file.
0:06 RepoOps searches the markdown and cites it.
0:09 Lexical ranking needs no model download or key.
0:13 Every hit carries the file, the heading and the line.
0:16 A counting question answers by SQL, and shows it.
0:23 Open the source and judge it yourself.
0:25 Save the answer as a decision.

Synthetic example. Read the guide

Where to find it

Desktop: Memory → Ask the brain in the local app.
Hosted: repoops.ai/team/ask, under Memory.
API: /api/brain/ask

When to use it

Recovering the reasoning behind a decision

Situation. A reviewer asks why the integration tests do not mock the database. You remember the argument being settled and cannot name the file.

What you do. Open Ask the brain, leave the scope chip on this repository, and type the question in the words you would say out loud.

What you see. The meta line reads the hit count, the chunks indexed and the files searched. The signal chips read BM25 and, when the vector half ran, Vector with its provider. Each hit carries the path, the heading and the line.

What it establishes. You open the cited section and read the original argument, rather than taking a summary of it. Nothing was sent anywhere to get that answer.

Asking for a number instead of a passage

Situation. You want the spend per active developer for last week, and you do not want a number a model produced.

What you do. Type the question, or press one of the Try the numbers chips. Switch the Brain and Telemetry toggle to Telemetry for a question about usage aggregates.

What you see. A metric card shows the figure, its window, the repositories it covered and the modules that produced it. In Telemetry mode the meta line reads either Answered by the deterministic resolver, no LLM call, or Answered by the BYOK tool loop with the API and tool call counts and a per-call trace.

What it establishes. Either a cited number or an honest refusal. A window with no active developers to divide by returns the abstain card with that reason, so a missing denominator never becomes a figure.

Keeping the answer where the next reader will find it

Situation. The synthesized answer is the summary you wish had been written down a month ago.

What you do. Press Save as decision or Save as note under the answer card, check the pre-filled title, path and body, and press Save.

What you see. A decision appends a titled block with a provenance footer to .claude/brain/decisions.md; a note writes a new file under .claude/brain/notes/ with YAML front matter and refuses to overwrite one that exists. The status line names the relative path and the repository. The audit row carries the title hash and the body's sha256, never the body.

What it establishes. The next Ask finds it, because the corpus is read from the working tree. There is no review step on this path: the write lands in the live file, and what bounds it is the path check, not a human gate. Undoing it is a git matter.

Before you start

Supported versions: RepoOps desktop v0.3.1, the release this guide was read against. Retrieval needs nothing else. Vector ranking uses an optional on-device dependency; without it, ranking is BM25 alone.
Where it runs: Local: Ask the brain, under Memory. Hosted: repoops.ai/team/ask, which is full-text search over the brain snapshot your desktop published, twenty hits a page, team-scoped with per-repo access. The hosted page makes no model call and asks for no key. The hosted path that reasons over a stored brain is the personal brain at repoops.ai/my-brain, and it is a different surface with its own rules, set out under Data and cost.
Permissions: A local query reads the repositories this machine tracks, and every Ask endpoint sits behind the server's same-origin gate. A scope spanning more than one client needs Allow cross-client Ask the brain switched on for the account; with it off, that query is refused with a 403. Saving the embeddings key is an operator write and asks for confirmation when the operator secret is configured. On the hosted page the team is derived server side and per-repo access narrows it further.
Connections: None for retrieval. ANTHROPIC_API_KEY in the data directory's .env for the Synthesize button and for the Telemetry tool loop. A Voyage, OpenAI or OpenRouter key only if you want a hosted embedding model instead of the on-device one.
Plan: The local tab has no plan gate; the pricing capability map has no Ask row. The hosted team page needs at least the hosted plan. The hosted personal Ask needs that plan and your own provider key.

Configure it

Pick the scope before you ask.
The Scope chip strip sets what is searched: This repo, This client, This account, All my repos, and a Cross-client indicator that reports the account setting as on, off or unknown. The tab starts on This repo when it opens for a repository and on This account otherwise. A query that names no scope, under an account with no scope setting, covers one repository; REPOOPS_BRAIN_ASK_DEFAULT_SCOPE=account in the data directory's .env makes that the account's repositories instead.
Ask, then read the hit rather than the summary.
The Ask button returns ranked hits with the path, the heading anchor and the line. Pivot runs a full new retrieval; Refine re-ranks the prior hits against the new query. When nothing matches, the tab says No matches. Try a broader query, or words that would actually appear in the brain, which is a statement about the words, not about the brain.
Choose an embedding provider, or turn vectors off.
Settings, the Brain embeddings card: Provider plus an API key field, with Save and Test. The lightweight installer uses BM25 without local model libraries. Choosing voyage, openai or openrouter with the matching key adds hosted vectors and sends chunk text to that provider. Choosing None keeps BM25 alone.
Set the token caps and the cross-client boundary.
Settings, the Ask the brain tenant boundary and cost gates card: Allow cross-client Ask the brain (off by default, and every allowed crossing writes one hashed row to the audit log), Max tokens per question (2,000) and Daily token cap (per user) (50,000), with today's used total beside them.
Synthesize only when the hits are not enough.
Synthesize this answer sends the query and the top hits to Anthropic on your key and returns a cited answer with Stream on by default. It never fires on its own. The footer names the tokens used against the daily cap, and a reached cap refuses with the numbers rather than silently truncating.
Switch to Telemetry for a question about usage.
The Brain and Telemetry toggle. Telemetry tries a deterministic resolver first, which costs nothing and says so; only an unmatched question falls through to a bounded tool loop on your key, at most six tool calls a turn, sharing the same daily token cap.
Write the good answers back.
Save as decision appends to the repository's decisions.md; Save as note writes a dated file under .claude/brain/notes/. The server refuses any path that does not resolve inside the brain directory of a repository your account owns.

Setting	Where	A sensible choice	Why it matters
`REPOOPS_BRAIN_EMBED_PROVIDER`	the data directory's .env, or Settings, Brain embeddings, Provider	unset (the on-device model where it is installed; the lightweight installer has none, so BM25 alone), or none for BM25 alone	Only none turns vectors off. A named provider whose key is missing falls back to the on-device model where one is installed rather than disabling the vector half, and a provider error degrades to BM25 rather than failing the query.
`REPOOPS_BRAIN_EMBED_DEADLINE_MS`	the data directory's .env	2500 (the default)	The foreground vector deadline. An overrun returns the BM25 result now and warms the vectors in the background.
`synthMaxTokensPerQuestion`	Settings, Max tokens per question	2000 (the default)	The ceiling on one synthesized answer. It bounds a single expensive question, not the day.
`synthDailyCapTokens`	Settings, Daily token cap (per user)	50000 (the default)	The per-user, per-UTC-day budget for synthesis and for the Telemetry tool loop together. Reaching it refuses the call and names the numbers.
`allowCrossClientAsk`	Settings, Allow cross-client Ask the brain	off (the default)	With it off a multi-client scope is refused with a 403. With it on, every crossing writes one hashed row to .claude/brain/audit/cross-client-ask.jsonl.
`REPOOPS_BRAIN_ASK_DEFAULT_SCOPE`	the data directory's .env	repo (the default) or account	What a query covers when no scope is chosen and no account setting applies.
`REPOOPS_ASK_ARCHIVE_PURGE_DAYS`	the data directory's .env	90 (the default)	How long an archived conversation is kept before it is deleted. Ask history is re-issuable, so purge after archive is the shipped behaviour.
`REPOOPS_ASK_METRIC_BUDGET_MS`	the data directory's .env	10000 (the default)	The per-aggregate budget before a Telemetry metric question abstains with a retry hint instead of holding the request open.
`REPOOPS_TELEMETRY_CHAT_MODEL`	the data directory's .env	unset (claude-sonnet-5)	The model the Telemetry tool loop calls on your key. REPOOPS_TELEMETRY_CHAT_CHEAP set to 1 uses the Haiku model instead.

ⓘ

To stop or undo

Retrieval has nothing to turn off; it reads files you already have. To stop every model call: do not press Synthesize this answer, leave the toggle on Brain, and remove ANTHROPIC_API_KEY from the data directory's .env. To stop every network call from ranking, set the embeddings Provider to None. To bound rather than stop the spend, lower Daily token cap (per user).

What you should see

The lightweight default

Configuration. No keys set, the lightweight desktop installer, scope on one repository.

Expect. Ranked hits with a path, heading and line each. The BM25 chip is lit; Vector and Synth are dark. Lexical retrieval makes no network call.

Verify. The meta line reports the hits, the chunks indexed and the files searched. Clicking a hit opens the cited page at its heading anchor, at the line the row named.

A counting question, answered or refused

Configuration. Any of the above. The question is shaped as a count, a trend, an extremum or an existence check.

Expect. An Exact answer card computed by SQL over the metadata ledger, with Show the SQL and its parameters, above the ranked hits. When the router sees a counting question and the ledger cannot answer it, the card says the ledger abstained and gives the reason, and the hits below are marked as ranked retrieval rather than a count.

Verify. Read the SQL. A wrong count is checkable; that is why it is shown. The metric card carries the same rule for spend questions and names the modules it read.

The vector half or the model is unavailable

Configuration. The optional on-device dependency absent, or a hosted provider key wrong, or no Anthropic key.

Expect. Hits still return, ranked by BM25, with the Vector chip dark. Synthesize this answer fails with the error on the card, and Telemetry mode reports that the chat needs a key. Nothing silently substitutes a different answer.

Verify. The signal chips are the readout. The embeddings line above the results reads the provider and the masked key, or says no hosted key with a link to set one.

Data and cost

What is captured: One JSONL line per turn at the repository's .claude/brain/sessions/asks/[convId].jsonl: timestamp, conversation id, turn index, scope, query, hits, the synthesized answer, tokens used, and the prior turn's hit ids. A cross-client query also writes one hashed row to .claude/brain/audit/cross-client-ask.jsonl. A write-back writes the file you approved and an audit row carrying the body's sha256, never the body.
Who can see it: Local by default; the files sit in the repository's own brain directory. The hosted page at repoops.ai/team/ask reads the redacted brain snapshot your desktop publishes, bounded to your team and narrowed by per-repo access; it never reads the conversation files. Your questions are not part of what publishes.
How long it is kept: A conversation caps at 10 turns and at most 100 stay active. A conversation whose newest turn is older than 30 days is archived to sessions/asks/archive/[YYYY-MM]/, and an archived conversation is deleted 90 days after that, or after REPOOPS_ASK_ARCHIVE_PURGE_DAYS, so the worst case is about 120 days. Both stages run on the app's shared five-minute maintenance tick. On the hosted personal Ask a synthesized answer and the question that produced it are held in server memory keyed to your account for 30 minutes, tunable to a 24 hour ceiling by REPOOPS_PERSON_ASK_CACHE_TTL_MS, never written to the database, and dropped whenever your brain changes. That number is rendered on the privacy and terms pages from one module rather than typed, and a test pins that.
What leaves the machine: BM25 and the on-device model make no network call. A hosted embedding provider receives the chunk text it embeds. Synthesize this answer sends the query and the top hits to Anthropic on your ANTHROPIC_API_KEY, on claude-haiku-4-5-20251001. The Telemetry tool loop sends the question and bounded aggregate rows on the same key, on claude-sonnet-5 by default. The hosted personal Ask calls the provider you chose (Anthropic, OpenAI or OpenRouter) on the key you stored, which is encrypted at rest under the deployment's vault key; with no key stored it refuses with 428 and names the three providers rather than falling back to a RepoOps key.
What it costs: Retrieval has no per-query cost, and a Telemetry question the deterministic resolver answers reports zero LLM calls. Synthesis is metered in tokens against the daily cap (default 50,000 per user per UTC day, 2,000 per question) and billed to you by Anthropic on your key; the daily ledger debits the projected token count for a question rather than the measured usage, and it records tokens, never dollars, so synthesis does not appear in the dollar views. The Telemetry tool loop shares that cap and does record a dollar cost, under the surface repoops-chat. The hosted personal Ask is metered per day against two counters, 500 ordinary asks and 100 deep ones, each keyed to the individual account; a repeat served from the memo charges neither counter and makes no call, and the provider bills the call to you.

When the result differs

Symptom	Likely cause	Next action
No matches. Try a broader query, or words that would actually appear in the brain.	Nothing in the indexed markdown matched the words used, or the scope is narrower than you think.	Re-ask in the author's likely wording, or widen the Scope chip. Check the meta line's file count against what you expected to be searched.
The Vector chip stays dark.	The optional on-device dependency is absent, the provider is set to None, a hosted provider key is wrong, or the 2,500 ms vector deadline overran.	Read the embeddings line above the results. Press Test on the Brain embeddings card in Settings. An overrun warms in the background, so the next ask usually shows the chip.
Daily synth cap reached, with the tokens used and the cap.	Synthesis and the Telemetry tool loop share one per-user, per-UTC-day token budget.	Wait for 00:00 UTC, or raise Daily token cap (per user) in Settings. The ranked hits are unaffected either way.
A 403 on a scope that spans more than one client.	Allow cross-client Ask the brain is off for the account.	Switch it on in Settings if that crossing is intended. Every allowed crossing is written to the audit log as a hashed row.
Too many active conversations; archive or delete some.	The active conversation directory is at its cap of 100.	Resume an existing conversation from the chip strip, or archive one with DELETE /api/brain/ask/conversations/[id].
Telemetry chat needs a BYOK key.	The question did not match the deterministic resolver and no ANTHROPIC_API_KEY is set on this machine.	Add the key to the data directory's .env, or rephrase toward a shape the free resolver answers; the Try the numbers chips show which shapes those are.
On repoops.ai, This needs your own model key.	The hosted personal Ask found no stored provider key for your account.	Store a key for Anthropic, OpenAI or OpenRouter. The panel opens in place of the answer; the hosted model key page covers it.
On repoops.ai/team/ask, no matches and a note about publishing.	Your team has no published brain snapshot yet, or the file is outside your per-repo access.	Turn on brain publishing in the desktop app and wait for the next snapshot.

Disable: Set the embeddings Provider to None to stop vector ranking. Remove ANTHROPIC_API_KEY, or set Daily token cap (per user) low, to stop or bound synthesis. Switch Allow cross-client Ask the brain off to refuse any multi-client scope. Retrieval itself is a read of files you already have and has no switch.
Roll back: Not provided. A write-back appends to .claude/brain/decisions.md or writes a file under .claude/brain/notes/, and nothing in the app undoes it; revert it in git. Before you save, Cancel on the write-back form discards the draft.
Revoke access: Embeddings: Remove on the Brain embeddings card clears the provider and key from this machine's data directory .env; a key set through the environment is managed there instead. Anthropic: replace or clear it on the Anthropic API key card. Hosted: Remove on the model key panel deletes the stored row, and switching provider replaces it rather than leaving two.
Delete: Not provided as an immediate delete. DELETE /api/brain/ask/conversations/[id] archives the conversation rather than removing it; the file moves to .claude/brain/sessions/asks/archive/[YYYY-MM]/ and is purged after the archive window. The tab has no button for it. The hosted answer memo has no delete route either; it expires on its own timer, on eviction, or when your brain changes.

Maintenance evidence

Feature id: brain-ask (spine leaf ask-the-brain)
Owner: Brain intelligence (P1 brain search) and the Knowledge fabric phases K2 and K6 to K9, which added the scope strip, the conversation state, the caps and the society fan-out. Guide: LDG-0717.
Supported product version: RepoOps main at 509e8e8ad (after v0.3.2)
Last verified: 2026-09-26, the scope strip, the default scope and the embedding default read again against origin/main at 509e8e8ad (public/brain-ask.html, lib/brain/ask-scope-resolver.mjs) and not opened on a running instance this time; the Brain library paragraph was rewritten with LDG-1007 against public/lib/brain-library.js and lib/brain-library/classify.mjs, and the library was opened on an isolated local instance. 2026-09-20: lightweight retrieval verified against an isolated installer dependency payload, with cited lexical hits and no pending vector work. Guide and in-browser walkthrough inspected locally. Other controls were source-reviewed on 2026-09-15 at 52366bb6d; this check does not establish hosted deployment behavior or complete installer performance.
Example fixtures: No fixture file; the shapes are inline. lib/brain-ask.test.mjs pins the rerank bound and the BM25-only fallback, lib/brain-corpus.fleet.test.mjs pins the fleet rows and the keyless end-to-end ask, lib/brain-ask-blast.test.mjs pins the blast-radius intent and its three fall-throughs, lib/ask-conversation.test.mjs and lib/ask-conversation-api.test.mjs pin the turn cap and the boundary, public/lib/ask-scope.test.mjs with test/brain-ask-client-scope.test.mjs pin the client scope, and website/app/(marketing)/hosted-retention-drift.test.ts pins the hosted memo wording and the rendered lifetime.
Source references: lib/brain-ask.mjs, lib/brain-corpus.mjs, lib/brain-bm25.mjs, lib/brain-synth.mjs, lib/local-embed.mjs, lib/byok-embed.mjs, lib/ask-conversation.mjs, lib/ask-conversation-api.mjs, lib/ask-writeback.mjs, lib/account-settings.mjs, lib/telemetry-chat.mjs, public/brain-ask.html, public/settings.html, website/app/api/brain/search/route.ts, website/app/api/me/brain/ask/route.ts, website/lib/hosted-ask-retention.ts
Documentation review: Revised 2026-09-26 by the authoring agent against the code (LDG-0988); independent review not yet recorded.
Video review: Narrated story rendered and published 2026-09-26 (render fcec328de430, LDG-0988), beside the desktop navigation with Memory selected. Six frames, the captions and the transcript were reviewed by the authoring agent, not an independent reviewer; the audio was not listened to by a person. Narration is the provisional Windows voice until LDG-0721. The in-browser BrainAskWalkthrough plays only when no narrated story is published.

Last updated October 3, 2026