> ## Documentation Index
> Fetch the complete documentation index at: https://keystroke.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/learn/brains/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:

```ts src/agents/support.ts theme={null}
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](/docs/learn/brains/sync-workflows)):

```ts src/workflows/upload-example.ts theme={null}
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](/docs/learn/brains/filters) — when to use a filter instead of a second Brain, and how to slice a corpus for different agents
* [Sync workflows](/docs/learn/brains/sync-workflows) — best practices for keeping a Brain in sync with an external app
* [Agents](/docs/learn/agents/overview) — attaching Brains as agent knowledge
* [Workflows](/docs/learn/workflows/overview) — the durable execution model sync workflows build on