> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.meetluno.ai/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 Luno OS 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). The embedding model must produce 1024-dimensional vectors (the default `voyage/voyage-4` does; OpenAI and Google models are asked for 1024). The dashboard only offers models that can, and the API rejects others such as `openai/text-embedding-ada-002`. Changing the configuration rebuilds the index in the background: search keeps serving the old index until the new one is ready, and a document that fails to re-index is marked failed with its error. Created and administered in the dashboard or with `luno 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](https://docs.os.meetluno.ai/learn/brains/filters.md). |
| **Knowledge graph** | While a document is indexed, a cheap model (`deepseek/deepseek-v4-flash` by default) extracts its entities (people, organizations, places, products, concepts, events) and the relations between them. Relation labels are written in the Brain's language, with one relation per pair of entities. The dashboard's Brain explorer draws them as a graph; click an entity to see the documents and passages that mention it. Tokens count as normal LLM usage. Turn it off in the Brain's **Settings → Knowledge graph**, or turn it off or pick another model with `indexConfig.graph` (`{ "enabled": false }` or `{ "model": "vendor/model" }`; the model must be enabled for your organization). Brains indexed before the graph existed get one when you re-index them. |
| **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 "@meetluno/luno/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](https://docs.os.meetluno.ai/learn/brains/sync-workflows.md)):

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.