lightning-memory MCP server
✓ VerifiedProvides persistent memory, vendor reputation tracking, and payment safety gates for AI agents operating in the Bitcoin Lightning economy.
Also known as singularityjason/lightning-memory
- Stars
- 9
- Tools
- 6
- Downloads, 30 days
- 67
- Latest version
- 0.4.1
- Last commit
- Mar 25, 2026
- License
- MIT
What is lightning-memory MCP?
lightning-memory provides persistent memory, vendor reputation tracking, and payment safety gates for AI agents operating in the Bitcoin Lightning economy. It exposes 6 tools, such as memory_store, memory_query, memory_list.
Summary generated from the project's README
About lightning-memory MCP server
Autonomous agents operating within the Bitcoin Lightning economy can use this tool to maintain a persistent memory of their financial activities. It solves the problem of agents starting every session with no knowledge of previous transactions, vendor reliability, or pricing history. By providing a layer of intelligence above L1 and L2 payments, it allows agents to learn from spending, track vendor reputations, and detect price anomalies.
Developers can integrate this via MCP with clients like Claude Desktop or Claude Code. The system is local-first, using SQLite for storage, and identifies agents through Nostr keys rather than traditional accounts or API keys. It includes specialized tools for budget enforcement, such as setting per-vendor limits, and safety features like pre-flight gates to approve or reject payments based on historical context. For those building distributed networks, it supports an L402 gateway where other agents can pay micropayments to query specific memory data.
What you can do with it
- 1Detecting suspicious price increasesAsk the agent to check if a current invoice is significantly higher than what was paid previously for the same vendor.
- 2Enforcing strict spending limitsInstruct the agent to prevent any single transaction from exceeding a specific amount of sats for a particular vendor.
- 3Verifying vendor reliabilityRequest a reputation report for a vendor based on the agent's past successful and failed transactions.
- 4Securing payments with pre-flight checksHave the agent run a safety check to verify budget availability and vendor trust before sending a Lightning payment.
Written from the project's README. Every use case is checked against a quote from it.
How to install lightning-memory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall lightning-memory MCP in Claude Code
$ claude mcp add lightning-memory -- uvx lightning-memoryInstall lightning-memory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"lightning-memory": {
"command": "uvx",
"args": [
"lightning-memory"
]
}
}
}Install lightning-memory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"lightning-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"lightning-memory"
]
}
}
}Install lightning-memory MCP in VS Code CLI
$ code --add-mcp '{"name":"lightning-memory","type":"stdio","command":"uvx","args":["lightning-memory"]}'Install lightning-memory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"lightning-memory": {
"command": "uvx",
"args": [
"lightning-memory"
]
}
}
}Install lightning-memory MCP in Codex
$ codex mcp add lightning-memory -- uvx lightning-memoryInstall lightning-memory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.lightning-memory] command = "uvx" args = ["lightning-memory"]
Install lightning-memory MCP in Gemini CLI
$ gemini mcp add -s user lightning-memory uvx -- lightning-memoryInstall lightning-memory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"lightning-memory": {
"command": "uvx",
"args": [
"lightning-memory"
]
}
}
}lightning-memory MCP tools 6
Detected from the READMEmemory_storememory_querymemory_listmemory_editmemory_syncmemory_export
| memory_store | — | |
| memory_query | — | |
| memory_list | — | |
| memory_edit | — | |
| memory_sync | — | |
| memory_export | — |
Configuration
PHOENIXD_PASSWORD
| Name | Description | |
|---|---|---|
| PHOENIXD_PASSWORD | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesingularityjason/lightning-memory is public and reachablegithub.com/singularityjason/lightning-memory ↗Pass
- Package names this repository as its sourcelightning-memory names singularityjason/lightning-memory as sourcepypi.org/project/lightning-memory/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-03-25github.com/singularityjason/lightning-memory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from lightning-memoryPass
- No critical advisory in the package or its dependencies29 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubLightning 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 — watch an agent learn, get rugged, and route around bad actors.
Building the Agent Economy — trust, budgets, compliance, and the memory marketplace.
Who Is This For
- Agents making L402 payments that need vendor reputation and spending discipline
- Developers building autonomous agents on Bitcoin/Lightning
- Anyone running an MCP-compatible AI agent (Claude, GPT, or any MCP client)
Quick Start
pip install lightning-memory
lightning-memory # starts MCP server
Configure in Claude Code
{
"mcpServers": {
"lightning-memory": {
"command": "lightning-memory"
}
}
}
Configure in Claude Desktop
{
"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 |
Tools (22)
Memory
| Tool | Description |
|---|---|
memory_store |
Store a memory (transaction, vendor, preference, error, decision) |
memory_query |
Search by relevance (FTS5 + optional semantic search) |
memory_list |
List memories with type/time filters |
memory_edit |
Edit content or metadata with audit trail |
memory_sync |
Sync with Nostr relays (push/pull) |
memory_export |
Export 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)
# → recency-weighted results with dedup and contradiction alerts
Lightning Intelligence
| Tool | Description |
|---|---|
ln_vendor_reputation |
Reputation score from transaction history |
ln_spending_summary |
Spending breakdown by vendor and protocol |
ln_anomaly_check |
Detect if a payment is abnormally high |
ln_vendor_reputation(vendor="bitrefill.com")
# → {reputation: {total_txns: 12, success_rate: 0.92, avg_sats: 450}, recommendation: "reliable"}
ln_anomaly_check(vendor="bitrefill.com", amount_sats=5000)
# → {anomaly: {verdict: "high", context: "5000 sats is 11.1x the historical average..."}}
Payment Safety
| Tool | Description |
|---|---|
ln_preflight |
Pre-flight gate: budget + anomaly + trust check before payment |
ln_budget_set |
Set per-vendor spending limits (per txn, per day, per month) |
ln_budget_check |
Check spending against limits |
ln_budget_status |
Gateway earnings and L402 payment stats |
ln_preflight(vendor="bitrefill.com", amount_sats=500)
# → {decision: {verdict: "approve", budget_remaining_today: 4500, trust_score: 0.89}}
# If the vendor suddenly charges 50x:
ln_preflight(vendor="bitrefill.com", amount_sats=25000)
# → {decision: {verdict: "reject", reasons: ["exceeds daily limit of 5000 sats"]}}
Trust & Compliance
| Tool | Description |
|---|---|
ln_vendor_trust |
Full trust profile (KYC + reputation + community score) |
ln_trust_attest |
Publish NIP-85 trust attestation to Nostr relays |
ln_agent_attest |
Store a KYA (Know Your Agent) attestation |
ln_agent_verify |
Look up an agent's compliance status |
ln_auth_session |
Store LNURL-auth session records |
ln_auth_lookup |
Look up LNURL-auth sessions |
ln_compliance_report |
Generate structured compliance export |
Marketplace
| Tool | Description |
|---|---|
ln_discover_gateways |
Find remote Lightning Memory gateways via Nostr |
ln_remote_query |
Query a remote gateway via L402 micropayment |
ln_discover_gateways(operation="memory_query")
# → {count: 2, gateways: [{url: "https://gw1.example.com", operations: {...}}, ...]}
ln_remote_query(
gateway_url="https://gw.example.com",
operation="ln_vendor_reputation",
params='{"vendor": "openai"}'
)
# → Pays 3 sats, returns remote agent's vendor intelligence
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 # Listening on 0.0.0.0:8402
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 |
|---|---|---|---|
/info |
GET | Free | Gateway status, pricing, node info |
/health |
GET | Free | Health check |
/memory/store |
POST | 3 sats | Store a memory |
/memory/query |
GET | 2 sats | Search memories by relevance |
/memory/list |
GET | 1 sat | List memories with filters |
/ln/vendor/{name} |
GET | 3 sats | Vendor reputation report |
/ln/spending |
GET | 2 sats | Spending summary |
/ln/anomaly-check |
POST | 3 sats | Payment anomaly detection |
/ln/preflight |
POST | 3 sats | Pre-flight payment gate |
/ln/trust/{name} |
GET | 2 sats | Vendor trust profile |
/ln/budget |
GET | 1 sat | Budget rules and spending |
/ln/compliance-report |
GET | 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 # Start MCP server
lightning-memory stats # Memory statistics dashboard
lightning-memory export json # Export memories as JSON
lightning-memory export csv # Export memories as CSV
lightning-memory relay-status # Check Nostr relay connectivity
lightning-memory-gateway # Start L402 HTTP gateway
lightning-memory-manifest # Generate gateway discovery 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.io |
Fast | High | Most popular, good uptime |
wss://nos.lol |
Fast | High | Reliable, good NIP-78 support |
wss://relay.nostr.band |
Medium | Medium | Search-focused, may be slow |
wss://relay.primal.net |
Fast | High | Well-maintained |
wss://nostr.wine |
Fast | 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
- Phase 1: MCP server with local SQLite storage
- Phase 2: Lightning intelligence (vendor reputation, spending summary, anomaly detection)
- Phase 3: Nostr relay sync (NIP-78, Schnorr signing, bidirectional sync)
- Phase 4: L402 payment gateway (macaroons, Phoenixd, HTTP gateway)
- Phase 5: Compliance & trust (budget enforcement, vendor KYC, community reputation, pre-flight gate)
- Phase 6: Memory marketplace (gateway discovery, remote L402 queries, gateway client)
- Phase 7: Agent reliability (semantic search, deduplication, contradiction detection, circuit breakers)
Star History
License
MIT
lightning-memory MCP questions
How do I add lightning-memory MCP to Claude Code?
Run claude mcp add lightning-memory -- uvx lightning-memory in your terminal. Add --scope user to make it available in every project.
How do I add lightning-memory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does lightning-memory MCP provide?
It exposes 6 tools, including memory_store, memory_query, memory_list, memory_edit, memory_sync.
What does Lightning Memory do for AI agents?
It provides persistent memory, vendor intelligence, and payment safety gates, allowing agents to learn from spending history and detect price anomalies.
Can I use this with Claude?
Yes, it is MCP-compatible and can be configured in Claude Code or Claude Desktop.