Search and prompt context | Living Brain

Semantic + keyword search

searchPages combines vector similarity with keyword matching and returns results ranked by relevance, each with a snippet explaining the match and a matchedOn value saying why it matched: semantic, keyword, or both.

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

Tune with topK (how many results) and minSimilarity (a floor, to drop weak matches rather than returning padding). Keyword matches are returned even when their similarity is below minSimilarity.

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.

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

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.

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

Graph

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

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