Permanent Agent Record

Sổ cái điểm dành cho các tác nhân AI, được cung cấp dưới dạng máy chủ MCP macOS có chữ ký. Con người cấp và trừ điểm trong ứng dụng SwiftUI gốc; các tác nhân được kết nối chỉ có thể xem số dư và lịch sử giao dịch của chính mình.

Tài liệu

Permanent Agent Record

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

How it's put together

agent (LLM) ──stdio JSON-RPC──▶ AgentRecordBridge ──NSXPC──▶  AgentRecordHost
   ◀────── MCP notifications ────      (CLI)        ◀──────    (faceless LaunchAgent)
                                                                • sole writer of the SQLite ledger
                                                                • runs all MCP logic + auth
Permanent Agent Record.app ─────────── NSXPC ───────────────▶  • streams the live API log to the UI
  (SwiftUI control app)                                         • performs every ledger mutation
  • AgentRecordHost — a faceless (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.
  • AgentRecordBridge — the tiny CLI each MCP client launches. It relays JSON-RPC between the client's stdio and the host over XPC, and is bidirectional: the host pushes notifications (new items, tools/list_changed) back through it.
  • Permanent Agent Record.app — the SwiftUI control app. A second XPC client of the same host: it lists accounts and live connections, performs transaction CRUD, streams the live API-call monitor, and toggles settings.

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.

MCP tools

ToolAvailabilityDescription
getBalancealwaysCurrent balance + count of unseen items.
getTransactionsalwaysRecent entries (newest first); viewing marks them seen.
signUpauth-required mode onlyCreate an account with a ≥40-char key; returns an account id and authenticates the session.
loginauth-required mode onlyAuthenticate a later session with the saved account id + key.

Identity modes (toggle in the app)

  • Allow unauthenticated (default): agents are identified by a fingerprint of their MCP clientInfo, auto-created on connect; signUp/login are absent. Flipping the toggle pushes notifications/tools/list_changed to live clients.
  • Auth required: connections start unauthenticated; every tool but 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).

Install & use

uvx permanent-agent-record --setup     # install the app to ~/Applications and open it (once)

Register the printed bridge path as the MCP server command with your client, e.g.:

claude mcp add --scope user permanent-agent-record \
  ~/Applications/PermanentAgentRecord.app/Contents/Helpers/AgentRecordBridge

Open Permanent Agent Record to grant/deduct points; agents see the changes on their next read (or via a push).

Build from source

Requires macOS 14+, Xcode 16+, XcodeGen, a Developer ID Application identity, and a notarytool keychain profile.

xcodegen generate                 # regenerate the Xcode project from project.yml
swift test                        # fast unit tests of the ledger + MCP engine
scripts/build-release.sh          # bump version, build, sign, notarize, staple, build the wheel
scripts/build-release.sh --skip-notarize --no-bump   # local signed build without notarization

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.

Layout

Sources/AgentRecordShared   XPC contract, DTOs, versioning (compiled into host, bridge, app)
Sources/AgentRecordCore     SQLite store, MCP server, auth, host engine
Sources/AgentRecordHost     faceless XPC host / LaunchAgent
Sources/AgentRecordBridge   stdio ⇄ XPC bridge (bidirectional)
Sources/AgentRecordApp      SwiftUI control app
python/                     PyPI wrapper (bootstrap: install + execv the bridge)
packaging/                  LaunchAgent plist
scripts/                    build-release.sh, make-icon.py