pi-delta-db

Pi extension that lets Pi store and read data through the Delta CLI (delta).

Delta's SQLite store behind delta db is internal and read-only from outside, so writes go through Delta's supported path: a private Delta thread bound to the Pi session, recorded with schema-1 JSONL (delta thread create + delta thread append). Everything Pi stores shows up in the Delta app and can be read back with or without Pi.

Auto-recording

Every finalized user message, assistant message, thought, tool call, and tool result is appended to this session's Delta thread, in order. The thread is created on the first message and titled with the first prompt; continuing a session (pi -c) keeps appending to the same thread.

Records are written to ~/.pi/agent/delta-db/outbox/ and fsynced before Delta is contacted. If Delta is closed, offline, or rejects the write, the turn stays queued and is retried on the next message and the next session start. A retry cannot duplicate or erase earlier turns: each message id is unique, and Delta replaces a record that reuses one.

Bindings whose Pi session file is gone and that have not been touched for a week are deleted on session start.

Tools

How it binds

One thread per Pi session:

• Producer: --source pi --external-id <pi-session-id>
• Created with --visibility private --organization <current org>, which is what makes thread append allowed (Delta rejects appends to unshared threads).
• The thread id and title state live in ~/.pi/agent/delta-db/<session-id>.json.
• Each write asks delta thread status for the next sequence, and writes are serialized through one queue, so records stay ordered.

Install

# from npm
pi install npm:pi-delta-db

# from git, or a local checkout in development
pi install git:github.com/morizkay/pi-delta-db
pi install ./pi-delta-db

Restart Pi (or run /reload). Requirements: Pi >= 1.4.0, Node >= 22.19.0, the delta CLI on PATH, and a signed-in account (delta auth login).

For local development of this repository, link it into the agent directory instead:

ln -sfn "$(pwd)" ~/.pi/agent/extensions/pi-delta-db

GitHub Packages mirror

Every release is also mirrored to GitHub Packages as @morizkay/pi-delta-db by .github/workflows/publish-github-packages.yml, which is why the repository's Packages tab lists it. Prefer npm: GitHub Packages requires a token with read:packages even for public packages.

# ~/.npmrc: //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
pi install npm:@morizkay/pi-delta-db

Development

npm install    # host packages are peer dependencies, dev-only here
npm run check  # tsc --noEmit
npm test       # record shapes, outbox retry, and prune, against a fake delta

CI runs both on every push. Publishing a GitHub release also mirrors the package to GitHub Packages, and publishes to npmjs.org when the NPM_TOKEN secret is set (gh secret set NPM_TOKEN; use an automation token so OTP is not required).

Gotchas found against delta 0.23.0

• messageId must be globally unique: a record whose messageId matches an earlier one replaces it, so a repeated id silently erases earlier messages.
• session_info_update re-titles the thread on every append, so the title is written once and remembered in the binding file.
• Appends send records to Delta's cloud (private visibility) — not purely local storage.
• Records are append-only: nothing can be overwritten or deleted individually.

License

MIT © 2026 morizkay. Changes are documented in the changelog.