openbrain-operator

name	openbrain-operator
description	Operate and troubleshoot OpenBrain memory through the `brain` CLI and OpenBrain HTTP API. Use when the user asks to capture thoughts, run semantic search, review recent/history, check stats/health, tune retrieval, or diagnose why memory read/write is failing.

OpenBrain Operator

This is the primary operator workflow and is optimized for localhost installations. Use this file as the default source of truth. Do not use repo-wide docs.

LAN Switch Rule (Required)

• references/lan-operations.md
• references/troubleshooting.md

1. Run:

brain health

If brain is unavailable:

npm run brain -- health

2. If health JSON shows "mode": "remote":
   • Switch to LAN workflow by loading references/lan-operations.md.
   • For this run, treat localhost instructions in this file as deleted.
   • Continue with LAN commands only.
3. If health JSON shows "mode": "local":
   • Stay in this file and run localhost workflow below.
4. If both CONVEX_URL and OPENBRAIN_REMOTE_URL exist, remote wins (lan).

Localhost Workflow (Default)

1. Preflight

node -v
npm -v
brain health

If brain is not found:

npm run brain -- health

Health must return JSON containing:

• "ok": true
• "mode": "local"

2. Core Operations

Capture:

brain capture "Decided to delay launch for QA blockers" --tags planning,qa

Search:

brain search "What did I note about QA blockers?" --limit 8 --threshold 0.2
brain search "What did I note about QA blockers?" today

Recent:

brain recent --limit 20
brain recent today

Stats:

brain stats

Remove:

brain remove --recent 1
brain remove --content "Decided to delay launch for QA blockers"
brain remove --query "the note about delaying launch"

3. Remove Validation

1. Inspect candidates:

brain recent --limit 20

2. Remove one thought:

brain remove --recent 1

3. Verify the thought is gone:

brain recent --limit 20
brain search "<same content>" --limit 20 --threshold 0.0

4. Retrieval Tuning

If too strict:

brain search "<query>" --limit 20 --threshold 0.0

If too noisy:

brain search "<query>" --limit 8 --threshold 0.3

Localhost Troubleshooting (Fast Path)

• brain: command not found:

npm run link:global
which brain

• Health fails:
  • Run npm run brain -- health.
  • If still failing, load references/troubleshooting.md.
• 401 unauthorized:
  • Align OPENBRAIN_API_KEY.
  • See references/troubleshooting.md.

Execution Contract

1. Execute only commands for the active mode.
2. Verify each step with concrete evidence (ok, IDs, counts, or HTTP responses).
3. On first failure, switch to references/troubleshooting.md and run the matching fix path.
4. Re-run health after each fix before continuing.

Response Contract

1. Report active mode (localhost or lan).
2. Show exact commands executed.
3. Show key outputs:
   • Health status.
   • Saved/removed thought summary when applicable.
   • Search results or empty result.
4. If unresolved, provide one next action with the exact command.