Brain

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