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

Open-source developer juanyque released agent-brain, an operating model that connects AI coding assistants to note folders while versioning configurations and memories across machines. According to github.com's report, the project organizes journals, active tasks, and session logs across runtimes using standard git version control. It establishes shared directory structures that synchronize agent instructions and historical context across multiple development environments.

This report details the architectural layers, installation routines, and governance policies of the open-source utility. Software engineers, automation specialists, and developer operations teams managing multiple command-line coding models can examine how configuration files and private memories stay consistent across operating systems. The system supports major command-line agents while preserving personal note collections and local privacy boundaries.

01Runtime prerequisites and supported agent targets

The tool requires Python 3.x and an accessible git executable on the system path. All runtime operations rely exclusively on the Python standard library, avoiding heavy external modules during everyday terminal execution. Comprehensive testing and validation scripts install their necessary verification dependencies through uv during formal quality checks.

The operating model works across several prominent coding assistants installed on a developer machine. Supported platforms include Claude Code targeting its standard home directory, OpenCode targeting user configuration paths, and a unified shared directory. The legacy Gemini CLI folder remains unmanaged, leaving historical command installations isolated from automated setup changes.

For the Codex CLI, the framework places agent definitions and configuration files inside private directories while wiring skills into shared repositories. Antigravity CLI receives integration through the gemini directory exclusively as a skill connection. Both configurations ensure underlying engine dependencies remain intact while runtime rules synchronize smoothly.

02Bootstrap installer and symlink preservation

Installation begins by retrieving the bootstrap script via a single terminal command that clones the repository into the user local share path. The orchestrator immediately prompts the operator for a target directory, which can be an Obsidian vault, standard notes directory, or an empty path. The script runs as a dry run by default to inspect changes safely.

When existing setups already contain a common symlink pointing to another location, the dry run explicitly isolates broken targets from valid links. Applying changes saves the legacy symlink under a timestamped backup name before repointing the link to the new repository. Managed template symlinks are repointed while standard files remain untouched.

Execution options let developers pass explicit command-line flags to bypass prompts, trigger fast-forward git pulls, and isolate specific runtime subsets. Operators can select symlink policies that either copy directory contents or keep top-level links in place. An automatic git snapshot commit or annotated tag provides a permanent local rollback anchor before changes occur.

03Multi-layer orchestrator and state transitions

The core architecture functions as an orchestrator that splits operational responsibilities across four distinct Python components. A specialized state module tracks the brain through virgin, attached, initial, and maintenance phases to determine necessary lifecycle workflows. This classification prevents redundant initialization routines and preserves existing note structures.

A setup component manages structural changes, running pre-cleanup tasks, staging directories for fresh setups, and anchoring template files. Alongside it, a runtime manager transfers local configurations into the knowledge base, implants managed configurations into runtime folders, and resolves linking conflicts. A post-apply verification script performs read-only checks across each detected environment.

Private runtime policies and credentials remain strictly contained within private storage rather than public codebases. When shared memory stores exist, Codex receives a stable directory link while ranking a small set of indexed notes through a query tool. Codex keeps its local memory store completely separate from the versioned knowledge repository.

04Environment profiles and resource validation

Environment profiles establish a runtime-neutral contract that defines issue trackers, code repositories, and project rules without hardcoding private data into shared files. Stored inside private brain folders, these profile configurations let global symlinks remain stable even when developer settings change. Specialized health scripts load and validate the profile schemas during diagnostic runs.

Profile context utilities translate generic model capabilities into sanitized provider details on demand. While Codex verifies registry bounds during live queries, live discovery checks for Claude Code are explicitly refused because official registry commands can rewrite local runtime configuration. Profile overlays project private resources, link brain sources, and quarantine file conflicts during updates.

Secret hygiene scripts check referenced credential names without exposing underlying secret values to logs or runtime contexts. Environment variable checks, macOS keychain queries, and sanitized native catalogs operate under a strict fail-closed contract. In addition, automated bootstrap snapshots disable commit signing to prevent interactive terminal prompts during unattended executions.

05Modular skill suite and session lifecycles

The core operating skill deploys automatically during initialization, enabling session tracking, daily note updates, and stand-up reporting via terminal commands. The session-open routine operates idempotently by generating a single session note, upserting a daily recovery record by session identifier, and protecting custom summaries from overwrites. An included verification script checks active work-in-progress files against a central markdown dashboard.

Three optional skills provide specialized task handling when activated by the operator. The boyscout skill flags code improvements during work sessions, routing them into remediation pipelines or backlog files. A card-based tutor mode presents session concepts with comprehension checks, while a guide module structures unresolved questions into ordered checklists that close one card at a time.

Skills exist outside the central brain and connect to runtime targets using symlinks without markdown filename extensions. Codex and OpenCode share a central skill directory, whereas Claude and Antigravity CLI use their own dedicated directories. A dedicated linking shell script handles dry runs and live applications across all detected runtime paths.