lightning-memory — Claude Code MCP server: install and use
Adds persistent memory and payment safety gates for AI agents spending satoshis over the Lightning network via L402.
claude mcp add lightning-memory -- uvx lightning-memoryWhat lightning-memory does
Standard coding agents lose payment history once a process terminates. Every session starts clean. As a consequence, agents accept price spikes blindly. This server solves that issue by logging transactions, vendors, and decisions into a local SQLite database powered by FTS5 search.
The server provides 22 callable tools. They evaluate prospective invoices via ln_preflight and enforce monthly spend thresholds. Agent identity maps directly to Nostr keypairs under BIP-340, skipping external platform registrations. State sync across nodes runs over Nostr relays using NIP-78 events.
Python 3.10 or higher is required. Running the optional remote HTTP gateway on port 8402 requires the extra lightning-memory[gateway] package. Without configured spending limits, the preflight check will not flag suspicious payment requests.
What it helps with
- halt suspicious Lightning invoices before spending sats
- store agent transaction logs in a local SQLite database
- track vendor history and calculate pricing reputation under L402
- sync agent memory across Nostr relays via NIP-78
- enforce per-vendor daily and monthly payment limits
Example prompts for the agent
- Run
ln_preflighton a 500 sat payment to bitrefill.com to check my daily budget. - Check the reputation and average order value for vendor bitrefill.com with
ln_vendor_reputation. - Record a new transaction of 500 sats for a gift card using
memory_store.
How to install lightning-memory
Platform CLI
claude mcp add lightning-memory -- uvx lightning-memoryuvx runs the command named after the package; if the README names another one, use uvx --from lightning-memory <command>
Platform CLI
codex mcp add lightning-memory -- uvx lightning-memoryuvx runs the command named after the package; if the README names another one, use uvx --from lightning-memory <command>
Config file
{
"mcpServers": {
"lightning-memory": {
"command": "uvx",
"args": [
"lightning-memory"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from lightning-memory <command>
Config file
{
"servers": {
"lightning-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"lightning-memory"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from lightning-memory <command>
Platform CLI
gemini mcp add lightning-memory uvx lightning-memoryuvx runs the command named after the package; if the README names another one, use uvx --from lightning-memory <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about lightning-memory
How to install lightning-memory in Claude Code?
Run claude mcp add lightning-memory -- uvx lightning-memory in your terminal. This command links the server directly via uvx.
What does lightning-memory do?
It gives agents persistent local memory for Bitcoin Lightning payments, detects billing anomalies, and checks balances against preset limits.
Does lightning-memory require third-party API keys?
No external accounts or subscription keys are needed. The agent authenticates using local Nostr BIP-340 keypairs.
