Overview

Brains are searchable knowledge bases that agents can read and workflows can keep in sync.

A Brain is an organization-level knowledge base: a set of documents that Keystroke extracts, chunks, embeds, and indexes for hybrid (semantic + keyword) search. Agents attach Brains to answer questions from your content; workflows write documents into them — usually by syncing an external app like a wiki, an issue tracker, or a file store.

The model

Concept	What it is
Brain	Owns documents and an index configuration (embedding model, chunking defaults, language). Created and administered in the dashboard or with keystroke brains.
Document	Content keyed by a documentId you choose. Raw text/markdown, authored blocks, or binary files (PDF, DOCX, XLSX, …).
Source	Required on every upload: a slug for where the content originated (linear, notion, google-drive, manual, or your own). Filterable, and shown throughout the UI.
Metadata	Optional key/value attributes per document. Filterable at query time, never embedded.
Filter	A saved narrowing expression over sources and metadata, addressable as {brain}:{filter}. Filters own no documents — they are read-only views. See Filters.
Project access	A Brain is shared with projects explicitly: read lets a project’s agents attach and search it, write also lets its workflows upload, update, and delete documents.

Using a Brain from an agent

Attach one or more Brain references to an agent. The agent gets brain_search and brain_read tools scoped to the attached references — use a qualified {brain}:{filter} reference to expose only a slice:

src/agents/support.ts

import { defineAgent } from "@keystrokehq/keystroke/agent";

export default defineAgent({
  slug: "support",
  name: "Support",
  description: "Answers from company knowledge.",
  model: "anthropic/claude-sonnet-4.6",
  brains: ["company-knowledge", "company-knowledge:support-docs"],
  systemPrompt: "Search the Brain before answering factual questions.",
});

Using a Brain from a workflow

Open a handle with brain(reference) and call durable document operations. Every upload requires source; revision is your change fingerprint (more on this in Sync workflows):

src/workflows/upload-example.ts

import { brain } from "@keystrokehq/keystroke/brain";

const knowledge = brain("company-knowledge");

await knowledge.uploadDocument({
  documentId: "linear:TEAM-123",
  title: "TEAM-123: Fix login",
  source: "linear",
  content: issueText,
  metadata: { team: "platform", state: "In Progress" },
  revision: issue.updatedAt,
});

const hits = await knowledge.search({ query: "login bug", mode: "hybrid", limit: 5 });
const doc = await knowledge.read("linear:TEAM-123");

The handle also provides list (cursor-paginated, by documentId prefix), updateMetadata, delete, and deleteMany. Uploads are synchronous through indexing — when uploadDocument resolves with outcome: "ready", the content is searchable.

Where to go next

• Filters — when to use a filter instead of a second Brain, and how to slice a corpus for different agents
• Sync workflows — best practices for keeping a Brain in sync with an external app
• Agents — attaching Brains as agent knowledge
• Workflows — the durable execution model sync workflows build on