How HN: Agent-brain – Notes-agnostic second-brain operating model for AI agents

A developer released agent-brain, an open-source "second-brain" operating model for AI coding agents including Claude Code, OpenCode, Codex CLI and Antigravity CLI, distributed via a bootstrap script that clones the repo to ~/.local/share/agent-brain and dry-runs by default. The tool keeps CLAUDE.md, AGENTS.md, memory and runtime settings in a git-tracked brain folder symlinked into each runtime (~/.claude, ~/.config/opencode, ~/.codex, ~/.gemini/antigravity-cli), with a brain_state machine moving from virgin to attached to initial to maintenance and a runtime_health check validating each selected runtime after apply. It requires Python 3.x (standard library only, with uv for test dependencies) and git, and on --apply preserves any existing _COMMON symlink as _COMMON.backup-<ts> while relinking stale managed templates.

Notes-agnostic second-brain operating model + multi-runtime agent config/memory versioning. agent-brain is a personal operating model for AI coding agents Claude Code, OpenCode, Codex, Antigravity CLI . It gives you: - A second-brain knowledge structure journal, WIP, memory, tasks that the model builds on top of any folder of notes — Obsidian is one option, not a requirement. - Version-controlled runtime config & memory : your CLAUDE.md / AGENTS.md , memory, and runtime settings live in a git-tracked brain and are symlinked into each runtime ~/.claude , ~/.config/opencode , … , so your agent configuration and memory travel with you across machines. - A session lifecycle daily notes, session notes, consolidation driven by the brain skill. - An optional boyscout skill: spot improvement opportunities while you work, then route them to an explicit remediation workflow or backlog. - Python 3.x the runtime scripts use only the standard library; the complete governed test gate installs its validation dependencies with uv - git on PATH - At least one supported agent runtime installed: - Claude Code https://docs.anthropic.com/en/docs/claude-code → ~/.claude/ - OpenCode https://opencode.ai/ → ~/.config/opencode/ - Shared agents dir → ~/.agents/ - Codex CLI → ~/.codex/ AGENTS.md and config.toml are persisted under the private brain's AGENTS/CODEX/ ; the brain skill is installed at ~/.agents/skills/brain - Antigravity CLI → ~/.gemini/antigravity-cli/ skill-only integration curl -fsSL https://raw.githubusercontent.com/juanyque/agent-brain/main/bootstrap-zero.sh | bash This clones agent-brain to ~/.local/share/agent-brain and runs the orchestrator, which will ask for your brain path an Obsidian vault, a notes folder, or a new empty dir . It dry-runs by default. After reviewing the plan, use the exact public apply command printed at the end; it preserves the selected brain, runtime filter, and symlink policy: curl -fsSL https://raw.githubusercontent.com/juanyque/agent-brain/main/bootstrap-zero.sh \ | bash -s -- --brain /path/to/brain --apply If your brain already has a COMMON symlink pointing to a different model e.g. a previous setup , the dry-run reports the current entry and desired symlink separately, including the raw target of a broken link. It also checks every template symlink managed by home setup and reports stale targets. On --apply , the installer preserves the existing COMMON entry as COMMON.backup-<ts , repoints COMMON to agent-brain, and relinks stale managed templates through the new COMMON . Regular template files remain untouched. The Git snapshot created before installation provides an additional rollback anchor. | Flag | Purpose | |---|---| | --brain <path | Brain root path skips interactive prompt | | --apply | Execute default: dry-run | | --update | git pull --ff-only the repo before wiring | | --runtime claude,opencode,agents,codex,antigravity | Restrict to a comma-separated runtime subset default: all detected | | --symlink-policy copy\|keep | Ingest top-level symlink content, or leave eligible non-canonical links at the brain root | The installer is a thin orchestrator that delegates to two layers: 1. brain state — state machine virgin → attached → initial → maintenance . Determines what flow to run based on the brain's current state. 2. home setup — structure: pre-cleanup, staging for virgin brains , COMMON symlink, wrapper files, templates. 3. runtime manager — all runtime config: detects each runtime, ingests local config into the brain Direction A , implants brain config into local Direction B , handles conflicts, links skills. 4. runtime health — read-only post-apply validation for every selected runtime, using the same mapping matrix as runtime manager . Runtime policy and private configuration belong to the private brain, not this public repository. When a brain contains AGENTS/SHARED/memory/ , Codex receives a stable pointer at ~/.agents/brain-memory ; the bundled query tool ranks a small number of indexed notes on demand. Codex's own generated ~/.codex/memories/ directory remains local and separate. Environment profiles provide a runtime-neutral contract for selecting issue trackers, repositories, project conventions, and optional private resources without embedding those values in the public core. Profiles live in the private brain under AGENTS/SHARED/profiles/ ; global runtime symlinks remain stable when profiles change. See docs/runtime-profiles.md https://github.com/juanyque/agent-brain/blob/main/docs/runtime-profiles.md for the versioned schema, selection algorithm, precedence, safety rules, and sanitized examples. model/SCRIPTS/runtime health.py loads and validates these files when they exist in a brain. Use --profile <id for explicit selection or --cwd <path to exercise project-rule selection. MCP/API availability is delegated to the active runtime adapter; the read-only check never treats a configured provider name as proof of live access. Skills can call skills/brain/scripts/profile context.py to resolve generic capabilities into sanitized provider context. --live checks the Codex MCP registry/auth boundary, while the caller can pass exact --available-tool names plus --tool-catalog-complete to enforce active exposure. An omitted or incomplete catalog remains unverified. Claude live discovery is refused because its official registry command may rewrite runtime settings. Runtime adapters can project standalone private profile resources with model/SCRIPTS/profile overlays.py . The adapter supplies explicit roots for each selected resource kind; the dry-run-first projector links brain-owned sources, quarantines conflicts, and is safe to apply repeatedly without rewriting runtime configuration. model/SCRIPTS/profile secrets.py checks referenced secret names without returning their values. Environment presence, metadata-only macOS keychain lookup, and sanitized runtime-native catalogs share the same fail-closed status contract. Git is used as rollback anchor: a local snapshot commit or annotated tag is created before any mutation. Snapshot messages are deterministic and snapshot signing is disabled so unattended bootstrap runs never open an editor or a GPG prompt. Nothing is pushed automatically. Agent-brain ships several skills, but only the operating skill is installed automatically; the rest are opt-in: | Skill | Command | Installation | Purpose | |---|---|---|---| | brain | /brain Codex: $brain | Automatic | Connect to the brain, manage session lifecycle, daily notes, stand-up reports /brain daily , and standardization | | boyscout | /boyscout Codex: $boyscout | Opt-in | Spot improvement opportunities and route them to an explicit remediation workflow or backlog | | explain-with-cards | /explain-with-cards Codex: $explain-with-cards | Opt-in | Tutor mode: teach a session topic through small cards with comprehension checks and a persistent learning plan | | step-by-step | /step-by-step Codex: $step-by-step | Opt-in | Guide mode: turn pending questions and tasks into an ordered checklist and close them one card at a time | Skills live outside the brain and are symlinked to the repo. Codex and OpenCode share ~/.agents/skills/ ; Claude uses ~/.claude/skills/ ; Antigravity CLI uses ~/.gemini/antigravity-cli/skills/ . The legacy Gemini CLI path is not managed. Skill files use normal names without the .common.md suffix. The brain skill's session-open apply is idempotent: it creates or updates one session note, upserts exactly one daily recovery entry keyed by the full session ID, preserves a manually edited summary, and checks the resulting session/daily state. Active WIP notes can be checked against the WIP/WIP.md dashboard with the bundled read-only brain check.py tool. Install an opt-in skill here boyscout , for Codex only when wanted. Review the dry-run first; the other opt-in skills install the same way with their directory name: bash ~/.local/share/agent-brain/model/SCRIPTS/skill link.sh boyscout ~/.agents bash ~/.local/share/agent-brain/model/SCRIPTS/skill link.sh boyscout ~/.agents --apply The same installer accepts a repo-owned skill directory and can link it into every detected runtime: bash ~/.local/share/agent-brain/model/SCRIPTS/skill link.sh /path/to/project/skills/confold bash ~/.local/share/agent-brain/model/SCRIPTS/skill link.sh /path/to/project/skills/confold --apply agent-brain/ ├── bootstrap-zero.sh curl entry point clones repo, dispatches to orchestrator ├── docs/ public architecture and versioned profile schemas ├── examples/profiles/ sanitized environment-profile examples ├── model/ the operating model — what COMMON symlinks to inside a brain │ ├── AGENTS.common.md shared agent instructions │ ├── BRAIN.common.md brain structure & conventions │ ├── RULES- .common.md daily notes, file naming, links, sessions, evidence │ ├── JOBS.common.md recurring maintenance routines │ ├── TASK TYPES/ how-to guides for recurring task types │ ├── TEMPLATES/ daily note, WIP, issue, report templates │ └── SCRIPTS/ │ ├── brain state.py state machine shared │ ├── home setup.py structure cleanup, staging, COMMON, wrappers │ ├── runtime catalog.py runtime config homes and skill destinations │ ├── runtime manager.py runtime config Direction A/B, conflict, skill link │ ├── runtime health.py post-apply checks for all supported runtimes │ ├── profile overlays.py optional private-resource projection │ ├── profile secrets.py value-free secret-reference preflight │ ├── runtime install.sh low-level symlink helper called by runtime manager │ └── skill link.sh manual skill installer for non-default skills └── skills/ ├── brain/ session lifecycle, daily notes, maintenance │ ├── SKILL.md │ ├── scripts/ session open.py, brain check.py, find home.py, ... │ └── references/ project-aware-loading, setup-and-attach, brain-maintenance, runtime-merge └── boyscout/ improvement-spotting + backlog management ├── SKILL.md ├── scripts/ backlog.py, doctor.py, fix-ceremony.sh └── references/ finding-schema, detection guides, ticket backends, deep-mode, ... Files under model/ keep the .common.md naming convention because they live inside a brain via COMMON and must stay link-safe for notes apps. skills/ and the repo root use normal names. The test suite runs entirely against temporary brains, homes, and Git repositories. The lifecycle and focused subsets are stdlib-only; the complete governed gate uses uv to provide jsonschema , pydantic , and pyyaml : uv run --python 3.12 \ --with 'jsonschema =4.25,<5' \ --with 'pydantic =2.10,<3' \ --with 'pyyaml =6.0.2,<7' \ python3 -m unittest discover -s tests -v CI executes the same suite on macOS and Linux. The profile integration test uses an isolated temporary HOME and verifies dry-run safety, conflict quarantine, and double-apply idempotence. See tests/README.md https://github.com/juanyque/agent-brain/blob/main/tests/README.md for the covered contracts, individual-test commands, and fixture rules. The canonical local gate is the todo19 QA-manifest alias complete-local-gate , executed only through tests/support/evidence cli.py run-todo . It runs the current unittest suite, the immutable 113-ID baseline replay, Python compilation, shell syntax checks, committed diff whitespace checks, worktree scope/whitespace checks, the strict operating-model checker, and a zero- pycache assertion. GitHub Actions mirrors the strict local gate on ubuntu-latest and macos-latest . The workflow checks out full history fetch-depth: 0 , resolves MODEL BASE from a valid pull-request base, push base, pinned immutable baseline, or root-commit fallback, proves the selected commit object, then runs committed-range gates before the suite and worktree gates after compile/shell checks. The workflow is a contract map only; private-brain migration remains explicit user work and is not automatic. TBD.