opendiff
Append-only, multi-tenant raw memory in Postgres — every meeting, message, and config a team's tools produce, stored byte-verbatim, versioned, and content-addressed — exposed read-only over HTTP and MCP so skills and agents can reason over it.
The argument for building it: BRIEFING.md. The canonical design: spec.md. Backing research: research/.
Quickstart
docker compose up -d # postgres:16 on :5433
uv venv && uv pip install -e ".[dev]"
opendiff migrate # tables, triggers, RLS, grants
opendiff tenant create acme # → tenant id
opendiff token create acme --name me # → odf_… bearer token (shown once)
opendiff serve # http://127.0.0.1:8000
Ingest your Granola workspace:
export GRANOLA_API_KEY=grn_…
curl -sX POST localhost:8000/v1/sources \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"kind":"granola","name":"prod","credential_ref":"env://GRANOLA_API_KEY"}'
curl -sX POST localhost:8000/v1/sources/<source-id>/sync \
-H "Authorization: Bearer $TOKEN"
Read it in Claude Code:
claude mcp add opendiff -e OPENDIFF_TOKEN=$TOKEN -- \
uv run --project /path/to/opendiff opendiff mcp
Eight read-only tools: ls · cat · stat · history · find · read_many · unrouted · sources. Start with ls(''), search with find(query=…).
ls, find and unrouted return {items, next_cursor}; a non-null next_cursor
means the result is incomplete, so pass it back for the next page. limit outside
1–500 is an error rather than being clamped — a listing that quietly stopped short
reads exactly like a complete one.
Plus publish_artifact / artifacts, which write derived memory back — a
versioned document rendered on the workspace home page. These two are a temporary
stand-in: the intended producer is a skill running on a schedule over raw memory,
and when that exists it calls the same endpoint.
Shape of the thing
Granola ─┐
Slack ───┤→ INGESTION APIs → store/ → Postgres raw memory ─┬→ HTTP read + sync (§8)
future ──┘ + CustomerResolver append-only · RLS └→ MCP, stdio (§9)
content-addressed ↓
CachedHttpReader (§10)
local cache · pinned reads
↓
agent reasons ─→ publish_artifact ─┐
↓
Postgres DERIVED memory ── versioned, human-reviewed
ACCOUNT.md · breach alerts · product signals
- Append-only, enforced twice — triggers and role grants; the app role cannot UPDATE or DELETE content even in a raw psql session.
- Multi-tenant from migration 0001 — Postgres RLS with
force row level security; an unset tenant returns zero rows, never all rows. - One read implementation — HTTP and MCP are transports over
store/read.py; a parity test asserts byte-identical JSON. - Connectors call the public API — no private ingest path; the watermark advances only on a clean, complete drain.
Tests
pytest # unit + integration + e2e (testcontainers postgres)
pytest -m live # §14.3 — the real Granola API; needs GRANOLA_API_KEY
The e2e suite runs against the real 82-meeting corpus in granola-transcripts/
(private, never committed) and asserts exact byte counts, dedup no-ops, and
twin-tenant isolation.
Metadata
Release files for opendiff 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| opendiff-0.2.0.tar.gz | 105.6 kB | With provenance | Details for opendiff-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| opendiff-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for opendiff-0.2.0-py3-none-any.whl |
Total release size: 206.8 kB
Release files / opendiff-0.2.0.tar.gz
| Download URL | opendiff-0.2.0.tar.gz |
|---|---|
| Size | 105.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2507e5eb3c81b5bf49158653366cd658e95bd5228919e1a4ddcf125634c25936
|
|
BLAKE2b-256 checksum How to use checksums |
07c20ec208e7b9e46d191200fe8f23ea9d4dce059406e40e610de533717df39a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logRelease files / opendiff-0.2.0-py3-none-any.whl
| Download URL | opendiff-0.2.0-py3-none-any.whl |
|---|---|
| Size | 101.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4eadbd6feed315077f60c1ad60fc032240b1768b814b153f648f2f3e5b087498
|
|
BLAKE2b-256 checksum How to use checksums |
4e1cf9bc0dee961040645309e521ccaa0e45376af8f3928ab70f45d992090ddc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logSecurity for opendiff 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for opendiff-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.