Potluck — Base de Conhecimento Pessoal Local
DoubleGremlin181/potluck
Base de conhecimento privada local para potencializar seu AI com seus dados pessoais
Ver no GitHubMCP server que transforma seus dados pessoais (Google Takeout, GDPR exports) em uma base de conhecimento local, criptografada e sem nuvem. Expõe acesso via web app, CLI e MCP para integração com assistentes de IA, permitindo personalização profunda mantendo privacidade total.
Instalação
npx convez-ai DoubleGremlin181/potluck1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar Google Keep e Gmail com Claude para busca contextual personalizada
- Criar assistentes de IA treinados em seus próprios dados sem exposição à nuvem
- Migrar dados de múltiplas fontes (GDPR exports) para um repositório unificado e pesquisável
Veredito

Projeto ambicioso em reescrita ativa (v1 alpha). Para quem prioriza privacidade e quer controle total dos dados pessoais conectados à IA — ainda em fase early, mas arquitetura sólida. Ideal para builders que querem base de conhecimento local com MCP nativo.
README
A tradução para o português deste README ainda está na fila.
Potluck
Privacy-first personal knowledge database for your AI — local-first, MCP-native.
Potluck ingests your data exports (Google Takeout first: Keep + Gmail; more sources each phase), stores everything in one local SQLite database, and exposes it three ways — a web app, a CLI, and MCP for AI assistants. 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 zip; FTS search via CLI + MCP | — |
| P2 Gmail at Scale & Search v1 | Multi-GB mbox ingested incrementally; filtered/snippeted search | — |
| P3 MVP Interfaces | Real search/item/imports UI, MCP toolset v1 — beta.1 = MVP | — |
| P4 Source Expansion & Automation | All v0 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
Requires uv (Python is fetched automatically).
Run straight from GitHub — CLI, API, and MCP work; the web UI needs a built SPA, which this form does not include:
uvx --from git+https://github.com/DoubleGremlin181/potluck potluck serve
Release wheels ship with the web app embedded:
uvx --from https://github.com/DoubleGremlin181/potluck/releases/download/v1.0.0-alpha.1/potluck-1.0.0a1-py3-none-any.whl potluck serve
Or Docker (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-alpha.1
Then open http://127.0.0.1:8765.
[!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 mcp --http (default 127.0.0.1:8766).
P0 toolset: get_stats. Search and item tools land with P1.
CLI
potluck status database overview (counts, paths, versions)
potluck serve web app + API on one port (opens your browser)
potluck mcp MCP server (stdio; --http for streamable HTTP)
potluck bench run benchmark harness (smoke/full tiers)
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.