pythia-knowledge 1.0.0__tar.gz

pythia_knowledge-1.0.0/.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.svg text eol=lf

pythia_knowledge-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,126 @@
+# Release: tag vX.Y.Z -> build wheel/sdist -> smoke test -> GitHub Release -> TestPyPI -> PyPI
+#
+# One-time setup (Trusted Publishing, no API tokens):
+#   1. GitHub Environments `testpypi` and `pypi` (optional required reviewers on `pypi`).
+#   2. Pending publishers on TestPyPI and PyPI for project `pythia-knowledge`,
+#      owner `caribeedu`, repository `pythia`, workflow `release.yml`,
+#      with the environment names above.
+name: release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-release:
+    name: build, smoke test, GitHub Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Check that the tag matches the package version
+        id: meta
+        run: |
+          set -euo pipefail
+          VERSION=$(python -c "import re; print(re.search(r'__version__ = \"([^\"]+)\"', open('src/pythia/__init__.py').read()).group(1))")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref_type }}" == "tag" ]]; then
+            TAG="${GITHUB_REF_NAME#v}"
+            if [[ "$TAG" != "$VERSION" ]]; then
+              echo "::error::tag v$TAG does not match the package version $VERSION"
+              exit 1
+            fi
+          fi
+          echo "Building pythia-knowledge==$VERSION"
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Smoke test the wheel
+        run: |
+          set -euo pipefail
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install dist/pythia_knowledge-*.whl
+          /tmp/smoke/bin/pythia --version | grep "${{ steps.meta.outputs.version }}"
+
+      - name: Extract release notes from the changelog
+        env:
+          VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          version = os.environ["VERSION"]
+          lines = Path("CHANGELOG.md").read_text(encoding="utf-8").splitlines()
+          start = next((i for i, l in enumerate(lines) if l.startswith(f"## v{version}")), None)
+          if start is None:
+              body = f"Release v{version}."
+          else:
+              end = next((j for j in range(start + 1, len(lines)) if lines[j].startswith("## v")), len(lines))
+              body = "\n".join(lines[start + 1:end]).strip()
+          Path("release_notes.md").write_text(body + "\n", encoding="utf-8")
+          PY
+
+      - name: Upload the distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Create the GitHub Release
+        if: github.event_name == 'push' && github.ref_type == 'tag'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          body_path: release_notes.md
+          fail_on_unmatched_files: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish-testpypi:
+    name: publish to TestPyPI
+    needs: build-release
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: [build-release, publish-testpypi]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

pythia_knowledge-1.0.0/.github/workflows/tests.yml

@@ -0,0 +1,31 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: pythia
+          POSTGRES_PASSWORD: pythia
+          POSTGRES_DB: pythia_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U pythia"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      PYTHIA_TEST_DATABASE_URL: postgresql://pythia:pythia@127.0.0.1:5432/pythia_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --frozen
+      - run: uv run python -m pytest -q

pythia_knowledge-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.env
+*.log
+.DS_Store
+dist/
+build/
+*.egg-info/

pythia_knowledge-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

pythia_knowledge-1.0.0/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## v1.0.0
+
+First stable release.
+
+- Ingests Claude Code sessions, GitHub pull requests, Slack, Confluence and the incident.io catalog into a base of atomic claims with provenance and time.
+- Resolves entities and conflicts with an LLM, with reversible merges and verdicts, and a periodic drift sweep.
+- Delivers knowledge through a hook push and five MCP tools.
+- A web interface (Evolution, Explore, Sources, Usage, Costs, Quality, Config), a cost ledger with a monthly cap, and golden questions with a plain-search baseline.

pythia_knowledge-1.0.0/CLAUDE.md

@@ -0,0 +1,31 @@
+# Pythia — instructions for Claude
+
+Before proposing or changing anything, read in this order:
+
+1. [docs/design-rationale.md](docs/design-rationale.md): why the project is the way it is, and the principles.
+2. [docs/architecture.md](docs/architecture.md): the architecture.
+3. [docs/decisions.md](docs/decisions.md): decisions D1–D22 and how each area applies them.
+4. [docs/known-issues.md](docs/known-issues.md), [docs/measuring-value.md](docs/measuring-value.md).
+
+## Non-negotiable rules
+
+- Judgment, analysis and context are **always LLM**. Determinism only for plumbing (I/O, cursors, hashes, ACLs, watermarks, cascade, queues, cache, budget). No regex or heuristics for meaning.
+- **No LLM, no function.** No fallback. Only raw ingestion and reading what was already concluded continue, with a notice.
+- **No human approval gates.** Truth is correctable: the owner's corrections have maximum authority.
+- **Rich internal agents, lean external interface**: 5 MCP tools plus the push.
+- An edit retracts the previous version; a deletion really erases, including derived text.
+
+## How to work here
+
+- Changed a prompt or schema? Bump `pipeline/prompts.py:VERSION`; the golden questions run on their own.
+- New decisions go to `docs/decisions.md`.
+
+## Commands
+
+```bash
+.venv/bin/pythia start
+```
+
+```bash
+.venv/bin/python -m pytest -q
+```

pythia_knowledge-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for your interest in Pythia. Before proposing a change, read [docs/design-rationale.md](docs/design-rationale.md): the project has a few non-negotiable principles, and changes that break them will not be merged.
+
+## Principles in short
+
+- Judgment, analysis and context are always done by an LLM. Determinism is for plumbing only (I/O, cursors, hashes, ACLs, watermarks, cascade, queues, cache, budget). No regex or heuristics for meaning.
+- No LLM, no function. No fallback that pretends otherwise.
+- No human approval gates. Truth is correctable, and the owner's corrections win.
+- Rich agents inside, a lean external interface (five MCP tools plus the push).
+- An edit retracts the previous version; a deletion erases everything derived from it.
+
+## Development setup
+
+You need Python 3.13 or 3.14, [uv](https://docs.astral.sh/uv/) and Docker.
+
+```bash
+uv sync
+```
+
+```bash
+docker compose up -d
+```
+
+```bash
+docker exec pythia-db psql -U pythia -c "create database pythia_test"
+```
+
+```bash
+uv run python -m pytest -q
+```
+
+The tests use a real Postgres, a fake LLM and a fake embedder, so they need no API key and cost nothing. Set `PYTHIA_TEST_DATABASE_URL` to use another database.
+
+## Pull requests
+
+- Keep a change focused, and add or update tests. Bug fixes should come with a regression test.
+- If you change a prompt or a schema, bump `VERSION` in `src/pythia/pipeline/prompts.py`; the golden questions run on their own.
+- If you touch deletion or editing, make sure derived text also goes away, and test `rebuild`.
+- Record a new design decision in [docs/decisions.md](docs/decisions.md).
+- Write code, comments and documentation in English.
+
+## Reporting problems
+
+Open an issue with what you did, what you expected and what happened. For security problems, follow [SECURITY.md](SECURITY.md) instead.

pythia_knowledge-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edu Caribé
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythia_knowledge-1.0.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: pythia-knowledge
+Version: 1.0.0
+Summary: Personal knowledge oracle
+Project-URL: Homepage, https://github.com/caribeedu/pythia
+Project-URL: Documentation, https://github.com/caribeedu/pythia/tree/main/docs
+Project-URL: Issues, https://github.com/caribeedu/pythia/issues
+Author: Edu Caribé
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,knowledge-base,knowledge-graph,llm,mcp,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.15,>=3.13
+Requires-Dist: anthropic>=0.70
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastembed>=0.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: keyring>=25
+Requires-Dist: mcp>=1.10
+Requires-Dist: pgvector>=0.3
+Requires-Dist: psycopg[binary,pool]>=3.2
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn[standard]>=0.30
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/caribeedu/pythia/main/assets/banner.svg" alt="Pythia — a personal knowledge oracle" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/caribeedu/pythia/actions/workflows/tests.yml"><img src="https://github.com/caribeedu/pythia/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
+  <img src="https://img.shields.io/badge/python-3.13%20%7C%203.14-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.13 | 3.14">
+  <img src="https://img.shields.io/badge/MCP-5%20tools-c07a2c?style=flat-square" alt="MCP, 5 tools">
+  <a href="https://github.com/caribeedu/pythia/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT"></a>
+</p>
+
+# 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](https://github.com/caribeedu/twin) and the goal is the same.
+
+> [!IMPORTANT]
+> **Need a knowledge oracle, or just an AI that truly sees you?** Pythia is for those who need to cross-reference complex contexts, and it spends a lot of tokens to do it.
+> **[who-am-ai](https://github.com/caribeedu/who-am-ai)**, a leaner alternative, listens to what you say to your assistant, and how, and keeps one short profile it loads every time.
+> It keeps only general, durable preferences, never one-off task details, in a file you can read, edit and veto. A fraction of the tokens. To stop repeating yourself, start there.
+
+## 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.
+
+## 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](https://github.com/caribeedu/pythia/blob/main/docs/measuring-value.md)).
+
+### Sources and consumers
+
+| Sources | Consumers |
+|---|---|
+| Claude Code sessions (per chat, explicit allowlist) | Claude Code: hook push (`SessionStart`, `UserPromptSubmit`) |
+| GitHub pull requests (diffs, reviews, comments) | Claude Code and any MCP client: pull |
+| Slack channels, threads and DMs (user token, no bot) | |
+| Confluence spaces and page trees, with comments | |
+| incident.io catalog (entity seed) | |
+
+Zoom is planned.
+
+### The web interface
+
+| Screen | What it shows |
+|---|---|
+| **Evolution** | What changed and why, newest first: one line per cause, with before/after of the claims, page diffs and per-attribute trajectories |
+| **Explore** | Ego graph around any entity with a time slider; correct, relink, merge or retract from the side panel |
+| **Sources** | The allowlist, connector state, backfill estimates and what is being processed right now |
+| **Usage** | Exactly what was pushed to each chat and what each MCP call returned |
+| **Costs** | Spend against the cap, by role, source and model |
+| **Quality** | Correction rate, golden questions and baseline, detector precision, value metrics |
+| **Config** | Models per role, budget, credentials (kept in the OS keychain), Claude Code integration |
+
+## How it works
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/caribeedu/pythia/main/assets/how-it-works.svg" alt="How Pythia works: sources become evidence, mentions, entities and claims; conflicts become tensions and verdicts; claims feed pages, narratives and the map that serve the push hook and the MCP tools" width="100%">
+</p>
+
+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](https://github.com/caribeedu/pythia/blob/main/docs/architecture.md).
+
+## Getting started
+
+**Requirements:** Python 3.13 or 3.14, [uv](https://docs.astral.sh/uv/), Docker (Postgres 17 with pgvector) and an [Anthropic API key](https://console.anthropic.com/). Credentials are stored with the OS keychain (`keyring`); autostart at login is available on macOS.
+
+Install it from PyPI (the package is `pythia-knowledge`; the command is `pythia`):
+
+```bash
+uv tool install pythia-knowledge
+```
+
+```bash
+pythia start
+```
+
+Or run it from a source checkout with `uv sync` and `uv run 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.
+
+| Command | Does |
+|---|---|
+| `pythia start` / `stop` / `status` | Start, stop or inspect the background process |
+| `pythia run` | Run in the foreground |
+| `pythia autostart` | Start at login (macOS LaunchAgent); `--off` undoes it |
+
+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.
+
+```bash
+docker compose up -d
+```
+
+```bash
+docker exec pythia-db psql -U pythia -c "create database pythia_test"
+```
+
+```bash
+.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
+
+| Path | What |
+|---|---|
+| `src/pythia/events.py` | Append-only event log, projections and `rebuild` |
+| `src/pythia/knowledge.py` | Knowledge commands: claims, mentions, verdicts, cascade, tombstones |
+| `src/pythia/connectors/` | Claude Code, GitHub, Slack, Confluence and incident.io |
+| `src/pythia/pipeline/` | Triage, extraction, resolution, integration, adjudication, sweep, derivation, corrections |
+| `src/pythia/llm/client.py` | Roles, structured output, agent loop, cost ledger, cap and halt |
+| `src/pythia/consumer.py`, `mcp_server.py` | The five MCP tools and the push briefing |
+| `src/pythia/web/` | FastAPI app, templates and the Explore graph |
+| `src/pythia/daemon.py`, `jobs.py` | Job queue, lanes and scheduler |
+| `src/pythia/migrations/` | Postgres schema |
+
+## Documentation
+
+| Document | About |
+|---|---|
+| [Architecture](https://github.com/caribeedu/pythia/blob/main/docs/architecture.md) | Knowledge model, entity resolution, conflicts, ingestion, consumption, stack |
+| [Decisions](https://github.com/caribeedu/pythia/blob/main/docs/decisions.md) | Numbered core decisions (D1–D22) and how each area applies them |
+| [Design rationale](https://github.com/caribeedu/pythia/blob/main/docs/design-rationale.md) | Why it is the way it is: principles, influences and what real use taught |
+| [Measuring value](https://github.com/caribeedu/pythia/blob/main/docs/measuring-value.md) | Metrics, experiment design and results |
+| [Known limitations](https://github.com/caribeedu/pythia/blob/main/docs/known-issues.md) | Open problems and their proposed fixes |
+
+## 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](https://github.com/caribeedu/pythia/blob/main/CONTRIBUTING.md) before opening a pull request, and [SECURITY.md](https://github.com/caribeedu/pythia/blob/main/SECURITY.md) to report a vulnerability.
+
+## License
+
+[MIT](https://github.com/caribeedu/pythia/blob/main/LICENSE)

pythia_knowledge-1.0.0/README.md

@@ -0,0 +1,162 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/caribeedu/pythia/main/assets/banner.svg" alt="Pythia — a personal knowledge oracle" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/caribeedu/pythia/actions/workflows/tests.yml"><img src="https://github.com/caribeedu/pythia/actions/workflows/tests.yml/badge.svg" alt="tests"></a>
+  <img src="https://img.shields.io/badge/python-3.13%20%7C%203.14-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.13 | 3.14">
+  <img src="https://img.shields.io/badge/MCP-5%20tools-c07a2c?style=flat-square" alt="MCP, 5 tools">
+  <a href="https://github.com/caribeedu/pythia/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT"></a>
+</p>
+
+# 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](https://github.com/caribeedu/twin) and the goal is the same.
+
+> [!IMPORTANT]
+> **Need a knowledge oracle, or just an AI that truly sees you?** Pythia is for those who need to cross-reference complex contexts, and it spends a lot of tokens to do it.
+> **[who-am-ai](https://github.com/caribeedu/who-am-ai)**, a leaner alternative, listens to what you say to your assistant, and how, and keeps one short profile it loads every time.
+> It keeps only general, durable preferences, never one-off task details, in a file you can read, edit and veto. A fraction of the tokens. To stop repeating yourself, start there.
+
+## 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.
+
+## 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](https://github.com/caribeedu/pythia/blob/main/docs/measuring-value.md)).
+
+### Sources and consumers
+
+| Sources | Consumers |
+|---|---|
+| Claude Code sessions (per chat, explicit allowlist) | Claude Code: hook push (`SessionStart`, `UserPromptSubmit`) |
+| GitHub pull requests (diffs, reviews, comments) | Claude Code and any MCP client: pull |
+| Slack channels, threads and DMs (user token, no bot) | |
+| Confluence spaces and page trees, with comments | |
+| incident.io catalog (entity seed) | |
+
+Zoom is planned.
+
+### The web interface
+
+| Screen | What it shows |
+|---|---|
+| **Evolution** | What changed and why, newest first: one line per cause, with before/after of the claims, page diffs and per-attribute trajectories |
+| **Explore** | Ego graph around any entity with a time slider; correct, relink, merge or retract from the side panel |
+| **Sources** | The allowlist, connector state, backfill estimates and what is being processed right now |
+| **Usage** | Exactly what was pushed to each chat and what each MCP call returned |
+| **Costs** | Spend against the cap, by role, source and model |
+| **Quality** | Correction rate, golden questions and baseline, detector precision, value metrics |
+| **Config** | Models per role, budget, credentials (kept in the OS keychain), Claude Code integration |
+
+## How it works
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/caribeedu/pythia/main/assets/how-it-works.svg" alt="How Pythia works: sources become evidence, mentions, entities and claims; conflicts become tensions and verdicts; claims feed pages, narratives and the map that serve the push hook and the MCP tools" width="100%">
+</p>
+
+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](https://github.com/caribeedu/pythia/blob/main/docs/architecture.md).
+
+## Getting started
+
+**Requirements:** Python 3.13 or 3.14, [uv](https://docs.astral.sh/uv/), Docker (Postgres 17 with pgvector) and an [Anthropic API key](https://console.anthropic.com/). Credentials are stored with the OS keychain (`keyring`); autostart at login is available on macOS.
+
+Install it from PyPI (the package is `pythia-knowledge`; the command is `pythia`):
+
+```bash
+uv tool install pythia-knowledge
+```
+
+```bash
+pythia start
+```
+
+Or run it from a source checkout with `uv sync` and `uv run 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.
+
+| Command | Does |
+|---|---|
+| `pythia start` / `stop` / `status` | Start, stop or inspect the background process |
+| `pythia run` | Run in the foreground |
+| `pythia autostart` | Start at login (macOS LaunchAgent); `--off` undoes it |
+
+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.
+
+```bash
+docker compose up -d
+```
+
+```bash
+docker exec pythia-db psql -U pythia -c "create database pythia_test"
+```
+
+```bash
+.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
+
+| Path | What |
+|---|---|
+| `src/pythia/events.py` | Append-only event log, projections and `rebuild` |
+| `src/pythia/knowledge.py` | Knowledge commands: claims, mentions, verdicts, cascade, tombstones |
+| `src/pythia/connectors/` | Claude Code, GitHub, Slack, Confluence and incident.io |
+| `src/pythia/pipeline/` | Triage, extraction, resolution, integration, adjudication, sweep, derivation, corrections |
+| `src/pythia/llm/client.py` | Roles, structured output, agent loop, cost ledger, cap and halt |
+| `src/pythia/consumer.py`, `mcp_server.py` | The five MCP tools and the push briefing |
+| `src/pythia/web/` | FastAPI app, templates and the Explore graph |
+| `src/pythia/daemon.py`, `jobs.py` | Job queue, lanes and scheduler |
+| `src/pythia/migrations/` | Postgres schema |
+
+## Documentation
+
+| Document | About |
+|---|---|
+| [Architecture](https://github.com/caribeedu/pythia/blob/main/docs/architecture.md) | Knowledge model, entity resolution, conflicts, ingestion, consumption, stack |
+| [Decisions](https://github.com/caribeedu/pythia/blob/main/docs/decisions.md) | Numbered core decisions (D1–D22) and how each area applies them |
+| [Design rationale](https://github.com/caribeedu/pythia/blob/main/docs/design-rationale.md) | Why it is the way it is: principles, influences and what real use taught |
+| [Measuring value](https://github.com/caribeedu/pythia/blob/main/docs/measuring-value.md) | Metrics, experiment design and results |
+| [Known limitations](https://github.com/caribeedu/pythia/blob/main/docs/known-issues.md) | Open problems and their proposed fixes |
+
+## 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](https://github.com/caribeedu/pythia/blob/main/CONTRIBUTING.md) before opening a pull request, and [SECURITY.md](https://github.com/caribeedu/pythia/blob/main/SECURITY.md) to report a vulnerability.
+
+## License
+
+[MIT](https://github.com/caribeedu/pythia/blob/main/LICENSE)