🧠 Project Brain Protocol

A lightweight, agent-agnostic memory layer for software projects.

Keep the right context available when you move between Codex, Claude Code, Cursor, Copilot, Windsurf, Aider, Antigravity, and other coding agents.

Agent install · Quick start · How it works · CLI reference · Agent support · Skill and npm package

Install with your coding agent

Open the project you want to equip with Project Brain Protocol, then paste the prompt below into Codex, Claude Code, Cursor, Copilot, Windsurf, Antigravity, or another terminal-capable coding agent:

Install Project Brain Protocol v1.1.0 in this repository.

Please do the following:

1. Check the current Git status. Preserve all existing work and do not discard,
   overwrite, or commit unrelated changes.
2. Confirm that Node.js 18 or newer and npm are available.
3. Install the pinned public release:
   npm install --global [email protected]
4. From the repository root, check whether AGENTS.md, docs/context.md, and
   docs/map.md already exist. If they exist, preserve them and do not reinitialize
   the protocol. Run `brain upgrade` to preview the managed protocol update. If the
   preview is safe, run `brain upgrade --apply`; if the existing AGENTS.md layout is
   not recognized, stop and report it instead of overwriting anything.
5. If the protocol is not initialized, inspect the repository contents before
   running init. Ignore version-control metadata such as .git when deciding whether
   the folder contains project files.
   - If there are no project files, ask me one brief question and wait for my
     answer: "What is this project about?" Do not run init before I answer and do
     not infer the purpose from the folder name. After I answer, run
     `brain init --yes`, then replace its generic project description in AGENTS.md
     and docs/context.md with my answer.
   - If project files exist, discover the project name, purpose, tech stack,
     commands, and conventions from the README, manifests, configuration, and
     representative source files. Ask only about material details that remain
     unclear, then run `brain init --yes` and make sure the generated brain files
     contain the discovered and clarified facts.
6. Review AGENTS.md without overwriting custom instructions. Make sure it records
   the project facts established during discovery. Ensure it also tells future
   agents to update AGENTS.md when durable project-wide facts become known or change,
   while keeping temporary status and recent work in docs/context.md.
7. Run `brain add-agent --list`. Configure only the coding agent currently being
   used, and only if it needs an agent-specific file. AGENTS.md already covers
   Codex, Antigravity/Gemini CLI, and Hermes.
8. Run:
   brain check
   brain status
9. Resolve only Brain Protocol documentation issues needed for `brain check` to
   pass. Do not change application source code as part of this setup.
10. Report the installed version, every file created or changed, and the final
   `brain check` result. Do not commit or push unless I explicitly ask.

The prompt pins the setup to the public v1.1.0 release, protects existing work, and asks the agent to show exactly what it changed.

Why this exists

AI coding agents are useful, but each new session can begin without the decisions, architecture, open issues, and recent changes that shaped the project. Switching tools usually makes that context loss worse.

Project Brain Protocol gives every agent the same small, version-controlled source of truth:

• AGENTS.md defines the working protocol and project conventions.
• docs/context.md records the current focus, next steps, and a rolling change history.
• docs/map.md explains what each important file does.
• brain check detects drift before an agent declares work complete.

The result is durable project memory without a database, hosted service, background daemon, or large context dump.

Quick start

Requirements

• Node.js 18 or newer
• npm (included with Node.js)

Install the public npm release

Install the CLI globally, pinned to v1.1.0:

npm install --global [email protected]
brain --version

Or run it once without a permanent global install:

npx [email protected] init

Initialize a project

cd your-project
brain init

brain init scans the project, asks a short set of setup questions, and creates the three brain files. In a blank folder it explicitly asks what the project will be about and requires a description. For CI, automation, or an explicitly unattended setup, use:

brain init --yes

After making changes:

brain check
brain status

How it works

The three brain files

your-project/
├── AGENTS.md          # Shared rules, commands, identity, and conventions
└── docs/
    ├── context.md     # Current focus, next steps, issues, and recent changes
    └── map.md         # File manifest and high-level architecture

| File | Responsibility | Typical size | | --- | --- | ---: | | AGENTS.md | Tells agents what to read, run, and update | ~200–500 tokens | | docs/context.md | Keeps a rolling window of current project state | ~300–800 tokens | | docs/map.md | Maps files to concise purpose descriptions | ~200–500 tokens |

The intended session-start footprint is roughly 500–1,500 tokens, depending on the project.

The lifecycle

flowchart LR
    A["1 · Pre-flight<br/>Read context + map"] --> B["2 · Work<br/>Build, fix, or refactor"]
    B --> C["3 · Post-flight<br/>Run brain check"]
    C -->|Healthy| D["4 · Complete<br/>Context is current"]
    C -->|Drift found| E["Update context.md<br/>and map.md"]
    E --> C

The protocol is deliberately simple:

1. Pre-flight: the agent reads docs/context.md and docs/map.md.
2. Work: the agent makes the requested project changes.
3. Post-flight: the agent runs brain check.
4. Checkpoint: the agent updates the map and rolling context when needed.

AGENTS.md also evolves, but only for durable project-wide information. Agents update it when the project purpose, stack, package manager, commands, conventions, or architectural constraints become known or change. Temporary status and recent work belong in docs/context.md.

Upgrading an existing project

Update the CLI, then preview the project-level protocol migration:

npm install --global project-brain-protocol@latest
brain upgrade

The preview does not change files. Apply a recognized migration explicitly:

brain upgrade --apply

The command backs up AGENTS.md under .brain/backups/, replaces only the versioned Brain Protocol block, preserves all content outside that block, refreshes recognized auto-generated agent configs, records the upgrade in docs/context.md, refreshes map dates, and runs brain check. Custom/unmarked agent configs are left untouched. Use brain upgrade --check in CI to exit with code 1 when a project update is available.

Anti-staleness checks

brain check validates the protocol files against the current project. It reports:

• missing brain files;
• a generic AGENTS.md project description that should be replaced once the purpose is known;
• project files that are absent from docs/map.md;
• map entries whose files no longer exist;
• context freshness and rolling-window health;
• project complexity signals that may justify a deeper Graphify map.

A healthy check exits with code 0. A stale or incomplete brain exits with code 1, which makes the command suitable for scripts and CI.

CLI reference

| Command | What it does | | --- | --- | | brain init | Interactively initialize the protocol in the current project | | brain init --yes | Initialize non-interactively with detected/default values | | brain upgrade | Preview the bundled project-protocol update without changing files | | brain upgrade --check | Exit 1 when the project protocol needs an update | | brain upgrade --apply | Back up and safely update the managed protocol block | | brain check | Validate brain health and return exit code 0 or 1 | | brain sync | Print the exact map entries that should be added or removed | | brain status | Show brain files, sizes, agent configs, and recent changes | | brain add-agent --list | List supported agent integrations | | brain add-agent <name> | Generate the selected agent’s instruction file | | brain graphify | Run the optional Graphify integration when available | | brain graphify --refresh | Regenerate existing Graphify output | | brain help | Show CLI help | | brain version | Show the installed version |

brain sync is intentionally advisory: it prints a proposed Markdown diff so an agent or maintainer can review purpose descriptions before editing docs/map.md.

Agent support

| Agent | Generated or reused config | Setup | | --- | --- | --- | | Google Antigravity / Gemini CLI | AGENTS.md | Included by brain init | | OpenAI Codex | AGENTS.md | Included by brain init | | Hermes | AGENTS.md | Included by brain init | | Anthropic Claude Code | CLAUDE.md | brain add-agent claude-code | | Cursor | .cursorrules | brain add-agent cursor | | Windsurf | .windsurfrules | brain add-agent windsurf | | GitHub Copilot | .github/copilot-instructions.md | brain add-agent copilot | | Aider | CONVENTIONS.md | brain add-agent aider |

Run brain add-agent --list at any time to see the names accepted by the installed version.

Graphify integration

For larger codebases, the optional brain graphify command can call Graphify to create a deeper local knowledge graph. When Graphify output is present, Project Brain Protocol links it from docs/map.md.

Graphify is not a runtime dependency of this package. The CLI checks for it and prints installation guidance only when you request the integration.

Generated output is kept in graphify-out/, which should normally remain untracked. Local upgrade recovery copies are kept in .brain/backups/ and are also ignored.

Skill and npm package

This repository contains two related deliverables:

1. The brain CLI, defined by package.json.
2. The portable agent skill, stored in skill/SKILL.md.

The skill describes the pre-flight, post-flight, checkpoint, and map-maintenance rules so a compatible agent can apply the protocol automatically.

Install the skill for Antigravity

From a local clone:

mkdir -p ~/.gemini/config/skills/project-brain-protocol
cp skill/SKILL.md ~/.gemini/config/skills/project-brain-protocol/SKILL.md

For other skill-capable agents, use skill/SKILL.md as the portable instruction source and copy it to that agent’s documented local skill directory.

npm registry

The package is published on the public npm registry. npm pack includes the CLI, templates, portable skill, protocol guides, README, and license.

Maintainers can inspect the publishable contents without publishing:

npm pack --dry-run

Useful local/global package-management commands:

npm list --global project-brain-protocol
npm install --global [email protected]
npm uninstall --global project-brain-protocol

Project structure

Project-Brain-Protocol/
├── bin/                  # Executable `brain` CLI entry point
├── src/
│   ├── commands/         # init, upgrade, check, sync, status, add-agent, graphify
│   └── utils/            # detection, scanning, parsing, and templates
├── templates/            # Brain files and agent-specific rule templates
├── skill/                # Portable agent skill instructions
├── docs/
│   ├── PROTOCOL.md       # Protocol specification
│   └── AGENTS-GUIDE.md   # Agent integration guide
├── test/                 # Dependency-free CLI release smoke test
├── package.json
└── LICENSE

The core CLI uses only Node.js built-in modules and has zero runtime dependencies.

Security and privacy

Core commands inspect and write files locally. They do not upload project contents or require API keys. Before committing brain files from a private project to a public repository, review docs/context.md and docs/map.md: durable context can still contain internal names, paths, decisions, or issue details.

This repository ignores common secret-bearing files such as .env and .env.*, but ignore rules are a guardrail—not a substitute for secret scanning and review.

Development

Clone and link the CLI:

git clone https://github.com/shaiadams10/Project-Brain-Protocol.git
cd Project-Brain-Protocol
npm link
brain help

Quick release checks:

node bin/brain.js help
node bin/brain.js version
npm test
npm pack --dry-run

Documentation

• Protocol specification
• Agent integration guide
• Portable skill

License

Released under the MIT License.