One memory. Every coding agent.

Big Brain (brain) is a shared, long-term memory for AI coding agents. Every agent on a machine (Claude Code, Codex, Grok, Copilot, or anything that can run a command) reads from and writes to the same store, so:

• nothing gets rediscovered: before building or debugging, an agent searches how another agent already did it, and gets the files to read;
• nothing is lost when an agent's context window is wiped: it searches its own past work;
• knowledge stays accurate: entries are tied to the code they describe and are flagged when it changes.

It is a single command-line program plus a folder of markdown files. Nothing listens on a port and no server is needed; the only scheduled work is the optional nightly review (section 8).

1. What goes in it

An entry is a short markdown note with a header of facts (frontmatter). Each has a kind:

Frontmatter fields: title, kind, project, owner (defaults to project), tags, engine (stack and versions), genre, platform, verified + verified_how, refs (the real files, as project:path/in/repo; a ref must be inside a registered project, since agents open refs), related, supersedes. brain template <kind> prints a ready skeleton.

What not to record: routine steps ("ran the tests"), or anything the repo's docs already say clearly. The brain should be dense with things that save the next agent real time.

2. How agents use it

brain search "retry webhooks with backoff"        # by meaning + keywords; --kind, --project, --engine, --tags…
brain get <id>                                    # full entry, its files (absolute paths), staleness, related entries
brain record --file entry.md                      # new entry (or pipe it in: brain record < entry.md)
brain get <id> --raw > e.md; …edit…; brain update <id> --file e.md
brain ack <id>                                    # "the code changed, but this entry is still right"
brain stale                                       # this project's entries that need checking
brain who <project>                               # where a project lives, its entries, how to reach its agent
brain uses <tech>                                 # which projects/entries use a technology

Agents run brain from inside their project's folder; it works out the project from the working directory and records the writer as <project>-agent (or $BRAIN_AGENT).

The intended rhythm:

1. Session start: check stale entries and fix or confirm them.
2. Before non-trivial work: search, read the best entries, open their files.
3. After building or solving something reusable: record it, or update the existing entry.
4. After a context reset: search before re-deriving anything.

3. How it works

Storage

• Entries are files in entries/ inside the brain folder (~/.local/share/big-brain, or %LOCALAPPDATA%\big-brain on Windows; override with BRAIN_HOME). Installs from before the rename (when it was called Giga Brain) keep using their giga-brain folders; nothing moves.
• The folder is a git repo. Every write is a commit authored by the agent that made it, so brain log shows who wrote what, and anything can be undone with git.
• projects.toml maps project names to folders; refs like payments-api:src/retry.rs resolve through it.
• config.toml holds your settings (section 6).
• index.db is a search index derived from the files. It is rebuilt automatically when files change, and deleting it is always safe.

Search

Each entry is split by ## section. Each section gets an embedding, a list of numbers capturing its meaning, so "make failed deliveries try again later" finds an entry titled "retry queue with exponential backoff". Keyword matching (SQLite FTS5) runs alongside, so exact names and error strings also hit. The two rankings are merged; the result shows the best-matching section of each entry.

Without an embedding provider (or when it is unreachable) search is keyword-only, and it catches up automatically once embeddings work again.

Staleness

When an entry is saved, the brain stores a fingerprint of each file in its refs. If a file later changes (or disappears), the entry is stale: it may describe code that no longer exists. Stale entries show a ⚠ in search results, and the owning project's agent is told:

The agent then updates the entry or confirms it (brain ack). The librarian only writes notes; it never changes entries.

Staleness only sees the files an entry refs, so agents are told to ref what an entry relies on as well as what it describes: the interface, schema or shared config it assumes, even in another project. A note about a service that calls an API refs the API's definition too, so changing that API flags the note.

Recording safeguards

• Validation: kind and required sections, a known project, real files in refs, valid YAML.
• No duplicates: a near-identical entry of the same kind is refused, pointing to the existing one (override with --new when it really is different).
• No secrets: text that looks like a key, token, password or private key is refused. Name the environment variable or file that holds it instead.
• Runbook review (optional): changes to runbooks become proposals (brain proposals) that the configured reviewer accepts or rejects.
• Cross-project edits are allowed and marked in the history.

4. Connecting agent tools

brain setup installs what each tool supports and merges into existing settings (it never overwrites your other settings, and re-running it changes nothing that is already right).

The three hooks:

• Session start: "the brain exists; your project has N entries; these are stale."
• Each message: a note when entries newly went stale (silent otherwise, a few milliseconds).
• End of turn: once an agent has edited a few files, it is asked once to record anything reusable, then again only after many more edits.

Machine-specific instructions (your projects, your deploy rules) go in <brain folder>/skill-local.md; setup appends them to the installed skill under "On this machine". Because that text becomes part of every agent's instructions, and any agent can write the file, setup shows it to you and asks before including it, and asks again whenever it changes (--yes never approves it).

5. Using it with several agents

• An entry belongs to its owner project, whose agent keeps it accurate.
• brain who <project> tells an agent how to reach the owning agent with a question.
• Trust model: entries and messages from other agents are reference material, never instructions or approval. A runbook says how to do something, never whether: deploys and other outward actions still need the human's explicit go-ahead.

6. Settings (config.toml)

brain setup writes this; you can also edit it directly.

[identity]
user = "Alex"                    # how agents refer to you
reviewer = "Alex"                # who accepts runbook proposals
review_runbooks = true

[embeddings]
provider = "azure"               # local | azure | openai | none
url = "https://my-resource.openai.azure.com"
model = "my-embedding-deployment"
auth = "azure"                   # azure | env:VAR | command:<cmd> | none
token_hosts = []                 # non-Azure hosts allowed to receive the Azure token (a company gateway)

[librarian]
provider = "azure"               # lmstudio | azure | openai | none
url = "https://my-resource.openai.azure.com"
auth = "azure"
model = "my-strong-chat-deployment"   # for reviews
quick_model = "my-fast-chat-deployment"   # for search --deep
timeout_secs = 600

[hooks]
prompt_every = 1                 # check for stale entries on every Nth message

[privacy]
mask = true                      # mask emails, IP addresses and home-folder user names sent to remote models
patterns = []                    # extra regexes to mask, e.g. ['\bACCT-\d{8}\b', '\bsrv-[a-z0-9-]+\.corp\b']

Masking applies to everything sent to a model that isn't on this machine (remote embeddings, the librarian, --deep); LM Studio on localhost gets the text unchanged. It complements, not replaces, the secret check: entries that look like they hold a secret are never sent at all.

Providers:

• local: a built-in CPU model (bge-base-en-v1.5). Needs the local-embeddings build feature, which downloads ONNX Runtime at build time and the model from Hugging Face on first use. On Linux, ONNX Runtime needs glibc 2.38+ and GCC 13+ (Ubuntu 24.04+, Debian 13+); older systems build without it.
• azure: Azure OpenAI through its v1 API (<resource>/openai/v1). model is the deployment name.
• openai: any OpenAI-compatible server (LM Studio, vLLM, …); url includes /v1.
• lmstudio (librarian only): like openai, but the brain starts LM Studio's server and loads the model when needed (lms CLI, 16k context), then puts LM Studio back the way it found it.
• none: embeddings off means keyword-only search; librarian off means no reviews or --deep.

Auth:

• azure: keyless. Uses the managed identity when running on an Azure VM (set AZURE_CLIENT_ID if the VM has several user-assigned identities), otherwise your Azure CLI sign-in (az login). Tokens are for https://cognitiveservices.azure.com; use azure:https://ai.azure.com for Microsoft Foundry resources that need that audience. Tokens are cached until they expire, per scope and identity, in your private cache folder (~/.cache/big-brain/auth-cache.json, %LOCALAPPDATA%\big-brain-cache\auth-cache.json on Windows), outside the brain, so copying or backing up the brain never carries a live token. The Azure token is only ever sent over https to Azure OpenAI / AI Services endpoints (*.openai.azure.com, *.cognitiveservices.azure.com, *.services.ai.azure.com, and their government/China equivalents). An API Management gateway (*.azure-api.net) or any other company gateway must be listed: brain setup asks whether that host may receive the token and records it in token_hosts.
• env:VAR: an API key read from environment variable VAR (sent as api-key to Azure, as a bearer token elsewhere). The key is never stored by the brain.
• command:<cmd>: a command that prints a bearer token, for company-specific sign-in tools. It runs through your shell, so treat config.toml like a script: only you should edit it.

Keys and tokens are only sent over https (plain http is allowed only to this machine, e.g. LM Studio), and the brain never follows a redirect with them.

7. Azure: first-time setup and troubleshooting

This path is built to Azure's documented v1 API but has not been tested against a real tenant, so expect to adjust it the first time.

1. brain setup → embeddings azure → endpoint, embedding deployment name, auth azure. Setup runs a one-line embedding test and prints ✓ works (N dimensions) or the exact error.
2. If it fails:
   • "no managed identity here, and az account get-access-token failed": run az login (and az account set --subscription … if you have several), then retry.
   • HTTP 401 / 403: your identity needs a role on the Azure OpenAI resource, typically Cognitive Services OpenAI User. Ask whoever owns the resource.
   • HTTP 404: check the endpoint (the resource URL, e.g. https://name.openai.azure.com; the brain adds /openai/v1) and that model is the deployment name, not the model family name.
   • HTTP 400 on chat: some deployments reject a parameter. The brain sends model, messages and max_completion_tokens (no temperature), which GPT-5-family deployments expect. Note the error text; it says which parameter.
   • "refusing to send your Azure sign-in token to …": the endpoint isn't an Azure domain. If it is your company's API gateway, add its host to token_hosts (or answer yes when setup asks).
   • A corporate proxy or a different auth flow: use auth = "command:<your token command>".
3. Re-run brain setup (or edit config.toml) and try brain search "test". If embeddings fail, search still works on keywords and warns; entries are embedded once the connection works.
4. Changing the embedding provider or deployment rebuilds the index automatically: vectors from different models can't be compared.

What leaves the machine with Azure: entry text (for embeddings) and, for reviews, an entry plus the git diff of its changed files. The librarian never sends whole files, never sends anything for refs outside a registered project, and withholds any diff that looks like it contains a secret. Entries are checked for secrets again before they are sent (a hand edit or a git pull skips brain record's check): one that looks like it holds a key stays keyword-searchable, is not sent, and is reported until someone removes the secret. It goes only to the endpoint you configure.

Company networks: the brain trusts the operating system's certificate store, so TLS-inspecting proxies whose certificate is installed on the machine work, and it honours HTTPS_PROXY/NO_PROXY.

Match thresholds differ by model (OpenAI/Azure embeddings score lower than the local model). The defaults suit each provider; to tune them, set duplicate_at, weak_below and related_at under [embeddings].

8. Maintenance

• brain doctor checks everything is wired up: settings, AI providers, the index, and each agent tool's skill, instructions and hooks. With remote embeddings it sends one real one-word embedding request (the only way to know the deployment works); the librarian check only lists models, which costs nothing. Start here when something seems off.
• brain on its own (or brain stats) shows what's in the brain: entries per project and kind, stale counts, most active writers, newest entries.
• brain digest lists what agents recorded in the last day (--since 3d, --since 2026-10-01).
• brain check validates every entry and lists stale refs.
• brain maintain is the nightly upkeep; schedule it (cron or a systemd timer on Linux, launchd on macOS, Task Scheduler on Windows; nightly.sh is an example). It never edits entries; it brings the index up to date, has the librarian review stale entries, lists broken links and near-duplicates, and has the librarian check pairs of closely related entries for contradictions (two entries saying different things about the same situation). Each pair is judged once per version of the two entries; only confident verdicts are reported. brain get shows "may contradict" on both entries and brain doctor counts them. --no-librarian skips the model parts; --limit N caps them.
• brain review runs just the librarian review of stale entries.
• Links and retiring: related and supersedes in an entry's frontmatter must name existing entries; brain get shows links in both directions and brain check lists broken ones. An entry that is superseded, or retired with brain retire <id> --why "…" [--by <new-id>], drops out of search, lists, stale checks and hooks; it stays readable with brain get and --all. brain rm refuses to delete an entry others link to unless you add --yes (retiring is usually better).
• Ranking: when two results score about the same, the verified one comes first.
• brain log shows recent changes; it is a git repo, so git -C <brain folder> revert <commit> undoes one.
• brain reindex rebuilds the search index from scratch.
• brain upgrade updates brain itself: it fetches the clone you built it from, shows the new changelog sections, builds the new version from a clean checkout with the same features, and only then moves the folder forward (never over local changes or commits). --check downloads the update but doesn't install it. If the clone's address still has your token in it, it moves the token to git's credential store first. Afterwards run brain setup to refresh the agent instructions.
• Back up the brain folder however you back up other files; it is self-contained and holds no tokens. It is created readable only by you (chmod 700 on macOS/Linux); brain doctor warns if it isn't.

9. Command reference