{"slug": "how-hn-agent-brain-notes-agnostic-second-brain-operating-model-for-ai-agents", "title": "How HN: Agent-brain – Notes-agnostic second-brain operating model for AI agents", "summary": "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.", "body_md": "**Notes-agnostic second-brain operating model + multi-runtime agent config/memory versioning.**\n\nagent-brain is a personal operating model for AI coding agents (Claude Code, OpenCode, Codex, Antigravity CLI). It gives you:\n\n- 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.\n- **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.\n- A **session lifecycle** (daily notes, session notes, consolidation) driven by the`brain` skill.\n- An optional **boyscout** skill: spot improvement opportunities while you work, then route them to an explicit remediation workflow or backlog.\n\n- **Python 3.x** (the runtime scripts use only the standard library; the complete\ngoverned test gate installs its validation dependencies with`uv` )\n- **git** on PATH\n- At least one supported agent runtime installed:\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) →`~/.claude/`\n  - [OpenCode](https://opencode.ai/) →`~/.config/opencode/`\n  - Shared agents dir → `~/.agents/`\n  - 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` )\n  - Antigravity CLI → `~/.gemini/antigravity-cli/` (skill-only integration)\n\n```\ncurl -fsSL https://raw.githubusercontent.com/juanyque/agent-brain/main/bootstrap-zero.sh | bash\n```\n\nThis clones agent-brain to `~/.local/share/agent-brain` and runs the orchestrator, which\nwill ask for your brain path (an Obsidian vault, a notes folder, or a new empty dir). It\ndry-runs by default. After reviewing the plan, use the exact public apply command printed\nat the end; it preserves the selected brain, runtime filter, and symlink policy:\n\n```\ncurl -fsSL https://raw.githubusercontent.com/juanyque/agent-brain/main/bootstrap-zero.sh \\\n  | bash -s -- --brain /path/to/brain --apply\n```\n\nIf 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.\n\n| Flag | Purpose | \n|---|---|\n| `--brain <path>` | Brain root path (skips interactive prompt) | \n| `--apply` | Execute (default: dry-run) | \n| `--update` | `git pull --ff-only` the repo before wiring | \n| `--runtime claude,opencode,agents,codex,antigravity` | Restrict to a comma-separated runtime subset (default: all detected) | \n| `--symlink-policy copy\\|keep` | Ingest top-level symlink content, or leave eligible non-canonical links at the brain root | \n\nThe installer is a thin orchestrator that delegates to two layers:\n\n1. **`brain_state`** — state machine (` virgin` →`attached` →`initial` →`maintenance` ). Determines what flow to run based on the brain's current state.\n2. **`home_setup`** — structure: pre-cleanup, staging (for virgin brains),`_COMMON` symlink, wrapper files, templates.\n3. **`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.\n4. **`runtime_health`** — read-only post-apply validation for every selected runtime, using the same mapping matrix as`runtime_manager` .\n\nRuntime policy and private configuration belong to the private brain, not this public repository.\nWhen a brain contains `_AGENTS/SHARED/memory/`, Codex receives a stable pointer at\n`~/.agents/brain-memory`; the bundled query tool ranks a small number of indexed notes on\ndemand. Codex's own generated `~/.codex/memories/` directory remains local and separate.\n\nEnvironment profiles provide a runtime-neutral contract for selecting issue trackers,\nrepositories, project conventions, and optional private resources without embedding those\nvalues in the public core. Profiles live in the private brain under\n`_AGENTS/SHARED/profiles/`; global runtime symlinks remain stable when profiles change.\n\nSee [`docs/runtime-profiles.md`](https://github.com/juanyque/agent-brain/blob/main/docs/runtime-profiles.md) for the versioned schema, selection\nalgorithm, precedence, safety rules, and sanitized examples. `model/SCRIPTS/runtime_health.py`\nloads and validates these files when they exist in a brain. Use `--profile <id>` for explicit\nselection or `--cwd <path>` to exercise project-rule selection. MCP/API availability is\ndelegated to the active runtime adapter; the read-only check never treats a configured\nprovider name as proof of live access.\n\nSkills can call `skills/brain/scripts/profile_context.py` to resolve generic capabilities into\nsanitized provider context. `--live` checks the Codex MCP registry/auth boundary, while the caller\ncan pass exact `--available-tool` names plus `--tool-catalog-complete` to enforce active exposure.\nAn omitted or incomplete catalog remains unverified. Claude live discovery is refused because its\nofficial registry command may rewrite runtime settings.\n\nRuntime adapters can project standalone private profile resources with\n`model/SCRIPTS/profile_overlays.py`. The adapter supplies explicit roots for each selected resource\nkind; the dry-run-first projector links brain-owned sources, quarantines conflicts, and is safe to\napply repeatedly without rewriting runtime configuration.\n\n`model/SCRIPTS/profile_secrets.py` checks referenced secret names without returning their values.\nEnvironment presence, metadata-only macOS keychain lookup, and sanitized runtime-native catalogs\nshare the same fail-closed status contract.\n\nGit 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.\n\nAgent-brain ships several skills, but only the operating skill is installed automatically; the rest are opt-in:\n\n| Skill | Command | Installation | Purpose | \n|---|---|---|---|\n| **brain** | `/brain` (Codex:`$brain` ) | Automatic | Connect to the brain, manage session lifecycle, daily notes, stand-up reports ( `/brain daily` ), and standardization | \n| **boyscout** | `/boyscout` (Codex:`$boyscout` ) | Opt-in | Spot improvement opportunities and route them to an explicit remediation workflow or backlog | \n| **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 | \n| **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 | \n\nSkills live outside the brain and are symlinked to the repo. Codex and OpenCode share\n`~/.agents/skills/`; Claude uses `~/.claude/skills/`; Antigravity CLI uses\n`~/.gemini/antigravity-cli/skills/`. The legacy Gemini CLI path is not managed. Skill files use\nnormal names without the `.common.md` suffix.\n\nThe brain skill's session-open apply is idempotent: it creates or updates one session note,\nupserts exactly one daily recovery entry keyed by the full session ID, preserves a manually\nedited summary, and checks the resulting session/daily state. Active WIP notes can be checked\nagainst the `WIP/WIP.md` dashboard with the bundled read-only `brain_check.py` tool.\n\nInstall 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:\n\n```\nbash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh boyscout ~/.agents\nbash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh boyscout ~/.agents --apply\n```\n\nThe same installer accepts a repo-owned skill directory and can link it into every detected runtime:\n\n```\nbash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh /path/to/project/skills/confold\nbash ~/.local/share/agent-brain/model/SCRIPTS/skill_link.sh /path/to/project/skills/confold --apply\nagent-brain/\n├── bootstrap-zero.sh     # curl entry point (clones repo, dispatches to orchestrator)\n├── docs/                 # public architecture and versioned profile schemas\n├── examples/profiles/    # sanitized environment-profile examples\n├── model/                # the operating model — what _COMMON symlinks to inside a brain\n│   ├── AGENTS.common.md  # shared agent instructions\n│   ├── BRAIN.common.md   # brain structure & conventions\n│   ├── RULES-*.common.md # daily notes, file naming, links, sessions, evidence\n│   ├── JOBS.common.md    # recurring maintenance routines\n│   ├── TASK_TYPES/       # how-to guides for recurring task types\n│   ├── TEMPLATES/        # daily note, WIP, issue, report templates\n│   └── SCRIPTS/\n│       ├── brain_state.py       # state machine (shared)\n│       ├── home_setup.py        # structure (cleanup, staging, _COMMON, wrappers)\n│       ├── runtime_catalog.py   # runtime config homes and skill destinations\n│       ├── runtime_manager.py   # runtime config (Direction A/B, conflict, skill link)\n│       ├── runtime_health.py    # post-apply checks for all supported runtimes\n│       ├── profile_overlays.py  # optional private-resource projection\n│       ├── profile_secrets.py   # value-free secret-reference preflight\n│       ├── runtime_install.sh   # low-level symlink helper (called by runtime_manager)\n│       └── skill_link.sh        # manual skill installer for non-default skills\n└── skills/\n    ├── brain/            # session lifecycle, daily notes, maintenance\n    │   ├── SKILL.md\n    │   ├── scripts/      # session_open.py, brain_check.py, find_home.py, ...\n    │   └── references/   # project-aware-loading, setup-and-attach, brain-maintenance, runtime-merge\n    └── boyscout/         # improvement-spotting + backlog management\n        ├── SKILL.md\n        ├── scripts/      # backlog.py, doctor.py, fix-ceremony.sh\n        └── references/   # finding-schema, detection guides, ticket backends, deep-mode, ...\n```\n\nFiles 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.\n\nThe test suite runs entirely against temporary brains, homes, and Git repositories.\nThe lifecycle and focused subsets are stdlib-only; the complete governed gate uses\n`uv` to provide `jsonschema`, `pydantic`, and `pyyaml`:\n\n```\nuv run --python 3.12 \\\n  --with 'jsonschema>=4.25,<5' \\\n  --with 'pydantic>=2.10,<3' \\\n  --with 'pyyaml>=6.0.2,<7' \\\n  python3 -m unittest discover -s tests -v\n```\n\nCI executes the same suite on macOS and Linux. The profile integration test uses an isolated\ntemporary `HOME` and verifies dry-run safety, conflict quarantine, and double-apply idempotence.\n\nSee [`tests/README.md`](https://github.com/juanyque/agent-brain/blob/main/tests/README.md) for the covered contracts, individual-test\ncommands, and fixture rules.\n\nThe canonical local gate is the todo19 QA-manifest alias `complete-local-gate`, executed only\nthrough `tests/support/evidence_cli.py run-todo`. It runs the current unittest suite, the\nimmutable 113-ID baseline replay, Python compilation, shell syntax checks, committed diff\nwhitespace checks, worktree scope/whitespace checks, the strict operating-model checker, and a\nzero-`__pycache__` assertion.\n\nGitHub Actions mirrors the strict local gate on `ubuntu-latest` and `macos-latest`. The workflow\nchecks out full history (`fetch-depth: 0`), resolves `MODEL_BASE` from a valid pull-request base,\npush base, pinned immutable baseline, or root-commit fallback, proves the selected commit object,\nthen runs committed-range gates before the suite and worktree gates after compile/shell checks.\nThe workflow is a contract map only; private-brain migration remains explicit user work and is not\nautomatic.\n\nTBD.", "url": "https://wpnews.pro/news/how-hn-agent-brain-notes-agnostic-second-brain-operating-model-for-ai-agents", "canonical_source": "https://github.com/juanyque/agent-brain", "published_at": "2026-11-13 09:43:45+00:00", "updated_at": "2026-11-13 09:50:04.201307+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["agent-brain", "Claude Code", "OpenCode", "Codex CLI", "Antigravity CLI", "Obsidian", "Anthropic", "uv"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-hn-agent-brain-notes-agnostic-second-brain-operating-model-for-ai-agents", "markdown": "https://wpnews.pro/news/how-hn-agent-brain-notes-agnostic-second-brain-operating-model-for-ai-agents.md", "text": "https://wpnews.pro/news/how-hn-agent-brain-notes-agnostic-second-brain-operating-model-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/how-hn-agent-brain-notes-agnostic-second-brain-operating-model-for-ai-agents.jsonld"}}