agent-brain docs

Getting started

Install

agent-brain ships as a prebuilt binary. You do not need Go. It runs on Linux, macOS and Windows, on amd64 or arm64.

macOS and Linux

curl -fsSL https://agentbrain.wecansync.com/install.sh | sh

Windows PowerShell

irm https://agentbrain.wecansync.com/install.ps1 | iex

What the installer does

Downloads the prebuilt binary for your OS and CPU from https://agentbrain.wecansync.com/releases/.
Checks its SHA-256 against the release's checksums.txt.
Installs it to ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\agent-brain).
Runs agent-brain install to integrate the assistants it finds. This step asks before changing anything unless AGENT_BRAIN_YES=1 is set.

Installer options

The installer reads environment variables. On Windows, set them with $env:NAME="value" before running irm.

Variable	Effect
`AGENT_BRAIN_VERSION=0.4.0`	Pins a version instead of the latest.
`AGENT_BRAIN_BIN_DIR=DIR`	Picks the install folder.
`AGENT_BRAIN_NO_INTEGRATE=1`	Installs the binary only. Skips `agent-brain install`.
`AGENT_BRAIN_YES=1`	Answers yes to prompts.

Manual download

https://agentbrain.wecansync.com/releases/latest.json names the current version and its files. Archives live at /releases/<version>/agent-brain_<os>_<arch>.tar.gz (.zip on Windows), with checksums.txt alongside. os is linux, darwin or windows. arch is amd64 or arm64.

OS	CPU	File	SHA-256
Loading the file list from latest.json. Without JavaScript, use the pattern above: `/releases/<version>/agent-brain_<os>_<arch>.tar.gz`.

From source

Building from source needs Go 1.25 or newer.

git clone https://github.com/ebrahim5801/agent-brain-cli.git && cd agent-brain-cli && ./install.sh

Or, with Go installed:

go install github.com/ebrahim5801/agent-brain-cli/cmd/agent-brain@latest
agent-brain install

Getting started

Verify

Check the integration and collection state:

agent-brain status

You get one line per assistant showing whether it is detected and integrated. The output also shows the database location and the last captured event. Run an assistant session, check again, and the last-event time should move.

agent-brain install detects every supported assistant and integrates each one. To limit it to some assistants, pass --assistant once for each one:

agent-brain install --assistant claude-code --assistant cursor

The names are claude-code (Claude Code), cursor (Cursor), copilot-cli (GitHub Copilot CLI), gemini-cli (Gemini CLI), opencode (OpenCode) and codex (Codex CLI). agent-brain uninstall takes the same --assistant option. Existing settings are kept, a timestamped backup is written first, no file inside a repository is touched, and running the command again is safe.

Codex CLI

Codex needs its hooks trusted once. See Troubleshooting.

Usage

Stats

Collection and agent-brain stats are free, local and offline, and need no account. Every session is captured automatically and attributed to its project, with no configuration.

agent-brain stats

Token usage and cost for the current week, grouped by project. Add flags to change the view.

agent-brain stats --daily

Groups by day.

agent-brain stats --weekly

Groups by week.

agent-brain stats --sessions

Lists individual sessions with their summaries.

agent-brain stats --session ID

Lists only the session with this id. The short id prefix works.

agent-brain stats --project NAME

Filters to one project by name.

agent-brain stats --since YYYY-MM-DD

Starts from this date. The default is the start of the current week.

agent-brain stats --json

Machine-readable output.

agent-brain stats --prompts

Also prints each sub-session's full spawn prompt. These are stored locally and never synced.

Where an assistant reports token counts, agent-brain records them. Where it does not, the count is recorded as absent rather than estimated.

Pro

Memory (Pro)

Assistants forget everything between sessions. agent-brain gives them an MCP server with two tools, memory_search and memory_save, plus a session-start hook that injects the most relevant entries. Memory needs a Pro account (agent-brain login) or membership in a paying team's project.

Entries are typed as decision, convention, task_state or fact. Each one records the git state it was captured at. Ranking flags stale entries rather than trusting them silently.

Turn memory on or off

agent-brain memory enable

Turns on personal memory, or re-enables it for this project.

agent-brain memory disable

Turns memory off for this project. Add --all to turn it off everywhere.

agent-brain memory pause

Stops contributing this project's memory. Serving continues.

agent-brain memory resume

Resumes contributing this project's memory.

Inspect and edit entries

agent-brain memory list

Lists this project's memory entries.

agent-brain memory show ID

Shows one entry in full.

agent-brain memory edit ID

Edits an entry's content in $EDITOR, or pass --content.

agent-brain memory priority ID critical|normal|background

Reclassifies how hard an entry competes for the session-start memory budget.

agent-brain memory delete ID

Permanently deletes an entry.

agent-brain memory restore ID

Re-activates a superseded or deleted entry.

agent-brain memory wipe

Deletes all memory for this project. Each entry can still be restored.

Capture settings

agent-brain asks the assistant to save memory at three points:

after 10 tool calls of work since the last save, not after every reply;
with a mid-task checkpoint every 25 tool calls;
before the context is compacted.

agent-brain memory capture

Shows the current settings.

agent-brain memory capture --every N

Changes the first trigger. 0 turns end-of-reply saves off. 1 means every reply that used a tool.

agent-brain memory capture --checkpoint N

Changes the mid-task checkpoint. 0 turns it off.

agent-brain memory capture --reset

Restores the defaults.

Optional

Cloud dashboard and team memory

The CLI works fully offline. The cloud dashboard is optional. Nothing is sent until you complete all three steps:

agent-brain login                  # once per machine; approve in the browser
agent-brain link <project-key>     # once per project, inside its directory
# the first link asks for consent to send usage numbers

Create the project on the web dashboard first to get its key. After linking, a background service syncs usage numbers. Only numbers are sent: timestamps, durations, token counts, model IDs and activity counts. Prompts, code, file paths and repository names stay on your machine.

agent-brain login

Signs in to the agent-brain platform. Add --no-browser to print the approval URL instead of opening a browser.

agent-brain link <project-key>

Connects this project directory to a cloud project. Add --force to rebind a directory that is linked to a different project. --auto finds or creates a personal project named after the directory.

agent-brain consent

Shows or changes what agent-brain may send to the cloud.

agent-brain sync

Syncs queued sessions to the cloud now.

agent-brain unlink

Stops syncing this project directory. Local collection continues.

agent-brain logout

Signs out this machine, revokes its token and stops syncing. Local data is kept.

Team memory

Team memory syncs to the agent-brain cloud service, under a separate per-project consent. To share an org project's memory with the team, run agent-brain memory share. Use agent-brain memory pause and agent-brain memory resume to stop and restart contributing. Entries can also be marked personal-only so they are never shared.

Advanced

Storage backends

The local store uses SQLite by default (Basic). agent-brain storage inspects the backend and can switch it. Advanced uses PostgreSQL.

agent-brain storage

Inspects the local storage backend and can switch it.

For the tables the client creates and how long each one is kept, see Privacy and data retention.

Maintenance

Updating

agent-brain updates itself in the background by default. You can also run the commands yourself:

agent-brain update

Fetches the latest release and replaces the binary.

agent-brain update --check

Reports whether an update is available, then exits.

agent-brain update --auto on|notify|off

Sets automatic-update mode.

Maintenance

Uninstall

agent-brain uninstall removes the assistant integrations and keeps your local data. Pass --purge-data to remove the data too. Then delete the binary.

agent-brain uninstall                # removes integrations, keeps your data
agent-brain uninstall --purge-data   # also removes the local data

Data

Privacy and data retention

Everything is stored in a local SQLite database you own. Nothing leaves your machine unless you link a project and grant consent. The wire package defines every struct that can be serialized to the network. A guard test fails the build if a field for a local path, git remote, project name, hostname or message text appears there. A second guard test fails the build if memory content reaches a transport package.

Every local table is listed in the retention matrix, and a test fails the build if a migration adds a table that is not documented there. The main tables are:

Table	Contents	Retention
`sessions`	Local session records awaiting or after sync	Kept locally until you clear it
`events`	Local per-session event counters	Kept locally until you clear it
`projects`	Local project link state	Kept locally until unlinked
`memories`	Local personal memory store	Kept locally until you delete it
`memory_usage_events`	Retrieval and citation counters. Syncs identifiers and counts only, never memory content	Kept locally until you clear it
`session_model_usage`	Per-session token totals split by model	Kept locally until you clear it
`team_memories`	Read-through cache of the team pool	Disposable cache, repopulated from the server

The full table, with legal basis for each row, is in docs/compliance/retention.md.

To report a security issue, follow SECURITY.md. Do not open a public issue.

Help

Troubleshooting

Start with status

Run agent-brain status. It reports integration health and collection activity, one line per assistant.

agent-brain status

Codex records nothing

Codex will not run a hook until you approve it. Until you do, Codex records nothing and reports no error. After agent-brain install, open codex, run /hooks, and trust the agent-brain entries. agent-brain status shows the same reminder.

Help

FAQ

Does agent-brain read my code or my prompts?

No. What can sync, and only after you opt in, is numbers: timestamps, durations, token counts, model IDs and activity counts. The wire protocol has no fields for prompts, code, file contents, file paths or repository names.

How is memory different from what the assistant keeps?

Memory is text the assistant distills at the end of a session: decisions, conventions and unfinished work. It is stored locally and served back at the start of the next session. Personal memory has no network transport. Team memory is the only case where memory text leaves a machine, and it needs its own consent.

Are the token numbers accurate?

Where an assistant reports token usage (Claude Code and Gemini CLI, per the FAQ), you get full counts. Where it does not (Cursor reports only the model), agent-brain records the count as absent rather than estimating it.

Do I need an account?

No, for collection and agent-brain stats. Memory needs a Pro account or team membership, and the cloud dashboard is optional.

Does it slow my assistant down?

The capture path writes to a local SQLite database and has no network capability. Cloud sync runs in a separate background service.

Can I keep a project out of sync?

Yes. A project you never link transmits nothing. agent-brain memory disable turns memory off for one project, or everywhere with --all. On team projects, agent-brain memory pause stops contributing while you keep receiving.

Can I self-host it?

The CLI in this repository is entirely local. It needs no server and works fully offline. Cloud sync is optional. The hosted backend is a separate, closed-source product.