HivemindOS manual

Sync and repair Hive Superbrain

Your vault is the brain; sync just gives your trusted machines the same files. Pick exactly one service to sync the vault. Two sync systems on the same folder are a common cause of conflict copies and confusing history.

For the feature overview, see Hivemind Sync. For your phone’s notes and skills, see Your Brain on phone and desktop.

Choose one sync owner

Owner	Use when
External provider	Obsidian Sync, iCloud Drive, Dropbox, Git, or your own Syncthing already syncs the vault.
HivemindOS Syncthing	Your trusted machines should pair over Tailscale or Link and each keep a local copy.
One-time repair	You need to copy a known-good vault from one machine to another.

When HivemindOS runs Syncthing, it fixes common pauses and pairing problems on its own. Fleet warns you only when that repair fails.

When you see a health warning

Wait a moment for automatic repair, then refresh Fleet health.
Check that the machine is online and your sync owner is running.
Make sure no second sync service is watching the same vault.
Run the vault doctor in read-only mode:
```
pnpm vault:doctor
```
If it proposes cleanup, back up your vault, then run pnpm vault:doctor -- --fix. The fix moves old or conflicting files to a recoverable place and writes a manifest; it never silently deletes.

Handoffs and secrets

HivemindOS may use a hidden vault folder to move task files between trusted machines. Treat it like any synced vault data, not as a secure channel. API keys belong in Shared Env.

Open the repair, recovery, and storage reference

Automatic Syncthing repair

Before showing a warning, Fleet health starts Syncthing when possible, resumes paused folders and devices, restores the vault’s paired devices, recreates .stfolder, rescans, and reports before/after health.

When HivemindOS pairs or repairs the vault folder, it also adds a marked block to that device’s .stignore so search indexes an older app version may still write into the vault never sync. Indexes are rebuilt on each device from the notes. Anything else in .stignore is left alone, and uninstall removes only that block.

Handoff transfers

Handoff files live in .hivemindos-transfers/. Use hive-handoff, /handoff-task, or hivemind-mcp so HivemindOS can match the target machine and pick the best receiving agent. Each transfer has a manifest, payload files, hashes, and acknowledgements. The folder is safe to sync but never safe for secrets.

Vault doctor

pnpm vault:doctor is read-only by default. With --fix, it moves content into standard folders or archives it. It checks for:

duplicate shared skills (by SKILL.md hash)
sync conflict and backup files
retired top-level folders and files
leftover hive-e2e-* test skills
misplaced AEON profile stubs and runtime mirrors
legacy Notes/ content and root Scheduled/ state
search indexes and index history left in the vault by an older version (each device now keeps its own, outside the vault)

Every fix writes a manifest to Operations/Vault Migrations/<timestamp>-vault-doctor/manifest.jsonl. These are your audit trail; don’t delete them casually.

Memory integrity and recovery

hive-brain health --json reports the current memory generation, retained and invalid generations, replay coverage, retention policy, journal size, embedding coverage, and active memories per layer. hive-brain generations lists each retained generation and the earliest generation from which replay is complete.

Reads verify checksums. If the current index is damaged, recall falls back to the newest verified older generation. Typed memory keeps at most 256 generations (a checkpoint every 32); full-vault search keeps at most 32 (every 4). Pruning never touches your Markdown notes, and it pauses if its coverage record is damaged or missing, until a good synced or backed-up copy is restored.

Memory writes are journaled. After a crash, the next write finishes staged files and rebuilds indexes from Markdown, so you never need to hand-edit generated files. Indexes and their history live on each device, outside the vault; deleting them is safe, and the next recall rebuilds them.

Opening a brain capsule checks its checksums, counts, and expiry; encrypted capsules also verify their authentication tag. Plain checksums catch corruption but don’t prove who sent it. Capsule imports stay proposals until approved in Brain Review.

Compiled Knowledge health

Use /api/brain/knowledge with action: "scan-health" to find broken links, orphan pages, duplicate slugs, and missing backlinks in Synthesis/Compiled Knowledge/<domain>/wiki/. action: "fix-health" applies only safe fixes. Other issues stay visible until dismissed with action: "dismiss-health"; dismissals are saved in that wiki’s .health-dismissed.jsonl. Only you can dismiss an issue; agents can apply the safe fixes.

Secure backups

Encrypted backups and public-key notes live in Operations/Secure (which replaces the retired Notes/Secure). Never store plaintext secrets in the vault. See Shared Env.