LLM-MCP: 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

A Model Context Protocol (MCP) server that gives AI assistants persistent, cross-platform memory backed by PostgreSQL + pgvector. Any MCP-capable platform (Cursor, Claude Desktop, VS Code Copilot, Windsurf, Gemini, etc.) connects to one shared memory store over Streamable HTTP, so anything learned in one tool is recalled in all the others.

Run / build / test

Everything runs via Docker Compose (Postgres + Ollama + MCP server + dashboard):

./setup.sh                      # one-shot: writes .env, builds, starts all services, prints platform configs
docker compose up -d --build    # build + start
docker compose logs -f mcp-server
docker compose logs -f ollama   # watch the first-boot model pull (~274MB)
docker compose restart
docker compose down             # stop (add -v to wipe the pgdata + ollama_models volumes)

Tests are integration tests — they require the server to be running (they connect to http://localhost:4040/mcp over the live MCP protocol; there are no unit tests or mocks):

python test_client.py       # exercises the core tools end-to-end
python test_versioning.py   # versioning + cross-platform conflict resolution
python test_prompts.py      # MCP prompt discovery

Run a single test by editing the relevant main() — these are scripts, not a pytest suite.

Ports

• 4040 — MCP server, endpoint is http://localhost:4040/mcp
• 4041 — web dashboard (dashboard.py)
• 4569 — host-mapped Postgres (maps to container 5432)
• 9050 — Ollama API (embeddings); the server reaches it in-network at http://ollama:9050

Inside the Docker network services reach Postgres on 5432; from the host it's 4569. DATABASE_URL differs between .env (host port) and docker-compose.yml (container port) for this reason.

Architecture

Three-layer split, no ORM:

• server.py — the MCP surface. Defines ~38 @mcp.tool()s, several @mcp.prompt()s, and memory:// resources via FastMCP. Tools are thin wrappers that call into db.py and return JSON strings. The FastMCP(instructions=...) block is a large behavioral contract that tells connected LLMs to auto-save preferences/facts/decisions and call recall/get_working_context at conversation start — editing it changes how every connected assistant behaves.
• db.py — all SQL and business logic (~2500 lines). Owns the schema (DDL string executed on init_db()), the asyncpg connection pool, and every query. All persistence logic lives here, not in server.py.
• embeddings.py — pluggable embedding provider selected by EMBEDDING_PROVIDER (local | ollama | openai). Default is ollama (neural embeddings from the bundled Ollama container, nomic-embed-text, 768-dim). ACTIVE_DIM/get_embedding_dim() is the single source of truth for the vector dimension; the local hash fallback projects to ACTIVE_DIM so a brief Ollama outage still yields insert-compatible vectors. Always falls back to the local hash embedder on any error or missing key.
• dashboard.py — separate Starlette app serving static/index.html plus a read/write REST API over the same db.py.