Montauk

Relationship memory for personal agents: durable, private, structured memory of the people in one person's life, with a web dashboard for the owner and an MCP server for their agent.

The canonical store is PostgreSQL, workspace-scoped, with field-level revision history. An agent reaches it over an authenticated MCP endpoint; the owner curates it through a server-rendered web dashboard. montauk_phase2_build_and_migration_spec.md and docs/adr/ are the design record.

Montauk began as a Markdown-file store with a stdio MCP server (montauk_phase1_build_spec.md). That store and its server were removed once the PostgreSQL store, the migrator that imported it, and this MCP surface were all live. The retrieval engine (person_context.py) and the local semantic index (semantic_index.py, now PostgreSQL-backed -- ADR 0005) carried over.

Identity vs. name. Each person has a permanent, generic ID (P0001, P0002, ...) that Montauk assigns and never changes or reuses. The person's name is just the best label currently known -- it can be partial or wrong at first and corrected later with update_person_name (former spellings are kept as searchable aliases), without touching the ID.

Briefing-first retrieval. The normal agent call is prepare_person_briefing(person_id, purpose, detail_level, mode): it selects the relevant curated evidence, compresses it with a configured low-cost model into a short, factual, purpose-specific briefing, and returns that plus lightweight source_refs. The agent drills into individual records with get_context_sources / get_facts / get_interactions only to verify a claim or get detail the briefing left out. A narrow factual question ("what is X's birthday?") is answered from the structured field with no model call. prepare_person_context is the deterministic, no-LLM path -- ranked raw records, hybrid BM25 + semantic retrieval, no synthesis. search_people matches names, aliases and contact details, and also vague descriptions ("the robotics guy from the MIT mixer") by semantic similarity over facts and interactions. Montauk never generates advice, quotations, or missing facts; that is the agent's job.

Running it

uv sync
export MONTAUK_DATABASE_URL=postgresql://user:pass@localhost:5432/montauk
export MONTAUK_MASTER_KEY=$(python -c "import base64,os;print(base64.b64encode(os.urandom(32)).decode())")

uv run montauk db upgrade      # create / update the schema
uv run montauk dashboard       # http://127.0.0.1:8817  (first visit = setup wizard)
uv run montauk mcp             # http://127.0.0.1:8766/mcp  (agent endpoint)

• MONTAUK_MASTER_KEY (32 bytes, base64) encrypts stored model-provider API keys. Without it, briefings fall back to the deterministic evidence packet.

• Both servers refuse to start against a stale schema; run montauk db upgrade after a pull.

• Semantic search uses a local embedding model (fastembed, all-MiniLM-L6-v2, ~90 MB), downloaded from Hugging Face on first use. Set FASTEMBED_CACHE_PATH to a persistent, writable directory (the default is under /tmp). The index maintains itself on read; montauk semantic status reports coverage and montauk semantic rebuild warms it after a deploy. If the model can't load, retrieval falls back to lexical and reports semantic_available: false.

• Put a TLS-terminating reverse proxy in front for anything beyond loopback. One hostname can serve both: route /mcp* to the MCP port, everything else to the dashboard (docs/deploy-phase2-shared-host.md).

Related MCP server: Link

Agent access

Create a bearer token for the agent in the dashboard (Settings -> agent tokens), then point an MCP-compatible host at the streamable-HTTP endpoint with Authorization: Bearer <token>. Every request is authenticated against the workspace's agent_credentials; the memory_read and memory_write capabilities gate reads and writes per tool.

The MCP surface: search_people, prepare_person_briefing, get_context_sources, prepare_person_context, get_person / get_facts / get_interactions / get_full_record, list_people, get_upcoming_birthdays, list_overdue_contacts, get_connector_health, and the write tools (create_person, add/update/remove fact, record/update/remove/reattribute interaction, contact/summary/name/birthday/cadence, update_person_batch, archive/restore).

Sources

Two ways to archive real conversations (both sides, text only — no attachments):

• Manual import — WhatsApp chat exports (.txt), on the Transcripts page.

• WhatsApp connector — a receive-only linked device (Baileys sidecar) that syncs enabled conversations continuously. Connectors → Connect WhatsApp. It never sends, replies, or marks anything read. Setup: docs/adr/0004-whatsapp-inbound-connector.md and sidecars/whatsapp/README.md.

Archived messages are immutable evidence; you map each sender to a person, then the extraction model turns new messages into facts and per-day interaction summaries.

Model provider

Briefings need a low-cost model, configured per purpose in Settings -> Model & provider:

• Local claude / codex CLI -- reuses the machine's Claude Code / Codex subscription auth; no API key. Extended thinking is disabled for these (every task here is compression, not reasoning).

• Anthropic API or an OpenAI-compatible endpoint -- with a stored, encrypted API key.

Month-to-date usage, a spend/token ceiling, and a hard pause switch live under Settings -> LLM cost controls.

Development

uv sync
uv run pytest              # needs Docker (spins a postgres testcontainer) or MONTAUK_TEST_DATABASE_URL
uv run ruff check . && uv run ruff format --check && uv run mypy