io.github.webaesbyamin/agent-receipts

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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

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 the Ed25519 signature on a stored receipt to confirm it has not been changed since signing. Receipt format v2 signs every field (summary, cost, model, metadata, files and the chain link); legacy v1 receipts sign 12 core fields only. Returns verified, sig_version and covers_all_fields. To check a whole chain for edited, removed or forked receipts, use the CLI: agent-receipts verify-chain <chain_id>. Use to audit receipts before using them as evidence or before completing payments based on agent work.