AOS Setup — Machine Level

Installing the AOS npm package is the easy half. The half that quietly fails is everything around it: memB has no venv, the ambient memory hook was never wired, OpenWiki has a CLI but no provider credentials, Synapse's binary is not on PATH. The result is a machine where most skills work and the memory, documentation and visualization layers silently do nothing.

This skill closes that gap: measure first, then fix only what is broken.

This is also where a new agent harness gets wired: adding Codex or Antigravity to a machine that already runs Claude Code is this skill's job, not a reinstall.

For per-project wiring — a folder's slug, its wiki, its memB binding — use /aos-project-init after this one.

What each harness can actually do

Portability is not uniform, and pretending otherwise is how people end up believing memory works everywhere:

	Skills	MCP	Hooks
Claude Code	~/.claude/skills	~/.claude.json	yes
Antigravity	~/.gemini/config/skills	mcp_config.json	yes (.agents/hooks.json / hooks.json)
Codex	~/.codex/skills	config.toml	yes (config.toml)
OpenCode	—	opencode.jsonc	no
Cursor / Roo	bdb-skills	mcp.json	no

Claude Code, Google Antigravity, and OpenAI Codex have native hook support, allowing memB to inject ambient memory per prompt across all three harnesses. For hookless harnesses (Cursor, Roo, OpenCode, Windsurf), the same context arrives through the rule files that harness loads at start — see section 5 — which means it is as fresh as the last write, not as fresh as the prompt. Say so plainly rather than letting someone assume parity.

---

1. Measure

Run the doctor. It is read-only; it installs and edits nothing.

node skills/global_config/aos-setup/scripts/aos-doctor.mjs        # from the AOS repo
node ~/.claude/skills/aos-setup/scripts/aos-doctor.mjs            # from an installed copy

Flags: --json for machine-readable output, --net to also compare the installed AOS version against npm.

It reports up to 29 checks across seven areas, each with the exact fix command. The exact number varies by machine: the LaunchAgent rows are macOS-only, the OpenWiki integrations row needs the CLI on PATH, the npm-version row needs --net, and the optional-module rows appear only for modules the manifest claims are installed.

Area	What is verified
prereq	Node ≥ 22, python3, git, uv, gh
aos	~/.agents/.bdb-manifest.json, skills synced into each harness's skill directory
hooks	go-gate.mjs, graph-gate.mjs, memb-inject.mjs — present and wired in ~/.claude/settings.json
memB	module, venv, ~/.MemBDB/memb.db, WebUI on :8088, autostart, memb-mcp venv, MCP registration
openwiki	CLI, ~/.openwiki/.env credentials, harness integrations, 2-hourly refresh daemon
synapse	binary on PATH, daemon on :7781
memory	identity layer (≥ 10 godmode facts), share of raw file chunks, stale paths

Exit code is 0 only when every check passes. Report the failing rows to the user before changing anything, then work the sections below in order — each one covers a block the doctor can flag.

---

2. Machine configuration

Two things are machine-specific and ship with no value, because AOS is a public package: one person's web, media, infra means nothing on someone else's disk.

aos-config propose     # read this machine's layout, suggest nothing more
aos-config show        # what is configured now

propose looks for a workspace root (~/dev, ~/Projects, ~/src, ~/code) and offers its immediate subdirectories as the domain vocabulary. Present the proposal, do not apply it — the user decides which of those are real domains and which are just folders. Then ask for the memB user_id, which must never be invented either.

aos-config set workspaceRoot ~/dev
aos-config set domains bdb-core,web,media,agents,infra
aos-config set userId <the user's memB id>

The result lands in ~/.agents/aos-config.json. /aos-project-init reads it to offer a domain per project and refuses to guess when it is missing.

The identity layer (godmode facts)

With workspaceRoot and userId set, section 2 has one more job: the identity interview, which fills memB's godmode layer — the standing facts about the person this machine belongs to, injected into every prompt. The doctor's memory rows report whether this layer exists.

Run it as a conversation, one question at a time: who the user is and their role, company and brands, how the workspace is structured, and their ground rules. Propose sources instead of asking blind — glob WORKSPACE.md, AGENTS.md and agents.md directly under the configured workspace root (e.g. ~/dev/WORKSPACE.md) and offer each as source material before using it. Never read the whole tree.

From the answers, draft 20–40 facts, one sentence each, each ≤ 300 chars. Show the full numbered list to the user and save only after explicit confirmation — writes happen only on a literal GO.

Save each fact via the memb-mcp add_memory tool, exactly this shape:

add_memory({ text: <fact>, category: "godmode", infer: false })

The shape is load-bearing. No project_id: omitting it stores the fact globally, which is what makes it identity rather than project context. infer: false: the text is stored verbatim, never LLM-rewritten. user_id defaults to bdb_developer, which the ambient hook accepts as its baseline user. Never write credentials or high-entropy strings into a fact.

---

3. Install or update AOS itself

npx -y @hybridlabor-api/aos@latest

The interactive installer asks which harnesses to target (Claude Code, Gemini / Antigravity, Codex, OpenCode, Claude Desktop, …), which MCP servers to wire, and which optional modules to pull. Non-interactive variants:

npx -y @hybridlabor-api/aos -y --platforms=2      # unattended, one platform
npx -y @hybridlabor-api/aos --dry-run             # show what it would do

Two things worth insisting on when the installer asks:

• Pick every harness the user actually runs. A harness left unselected gets no skills at all, which is the single most common "AOS doesn't work here".
• Enable the optional modules — memB, Synapse, OS Remote, Creator Extension, Tool Installer. They are what the doctor's memB and Synapse sections check for.

The installer writes ~/.agents/.bdb-manifest.json. If that file is absent, nothing was ever installed globally, no matter how many skills happen to sit in a harness directory.

---

4. memB — memory that actually retains

memB is three separate pieces, and a machine can have any subset:

Piece	Lives at	Doctor row
Engine + WebUI	~/.agents/memB (venv, :8088 daemon)	module, python venv, WebUI :8088, autostart
MCP server	~/.gemini/config/mcps/memb-mcp (venv + run.py)	memb-mcp server, memb_mcp registered
Ambient hook	~/.claude/hooks/memb-inject.mjs	memb-inject.mjs, memb-inject.mjs wired

The engine and the MCP come from the installer. If the venv is missing, repair it in place rather than reinstalling everything:

cd ~/.agents/memB
uv venv --seed .venv
uv pip install --python .venv/bin/python -r requirements.txt

uv venv --seed has been observed to create a venv without pip; that is why uv pip install --python <venv> is the command above and not python -m pip.

The store lives in ~/.MemBDB/memb.db. An empty store is normal on a fresh machine — /aos-project-init seeds it per project.

---

5. The ambient memory hook

The hook is what makes memB ambient rather than something an agent has to remember to query. On every prompt it reads the SQLite store directly and injects the relevant memories as context. It fails open: any error exits 0 and the prompt proceeds untouched.

Since v4.4.0 the installer ships memb-inject.mjs into ~/.claude/hooks/ and wires it as an automated prompt hook across Claude Code (UserPromptSubmit in settings.json), Google Antigravity (PreInvocation in hooks.json / .agents/hooks.json), and OpenAI Codex (UserPromptSubmit in config.toml). v4.4.0's Quick Update did not — it refreshes skills and submodules, and hooks are harness plumbing rather than skills, so a machine that already had AOS updated to 4.4.0 without ever receiving the hook. Fixed in v4.4.1; a machine that took that update needs one more run:

npx -y @hybridlabor-api/aos@latest

The wiring is merged into ~/.claude/settings.json, Antigravity hooks.json, and Codex config.toml, never written over them: user keys and foreign hook entries survive, and a re-run replaces the BDB entry rather than adding a second copy.

The hook carries an aos-hook-version: line on its second line, and the doctor compares it against what the installed release expects. That is why the row can read stale rather than simply passing: a hook file that exists and is wired can still be an old copy carrying a bug this version fixed. When you change the hook in a way machines must pick up, bump that line and the expected value in aos-doctor.mjs in the same commit — the test suite fails if the two disagree.

Unlike the two gate hooks, this one stays $HOME-anchored even in a project harness — the memB store is machine-global, and pointing it at $CLAUDE_PROJECT_DIR would make it fail on every prompt in any project the harness was never installed into.

On hookless harnesses — Cursor, Roo, OpenCode, Windsurf — native hooks are not supported, so the same context is written into the rule files that harness loads instead:

python3 ~/.agents/memB/memb_auto_inject.py --global      # RULES.md, CODEX.md, …
python3 ~/.agents/memB/memb_auto_inject.py --dir <repo>  # a project's AGENTS.md

It merges into a delimited block and leaves everything outside it alone. The block carries the time it was written, because this path is only ever as fresh as its last run.

Standing facts that should reach every prompt — persona, brand rules, house style — go one per line into ~/.MemBDB/ambient-persona.txt. Lines starting with # are ignored. This file is deliberately not shipped: ask the user what belongs there rather than inventing it, and never copy another machine's.

Verify by starting a session and checking that the first prompt carries a [memB Ambient Memory Context] block.

---

6. OpenWiki

npm install -g openwiki@latest        # CLI, needs Node >= 22
openwiki --init                       # run in a repo: the wizard saves provider, model and key to ~/.openwiki/.env
                                      # (`openwiki auth <x>` only authenticates connectors: slack, gmail, x, notion)
openwiki integrations list            # per-harness host integration status
openwiki integrations install claude  # repeat for codex / cursor / opencode

Credentials land in ~/.openwiki/.env. Without them every wiki run fails at auth — the CLI being on PATH proves nothing on its own.

The 2-hourly refresh daemon comes from the AOS installer when an OpenWiki API key is supplied. To install it separately:

bash ~/.claude/skills/openwiki-skill/scripts/install_daemon.sh          # macOS / Linux
powershell -ExecutionPolicy Bypass -File install_daemon.ps1             # Windows

Wikis themselves are per-repository (.openwiki/ in each project) — that is /aos-project-init's job, not this one's.

---

7. Synapse

The installer downloads the module, symlinks the binary to ~/.local/bin/synapse and registers a daemon on port 7781. Two failure modes the doctor separates deliberately:

• Binary not found — usually ~/.local/bin missing from PATH. Add it to the shell profile; do not copy the binary somewhere else.
• Port closed — the daemon is not running. On macOS: launchctl load -w ~/Library/LaunchAgents/com.bdb.synapse.plist.

If no pre-built binary exists for the platform, build it: cd ~/.agents/bdb-synapse && go build -o synapse ./cmd/synapse/.

---

8. The dashboard

aos-dashboard serves one page on http://127.0.0.1:7900 showing every BDB service live — memB, Synapse, the OpenWiki daemon, AO Orchestrator and RemoteOS — with its version, port, LaunchAgent state, start/stop/restart, and its log files inline. It polls every five seconds.

aos-dashboard                 # opens the browser
aos-dashboard --no-open       # just serve
aos-dashboard --port 7901     # if 7900 is taken

It binds to 127.0.0.1 only, and every control action is matched against a fixed service table — an id or action the table does not contain is refused, and no value from the request ever reaches a shell or a file path.

It also surfaces causes a port probe cannot see. The AO Orchestrator card checks the code signature of ~/.local/bin/ao: a binary rebuilt and copied into place unsigned is SIGKILLed by AMFI at launch (exit 137), which otherwise looks like a daemon that is simply down, with nothing in the log. The fix it names is codesign -s - -f ~/.local/bin/ao.

Use it when the user asks what is running, or when a doctor row says a port is closed and the question is why.

---

9. Confirm

Re-run the doctor. Do not report success from the fact that commands ran — report the doctor's own count:

node skills/global_config/aos-setup/scripts/aos-doctor.mjs
# 26/26 checks pass. AOS is fully wired.

Anything still failing that the user deliberately does not want (no Synapse on a headless server, no OpenWiki daemon on a laptop) is fine — say so explicitly instead of leaving it looking broken.

Then hand off: the machine is ready; per-project setup runs through /aos-project-init in each repository.

---

Red flags

• Reporting "AOS installed" on the strength of a successful npx run. The installer succeeds happily with memB skipped and no hook wired.
• Overwriting ~/.claude/settings.json instead of merging into its hooks object — that silently removes the go-gate.
• Treating an empty ~/.MemBDB as a defect. It is the expected state until something is ingested.
• Copying the reference machine's persona file verbatim onto someone else's computer. Ask what their standing facts are.
• Saving godmode facts the user never saw — the interview shows the list first, always.