Lightning Memory
Persistent memory for AI agents in the Lightning economy.
The Problem
AI agents spend sats over Lightning via L402 — but they can't remember what they bought. Every session starts from zero. Every vendor is a stranger. Every price is accepted at face value. An agent that paid 500 sats yesterday doesn't know if today's 5,000 sat invoice is a price spike or normal.
The Solution
L1: Bitcoin — settles
L2: Lightning — pays
L3: Lightning Memory — remembers
Lightning Memory gives agents persistent memory, vendor intelligence, and payment safety gates. Agents learn from their spending history, track vendor reputations, detect price anomalies, enforce budgets, and share trust signals with other agents.
Interactive Demo
Building the Agent Economy
Who Is This For
Agents making L402 payments that need vendor reputation and spending disciplineDevelopers building autonomous agents on Bitcoin/LightningAnyone running an MCP-compatible AI agent (Claude, GPT, or any MCP client)
Quick Start
pip install lightning-memory
lightning-memory
{
"mcpServers" : {
"lightning-memory" : {
"command" : "lightning-memory"
}
}
}
{
"mcpServers" : {
"lightning-memory" : {
"command" : "python" ,
"args" : [ "-m" , "lightning_memory.server" ]
}
}
}
How It Compares
Feature Lightning Memory Mem0 Raw file storage No memory Lightning/L402 awareness Yes No No No Vendor reputation tracking Yes No Manual No Spending anomaly detection Yes No No No Nostr identity (BIP-340) Yes No No No Relay sync (NIP-78) Yes No No No Full-text + semantic search Yes Yes No No Agent-to-agent knowledge markets Yes (L402 gateway) No No No Budget enforcement Yes No No No KYC/trust profiles Yes No No No Payment pre-flight gate Yes No No No Contradiction detection Yes No No No Local-first / offline Yes Cloud Yes N/A MCP native Yes Plugin No No Zero config Yes API key required Manual setup N/A
Memory
Tool Description memory_storeStore a memory (transaction, vendor, preference, error, decision) memory_querySearch by relevance (FTS5 + optional semantic search) memory_listList memories with type/time filters memory_editEdit content or metadata with audit trail memory_syncSync with Nostr relays (push/pull) memory_exportExport as NIP-78 Nostr events
memory_store(
content="Paid 500 sats to bitrefill.com for a $5 Amazon gift card via L402." ,
type ="transaction" ,
metadata='{"vendor": "bitrefill.com", "amount_sats": 500}'
)
memory_query(query="bitrefill payment history" , limit=5 )
Lightning Intelligence
Tool Description ln_vendor_reputationReputation score from transaction history ln_spending_summarySpending breakdown by vendor and protocol ln_anomaly_checkDetect if a payment is abnormally high
ln_vendor_reputation(vendor="bitrefill.com" )
ln_anomaly_check(vendor="bitrefill.com" , amount_sats=5000 )
Payment Safety
Tool Description ln_preflightPre-flight gate: budget + anomaly + trust check before payment ln_budget_setSet per-vendor spending limits (per txn, per day, per month) ln_budget_checkCheck spending against limits ln_budget_statusGateway earnings and L402 payment stats
ln_preflight(vendor="bitrefill.com" , amount_sats=500 )
ln_preflight(vendor="bitrefill.com" , amount_sats=25000 )
Trust & Compliance
Tool Description ln_vendor_trustFull trust profile (KYC + reputation + community score) ln_trust_attestPublish NIP-85 trust attestation to Nostr relays ln_agent_attestStore a KYA (Know Your Agent) attestation ln_agent_verifyLook up an agent's compliance status ln_auth_sessionStore LNURL-auth session records ln_auth_lookupLook up LNURL-auth sessions ln_compliance_reportGenerate structured compliance export
Marketplace
Tool Description ln_discover_gatewaysFind remote Lightning Memory gateways via Nostr ln_remote_queryQuery a remote gateway via L402 micropayment
ln_discover_gateways(operation="memory_query" )
ln_remote_query(
gateway_url="https://gw.example.com" ,
operation="ln_vendor_reputation" ,
params='{"vendor": "openai"}'
)
Architecture
Nostr identity : Agent identity = Nostr keypair (BIP-340). No accounts, no API keys.Local-first : SQLite with FTS5 full-text search + optional ONNX semantic search. Works offline.Nostr sync : Memories written as NIP-78 events to relays. Portable, tamper-proof.L402 payments : Pay-per-query gateway. 1-10 sats per operation.Memory quality : Deduplication, contradiction detection, noise filtering, recency-weighted ranking, access tracking.
L402 Gateway
Run an L402 pay-per-query HTTP gateway. Other agents pay Lightning micropayments to access your agent's memory — no API keys, no accounts.
pip install lightning-memory[gateway]
lightning-memory-gateway
How L402 Works
Agent Gateway Phoenixd
| | |
|-- GET /memory/query?q=... --->| |
|<-- 402 + Lightning invoice ---|--- create_invoice -------->|
| |<-- bolt11 + payment_hash --|
| | |
| [pay invoice via Lightning] | |
| | |
|-- GET + L402 token ---------->| |
| (macaroon:preimage) |--- verify preimage ------->|
|<-- 200 + query results -------| |
Endpoints
Endpoint Method Price Description /infoGET Free Gateway status, pricing, node info /healthGET Free Health check /memory/storePOST 3 sats Store a memory /memory/queryGET 2 sats Search memories by relevance /memory/listGET 1 sat List memories with filters /ln/vendor/{name}GET 3 sats Vendor reputation report /ln/spendingGET 2 sats Spending summary /ln/anomaly-checkPOST 3 sats Payment anomaly detection /ln/preflightPOST 3 sats Pre-flight payment gate /ln/trust/{name}GET 2 sats Vendor trust profile /ln/budgetGET 1 sat Budget rules and spending /ln/compliance-reportGET 10 sats Compliance report export
Phoenixd Setup
Download and run Phoenixd (listens on localhost:9740)
Fund it with ~10,000 sats for initial channel opening
Configure: ~/.lightning-memory/config.json → {"phoenixd_password": "<from ~/.phoenix/phoenix.conf>"}
Start: lightning-memory-gateway
Docker
PHOENIXD_PASSWORD=your-password docker compose up
CLI Commands
lightning-memory
lightning-memory stats
lightning-memory export json
lightning-memory export csv
lightning-memory relay-status
lightning-memory-gateway
lightning-memory-manifest
Relay Configuration
Default relays: wss://relay.damus.io, wss://nos.lol, wss://relay.nostr.band
Customize in ~/.lightning-memory/config.json:
{
"relays" : [ "wss://relay.damus.io" , "wss://nos.lol" , "wss://relay.primal.net" ] ,
"sync_timeout_seconds" : 30 ,
"max_events_per_sync" : 500
}
Relay Speed Reliability Notes wss://relay.damus.ioFast High Most popular, good uptime wss://nos.lolFast High Reliable, good NIP-78 support wss://relay.nostr.bandMedium Medium Search-focused, may be slow wss://relay.primal.netFast High Well-maintained wss://nostr.wineFast High Paid relay, less spam
Optional: Semantic Search
Add ONNX-based semantic similarity search alongside FTS5 keyword search:
pip install lightning-memory[semantic]
Queries then use hybrid ranking: FTS5 BM25 + cosine similarity with reciprocal rank fusion. "Which vendors are reliable for transcription" matches memories containing "whisper API" and "audio-to-text" even without exact keyword overlap.
Data Storage
~/.lightning-memory/
memories.db # SQLite database
keys/
private.key # Nostr private key (chmod 600)
public.key # Nostr public key (your agent identity)
Roadmap
Star History
License
MIT
