Agent Brain

Agent Brain is a local-first, review-gated knowledge runtime for coding agents. It keeps reusable knowledge in ordinary files and Git repositories while separating reviewed facts from unreviewed candidates.

The alpha release is intentionally small: one dependency-free Python CLI, one local pack created by default, explicit promotion and deprecation, semantic federation locks, adapter fingerprints, and a fail-closed session preflight.

Alpha software. Back up important data and inspect commands before adopting it in a production workflow.

简体中文

Why it exists

Long agent sessions accumulate decisions, corrections, and procedures. Copying all of that into every prompt creates noise; silently treating every note as truth creates risk. Agent Brain provides a narrow lifecycle:

candidate -> inbox -> explicit review -> accepted -> active index
                                      \-> rejected (negative sample)
accepted -> explicit deprecation -> deprecated (preserved, inactive)

Only accepted/ content is an active knowledge source. inbox/, rejected/, and deprecated/ remain outside the active read path.

Requirements

• Python 3.11 or newer
• Git
• A local filesystem that supports atomic rename

The runtime has no third-party Python dependencies.

Install from a release checkout

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
brain --help

Create a brain

Choose a new path that does not exist:

brain init --root "$HOME/my-agent-brain" --reviewer example-maintainer
export BRAIN_ROOT="$HOME/my-agent-brain"
brain lint

init creates brain-core plus a brain-general Git repository. The general pack is local-only: it has no remote and receives a blocking pre-push hook. Initialization does not create a commit or configure a remote.

Add the generated adapter file from brain-core/adapters/generated/ to the matching agent configuration location, or adapt its generic instructions to your own tool.

Daily flow

At session start:

brain preflight

Preflight validates the semantic lock and refreshes only the short-lived session marker. It never accepts drift. When an intentional pack commit changes the lock input, run the explicit reconciliation command:

brain session-check

Place a candidate in the matching inbox/*-candidates/ directory, then run:

brain dedupe-check /absolute/path/to/candidate.md
brain review accept /absolute/path/to/candidate.md
brain index
brain sync

The reviewer recorded in MANIFEST.yaml is written into accepted frontmatter. Review is a local policy gate, not identity verification or cryptographic approval.

Commands

The public surface is:

• init, sync, lint, preflight, session-check
• index, adapter-build
• review, dedupe-check, deprecate, stale

See command contracts, the configuration grammar, and the privacy and threat model.

Non-goals

Agent Brain does not provide cloud sync, encryption, authentication, autonomous fact verification, prompt-injection isolation, semantic vector search, or multi-user authorization. A local-only hook is defense in depth, not a substitute for careful remote configuration and filesystem permissions.

Development

python -m unittest discover -s tests -v
python scripts/public_release_gate.py --repo .

The maintainer's release process adds private deny rules outside the repository and scans the worktree, staged snapshot, reachable Git history, and Git metadata before publication.

License

Apache License 2.0. See LICENSE.