# Import your team's work into a Brain

Agents don't need memory. They need a Brain.

This is a single bootstrap procedure for a coding agent working on a person's machine, not an installable Agent Skill. It populates a Brain, which is the system of record for what a team knows: decisions, standards, current answers. It is not a system of record for operational data. Invoices stay in the accounting system and deals stay in the CRM.

The source can be a folder of markdown, a wiki export, or a docs directory in a repo. It can also be Notion, Google Drive, Confluence, or Slack: if you already hold the person's credentials for those tools, you are the connector. Read from them directly and populate the Brain the same way.

**This reads. It never writes back.** Nothing in the source is modified, moved, or deleted, no sync is established, and no credential of ours touches their systems. What you produce is a copy, which makes this a cheap thing to try and a cheap thing to abandon.

**A copy has a shelf life.** While the team keeps authoring in the old place, the Brain drifts away from it and the answers get worse. Tell the person this plainly: run both for a week or two, compare the answers, and then decide whether the Brain becomes the place they write. That cutover is their decision and their moment, not a side effect of running this.

If they have nothing written down yet, or you are adding Brains to a product you ship, or you are migrating Brains from somewhere else, stop here and use [the build procedure](https://nicia.ai/build.md).

## Read in this order

1. [Docs overview](https://nicia.ai/docs/)
2. [Detailed activation guide](https://nicia.ai/docs/start/add-a-brain/)
3. [Authentication](https://nicia.ai/docs/start/authentication/)
4. [Brain keys](https://nicia.ai/docs/scale/brain-keys/)
5. [Review](https://nicia.ai/docs/govern/review/)
6. [Errors](https://nicia.ai/docs/api/errors/) and [idempotency](https://nicia.ai/docs/api/idempotency/)
7. [Scalar API reference](https://nicia.ai/docs/reference/) and [generated OpenAPI JSON](https://nicia.ai/docs/openapi.json)
8. [llms.txt](https://nicia.ai/llms.txt) and [llms-full.txt](https://nicia.ai/llms-full.txt)

## Runnable import sequence

1. Ask the person for the folder to import and for the Brain handle. Use a stable, lowercase, human-meaningful handle for a team Brain, such as `revops` or `support`. Do not derive it from a directory name that may be renamed.
2. Create the Brain from their machine with `PUT https://api.nicia.ai/v1/brains/{handle}`, sending `x-api-key: $MANAGEMENT_KEY`, `x-organization-id: $ORGANIZATION_ID`, and `{"name":"…","mode":"open"}`. Create it `open`. A Brain that stages every write answers nothing on its first day; review gets turned on in step 7, once there is something worth reviewing. Repeat the same request safely after a timeout.
3. Mint one Brain key with `read` and `write` for the import, following [Brain keys](https://nicia.ai/docs/scale/brain-keys/). Each Brain-key secret is returned once. Never write the management credential into a script that lives in the person's repo.
4. Enumerate the source. For a folder, walk it and derive a deterministic id from each file's path relative to the root, so a second run addresses the same document instead of creating a duplicate; skip binaries, lockfiles, and anything already ignored by git. For a hosted source such as Notion, Drive, or Confluence, use that tool's own stable page or file id as the deterministic id, and record the original URL so the Brain can cite where it came from.
5. Add each document with `POST https://api.nicia.ai/v1/brains/{handle}/documents` using `authorization: Bearer $BRAIN_KEY`. Send the file's full text; nothing you send is dropped, and frontmatter round-trips whether or not a schema declares it. An empty document or malformed request fails validation, and no empty input implies deletion.
6. Verify before declaring success. Ask a question the folder can answer with `POST https://api.nicia.ai/v1/brains/{handle}/context`, and confirm the response carries citations and a receipt. Report the cited source back to the person by name so they can check it themselves.
7. Only now offer to turn review on: `PATCH https://api.nicia.ai/v1/brains/{handle}` with `{"mode":"reviewed"}`. Explain what changes, which is nothing about how anyone writes; the same call returns a different `status` and the change waits for a person. Recommend it as soon as an agent nobody on the team wrote starts producing knowledge.
8. Offer to connect the agents the team already uses. Point them at [the sharing guide](https://nicia.ai/docs/team/share-it/) so Claude Code, Codex, or Cursor read this Brain over MCP with a scoped Connection.
9. Optional, and only when the person asks for it: declare a schema so fields they already send become filterable. `PATCH /v1/brains/{handle}` with `{"schema":{"extends":"nicia-core","kinds":[{"name":"company","fields":[{"name":"plan","type":"string"},{"name":"ownerEmail","type":"string"}]}]}}`. Declaring a field is retroactive and never drops data, so this is safe to defer and safe to change later.

## Success checks

- Running the import twice produces the same document count, not double.
- A `POST /context` question returns an answer with at least one citation and a receipt id.
- Nothing in the folder was rewritten, moved, or deleted.

## Report back

Tell the person the Brain handle, the number of documents imported, the one question you verified with, and the exact citation it returned. If anything failed validation, name the file and the error rather than skipping it silently.

Then say the two things they need to decide next. First, that this is a copy until they choose to cut over, and that comparing answers for a week or two is the way to make that call. Second, that their knowledge is never captive: exporting a Brain returns plain markdown with their frontmatter intact, a catalog, a greppable activity log, the full revision history, and an `AGENTS.md` that teaches any agent how to read it. They arrived with a folder; they leave with a model. See [keeping it good](https://nicia.ai/docs/team/tend-it/).