potluck

Potluck

Privacy-first personal knowledge database for your AI — local-first, MCP-native.

Potluck ingests your data exports — Google Takeout (Gmail, Keep, Calendar, Chat, Chrome history, Photos metadata, Timeline), WhatsApp, Reddit, YNAB, plus generic folders of images, notes, and mbox files — stores everything in one local SQLite database, and exposes it three ways: a web app, a CLI, and MCP for AI assistants. Watched folders and scheduled Google Drive pulls keep it current automatically. No cloud, no telemetry: nothing leaves your machine.

Status — v1 rewrite in progress

| Phase | Shippable increment | Status | |---|---|---| | P0 Reset & Walking Skeleton | potluck serve zero-config: SPA shell; CLI/API/MCP answer stats from one service layer; bench rig + CI | ✅ v1.0.0-alpha.1 | | P1 Storage Core & First Ingest | Google Keep from a Takeout archive (zip/tgz/dir); FTS search via CLI + MCP | ✅ v1.0.0-alpha.2 | | P2 Gmail at Scale & Search v1 | Multi-GB mbox ingested incrementally; filtered/snippeted search | ✅ v1.0.0-alpha.3 | | P3 MVP Interfaces | Real search/item/imports UI, MCP toolset v1 — beta.1 = MVP | ✅ v1.0.0-beta.1 | | P4 Source Expansion & Automation | Remaining planned sources, watch-folder, scheduled GDrive pull | — | | P5 Semantic Search | Unified embedding space, HNSW index, hybrid RRF | — | | P6 Vision & Media Enrichment | OCR, image embeddings, faces, media gallery | — | | P7 Linkers, People & Timeline | Related-items everywhere, people review, timeline | — | | P8 Hardening & 1.0 | Docs, backup/restore, doctor, perf sweep | — |

Full plan, architecture, and locked decisions: pinned issue #98. v0 is archived at archive/v0.

Quickstart — 60 seconds to running

Requires uv (Python is fetched automatically).

1 — Start the server. Straight from GitHub:

uvx --from git+https://github.com/DoubleGremlin181/potluck potluck serve

CLI, API, and MCP are fully functional in this form; only the web app is not bundled (the page at / says so and points at the API docs). Release wheels ship with the web app embedded:

uvx --from https://github.com/DoubleGremlin181/potluck/releases/download/v1.0.0-beta.1/potluck-1.0.0b1-py3-none-any.whl potluck serve

Or Docker (web app included; data persists in the potluck-data volume):

docker run -p 127.0.0.1:8765:8765 -v potluck-data:/data ghcr.io/doublegremlin181/potluck:1.0.0-beta.1

2 — Import your data. Feed it a Google Takeout export, a WhatsApp/Reddit/YNAB export, a bare Timeline.json, or any folder of notes/images/mbox files (zip, tgz, unpacked dir, or single file) — reuse the same uvx --from … potluck prefix for every command, or upload from the web app's Imports page. Drop exports into a watched folder (see watch_folders in the config) or set up scheduled Google Drive pulls to automate it:

uvx --from git+https://github.com/DoubleGremlin181/potluck potluck import ~/Downloads/takeout-20260707T120000Z-001.zip

3 — Search it.

uvx --from git+https://github.com/DoubleGremlin181/potluck potluck search "garden fence"

The web app lives at <http://127.0.0.1:8765> — potluck serve opens it for you. Search and browse everything, start imports, and watch their progress live.

[!WARNING] Potluck is localhost-only by design — there is no authentication in v1. Do not expose it to other machines or the internet.

MCP for AI assistants

stdio (Claude Desktop, Claude Code, …):

{
  "mcpServers": {
    "potluck": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DoubleGremlin181/potluck", "potluck", "mcp"]
    }
  }
}

Streamable HTTP instead: potluck serve exposes the same tools at http://127.0.0.1:8765/mcp — one server surface for web app, API and MCP.

Toolset: search (keyword search with ranked, snippeted hits), list_items (browse/filter without a query), get_item (full content by id), get_thread (the whole email conversation around an item), get_stats (database overview), list_sources (what this build can ingest).

Setup guides — Claude Desktop, Claude Code, OpenClaw, Hermes, direct REST without MCP, and troubleshooting: docs/ai-integration.md.

CLI

potluck import PATH  ingest an export (zip/tgz/dir/single file; source auto-detected)
potluck search Q     full-text search (--kind, --prefix, --cursor, --limit, --json)
potluck list         browse items without a query (--kind, --source, --since, --sort, --json)
potluck show ID      full item content + metadata (--thread: the whole conversation)
potluck status       database overview + per-import stats
potluck rm           delete items by id, --import run, or --source (confirms; --yes to skip)
potluck forget       rm + block the deleted content from ever re-importing
potluck gdrive       Google Drive Takeout auto-pull (auth / status; docs/gdrive-setup.md)
potluck serve        web app + API + MCP (/mcp) on one port (opens your browser)
potluck mcp          MCP server on stdio (HTTP lives at /mcp on the serve port)
potluck bench run    benchmark harness (smoke/full tiers)
potluck dev          source-plugin scaffolding (new-source / check-source)

Search queries can carry inline operators, combinable with each other and free text: from:alice@example.com (or a name prefix: from:alice), source:gmail, kind:email, after:2024-01-01 (inclusive), before:2025-06-30 (exclusive), with quoted values supported. Source values are case-insensitive and spaces map to underscores, so source:"google keep" ≡ source:google_keep. Invalid operator values are ignored — the response's warnings list says what was dropped — and unknown key:value pairs are searched as plain text. Operators alone (no free text) list the matching items newest-first.

Search-as-you-type: --prefix (CLI) / prefix=true (MCP) matches the last word as a prefix (gar finds garden/garlic/garnet). Pagination uses opaque keyset cursors — pass a response's next_cursor back as cursor for the next page; the result set is frozen at the first page, so items ingested mid-pagination never shift, repeat, or hide existing hits.

Configuration is optional: defaults work out of the box. Override via POTLUCK_* env vars or ~/.config/potluck/config.toml (env > toml > defaults); the database lives at ~/.local/share/potluck/potluck.db by default.

Development

git clone https://github.com/DoubleGremlin181/potluck && cd potluck
uv sync && uv run pre-commit install
(cd web && npm ci && npm run build)
uv run potluck serve

Tests: uv run pytest (unit tier), -m browser for the Playwright smoke. Conventions live in CLAUDE.md; test patterns in tests/README.md.

License

MIT