{"key":"brain_operator_runbook_2026_03_22","title":"Brain Operator Runbook (2026-03-22)","content":"Purpose\n- This is the short operator runbook for the `brain` memory system running on `svc-dev`.\n- Use this for day-to-day operation, validation, and quick recovery.\n\nLocation and services\n- Host: `svc-dev` (`192.168.4.123`)\n- Project path: `/home/svc-admin/projects/brain`\n- Compose file: `/home/svc-admin/projects/brain/docker-compose.yml`\n- Main containers:\n  - `brain-api`\n  - `brain-mcp`\n  - `brain-db`\n\nPorts and endpoints\n- REST API: `http://192.168.4.123:8010`\n- MCP endpoint: `http://192.168.4.123:8011/mcp`\n- Health check: `http://192.168.4.123:8010/health`\n\nCore design\n- One shared brain for multiple AI clients.\n- Separation is handled by `source` values such as `codex`, `claude`, `gemini`, `manual`, and `contextkeep`.\n- Default DB mode is bundled Postgres in the compose stack.\n- External Postgres later only requires changing `DATABASE_URL` in `.env`.\n\nCurrent state\n- ContextKeep legacy memories have already been imported.\n- Imported memory count at import time: `54`.\n- Imported records use `source=contextkeep`.\n- Codex, Claude, and Gemini were all configured to point to the same MCP endpoint.\n\nUseful API operations\n- List memories:\n  - `curl http://192.168.4.123:8010/memories?status=all | jq`\n- Filter by source:\n  - `curl \"http://192.168.4.123:8010/memories?source=codex&status=all\" | jq`\n  - `curl \"http://192.168.4.123:8010/memories?source=contextkeep&status=all\" | jq`\n- Get one memory:\n  - `curl http://192.168.4.123:8010/memories/<key> | jq`\n- List tags:\n  - `curl http://192.168.4.123:8010/tags | jq`\n\nUseful compose commands\n- Check status:\n  - `cd /home/svc-admin/projects/brain && docker compose ps`\n- View logs:\n  - `cd /home/svc-admin/projects/brain && docker compose logs --tail=100 api`\n  - `cd /home/svc-admin/projects/brain && docker compose logs --tail=100 mcp`\n  - `cd /home/svc-admin/projects/brain && docker compose logs --tail=100 db`\n- Restart stack:\n  - `cd /home/svc-admin/projects/brain && docker compose restart`\n- Rebuild after code changes:\n  - `cd /home/svc-admin/projects/brain && docker compose up -d --build`\n\nDatabase notes\n- DB name: `ai-brain`\n- DB user: `ai-brain`\n- Local/default connection is driven by `.env` via `DATABASE_URL`.\n- Alembic migrations run on container startup.\n\nValidation checklist\n- `docker compose ps` shows all three containers up\n- `curl http://127.0.0.1:8010/health` returns OK on the host\n- `curl http://127.0.0.1:8010/memories?status=all | jq length` returns records\n- MCP endpoint is reachable by the configured AI clients\n\nKnown quirks\n- MCP host-header restrictions had to be explicitly opened for `192.168.4.123` and `svc-dev`.\n- If the MCP endpoint starts rejecting clients again, inspect `backend/app/mcp_server.py` first.\n- ContextKeep import was done directly from its JSON store because the old ContextKeep MCP transport became unreliable during bulk reads.\n\nClient wiring notes\n- Codex uses `~/.codex/config.toml`\n- Claude uses `~/.claude.json`\n- Gemini uses `~/.gemini/settings.json`\n- All should point to `http://192.168.4.123:8011/mcp` for the shared brain\n\nOperational recommendations\n- Use `source=codex`, `source=claude`, `source=gemini`, or `source=manual` consistently for new writes.\n- Keep imported legacy data under `source=contextkeep`.\n- Treat REST as the admin/debug interface and MCP as the normal AI client interface.\n\nCurrent gaps\n- No web UI yet\n- No `namespace` field yet\n- No built-in reusable import command yet\n\nRelated reference memory\n- Detailed implementation handoff: `brain_project_implementation_handoff_2026_03_22`\n\nThis runbook is the short operational companion to the full implementation handoff.","summary":"Purpose\n- This is the short operator runbook for the `brain` memory system running on `svc-dev`.\n- Use this for day-to-day operation, validation, and quick recovery.\n\nLocation and services\n- Host: `svc-dev` (`192.168.4.123`)\n- Project path: `/home/svc-admin/projects/brain`\n- Compose file: `/home/svc-admin/projects/brain/docker-compose.yml`\n- Main containers:\n  - `brain-api`\n  - `brain-mcp`\n  - `brain-db`\n\nPorts and endpoints\n- REST API: `http://192.168.4.123:8010`\n- MCP endpoint: `http://192.168.4.123:8011/mcp`\n- Health check: `http://192.168.4.123:8010/health`\n\nCore design\n- One shared brain for multiple AI clients.\n- Separation is handled by `source` values such as `codex`, `claude`, `gemini`, `manual`, and `contextkeep`.\n- Default DB mode is bundled Postgres in the compose stack.\n- External Postgres later only requires changing `DATABASE_URL` in `.env`.\n\nCurrent state\n- ContextKeep legacy memories have already been imported.\n- Imported memory count at import time: `54`.\n- Imported records use `source=contextkeep`.\n- Codex, Claude, and Gemini were all configured to point to the same MCP endpoint.\n\nUseful API operations\n- List memories:\n  - `curl http://192.168.4.123:8010/memories?status=all | jq`\n- Filter by source:\n  - `curl \"http://192.168.4.123:8010/memories?source=codex&status=all\" | jq`\n  - `curl \"http://192.168.4.123:8010/memories?source=contextkeep&status=all\" | jq`\n- Get one memory:\n  - `curl http://192.168.4.123:8010/memories/<key> | jq`\n- List tags:\n  - `curl http://192.168.4.123:8010/tags | jq`\n\nUseful compose commands\n- Check status:\n  - `cd /home/svc-admin/projects/brain && docker compose ps`\n- View logs:\n  - `cd /home/svc-admin/projects/brain && docker compose logs --tail=100 api`\n  - `cd /home/svc-admin/projects/brain && docker compose logs --tail=100 mcp`\n  - `cd /home/svc-admin/projects/brain && docker compose logs --tail=100 db`\n- Restart stack:\n  - `cd /home/svc-admin/projects/brain && docker compose restart`\n- Rebuild after code changes:\n  - `cd /home/svc-admin/projects/brain && docker compose up -d --build`\n\nDatabase notes\n- DB name: `ai-brain`\n- DB user: `ai-brain`\n- Local/default connection is driven by `.env` via `DATABASE_URL`.\n- Alembic migrations run on container startup.\n\nValidation checklist\n- `docker compose ps` shows all three containers up\n- `curl http://127.0.0.1:8010/health` returns OK on the host\n- `curl http://127.0.0.1:8010/memories?status=all | jq length` returns records\n- MCP endpoint is reachable by the configured AI clients\n\nKnown quirks\n- MCP host-header restrictions had to be explicitly opened for `192.168.4.123` and `svc-dev`.\n- If the MCP endpoint starts rejecting clients again, inspect `backend/app/mcp_server.py` first.\n- ContextKeep import was done directly from its JSON store because the old ContextKeep MCP transport became unreliable during bulk reads.\n\nClient wiring notes\n- Codex uses `~/.codex/config.toml`\n- Claude uses `~/.claude.json`\n- Gemini uses `~/.gemini/settings.json`\n- All should point to `http://192.168.4.123:8011/mcp` for the shared brain\n\nOperational recommendations\n- Use `source=codex`, `source=claude`, `source=gemini`, or `source=manual` consistently for new writes.\n- Keep imported legacy data under `source=contextkeep`.\n- Treat REST as the admin/debug interface and MCP as the normal AI client interface.\n\nCurrent gaps\n- No web UI yet\n- No `namespace` field yet\n- No built-in reusable import command yet\n\nRelated reference memory\n- Detailed implementation handoff: `brain_project_implementation_handoff_2026_03_22`\n\nThis runbook is the short operational companion to the full implementation handoff.","status":"active","namespace":"general","namespace_name":"general","namespace_tier":"shared","tags":[]}