Machinery

Rendered from knowledge/exobrain/machinery.md — the text an agent reads.

A map of the concrete machinery that makes an exobrain work — the scripts, hooks, registries, and gates. One row per artifact: what it does, with a pointer to the topic file that explains it in depth. This is an index, not a description — the semantics live in the topic files (scopes.md, agents.md, skills.md, tools.md, domains.md, mounts.md, authoring.md, propagation.md, security.md, compat.md) and in root AGENTS.md. Come here for the whole moving-parts surface at a glance; follow the pointer for how each piece works.

Paths are repo-relative. Generated artifacts are produced by connect-agent.sh and gitignored (under .claude/, or the agent’s $TARGET_DIR); everything else is tracked. Keep this map current when machinery is added or removed — it’s part of auditing the surface area of a change.

Connection & linking

The connect-agent.sh ecosystem wires repo content into each agent’s context — see agents.md.

Artifact	Role
scripts/connect-agent.sh	The connector. Resolves identity by name-match from one of four sources — flags (--handle/--host/--scope/--guest), existing config, the interactive wizard (checkbox menu, person/host pre-checked), or guest; --relink / --configure / --wire-sandbox thereafter. Resolves the skills registry, links always-tier skills, fetches external skills, composes each agent’s own context surface, installs the git hooks, reconciles OpenClaw’s runtime config (trusted skill symlink roots, Skill Workshop off, the knowledge domains in its memory index) and its workspace .gitignore (raw memory capture), reconciles the connected chain’s crons.json registries into OpenClaw’s scheduler, runs each connected scope’s own connect hook.
.claude/CLAUDE.md (generated)	Claude’s generated entry point — @-imports .claude/connected-scopes.md plus one import per generated index. (The handcrafted root CLAUDE.md is separate and loads the global scope via @AGENTS.md.)
.claude/connected-scopes.md (generated)	A manifest of @-imports to each connected deeper scope’s source AGENTS.md/CLAUDE.md, shallow→deep — referenced by relative path, not copied, so scope edits show up without a recompose.
.claude/optional-skills.md (generated)	The Claude-filtered optional-skills index.
AGENTS.override.md (generated, Codex)	Codex surface — the full composition (root AGENTS.md + root sidecar + deeper-scope specs + index) written to an in-repo, gitignored AGENTS.override.md, which Codex reads natively and which outranks AGENTS.md at the same directory level (so it must carry the root spec too).
~/.openclaw/workspace/USER.md (generated)	OpenClaw surface — the same composed context inlined between markers, since OpenClaw has no @-import primitive.
.claude/CLAUDE.md · .codex · .openclaw	Per-agent markers (generated, gitignored) — which agents this checkout connects. --relink silently skips agents without a marker, and with no agent named relinks every agent that has one.
.exobrain.json (gitignored)	Saved per-machine config — identity, per-tool and per-mount state. Keys: tools.md § State: .exobrain.json.
mounts.json · mounts.schema.json	Declares the mounts — shared knowledge repositories this instance reads — each with its charter, plus this instance’s own charter under instance. See mounts.md.
scripts/mount-isolation.py	The leak gate between roots (mounts.md § Isolation): scans what a land adds — added lines of every changed file, _raw/ included, each file’s name, the branch name, the commit messages, the PR title, and any text handed in — against the charters, reports a text file it cannot read (not UTF-8), and exits non-zero on a hit. --plan names which roots gate a land and why; --lens writes the audience lens the authoring review runs with.
scripts/mounts.sh	status (charter, checkout state, charter drift) / enable / disable / sync / worktree / audience (collaborators and visibility through gh) for the mounts: clones or verifies a mount’s checkout, records its state, relinks the connected agents, fast-forwards only a clean checkout on its origin’s default branch, and opens a worktree of the checkout for a change to the mount (landed with persist.sh --repo).
.agents/skills/ (generated, Codex)	Repo-local Codex skills dir (real dir, symlinked children) — keeps exobrain skills out of the global ~/.codex/skills.
scripts/skills-registry.sh · scripts/fetch-external-skills.sh	Sourced/invoked by the connector — see § Skills system.
skills/exobrain-tests/unit/test-connect-agent.sh	Deterministic connector/registry harness — fake exobrains in temp dirs, no agent. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-mounts.sh	Harness for mounts — scripts/mounts.sh, the mount paths of the connector, healthcheck, and validator, and the isolation gate through persist.sh. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-raw-data.sh	Harness for validate-exobrain.sh’s raw-format gate. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-portable-paths.sh	Harness for validate-exobrain.sh’s machine-specific-path gate. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-script-syntax.sh	Harness for validate-exobrain.sh’s shell and Python syntax gates. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-validator-scan.sh	Harness for validate-exobrain.sh’s find_repo pruning. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-validator-checks.sh	Harness for validate-exobrain.sh’s whole-tree checks. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-skills-validate.sh	Harness for scripts/skills-validate.sh. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-skills-status.sh	Harness for scripts/skills-status.sh --all. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-repair-findings/tests/test-findings-pending.sh	Harness for the repair skill’s findings-pending.sh; runs as the unit suite’s findings-pending harness. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-persist.sh	Deterministic harness for scripts/persist.sh — a bare origin, a main checkout, worktrees, stub gates (validator, authoring review, unit suite), recorded behavior runs, and a fake gh that squash-merges into the bare origin.
skills/exobrain-tests/unit/test-behavior-runner.sh	Harness for the behavior suite’s runner — a fake instance and a fake claude. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-authoring-review.sh	Harness for scripts/authoring-review.sh against a fake engine. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-agent-attribution.sh	Harness for scripts/strip-agent-attribution.sh and the validator’s attribution check. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-compat-ledger.sh	Harness for the compat-shim gates. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-openclaw-cron-sync.sh	Harness for scripts/openclaw-cron-sync.py against a fake gateway. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-secret-scan.sh	Harness for validate-exobrain.sh’s secret scan. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-scratch-retention.sh	Harness for the healthcheck’s scratch report. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-security-findings.sh	Harness for scripts/security-findings.py and the gates that read it. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-envfile.sh	Harness for scripts/envfile.py. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/unit/test-exobrain-ab.sh	Harness for the exobrain-ab runner’s own machinery — run_one.sh’s grading against a fake claude and run.sh’s task-row check. Coverage: the exobrain-tests SKILL.md § unit/.
skills/exobrain-tests/ · seed/skills/seed-tests/	The instance self-test skill, three sub-suites: unit/ (deterministic, no agent — harnesses for the framework scripts under scripts/), behavior/ (hermetic, agent-driven — runs concrete tasks against a snapshot copy) and onboarding/ (non-hermetic — fresh Docker machine → clone the instance’s origin → connect → healthcheck/validator; optional headless-agent e2e; per-case requirements skip when unmet). seed-tests is seed-only — builds an instance from the seed, then runs its unit + behavior suites against it. See § Skills system.

Verifying a connector/wiring change (connect-agent.sh, skills-registry.sh, fetch-external-skills.sh, the injection): first run skills/exobrain-tests/unit/run.sh --harnesses connect-agent for the fixture-level logic. Then wire a real checkout with connect-agent.sh <agent> --wire-sandbox (see agents.md § connect-agent.sh end-to-end for its write envelope and the openclaw guard), and spot-check the agent’s surface — for Claude that .claude/connected-scopes.md + .claude/optional-skills.md exist and every manifest @-import resolves to a real file; for Codex that the generated in-repo AGENTS.override.md holds the expected scopes, for OpenClaw that the marker block in USER.md does — plus the .claude/ and .agents/skills/ dirs. Finally run scripts/validate-exobrain.sh for conventions.

Git hooks

Installed by connect-agent.sh, refreshed idempotently on every relink.

Hook	Runs
post-merge	After a fast-forward/merge git pull: scripts/mounts.sh sync when mounts.json exists, then connect-agent.sh <agent> --relink for each connected agent; for OpenClaw, the relink also reconciles the scheduled jobs.
post-rewrite	The same mount sync and relink after a rebase-based pull (git pull --rebase); guarded to skip plain commit --amend.
pre-push	scripts/validate-exobrain.sh (deterministic) — blocks the push on a violation.
commit-msg	scripts/strip-agent-attribution.sh — rewrites the message in place; never blocks a commit.

Session hooks (Claude)

Hook	Runs
SessionStart (committed .claude/settings.json)	scripts/exobrain-healthcheck.sh — warns if the agent isn’t connected or its links are stale, and relays the suggested connect-agent.sh command. Read-only, advisory. See AGENTS.md → “Setup and relink safety”.

Validation & quality gates

Gate	Checks	When
scripts/validate-exobrain.sh	Deterministic conventions: AGENTS.md placement, file naming, JSON syntax, scopes.json shape, the skills registry, agent-neutral outgoing commit messages, machine-specific absolute paths outside host scope (diff-scoped against the default branch, so existing paths are grandfathered; _raw/ and Dockerfile-siblings exempt), relative markdown links escaping the repository and shell or Python that does not parse (both diff-scoped the same way), raw-format files newly added under knowledge/ or workspaces/ (entities.md § Synthesized, not raw), secrets in the commits added against the default branch (gitleaks with the repo’s .gitleaks.toml, redacted; a note when gitleaks is not installed), mounts.json shape (each mount’s charter), <mount>:<path> citations in changed markdown that the enabled mount’s checkout cannot resolve, compat markers against the shim ledger both ways (see compat.md; the removal date never fails the gate), every per-scope crons.json registry’s shape (delegated to openclaw-cron-sync.py --check; no gateway), every per-scope security.json registry’s shape (delegated to security-findings.py --check), bash-4-only constructs in *.sh (declare -A, mapfile, readarray — comment lines exempt, a script opts out with # exobrain-allow-bash4), unguarded expansion of any array some script assigns empty (names collected repo-wide; write ${name[@]+"${name[@]}"}) — plus every connected scope’s validator hook (<scope>/scripts/validate-exobrain.sh, run with the checkout under validation as $1; non-zero exit → its output becomes violations; the gitignored local/ scope’s hook is the private leak scan). --repo <dir> runs the content checks on another checkout, such as a mount’s worktree.	pre-push + manual
scripts/changed-paths.sh	The one list of paths a branch changes (committed against a base, uncommitted, or both; --added for additions only) that every diff-scoped gate reads — validate-exobrain.sh, authoring-review.sh, mount-isolation.py, persist.sh — with non-ASCII names unchanged. The validator records its absence as a violation.	called by the gates above
scripts/strip-agent-attribution.sh	Removes agent attribution — Co-Authored-By trailers naming an agent, “Generated with <agent>” footers — from a commit message file in place. Its pattern is kept identical to the validator’s agent-attribution check.	commit-msg hook
scripts/authoring-review.sh	Two layers. Deterministic (§0, exit 2): the new-shared-skill proof gate — criteria in skills.md. LLM (exit 1): judgment over changed specs/knowledge domains against the authoring rules, plus the skill-authoring rubric (type / leverage / proof / reach → KEEP, TRIM, PROVE, DEMOTE, MERGE) for changed SKILL.md files. --repo <dir> reviews another checkout; --lens <file> adds the audience lens ahead of the diff and brings every changed text file under knowledge/ and workspaces/ into scope. Self-skips when nothing changed, saying so; degrades open when no agent CLI is installed or the engine errors, times out, or answers nothing — except under a lens whose target is a mount (exit 3): there the review is the only judge of the never-topics, so persist refuses the land until a review answers. AUTHORING-OK passes only as a whole line. Skippable with EXOBRAIN_SKIP_AUTHORING_REVIEW=1, which never waives the proof gate.	exobrain-persist (after commit, before push) + manual; not a push-hook gate
scripts/exobrain-healthcheck.sh	Connection integrity (not-connected / stale links; Codex: agents.md § Worktree context) + trunk freshness (main checkout behind upstream → suggests git pull --ff-only; the fetch is throttled and time-boxed, and it never pulls) + mount freshness and charter drift (mounts.md § Freshness) + compatibility shims past their removal date (compat.md § Ledger, read from the current checkout) + security findings that need a person (security.md § Reaching a person) + stale scratch — tmp/ entries and _cache/ directories in the main checkout past the window (security.md § Posture). Read-only; resolves the main checkout from a worktree; always exits 0.	SessionStart + manual
exobrain-authoring-audit skill	Scopes a new or justification-heavy doc by its readers, tracing each contested fact to a real reader need.	before drafting/revising a substantial doc

The authoring rules these enforce live in authoring.md and AGENTS.md → “Reader Lens” / “Conventions”.

Registry	Role
knowledge/exobrain/compat.md	The compatibility-shim ledger: one row per piece of transitional code (id, what it heals, the files carrying its COMPAT <id> marker, when it landed, when it may go), plus the marking convention. Read by both gates above — see compat.md.
security.json (per scope, optional) · security.schema.json	The security findings ledger: what is known to be weak, each finding with its severity, surface, impact, fix and who can carry it out; open or knowingly accepted. Discovered at the repo root and in any scope dir (the gitignored local/ included). See security.md.
scripts/security-findings.py	Owns the ledger: add / accept / reopen / close / reviewed / list; summary names what needs a person and exits 2 when anything does; --check validates every registry.

Skills system

Physical skill directories at any scope, inert until declared in a skills.json — see skills.md.

Artifact	Role
skills.json (root) + per-scope (<group>/, <person>/, <host>/)	Registries. Declarations (name, owner, tier, optional force) introduce a skill in their own scope; overrides (from + tier) opt one in/out elsewhere. Tiers always / optional / unlisted / off; agent filtering via agent / skipAgents.
skills.schema.json	Registry schema (declaration/override).
scripts/skills-registry.sh	Resolver — walks the connected scope chain (build_scope_chain), deepest contribution wins; a declaration fires only if forced or owned.
scripts/skills-status.sh	Show the resolved registry; --all catalogs every declared skill for discovery.
scripts/skills-validate.sh	Verify declarations have directories and overrides reference real declarations.
scripts/skills-promote.sh	Opt a skill in/out (override) or --force a declaration, without hand-editing JSON.
scripts/fetch-external-skills.sh	Fetch external (third-party) skills declared with source.
optional-skills index (generated)	Index of optional-tier skills, read on demand — .claude/optional-skills.md (Claude), or inlined into AGENTS.override.md (Codex) / ~/.openclaw/workspace/USER.md (OpenClaw).

Global skills the seed ships: exobrain-ab, exobrain-authoring-audit, exobrain-knowledge, exobrain-evolve, exobrain-mounts, exobrain-persist, exobrain-repair-findings (unlisted), exobrain-tests, exobrain-tools.

Tools

The per-tool catalog of external data sources — see tools.md.

Artifact	Role
tools/*.md	The catalog: one self-contained doc per tool (its presence at a scope is its registration). The seed ships tools/README.md + tools/example-tool.md (a template); add a doc per tool you connect, with group/person/host overlays as needed.
.exobrain.json (gitignored)	Per-machine, per-tool connection state (the tools block).
tools index (generated)	Flat catalog of every visible tool doc (name + path + first-line purpose), composed into each agent’s surface like the optional-skills index — .claude/tools-index.md (Claude), or inlined into AGENTS.override.md (Codex) / ~/.openclaw/workspace/USER.md (OpenClaw). Visibility only; connection stays per-machine in .exobrain.json.
exobrain-tools skill	Drives the catalog: onboard / status / add / refresh / doctor over the connected scope chain.
scripts/envfile.py	The one reader/writer of .env for a tool client that rotates a token: a save replaces the file atomically (temp file + os.replace) under a lock beside it, follows a worktree’s symlinked .env to the real file, and never prints a value. Imported as a sibling by a script under scripts/.

Each tool doc carries its own Setup → Verify procedure; run it by hand, or let the exobrain-tools skill drive it (it never reads or stores a secret value).

Knowledge domains

The durable knowledge areas — see domains.md.

Artifact	Role
knowledge/*/README.md	Each domain’s entry point — frontmatter (name, type, curator, summary) + TL;DR + file index. The one-line summary: is pulled verbatim into the knowledge index.
knowledge index (generated)	Flat catalog of every knowledge domain (name + README path + summary:), composed into each agent’s surface like the tools index — .claude/knowledge-index.md (Claude), or inlined into AGENTS.override.md (Codex) / ~/.openclaw/workspace/USER.md (OpenClaw). Root-only and unscoped (no tiers/overlays), followed by one section per mount — its purpose, audience, and one row per held domain with the charter’s own description, never text the mount’s audience wrote (mounts.md); a function of the committed READMEs, mounts.json, and this machine’s mount state, regenerated on relink.
exobrain-knowledge skill	Builds and maintains knowledge domains (create / distill / curate / update), including setting and refreshing each README’s summary:.

Git workflow

See AGENTS.md → “Git workflow” and the exobrain-persist skill.

Artifact	Role
scripts/create-worktree.sh	Create a worktree off the default branch — symlinks .env* / .exobrain.json into it and invokes link-worktree-context.sh.
scripts/link-worktree-context.sh	Inherit generated markdown, Claude’s per-machine .claude/settings.local.json, and Codex skill folders into a new or existing worktree, preserving destination files. See agents.md § Worktree context.
src/<repo>/ (gitignored)	Clones of external code; src/exobrain-seed/ is the one fixed name — the seed’s update cache for exobrain-evolve.
exobrain-persist skill	The worktree → commit → verify → land procedure and the standing authorization to run it; the agent-judged steps (what is a logical change, which behavior cases a change could move) stay with the agent.
scripts/persist.sh	The mechanical land as one idempotent command, run from inside the worktree or on one named with --repo (a mount’s worktree, validated with this instance’s validator): timeline rows → commit → isolation gate (when mounts are declared) → validator → authoring review → push → PR → squash-merge → fast-forward main → cleanup. A gate finding blocks in every mode, and so does an authoring finding on a land into a mount. Its verification gate refuses an agent-spec change (any scope) that no passing behavior run recorded under tmp/test-runs covers, and lists the covering runs in the PR body; on any other machinery diff it runs the unit suite itself and lands only with --machinery-verified; --detach returns after the commit and lands in the background; --context carries a session handover into the PR body; --sweep lands claimed and quiet worktrees and fails on one left stale; --dry-run prints the plan. An unattended land (detached or swept) posts authoring findings as a comment review on the PR instead of blocking. Semantics in the exobrain-persist skill.
exobrain-repair-findings skill · its scripts/findings-pending.sh	Clears the findings unattended lands record: the script lists merged PRs carrying a findings review and not labelled findings-repaired, oldest first; the skill repairs one PR per isolated session — apply only what each finding prescribes, land in the foreground, label the PR.

Periodic jobs

Artifact	Role
crons.json (per scope, optional)	The scheduled-jobs registry — the source of truth for every recurring job. Discovered at the repo root and in any scope dir (the gitignored local/ included); job names unique across all registries. Each job declares a schedule (cron+tz / every / at), an agent or command payload, delivery (announce on a channel, or silent), and an optional failure alert; {ROOT} in messages and argv expands to the repo root at sync time so registries stay machine-neutral. Full shape: the sync script’s docstring.
scripts/openclaw-cron-sync.py	Reconciles the registries into the OpenClaw cron scheduler on the host running it: owns every gateway job whose declarationKey starts with exobrain., adds/patches/removes to match the registries, and never touches other jobs. Drift is judged only on declared fields, so gateway defaults never fight the sync. --dry-run prints the plan; --check validates registries offline (run by validate-exobrain.sh); --scopes <csv> limits it to the root’s and those scopes’ registries; refuses to run from a linked worktree; OPENCLAW_BIN overrides the binary. The connector runs it with the connected chain on every OpenClaw connect and relink; run it by hand after editing a crons.json in place.

Agent-agnostic mechanism

How one body of content serves Claude, Codex, and OpenClaw without bleed — see agents.md.

Mechanism	Role
Per-scope sidecars CLAUDE.md / CODEX.md / OPENCLAW.md	Agent-specific content at any scope; composed only for the matching agent.
<name>.<agent>.sh script suffix	Agent-specific script variant; invokers pick the right one.
Per-agent surface	Each agent owns its surface and no two write the same file: Claude @-imports .claude/connected-scopes.md plus the generated indexes; Codex reads a generated in-repo AGENTS.override.md; OpenClaw gets the same context inlined into USER.md via marker block.
Non-interference	The linker and fetcher filter by agent / skipAgents, so one agent’s artifacts never enter another’s context.

Propagation

How improvements move between this seed and downstream instances — see propagation.md. This repo is the canonical read-target + generator, so it publishes and harvests rather than adopts.

Artifact	Role
seed/feed/	The published changelog — dated pattern-cards (a problem, a pattern, the files it touches, adapt notes) that instances read (from the seed cache) to adopt. Seed-only; never copied into an instance.
exobrain-evolve skill	The command an instance runs to move forward: fetch the seed into src/exobrain-seed/, diff the feed against its own adoption ledger, copy/re-synthesize each new card, record what it adopted.
seed-harvest skill (seed-only)	The reverse pull: scan the instances listed in .exobrain.json (instances — slugs cached in src/, or local paths read in place), report framework drift, offer the universal ones as a checkbox list, re-synthesize each pick into the framework body, and publish a card. Read-only toward the instances.
harvest ledger (seed-only)	Every candidate seed-harvest presented — adopted (with its card id) or declined (with a reason) — so settled divergence isn’t re-proposed. Untracked, in the gitignored local/ scope.

A downstream instance keeps an adoption ledger (adopted-feed.md at its repo root) of the card IDs it has taken; the seed keeps no adoption ledger, only the harvest ledger of what it pulled up.

Behavioral rules

The rules that drive several of these gates — Reader Lens, propose-a-tool, validate-the-request, audit-the-surface-area, worktree-first, auto-persist — live in root AGENTS.md. They’re auto-loaded, so every agent carries them; this map covers the machinery they trigger.