commonplace: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

commonplace is infrastructure only — a Docker Compose stack, two MCP config files, a Dockerfile, seven build-time patches, and a second image for the Whelk Server org brain (brain/). There is no application source and no lint step. The only test is the brain image's end-to-end smoke test (brain/test/smoke.sh), which CI runs. It deploys a self-hosted, two-tier Graphiti knowledge graph that Claude Code and Pi use as long-term memory over a Tailscale tailnet.

Read README.md first — it is the real documentation. It contains the architecture diagram, the endpoint/graph map, a 15-item "Gotchas" list, and client-config instructions. This file summarizes only the load-bearing facts and points back to it.

Deployment model (source of truth lives in two places)

• The repo is the source of truth for config. Edit a clone → push → on the host git pull → docker compose up -d.
• Runtime + secrets live only on the host (a Linux server with Docker, Ollama, and an optional consumer NVIDIA GPU) in the repo directory (e.g. ~/commonplace). Other devices are pure clients — they host nothing.
• Secrets are in .env on the host only (gitignored; .dockerignore also excludes it from the build context). .env.example is the template. Never commit real values.

Architecture invariants (don't break these)

• One FalkorDB, two graphs. Both MCP instances share one FalkorDB; the graph is selected per instance by FALKORDB_DATABASE (commonplace_personal vs commonplace_client). group_id does not select the graph — it only namespaces nodes within one.
• Two MCP instances, one custom image. commonplace-mcp:local is built locally from zepai/knowledge-graph-mcp:standalone (see Dockerfile) — the upstream :standalone image lacks the anthropic SDK and rejects remote Host headers, so the Dockerfile adds the SDK and runs patch_transport_security.py (plus patch_agent_identity.py → add_memory agent_id, patch_entity_fields.py → optional typed entity fields, patch_content_guard.py → reject_pattern tier guard, patch_queue_backpressure.py → max_queue_size GPU backpressure, patch_episode_uuids.py → get_episodes(uuids=…), and patch_serial_ingest.py → one episode at a time across groups, so concurrent groups cannot cross-write graphs). Use :standalone, never :latest (the latter bundles its own FalkorDB and can't share one).
• Offline-first. Both tiers extract locally (mistral:7b-instruct-q4_0 on the GPU) by default — no API keys, nothing leaves the box. The personal tier (config/personal.yaml, host :8000) is env-switchable to a HOSTED model for non-confidential data: set PERSONAL_LLM_PROVIDER=anthropic / PERSONAL_LLM_MODEL=claude-haiku-4-5 / PERSONAL_SEMAPHORE_LIMIT=5 / ANTHROPIC_API_KEY in .env (both provider blocks always exist; provider picks one). The client tier (config/client.yaml, host :8001) is always local — confidential data never leaves the box. Concurrency: SEMAPHORE_LIMIT defaults to 1 (GPU-bound); raise the personal tier to 5 if you switch it to hosted. Both env-overridable in docker-compose.yml. Optional GPU backpressure: set graphiti.max_queue_size and add_memory refuses new episodes once that many are pending (via patch_queue_backpressure.py); 0 = unbounded (default).
• Gateway fronts both tiers. The gateway service (Caddy, gateway/Caddyfile) owns host ports :8000/:8001; the MCP containers are internal-only (expose, no host ports). It enforces per-tier bearer auth (PERSONAL_TOKEN/CLIENT_TOKEN) — separate tokens = tier isolation — and emits JSON access logs (audit) + Prometheus metrics (:9180, host-local). Clients must send Authorization: Bearer <token>. Optional defense-in-depth: set graphiti.reject_pattern (a regex) in a tier's config and add_memory refuses matching content (payload-level guard, via patch_content_guard.py) — e.g. the personal tier rejecting confidential-tagged writes.
• Shared embedder. Both tiers use Ollama nomic-embed-text (768-dim). Do not change the embedder on only one tier — vectors from different embedders are not comparable.
• MCP path has a trailing slash: /mcp/ (FastMCP default, not configurable). FalkorDB UI is on :3000; FalkorDB :6379 binds to 127.0.0.1 only.
• Ollama runs on the host, so each MCP service needs extra_hosts: host.docker.internal:host-gateway and an api_url of http://host.docker.internal:11434/v1.