Store a memory for later retrieval.

Use this to remember transactions, vendor experiences, decisions, spending patterns, API responses, or any information worth recalling.

Args: content: The memory content to store. Be descriptive. Examples: - "Paid 500 sats to bitrefill.com for a $5 Amazon gift card via L402. Fast, reliable." - "OpenAI API returned 429 rate limit after 50 requests/min. Backoff to 30/min." - "User prefers to cap spending at 10,000 sats per session." type: Memory category. One of: - general: Default, uncategorized - transaction: Payment records, invoices, L402 purchases - vendor: Service/API reputation and reliability notes - preference: User or agent preferences and settings - error: Error patterns and failure modes - decision: Key decisions and their reasoning metadata: JSON string of additional key-value pairs. Example: '{"vendor": "bitrefill.com", "amount_sats": 500}'

Returns: The stored memory record with id, content, type, and timestamps.

Search memories by relevance. Returns the most relevant matches.

Use this to recall past transactions, check vendor reputation, retrieve spending patterns, or find any previously stored information.

Args: query: Natural language search query. Examples: - "bitrefill payment history" - "which APIs gave rate limit errors?" - "spending decisions this week" limit: Maximum number of results (default 10, max 100). type: Optional filter by memory type (transaction, vendor, preference, error, decision, general).

Returns: List of matching memories ranked by relevance, with scores.

List memories, optionally filtered by type and time range.

Use this to browse recent memories, check all transactions, or review memories of a specific type.

Args: type: Filter by memory type (transaction, vendor, preference, error, decision, general). since: Time filter. Relative: "1h", "24h", "7d", "30d". Or Unix timestamp. limit: Maximum number of results (default 50, max 200).

Returns: List of memories in reverse chronological order with stats.

Edit an existing memory's content or metadata.

Use this to correct wrong vendor information, update prices, or add context to an existing memory. Tracks edit history.

Args: id: The memory ID to edit. content: New content to replace the existing content. If omitted, content is unchanged. metadata: JSON string of metadata fields to merge into existing metadata. Example: '{"vendor": "bitrefill.com", "note": "price updated"}'

Returns: The updated memory record with old_content_preview for audit trail.

Check a vendor's reputation based on transaction history.

Use this before paying a vendor to see if they're reliable. Aggregates all past transactions to build a reputation score.

Args: vendor: Vendor name or domain (e.g., "bitrefill.com", "openai").

Returns: Reputation report: total transactions, total sats spent, success rate, average payment size, and tags.

Get a spending summary for budget awareness.

Shows total sats spent, broken down by vendor and protocol.

Args: since: Time period. Relative: "1h", "24h", "7d", "30d". Or Unix timestamp.

Returns: Spending breakdown with totals by vendor and protocol.

Check if a proposed payment amount is normal for a vendor.

Use this before making a payment to catch price anomalies. Compares the proposed amount against historical averages.

Args: vendor: Vendor name or domain. amount_sats: Proposed payment amount in satoshis.

Returns: Anomaly report: verdict (normal/high/first_time), context, and historical average.

Sync memories with Nostr relays.

Push local memories to relays and/or pull remote memories to local. When gateway_discovery is enabled, also syncs gateway announcements. Requires secp256k1 for push (signing). Pull works with any identity.

Args: direction: Sync direction. One of: - "push": Upload local memories to relays - "pull": Download memories from relays - "both": Push then pull (default)

Returns: Sync result with counts of pushed/pulled memories and any errors.

Export memories as Nostr NIP-78 events.

Converts local memories into portable Nostr event format. Events are signed if secp256k1 is available. Useful for backup, sharing, or manual relay publishing.

Args: limit: Maximum number of memories to export (default 100).

Returns: List of NIP-78 events with memory content.

Check L402 gateway earnings and payment stats.

Shows total sats earned from L402 gateway payments, broken down by operation. Reads from locally stored payment records (logged by the gateway).

Returns: Earnings summary: total sats, payment count, breakdown by operation.

Set spending limits for a vendor.

Creates budget rules that the pre-flight gate enforces. Any payment exceeding these limits will be rejected.

Args: vendor: Vendor name or domain (e.g., "bitrefill.com"). max_sats_per_txn: Maximum sats allowed per single transaction. max_sats_per_day: Maximum total sats per day to this vendor. max_sats_per_month: Maximum total sats per month to this vendor.

Returns: The created/updated budget rule.

List budget rules and current spending status.

Shows all active budget rules, or details for a specific vendor including how much has been spent today and this month.

Args: vendor: Optional vendor to check. If omitted, lists all rules.

Returns: Budget rules with current spending against limits.

Get a vendor's full trust profile.

Combines KYC verification status, local transaction reputation, and community trust attestations (from Nostr NIP-85) into a unified trust profile.

Args: vendor: Vendor name or domain.

Returns: Trust profile: KYC status, jurisdiction, community score, attestation count, and local reputation data.

Pre-flight check before making a payment.

Runs budget limits, anomaly detection, and trust verification to produce an approve/reject/escalate decision. Use this before every payment to catch overspending, price anomalies, and unverified vendors.

Args: vendor: Vendor name or domain. amount_sats: Proposed payment amount in satoshis.

Returns: Decision: verdict (approve/reject/escalate), reasons, budget remaining, anomaly status, and trust score.

Publish a trust attestation for a vendor.

Creates a NIP-85 Trusted Assertion and pushes it to Nostr relays. Other agents can pull these attestations to build community reputation.

Args: vendor: Vendor name or domain to attest. score: Trust score 0.0-1.0. If omitted, auto-calculated from local reputation (success_rate * volume factor). basis: Reason for the score (default: "transaction_history").

Returns: Attestation details including score and relay push status.

Store an attestation about an agent's identity and compliance status.

Used for Know Your Agent (KYA) — agents self-attesting, operators attesting their agents, or third-party KYA providers.

Args: agent_pubkey: The agent's Nostr public key (64 hex chars). owner_id: Owner identifier (email, company name, etc.). jurisdiction: Legal jurisdiction (e.g., "US", "EU", "SG"). compliance_level: One of: unknown, self_declared, kyc_verified, regulated_entity. source: Verification source (e.g., "manual", "sumsub", "trulioo").

Returns: The stored attestation record.

Look up an agent's compliance attestation.

Args: agent_pubkey: The agent's Nostr public key to verify.

Returns: Attestation details or {status: "unknown"} if not found.

Store or update an LNURL-auth session record.

Record-keeping for externally-established LNURL-auth sessions.

Args: vendor: Vendor name or domain. linking_key: The LNURL-auth linking key for this vendor. session_state: Session state: active, expired, or revoked.

Returns: The stored session record.

Check if an LNURL-auth session exists with a vendor.

Args: vendor: Vendor name or domain to check.

Returns: Session details if found, or {has_session: false}.

Generate a structured compliance report.

Produces a comprehensive report covering agent identity, transactions, budget rules, vendor KYC status, anomaly flags, and trust attestations. Designed for regulatory compliance export.

Args: since: Time period for temporal data. Relative: "1h", "24h", "7d", "30d". Current-state data (budget rules, KYC) is always included. format: Output format. Only "json" supported in v1.

Returns: Compliance report as a structured dict.

List known Lightning Memory gateways discovered via Nostr relays.

Args: operation: Optional filter — only return gateways offering this operation (e.g., "memory_query", "ln_vendor_reputation").

Returns: List of known gateways with URL, operations, pricing, and last seen time.

Query a remote Lightning Memory gateway via L402 micropayment.

Pays the gateway's Lightning invoice automatically via Phoenixd, then returns the query results. The payment is logged as a transaction memory.

Args: gateway_url: URL of the remote gateway (e.g., "https://gw.example.com"). operation: Operation to perform. One of: memory_query, memory_list, ln_vendor_reputation, ln_spending_summary, ln_anomaly_check, ln_preflight, ln_vendor_trust, ln_budget_check, ln_compliance_report. params: JSON string of operation-specific parameters.

Returns: Remote gateway's response data, or error details.