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

> Source: <https://github.com/juanyque/agent-brain>
> Published: 2026-11-13 09:43:45+00:00

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