Skip to content

About

🧠 The memory layer for your Git repository. Turn retained agent sessions, checkpoint history, docs, code structure, and durable facts into something you and your coding agents can actually query.

Resources

Code of conduct

Contributing

Security policy

Stars

101 stars

Watchers

0 watching

Forks

Latest commit

 

History

2,963 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

entire-brain theme

Entire Brain

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.

What to ask

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.

Features

  • 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.

Install

# 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 graph

The 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.sh

Builds 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.

Transcript storage and version compatibility

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.

How Brain compares

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.

Activate it for your agent

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 setup

By 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.md and CLAUDE.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.

Brain without fact extraction

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-daemon

Configured remote history sources and hosted memories sync also use the network; see privacy and egress for controls.

Background maintenance and memory sync

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.

Usage Examples

Check what the brain knows

# 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

Record and retrieve facts (episodic memory)

# 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 verify

remember 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 operation

Both 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.

Remember something that is not about one repository

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> --global

Global 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.

Search

# 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]'

Read documents that are not code

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 file

Extraction 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.

Navigate the code semantically

# 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

Build a task packet for an agent

# A bounded context packet scoped to one task.
entire brain brief "add rate limiting to the upload endpoint"

Explore the brain interactively

entire brain dash   # TUI: status, facts, sessions, history, semantic
entire brain viz    # offline graph in your browser

entire brain viz — a walkthrough of the five sections of a brain

viz 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.

Notify another service when the brain changes

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.refreshed

Events 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.

Recover from a split brain

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>

Stored memory and freshness

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.

Command reference

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)

Limitations

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.

Documentation

Please report problems in GitHub Issues or open a pull request.

License

Entire Brain is distributed under the MIT License.

About

🧠 The memory layer for your Git repository. Turn retained agent sessions, checkpoint history, docs, code structure, and durable facts into something you and your coding agents can actually query.

Resources

Code of conduct

Contributing

Security policy

Stars

101 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

⌂