Working with a brain

Search and prompt context

Find pages, and feed the right slice of a brain into an LLM.

Semantic + keyword search

searchPages combines vector similarity with keyword matching and returns results ranked by relevance, each with a snippet explaining the match.

1const results = await client.workspace.searchPages({
2  brainId,
3  query: "why did we drop the cache",
4  topK: 5,
5});
6
7for (const r of results) {
8  console.log(r.similarity.toFixed(2), r.title);
9}

Tune with topK (how many results) and minSimilarity (a floor, to drop weak matches rather than returning padding).

Prompt index

Search answers a specific question. When you instead want to give an agent general working context, use index — a compact, prompt-shaped digest of the brain’s most important pages.

1const index = await client.workspace.index({ brainId, limit: 40 });
2
3const completion = await openai.chat.completions.create({
4  model: "gpt-4o",
5  messages: [
6    { role: "system", content: `What you know about this user:\n\n${index}` },
7    { role: "user", content: userMessage },
8  ],
9});

This is the intended way to make an agent remember. Pinned pages rank first, so pinning is how a user says “always keep this in mind.”

Pick limit to fit your context budget — start around 40 and tune against token cost.

Connections

Connections are the non-obvious links the brain finds on its own.

1// Strong connections the user hasn't dismissed yet
2for await (const c of await client.workspace.listConnections({
3  brainId, strength: "strong", unackedOnly: true,
4})) {
5  console.log(c.pageASlug, "↔", c.pageBSlug);
6}
7
8// Connections for one page
9const related = await client.workspace.pageConnections({ brainId, slug });
10
11// Dismiss without deleting
12await client.workspace.ackConnection({ brainId, connectionId });

Graph

For visualization, graph returns a renderable subgraph. Keep nodeLimit low enough to draw.

1const { nodes, edges } = await client.workspace.graph({ brainId, nodeLimit: 150 });