The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Permanent Agent Record listing page.
A points ledger for AI agents, delivered as a signed macOS Model Context Protocol (MCP) server. A human grants and deducts points in a native SwiftUI app; connected AI agents can only read their own balance and transaction history and are notified when new items appear. Every mutation to the ledger is human‑driven — an agent can never change its own points.
Points come in five human-facing kinds: credit, debit, note (no balance effect), bonus (a flagged credit), and penalty (a flagged debit).
LSUIElement) background app, registered as an on-demand
LaunchAgent via SMAppService, vending a team-scoped XPC Mach service. It is the single
writer of the SQLite store and runs the entire MCP server. Launched on demand by launchd
when a bridge or the app connects.tools/list_changed) back through it.The .app embeds the host and bridge under Contents/Helpers/. It is distributed as a Python
Package Index wheel with the signed, notarized .app zipped inside; installing extracts it to
~/Applications. A team-scoped XPC Mach service cannot be ad-hoc signed, so a Developer ID and
notarization are required.
| Tool | Availability | Description |
|---|---|---|
getBalance | always | Current balance + count of unseen items. |
getTransactions | always | Recent entries (newest first); viewing marks them seen. |
signUp | auth-required mode only | Create an account with a ≥40-char key; returns an account id and authenticates the session. |
login | auth-required mode only | Authenticate a later session with the saved account id + key. |
clientInfo, auto-created on connect; signUp/login are absent. Flipping the toggle pushes
notifications/tools/list_changed to live clients.signUp/login errors
until the agent signs up or logs in. Keys are stored salted-hashed, never in plaintext.New items are signalled two ways: a best-effort MCP notifications/message push, and an
unseenCount on every read response (the reliable signal, since clients vary in whether they
surface server notifications to the model).
Register the printed bridge path as the MCP server command with your client, e.g.:
Open Permanent Agent Record to grant/deduct points; agents see the changes on their next read (or via a push).
Requires macOS 14+, Xcode 16+, XcodeGen, a Developer ID Application identity, and a
notarytool keychain profile.
project.yml (XcodeGen) is the source of truth for the app bundle; Package.swift builds the
libraries and CLIs for fast iteration. See CLAUDE.md for the full architecture and the
locked design decisions.