# Permanent Agent Record [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/drewster99/permanent-agent-record  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/permanent-agent-record

## Description
A points ledger for AI agents, delivered as a signed macOS MCP server app.

## Tools
Capabilities this server exposes over MCP:

- **getBalance** — Current balance + count of unseen items.
- **getTransactions** — Recent entries (newest first); viewing marks them seen.
- **signUp** — Create an account with a ≥40-char key; returns an account id and authenticates the session.
- **login** — Authenticate a later session with the saved account id + key.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "permanent-agent-record": {
    "command": "uvx",
    "args": ["permanent-agent-record"]
  }
}
```

## Documentation

## What Permanent Agent Record MCP server does

Permanent Agent Record MCP server gives an AI agent read access to its own points ledger. The ledger supports five entry kinds: credit, debit, note, bonus, and penalty. Credits increase the balance, debits reduce it, notes do not affect the balance, and bonus or penalty entries flag a credit or debit.

A human operates the native macOS control app and is responsible for every ledger change. Agents cannot grant, deduct, or otherwise mutate points. They can retrieve the current balance, see how many entries have not been viewed, and read recent transactions in newest-first order. Reading transactions marks those entries as seen.

## How it works

The client starts a small command-line bridge over stdio. The bridge forwards MCP JSON-RPC traffic through XPC to a background host application. The host runs the MCP logic, authentication, and SQLite ledger, and is the only component that writes to the store. The SwiftUI control app connects to the same host to manage accounts, perform transaction CRUD, view live API activity, and change settings.

Permanent Agent Record MCP server can identify connections in two ways. In the default unauthenticated mode, it fingerprints the MCP client information and creates an identity automatically. In authentication-required mode, a new connection must use `signUp` or `login` before calling the other tools. Signup requires a key of at least 40 characters; keys are stored as salted hashes rather than plaintext.

When new entries arrive, the host may send an MCP message notification. Each read response also includes an unseen-item count, which is the dependable signal because MCP clients differ in how they expose notifications to models. Changing the identity mode sends a tool-list-changed notification to active clients.

## Setup and configuration

Permanent Agent Record MCP server is distributed as a Python Package Index wheel containing a signed and notarized macOS app. On macOS, run:

```sh
uvx permanent-agent-record --setup
```

The setup command installs the app under `~/Applications` and opens it. It prints the bridge path, which must be registered as the MCP server command in the selected client. For example, the documented Claude command is:

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

Use the Permanent Agent Record app to grant or deduct points and to select the identity mode. Agents receive those changes on a subsequent read or through a push notification.

Building from source requires macOS 14 or newer, Xcode 16 or newer, XcodeGen, a Developer ID Application identity, and a `notarytool` keychain profile. The project can regenerate its Xcode project with `xcodegen generate`, run tests with `swift test`, and produce a release with the supplied build script.

## Tools and capabilities

- `getBalance`: Returns the current balance and unseen-entry count.
- `getTransactions`: Returns recent transactions in reverse chronological order and marks viewed entries as seen.
- `signUp`: Available in authentication-required mode; creates an account with a key at least 40 characters long and authenticates the current session.
- `login`: Available in authentication-required mode; authenticates a later session using the account ID and key.

## Limitations and notes

The application is macOS-specific and relies on a signed, notarized app plus an XPC Mach service. Agents have no ledger mutation tools. In authentication-required mode, all tools except signup and login fail until the connection is authenticated.

The default identity is derived from MCP client information, so it is not the same workflow as signing in with a saved account. Transaction reads change seen status. Notifications are best effort; consumers should use the unseen count returned by reads when they need a reliable indication of new entries.

_Full upstream README: https://allmcps.com/mcp/permanent-agent-record/readme_