distill: Instructions file for Claude Code

Distill — Privacy-first Team Memory MCP Server

What this is

An MCP server that gives Claude Code access to a shared team knowledge base. Raw developer input is distilled into anonymous factual knowledge by an LLM before being stored.

Core principle

By default, the local LLM is the privacy component. Raw text → Ollama (local) → distilled fact → team DB. Three independent axes: BACKEND (storage), EMBEDDING_PROVIDER, DISTILLER_PROVIDER. Setting DISTILLER_PROVIDER=gemini sends raw text to Google instead of keeping it local.

Architecture (Uncle Bob / Clean Architecture)

Dependencies point inward. Business logic has no knowledge of frameworks, databases, or transport.

src/distill_mcp/
├── domain/              # Inner ring: pure business logic, no dependencies
│   ├── models.py        # Memory, DistilledMemory, SearchResult (dataclasses/Pydantic)
│   ├── ports.py         # Abstract interfaces (StoragePort, EmbeddingPort, DistillerPort)
│   └── services.py      # Use cases: search, get, update, list_recent, forget (depends only on ports)
│
├── adapters/            # Outer ring: implementations of ports
│   ├── storage/
│   │   ├── sqlite_store.py    # StoragePort → SQLite + FTS5 + LanceDB
│   │   └── postgres_store.py  # StoragePort → asyncpg + pgvector + tsvector
│   ├── embeddings/
│   │   ├── ollama_embed.py    # EmbeddingPort → local Ollama
│   │   ├── vertex_embed.py    # EmbeddingPort → Vertex AI
│   │   └── gemini_embed.py    # EmbeddingPort → Gemini API
│   └── distiller/
│       ├── ollama_distill.py  # DistillerPort → local Ollama
│       └── gemini_distill.py  # DistillerPort → Gemini API
│
├── server.py            # FastMCP tool definitions — thin adapter calling services
├── ingest.py            # Auto-observe: receives raw hook events, queues for worker
├── worker.py            # Background worker: distills and stores queued events
├── config.py            # pydantic-settings, env var loading
├── dedup.py             # Cosine similarity > 0.95 check
├── private_store.py     # Raw text → local JSONL (never synced)
├── cli.py               # seed, export commands
└── __main__.py          # Entry point: wires adapters, starts FastMCP