second-brain-mcp AGENTS.md

AGENTS.md — Second Brain Operating Manual for AI Agents

Read this document before making any vault changes. It defines tool usage, note types, security rules, and standard operating procedures.

How to get this document: When connected via MCP, call get_agent_instructions(). When working locally with Claude Code in the second-brain/ directory, it is auto-loaded via CLAUDE.md.

When adding documentation: modify the relevant section here, then update the Last updated date.

Last updated: 2026-09-03

---

System Overview

Second Brain is a personal knowledge management server that exposes vault read/write, search, archiving, and maintenance via MCP.

• MCP server: server.py (40 tools — see Tool Reference; keep this count in sync when adding/removing tools)
• Index backend: pluggable VaultStore (store/), selected by SB_DB_BACKEND:
  • postgres (central brain) — store/postgres_store.py, Postgres 16 + pgvector + pg_trgm, connection-pooled, multi-machine concurrent read/write via MVCC.
  • duckdb (default / offline fallback) — store/duckdb_store.py wrapping vault_db.py.
• Vault path: controlled by environment variable SECOND_BRAIN_PATH
• Source of truth: markdown is canonical (L1); the index (Postgres or DuckDB) is a rebuildable L2 — sync_all regenerates it from markdown. Switching backends never touches markdown.

---

Connection Topology & Write Discipline

The production setup is one central HTTP server + Postgres; clients never touch Postgres directly.

• Central host: the mac-mini <central-host>, Tailscale <tailscale-ip> (SSH as <user>).
• Central server: launchd com.user.second-brain-remote, streamable-http bound to the Tailscale IP :9100, SB_DB_BACKEND=postgres. Single instance (PID guard).
• Sibling instances on the same host and the same package: lcdda (:9104, a second vault) and lcdda-harvest (:9106). They import the same mcp_second_brain from the same venv, so one pip install changes all three — deploying means restarting all three, or new and old code run side by side. (finance-kit on :9108 is a separate codebase.)
• Postgres: Docker sb-pg, bound to 127.0.0.1:5432 only — never exposed off-host.
• Clients connect via MCP over HTTP: http://<tailscale-ip>:9100/mcp with header X-API-Key: <key> (auth is enforced when SB_API_KEY/SB_API_KEYS is set on the server). Setup per client type is in NEW_MACHINE_SETUP.md §A.
• Index freshness: com.user.second-brain-pg-sync runs sync_incremental against Postgres at minute :00 and :30 via StartCalendarInterval, so cron-driven markdown edits do not let the index drift. Keep the source plist template on calendar triggers; StartInterval=1800 was observed to stall on the central host.
• Backups: com.user.second-brain-pg-backup runs pg_dump daily (markdown is still the real backup; this only speeds recovery).