Every developer builds on what came before: code written, ideas discussed, lessons learned, decisions made, feedback received, and failures understood. Our agents are trained on the world’s knowledge, but they lack the memory of how our projects got here. Entire Brain brings that experience forward, giving agents the context they need to start informed and build on prior work.
Entire Brain combines captured agent sessions and checkpoints with durable facts, documentation, and code understanding from Entire Graph. Graph maps how the code fits together; Brain connects that structure to why it exists, what happened before, and how to approach similar work.
Through the CLI, agents can retrieve earlier decisions, revisit past attempts and their outcomes, assemble context for a task, and turn reviewed lessons into reusable skills. Knowledge stays linked to its supporting evidence, so it can be checked, revised, and applied as the project evolves.
Ask your coding agent in plain language.
| Goal | Example prompt |
|---|---|
| Start a task | What should I know before changing the retry policy? |
| Recover a past decision | Why did we remove the queue abstraction? |
| Find what we already know | What do we know about retry limits? |
| Search past sessions and docs | Where did we discuss backpressure? |
| Understand the project | Summarize this project's structure and conventions. |
| Check saved facts | Check whether the sources for our saved facts still match the repository. |
| Inspect memory health | Which sources are missing or out of date? |
Directly: entire brain brief "<task>" to start a task, recall "<question>" for
decisions and saved facts, query "<text>" for prose search across sessions, docs
and history, overview for the project, verify to re-check fact sources, and
status for memory health.
Facts are stored per branch. recall on a branch that has no facts prints
nothing and adds a note that every captured session is already distilled — which
reads as "the brain does not know", not "you are on the wrong branch"; pass
--branch main (or the branch the work happened on) before concluding anything.
- Give an agent relevant decisions, code locations, and suggested tests before it starts a task.
- Save project facts by hand or extract them from past sessions, then check their source references against the repository.
- Search facts, history, documentation, and conversations by keyword or meaning.
- Find code, inspect the impact of a change, and investigate regressions with Entire Graph.
- Connect agents through the CLI, with response size limits and repository instructions.
- Browse saved knowledge in a terminal dashboard or an offline graph view.
- Record facts globally, not just per repository, so a preference or team convention applies everywhere.
- Read the documents that are not code: PDFs, Word, Excel and PowerPoint files under
docs/. - Notify CI, a chat channel, or an index with signed webhooks when the brain changes.
- Brain reads sessions captured by Entire CLI and uses Entire Graph for code analysis. Without captured sessions, Brain builds from code, docs, and Git history.
- Graph is required for code analysis, but you can use Brain to search sessions, docs, and facts without it.
# Entire CLI — captures the agent sessions Brain learns from.
curl -fsSL https://entire.io/install.sh | bash
# Brain.
curl -fsSL https://raw.githubusercontent.com/entireio/entire-brain/main/scripts/get-brain.sh | bash
# Graph — the code analysis Brain builds on.
entire plugin install graphThe script downloads a prebuilt binary for your platform, checks it against the
release checksums, and registers it with the CLI as the entire brain plugin.
There is nothing to compile. Pin a release with --version vX.Y.Z, take the
current prerelease with --nightly, or install somewhere other than
~/.local/bin with --dir.
Without Graph, setup reports the semantic index as unavailable; sessions, docs
and facts still work. Without the CLI there are no sessions to read, and Brain
falls back to code, docs and Git history.
Building from source
Needs Go 1.27.3+, Git 2.36+, the Entire CLI on PATH, and a C compiler for
Graph's tree-sitter bindings.
git clone https://github.com/entireio/entire-brain.git
cd entire-brain
./scripts/install.shBuilds and registers Brain and Graph. It does not initialize a repository's memory or install the watcher.
The clone is itself a git repository, and setup acts on the repository you
run it in. Go back to your own project's directory before you run
entire brain setup, or pass the project's path as an argument.
See installation options for choosing a Graph checkout, installing offline, or building Brain alone.
The storage change introduced in #392 makes persistent brains read transcripts from local Git checkpoint refs instead of keeping exported transcript files. Existing file-based brains and standalone bundles remain readable. On the next persistent session refresh, Brain verifies that legacy cached transcripts can be recovered from local checkpoints before removing them. If recovery cannot be proven, refresh fails and retains the cache.
| Scenario | Compatibility |
|---|---|
| Upgrade an existing file-based brain | Supported; migration checks recovery before deleting cached transcripts. |
| Read a materialized bundle with an older binary | Supported when the older binary supports the bundle's schema. |
| Run an older binary against a migrated persistent brain | Not supported. Current memory and manifest schemas require the upgraded binary. |
Upgrade and restart all Brain CLI and watcher processes that share a brain before migrating it. Installing or upgrading Graph does not upgrade Brain.
Local memory migration is one-way. A post-migration bundle is not a downgrade format. To use an older release, restore a complete pre-migration backup into a separate environment. That backup does not include later writes. See memory storage compatibility before upgrading.
docs/feature-matrix.md — 51 capabilities against five
alternatives, including the 18 rows where neither Graph nor Brain answers Yes.
Our columns are read from the binaries; the competitor columns are not.
Every number we publish, how to reproduce it, and what we deliberately do not claim: benchmarks.
For Claude capture, follow the capture requirements.
Brain is set up per repository. Start in a local Git repository with at least one commit:
entire brain setupBy default, setup indexes the repository, extracts facts from up to 25 past sessions in the background, installs a watcher to keep the memory updated, and installs the agent instructions. The watcher runs as a persistent service on macOS and Linux with systemd.
The agent instructions live in these files, created or updated by setup:
.entire/agent-guide.md: the agent instructions. Rerunning setup replaces this file.AGENTS.mdandCLAUDE.md: references to the guide inside managed blocks. Your text outside those blocks is preserved.
The guide is assembled from whichever products have been activated, and each
product activates itself. entire brain setup on its own writes a
Brain-only guide containing no Graph instructions at all — installing Graph does
not change that, because activation is recorded in the guide rather than probed.
Run entire graph setup too if you want both.
The two setups compose in either order. The guide text is mirrored between the two products, so both render the same combined guide; each run only adds its own product to the recorded activation.
Review the generated files and commit them together when the instructions should apply to your team. Restart your agent or reload its repository instructions so it picks up the guide.
See the agent integration guide and coordination contract for more setup details.
Extracting facts uses an available agent CLI and can send session content to its model provider and incur token charges. Without an agent CLI, this step is skipped.
To build without fact extraction or a background service, use:
entire brain setup --no-backfill --no-daemonConfigured remote history sources and hosted memories sync also use the network; see privacy and egress for controls.
The watcher updates local repository context and runs distillation within the configured budget. For connected repositories, Brain syncs after a post-commit checkpoint notification and after distillation saves its results. Existing push notifications and manual sync remain supported. The watcher does not upload or pull memories on idle ticks. Brain no longer processes session-end notifications.
Sync sends new or changed record versions and saves server acknowledgements locally. Overlapping uploads use one process lock; successful batches do not need another upload. Failed or interrupted uploads remain eligible for the next sync event. Original session, checkpoint, and commit references remain unchanged.
# One-line health and coverage summary.
entire brain status
# The full picture: sources, freshness, blind spots.
entire brain status --verbose
# What is this project? Stack, boundaries, commands, recent decisions.
entire brain overview# Author a durable fact about this repository.
entire brain remember "Retries are capped at 3; the 4th failure must page."
# Retrieve facts for the current branch (--branch <name> for another).
entire brain recall "retry policy"
# Re-check every fact's anchors against the current tree.
entire brain verifyremember infers where the fact belongs using a coding agent on PATH. Without
one, pass it yourself: --path constraints.retry.policy, shaped
category.subcategory.type, from architecture, constraints, preferences,
project, workflow. Segments use lowercase letters, digits and _; a hyphen
is rejected.
verify reports hand-written facts as unverifiable-here — they have no source
anchor in the repository. Expected, not a failure.
Memory access uses one repository API and one facts/store.json file (schema 3).
Memories are visible across branches. Migration combines copies with the same ID
and retains provenance and lifecycle state. Brainstore's per-record wire format
remains unchanged.
Normal writes and refreshes migrate legacy stores automatically. Verified
redundant facts/.legacy-* files are then removed automatically, including copies
retained by v0.5.0. Watcher maintenance also runs when repository contents have not
changed. No migration or cleanup command is required for normal operation.
Cleanup preserves unknown files and records whose preservation cannot be proved. Large-file verification runs outside the write lock; a concurrent change defers removal until another pass. Interrupted cleanup resumes automatically. Background pause settings remain effective, and ordinary reads never migrate or clean up.
Storage diagnostics are available when needed:
entire brain memories storage status --json
entire brain memories storage migrate # optional diagnostic/retry operationBoth commands accept --global. Status includes cleanup state, pending
legacy directories, retained reasons, and recorded reclaimed bytes. A crash after
removal can make the byte count an underestimate; it does not authorize deletion.
Local migration is one-way. Stable v0.2.0, v0.3.0, and v0.4.0 cannot read the migrated directory. Older and newer clients can exchange hosted memories through separate local stores. Returning to an older version requires a complete pre-migration backup in a separate environment; later writes are not in that backup. Do not share a migrated local directory with older clients.
Run bash scripts/test-memory-storage-compat.sh for released-binary checks.
The script builds pinned stable releases v0.2.0, v0.3.0, v0.4.0, and v0.5.0.
Nightly releases are excluded. Tests use temporary repositories and isolated
stores. They do not change your installed plugin or your memories.
See compatibility coverage for test scope.
Most facts belong to a codebase. Some — a preference, a team convention, where the staging cluster lives — are true in every repository you work in, and had nowhere to live but one repo's brain.
entire brain remember "The staging cluster is in eu-west-1." --global
entire brain facts global # everything recorded globally
entire brain facts retract <id> --globalGlobal facts are recalled from every repository on the machine that recorded
them and labelled (global) when they surface, so a general convention is never
mistaken for something this codebase declared. memories sync does not upload
them, so another machine does not see them. --no-global, or
ENTIRE_BRAIN_NO_GLOBAL_FACTS=1, leaves them out.
Running remember outside a checkout records the fact globally instead of
failing — which is usually where you are when the thing you want to write down
is not about one repo.
# BM25 lexical ranking across facts, history, and docs.
entire brain query "why did we drop the queue abstraction"Semantic (embedding) retrieval was removed: a 1,748-run agent eval measured
BM25 lexical ranking matching or beating the embedder stack end-to-end while
cutting agent tokens 18-28%, query memory 96%, and 31 MB off the binary (see
docs/eval_ledger.md and trail #278). --keyword is accepted for
compatibility (it is the only mode); --semantic and vsearch run the same
BM25 ranking and print a stderr notice.
Supply the query text positionally or with --query; flags can appear before or after it:
entire brain query --keyword --query "RetryPolicy"Supplying both a positional query and --query is an error.
The same forms work with entire brain workspace query <workspace>.
query also takes --source (all | fact | history | doc | conversation) to narrow the corpus, and --json for machine-readable output:
entire brain query "auth middleware" --source fact --json | jq '.results[0]'A design doc written in Word, a spec that arrived as a PDF, a requirements
matrix in a spreadsheet — put them in docs/ and refresh reads them into the
brain alongside markdown, so they come back from search and brief like
anything else.
entire brain docs extract docs/spec.pdf # what it will get out of one fileExtraction is deterministic and local: no model, no network, no external tools, no OCR. A scanned PDF has no text layer, and Brain says so rather than indexing an empty document:
docs/scanned-form.pdf: the PDF has no text layer
(it is probably a scan; OCR is out of scope for this build)
Fact text from documents is indexed as-is; see documents for what is read from each format and what is left out.
# What does changing this symbol affect?
entire brain inspect impact --symbol ValidateToken
# What is unreachable?
entire brain inspect dead-code --json
# What changed since the brain was last indexed?
entire brain inspect changes# A bounded context packet scoped to one task.
entire brain brief "add rate limiting to the upload endpoint"entire brain dash # TUI: status, facts, sessions, history, semantic
entire brain viz # offline graph in your browserviz opens the whole brain as one graph and lets you walk into each part of it:
semantic (functions, types and calls), facts (decisions, gotchas and
rules), sessions (agents, turns and work), history (commits and
checkpoints) and docs (seed, guides and context). The recording above is a
real brain — 20,478 symbols, 807,186 history records, 2,375 sessions — and it
runs entirely on your machine: no network, no model calls, read-only.
Point Brain at an HTTP endpoint and it posts a small JSON event when a fact is recorded or retracted, or the brain is refreshed — so a CI job, a chat channel, or an index can react without polling.
export ENTIRE_BRAIN_WEBHOOK_URL=https://hooks.example.com/entire
export ENTIRE_BRAIN_WEBHOOK_SECRET=a-long-random-string
entire brain webhook test # prove the endpoint works
entire brain webhook events # fact.recorded, fact.retracted, brain.refreshedEvents carry the fact's id, kind, and taxonomy paths — not its text, unless you
set ENTIRE_BRAIN_WEBHOOK_INCLUDE_TEXT=1. With a secret set, each POST is
signed with HMAC-SHA256 in X-Entire-Signature-256. Unset the URL and nothing
is sent. See webhooks.
A repository reached through two different paths — a symlink, or /tmp on
macOS — could once end up with two brains and then refuse every repo-scoped
command. Keys are now derived from the resolved directory, so new splits
cannot happen; if you have an existing one:
# List every store this repository resolves to.
entire brain repo-identity
# Keep one and retire the others (renamed to a dated sibling, never deleted).
entire brain repo-identity --keep <repo-key>Brain's code index can fall behind your working tree. The watcher updates it automatically; run entire brain refresh to update it manually. Graph's interactive queries normally read the current working tree directly.
Run entire brain verify to check whether a fact's source references still match the repository.
entire brain path prints where this repository's memory is stored. See storage and configuration to change storage locations or search settings.
To stop and remove the watcher, run entire brain setup --uninstall-daemon. See operations for service management.
Every command entire brain --help lists, in the groups it lists them in. Run
any of them with --help for its flags; docs/reference.md has the long form.
A command that is visible here but missing from this table fails
TestEveryVisibleCommandIsDocumented, so this list cannot quietly fall behind
the binary.
Set up the brain and agents
| Command | What it does |
|---|---|
entire brain setup |
Build the brain and start background updates |
entire brain add |
Clone a repository, fetch its Entire history, and build its brain |
entire brain agent-guide |
Preview repository-specific agent instructions |
entire brain webhook |
Notify another service when this brain changes |
entire brain config |
Inspect or initialize plugin configuration |
entire brain connect |
Bind this repository to its hosted brain explicitly |
entire brain disconnect |
Stop syncing this repository with its hosted brain |
Search and explore
| Command | What it does |
|---|---|
entire brain overview |
Summarize the project, its structure, and decisions |
entire brain brief |
Gather relevant context for a task |
entire brain query |
Search the brain (BM25 lexical) |
entire brain get |
Fetch a brain item by ID |
entire brain multi-get |
Fetch several brain items by ID in one call |
entire brain dash |
Browse the brain in an interactive dashboard |
entire brain show |
Show one semantic brain record |
entire brain inspect |
Explore code, dependencies, and change history |
entire brain entities |
Find checkpoints and sessions that changed a symbol |
entire brain viz |
Explore the brain as a graph in your browser |
entire brain docs |
Inspect how non-code documents are read into the brain |
Durable facts and patterns
| Command | What it does |
|---|---|
entire brain remember |
Record a durable fact about this repository |
entire brain recall |
Retrieve durable facts for the current branch |
entire brain distill |
Extract durable facts from sessions (requires an agent) |
entire brain facts |
Inspect, retract, and garbage-collect durable facts |
entire brain verify |
Verify durable fact anchors against local retained sources |
entire brain patterns |
Inspect and rebuild recurring patterns from sessions |
State, maintenance and troubleshooting
| Command | What it does |
|---|---|
entire brain status |
Show brain coverage, freshness, and workspace state |
entire brain stats |
Show brain record counts and breakdowns, by branch, agent and source |
entire brain doctor |
Report what is wrong and the command that fixes it (--verbose for the full report) |
entire brain capabilities |
List supported features and retrieval sources |
entire brain version |
Print plugin version |
entire brain path |
Print the persistent brain path for a repo path or URL |
entire brain refresh |
Create or refresh the repository brain |
entire brain watch |
Keep the brain up to date automatically |
entire brain memory |
Manage conversation indexing and background jobs |
entire brain repair |
Rebuild derived semantic indexes |
entire brain stop |
Pause background brain work on this machine |
entire brain start |
Resume background brain work paused by stop |
entire brain gc |
Prune old local semantic overlays and snapshots |
entire brain reset |
Remove local generated brain data |
entire brain repo-identity |
Find and resolve conflicting brain stores |
Workspaces and sharing
| Command | What it does |
|---|---|
entire brain workspace |
Manage local multi-repo brain workspaces |
entire brain bundle |
Import or export local brain bundles |
entire brain memories sync |
Sync repository memories with the hosted memory set (opt-in) |
Facts extracted by a model can be wrong. Check the linked sources before relying on them. brain verify checks source references, not whether a conclusion is correct.
Code analysis inherits Graph's limitations: dynamic calls can go unresolved, and parsing support varies by language.
The historical scale benchmark measured a 1.2 GB index and roughly 12-second median code search on one 4.8M-line repository. Those runs do not establish a scaling law or performance at 100M lines. See scale for the measurements, their limits, and the command to benchmark a current build.
Search support varies by build and source. Check entire brain capabilities for available retrieval modes and the conversation recall documentation for experimental features.
See the recall threat model for how Brain handles untrusted session content and retained secrets.
- Complete reference
- Installation and operations
- Agent activation and coordination
- Semantic features
- Storage and configuration
- Benchmarks: what we measure, what we found, what we do not claim
- Scale: index size and query latency, measured
- Global facts
- Documents (PDF, Word, Excel, PowerPoint)
- Privacy and egress
- Webhooks
- Conversation recall and source citations
- Contributing and build options
- Contributor concepts and data flow
- Release readiness
Please report problems in GitHub Issues or open a pull request.
Entire Brain is distributed under the MIT License.