Pythia

Pythia continuously reads the places where your work happens, keeps a base of atomic claims with provenance and time, detects when knowledge becomes outdated or contradictory, and delivers what matters to your LLMs, automatically through hooks (push) and on demand through MCP (pull).

It is the spiritual successor of Twin and the goal is the same.

Why

AI assistants forget. Each session starts blank, so you keep explaining how you write, who owns which system, what the team decided last week and what caused that bug. Product memories help inside one assistant; retrieval returns fragments without knowing which are still true. Pythia keeps what is currently true, where it came from, and what changed.

Related MCP server: io.github.norrietaylor/distillery-mcp

Features

• Claims, not documents. The source of truth is the atomic claim (subject, attribute, value, validity, status, evidence). Pages and narratives are derivatives that cite claims, go stale only when a cited claim changes, and can be regenerated at any time.

• Open-world entity resolution. People, teams, systems and projects are resolved from context by an LLM, seeded by registries such as the incident.io catalog. Merge, split and relink are reversible events.

• Conflict and drift handling. New claims are confronted with what is already known. An adjudicator agent investigates, with live access to the sources (current file, CODEOWNERS, Slack thread, Confluence page), and records a reversible verdict: temporal supersession, real conflict, different scope, outdated source, duplicate. A periodic sweep looks for drift with no trigger.

• You are the authority. There are no approval queues. The system writes its result and you correct it afterwards; your corrections always win and become quality metrics and test examples.

• Edits and deletions are respected. An edit retracts the previous version; a deletion at the source erases the content and every derived text, including old page versions.

• Small external interface. Five MCP tools (search, open, timeline, correct, define) and a short push briefing whose text is always stored knowledge, never generated prose.

• No LLM, no guessing. Judgment is always done by an LLM; there are no regex or heuristic fallbacks. Without a key, network or budget, ingestion continues and reads serve what was already concluded, with a notice.

• Measured. Cost ledger and monthly cap, golden questions with a sealed half and a plain-search baseline, correction rate per role, and a method to measure avoided re-explanation (docs/measuring-value.md).

Sources and consumers

Zoom is planned.

The web interface

How it works

A unit of a source (a settled thread, a merged PR, a chat delta, a page edit) goes through triage → extraction → entity resolution → integration → adjudication (when needed) → regeneration of derivatives, on a single Postgres job queue with separate lanes for I/O, cognition and derivation. State is event-sourced, so the base can answer both what is true and what Pythia believed at time T.

Details: docs/architecture.md.

Getting started

Requirements: Python 3.13 or 3.14, uv, Docker (Postgres 17 with pgvector) and an Anthropic API key. Credentials are stored with the OS keychain (keyring); autostart at login is available on macOS.

uv sync

.venv/bin/pythia start

start brings up the database container if needed, then runs the daemon and the web server in the background. Open http://127.0.0.1:7117 and:

1. Config: add your Anthropic API key, review the models per role and set the monthly cap.

2. Sources: turn on the Claude Code chats to read, and add repositories, Slack conversations or Confluence spaces. Each new source enters paused with a cost estimate for its backfill.

3. Config → Claude Code integration: copy the MCP command (pull) and the hooks snippet (push) into your Claude Code setup.

Command line

The CLI only manages the process; everything else is configured on the web.

Environment: PYTHIA_HOME (default ~/.pythia: pid file and logs) and PYTHIA_DATABASE_URL (use your own Postgres instead of the container; it needs the vector extension).

Development

Tests run against a real Postgres, a fake LLM and a fake embedder, so they are fast and cost nothing.

docker compose up -d

docker exec pythia-db psql -U pythia -c "create database pythia_test"

.venv/bin/python -m pytest -q

If you change a prompt or schema, bump VERSION in src/pythia/pipeline/prompts.py; the golden questions then run on their own.

Repository layout

Documentation

Principles

1. Judgment is always an LLM; determinism is for plumbing only.

2. No LLM, no function, and no fallback that pretends otherwise.

3. A truth that is wrong but correctable beats a hypothesis waiting for approval.

4. Rich agents inside, a lean interface outside.

5. Derivatives are disposable; evidence, entities, claims, verdicts and human decisions are the only state that matters.

Contributing and security

See CONTRIBUTING.md before opening a pull request, and SECURITY.md to report a vulnerability.

License

MIT