Agent Receipts

Create an Ed25519-signed receipt with pre-computed SHA-256 hashes. Use when you have already hashed the input/output data externally or need full control over receipt fields. For automatic hashing, use track_action instead. Returns the signed receipt object with receipt_id. The receipt is stored locally in SQLite and can be completed later with complete_receipt.

Finalize a pending receipt by recording execution results, costs, and output data. Updates the receipt status to completed, failed, or timeout and re-signs with Ed25519. Use after create_receipt when you need to record results separately from creation (two-phase tracking). Cannot complete an already-completed receipt. Returns the updated signed receipt.

Create a completed Ed25519-signed receipt for an AI agent action with automatic SHA-256 hashing of input and output data. Records model usage, costs, latency, and constraint evaluations. Returns the signed receipt with receipt_id for future reference. Use this as the primary tool for recording agent actions — prefer over create_receipt + complete_receipt for single-step actions.

Cryptographically verify an Ed25519 signature on a stored receipt to confirm it has not been tampered with since signing. Extracts the 12-field signable payload, canonicalizes it, and verifies against the stored public key. Returns verified: true if the signature is valid. Use to audit receipts before using them as evidence or before completing payments based on agent work.

Retrieve a single receipt by its ID from local SQLite storage. Returns the full receipt object including all 27 fields: identity, timestamps, action data, performance metrics, constraints, cryptographic proof, and metadata. Returns an error message if the receipt ID does not exist. Use to inspect a specific receipt or retrieve it before verification.

Query and paginate receipts from local SQLite storage with optional filtering by agent, action, status, environment, type, chain, or tag. Supports sorting by timestamp, cost, or latency. Returns paginated results with total count, page info, and has_next/has_prev flags. Default: 50 receipts per page, sorted by timestamp descending. Use to audit agent activity, generate reports, or find specific receipts.

Retrieve all receipts belonging to a chain, ordered by timestamp ascending to show the sequence of operations. A chain groups related receipts from a multi-step agent workflow. Returns the complete receipt objects for every step. Use to audit a complete workflow, calculate total chain cost and duration, or identify which step in a pipeline failed.

Export the Ed25519 public key used to sign all receipts on this instance. Returns the key as a 64-character hex string. Share this key with clients or third parties so they can independently verify receipt signatures without accessing your private key. The private key never leaves your machine — only the public key is needed for verification.

Start an AI judgment evaluation for a receipt by creating a pending judgment receipt and returning a structured evaluation prompt. The host model (you) evaluates the receipt's output against the provided rubric criteria and then calls complete_judgment with the results. Use to assess output quality beyond simple pass/fail constraints — supports weighted criteria, partial verdicts, and confidence scores. Judgment receipts are themselves Ed25519-signed for auditability.

Submit evaluation results to finalize a pending judgment receipt created by judge_receipt. Records the verdict, overall score, per-criterion scores and reasoning, and confidence. The judgment receipt is re-signed with Ed25519 and linked to the original receipt via parent_receipt_id. Returns the judgment receipt ID, verdict, score, and chain ID. Use immediately after evaluating the prompt returned by judge_receipt.

Retrieve all judgment receipts associated with a given receipt ID. Judgment receipts are linked via parent_receipt_id. Returns an array of judgment receipt objects ordered by timestamp, including verdict, score, criteria results, and confidence. Use to review the evaluation history of a receipt, compare multiple judgments, or audit AI quality assessments. Returns empty array if no judgments exist.

Delete receipts that have passed their expiration time based on the expires_at field in metadata. Expired receipts are receipts where metadata.expires_at is set and is earlier than the current time. Supports dry_run mode to preview deletions without committing. Returns count of deleted receipts and remaining total. Use periodically to manage storage and enforce TTL policies set during receipt creation. Set cleanup_memory to also soft-delete expired memory observations.

Generate a client invoice from cryptographically signed receipts within a date range. Aggregates receipt data by agent, action, or day and calculates total costs, token usage, and receipt counts. Supports JSON, CSV, and Markdown output formats. Each line item references a signed receipt for verifiable billing. Use to bill clients for AI agent work with cryptographic proof of every billed action.

Display a getting-started guide with usage examples for all Agent Receipts tools. Shows how to record agent actions, verify receipts, use receipt chains, evaluate with constraints, and generate invoices. Call this tool first when setting up Agent Receipts or when you need a reference for available tools and their typical usage patterns.

Store a memory observation about a person, project, preference, or any entity. Automatically creates the entity if it doesn't exist. Every observation is cryptographically signed and linked to a receipt.

Search and retrieve stored memories. Use text search to find relevant observations across all entities, or filter by entity type, specific entity, or scope. Every recall is logged as a receipt.

Forget a specific observation or an entire entity. This is a soft delete — the memory is marked as forgotten but retained for audit purposes. The forget operation itself is recorded as a signed receipt.

List known entities (people, projects, organizations, etc.) with optional filtering. Returns entities with their observation counts.

Create a relationship between two entities (e.g., "Amin" builds "ModQuote"). Relationships are bidirectional for querying but stored with a direction.

Get the full provenance chain for a memory observation. Shows when it was created, which conversation produced it, which agent made the observation, and every subsequent modification.

Generate an audit report of memory operations. Shows what was remembered, forgotten, merged, and by which agents over a time period.

Get a complete context dump of all stored memories — top entities, recent observations, active relationships, and preferences. Call this at the start of a conversation to understand what is already known about the user, their projects, and their preferences. Every context pull is logged as a signed receipt.

Export memories as a portable, verifiable bundle. Includes entities, observations, relationships, source receipts, and the public key needed to verify them. Share with other agents or import into another Agent Receipts instance.

Import a memory bundle from another Agent Receipts instance. Verifies checksums before importing. Skips memories that already exist locally. The import operation itself is recorded as a signed receipt.