Skip to main content

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)

Source distribution for opendiff 0.2.0
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)

Table of built distributions (wheels) for opendiff 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page