{"id":47296410,"url":"https://github.com/singularityjason/lightning-memory","last_synced_at":"2026-04-08T13:30:23.659Z","repository":{"id":341947041,"uuid":"1167170204","full_name":"singularityjason/lightning-memory","owner":"singularityjason","description":"Decentralized agent memory for the Lightning economy. Nostr identity, L402 payments, MCP server.","archived":false,"fork":false,"pushed_at":"2026-03-25T02:36:23.000Z","size":903,"stargazers_count":6,"open_issues_count":6,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-25T20:37:02.408Z","etag":null,"topics":["agent-memory","ai-agents","ai-memory","bitcoin","claude-code","decentralized","developer-tools","l402","lightning","lightning-network","llm-tools","macaroon","mcp","mcp-server","nostr","open-source","payments","python","semantic-search","sqlite"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/lightning-memory/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/singularityjason.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T02:29:37.000Z","updated_at":"2026-03-25T02:36:26.000Z","dependencies_parsed_at":"2026-03-24T18:04:02.841Z","dependency_job_id":null,"html_url":"https://github.com/singularityjason/lightning-memory","commit_stats":null,"previous_names":["singularityjason/lightning-memory"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/singularityjason/lightning-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityjason%2Flightning-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityjason%2Flightning-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityjason%2Flightning-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityjason%2Flightning-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/singularityjason","download_url":"https://codeload.github.com/singularityjason/lightning-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityjason%2Flightning-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31558378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T10:21:54.569Z","status":"ssl_error","status_checked_at":"2026-04-08T10:21:38.171Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-memory","ai-agents","ai-memory","bitcoin","claude-code","decentralized","developer-tools","l402","lightning","lightning-network","llm-tools","macaroon","mcp","mcp-server","nostr","open-source","payments","python","semantic-search","sqlite"],"created_at":"2026-03-16T17:00:15.522Z","updated_at":"2026-04-08T13:30:23.645Z","avatar_url":"https://github.com/singularityjason.png","language":"Python","readme":"# Lightning Memory\n\n[![PyPI version](https://img.shields.io/pypi/v/lightning-memory.svg)](https://pypi.org/project/lightning-memory/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n\nPersistent memory for AI agents in the Lightning economy.\n\n## The Problem\n\nAI 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.\n\n## The Solution\n\n```\nL1: Bitcoin      — settles\nL2: Lightning    — pays\nL3: Lightning Memory — remembers\n```\n\nLightning 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.\n\n**[Interactive Demo](https://www.jasonsosa.com/blog/agent-lightning-memory)** — watch an agent learn, get rugged, and route around bad actors.\n\n**[Building the Agent Economy](https://www.jasonsosa.com/blog/agent-economy-trust-marketplace-bitcoin-lightning)** — trust, budgets, compliance, and the memory marketplace.\n\n## Who Is This For\n\n- **Agents making L402 payments** that need vendor reputation and spending discipline\n- **Developers building autonomous agents** on Bitcoin/Lightning\n- **Anyone running an MCP-compatible AI agent** (Claude, GPT, or any MCP client)\n\n## Quick Start\n\n```bash\npip install lightning-memory\nlightning-memory  # starts MCP server\n```\n\n### Configure in Claude Code\n\n```json\n{\n  \"mcpServers\": {\n    \"lightning-memory\": {\n      \"command\": \"lightning-memory\"\n    }\n  }\n}\n```\n\n### Configure in Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"lightning-memory\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"lightning_memory.server\"]\n    }\n  }\n}\n```\n\n## How It Compares\n\n| Feature | Lightning Memory | Mem0 | Raw file storage | No memory |\n|---------|:---:|:---:|:---:|:---:|\n| Lightning/L402 awareness | Yes | No | No | No |\n| Vendor reputation tracking | Yes | No | Manual | No |\n| Spending anomaly detection | Yes | No | No | No |\n| Nostr identity (BIP-340) | Yes | No | No | No |\n| Relay sync (NIP-78) | Yes | No | No | No |\n| Full-text + semantic search | Yes | Yes | No | No |\n| Agent-to-agent knowledge markets | Yes (L402 gateway) | No | No | No |\n| Budget enforcement | Yes | No | No | No |\n| KYC/trust profiles | Yes | No | No | No |\n| Payment pre-flight gate | Yes | No | No | No |\n| Contradiction detection | Yes | No | No | No |\n| Local-first / offline | Yes | Cloud | Yes | N/A |\n| MCP native | Yes | Plugin | No | No |\n| Zero config | Yes | API key required | Manual setup | N/A |\n\n## Tools (22)\n\n### Memory\n\n| Tool | Description |\n|------|-------------|\n| `memory_store` | Store a memory (transaction, vendor, preference, error, decision) |\n| `memory_query` | Search by relevance (FTS5 + optional semantic search) |\n| `memory_list` | List memories with type/time filters |\n| `memory_edit` | Edit content or metadata with audit trail |\n| `memory_sync` | Sync with Nostr relays (push/pull) |\n| `memory_export` | Export as NIP-78 Nostr events |\n\n```python\nmemory_store(\n  content=\"Paid 500 sats to bitrefill.com for a $5 Amazon gift card via L402.\",\n  type=\"transaction\",\n  metadata='{\"vendor\": \"bitrefill.com\", \"amount_sats\": 500}'\n)\n\nmemory_query(query=\"bitrefill payment history\", limit=5)\n# → recency-weighted results with dedup and contradiction alerts\n```\n\n### Lightning Intelligence\n\n| Tool | Description |\n|------|-------------|\n| `ln_vendor_reputation` | Reputation score from transaction history |\n| `ln_spending_summary` | Spending breakdown by vendor and protocol |\n| `ln_anomaly_check` | Detect if a payment is abnormally high |\n\n```python\nln_vendor_reputation(vendor=\"bitrefill.com\")\n# → {reputation: {total_txns: 12, success_rate: 0.92, avg_sats: 450}, recommendation: \"reliable\"}\n\nln_anomaly_check(vendor=\"bitrefill.com\", amount_sats=5000)\n# → {anomaly: {verdict: \"high\", context: \"5000 sats is 11.1x the historical average...\"}}\n```\n\n### Payment Safety\n\n| Tool | Description |\n|------|-------------|\n| `ln_preflight` | Pre-flight gate: budget + anomaly + trust check before payment |\n| `ln_budget_set` | Set per-vendor spending limits (per txn, per day, per month) |\n| `ln_budget_check` | Check spending against limits |\n| `ln_budget_status` | Gateway earnings and L402 payment stats |\n\n```python\nln_preflight(vendor=\"bitrefill.com\", amount_sats=500)\n# → {decision: {verdict: \"approve\", budget_remaining_today: 4500, trust_score: 0.89}}\n\n# If the vendor suddenly charges 50x:\nln_preflight(vendor=\"bitrefill.com\", amount_sats=25000)\n# → {decision: {verdict: \"reject\", reasons: [\"exceeds daily limit of 5000 sats\"]}}\n```\n\n### Trust \u0026 Compliance\n\n| Tool | Description |\n|------|-------------|\n| `ln_vendor_trust` | Full trust profile (KYC + reputation + community score) |\n| `ln_trust_attest` | Publish NIP-85 trust attestation to Nostr relays |\n| `ln_agent_attest` | Store a KYA (Know Your Agent) attestation |\n| `ln_agent_verify` | Look up an agent's compliance status |\n| `ln_auth_session` | Store LNURL-auth session records |\n| `ln_auth_lookup` | Look up LNURL-auth sessions |\n| `ln_compliance_report` | Generate structured compliance export |\n\n### Marketplace\n\n| Tool | Description |\n|------|-------------|\n| `ln_discover_gateways` | Find remote Lightning Memory gateways via Nostr |\n| `ln_remote_query` | Query a remote gateway via L402 micropayment |\n\n```python\nln_discover_gateways(operation=\"memory_query\")\n# → {count: 2, gateways: [{url: \"https://gw1.example.com\", operations: {...}}, ...]}\n\nln_remote_query(\n  gateway_url=\"https://gw.example.com\",\n  operation=\"ln_vendor_reputation\",\n  params='{\"vendor\": \"openai\"}'\n)\n# → Pays 3 sats, returns remote agent's vendor intelligence\n```\n\n## Architecture\n\n- **Nostr identity**: Agent identity = Nostr keypair (BIP-340). No accounts, no API keys.\n- **Local-first**: SQLite with FTS5 full-text search + optional ONNX semantic search. Works offline.\n- **Nostr sync**: Memories written as NIP-78 events to relays. Portable, tamper-proof.\n- **L402 payments**: Pay-per-query gateway. 1-10 sats per operation.\n- **Memory quality**: Deduplication, contradiction detection, noise filtering, recency-weighted ranking, access tracking.\n\n## L402 Gateway\n\nRun an L402 pay-per-query HTTP gateway. Other agents pay Lightning micropayments to access your agent's memory — no API keys, no accounts.\n\n```bash\npip install lightning-memory[gateway]\nlightning-memory-gateway  # Listening on 0.0.0.0:8402\n```\n\n### How L402 Works\n\n```\nAgent                          Gateway                      Phoenixd\n  |                               |                            |\n  |-- GET /memory/query?q=... ---\u003e|                            |\n  |\u003c-- 402 + Lightning invoice ---|--- create_invoice --------\u003e|\n  |                               |\u003c-- bolt11 + payment_hash --|\n  |                               |                            |\n  | [pay invoice via Lightning]   |                            |\n  |                               |                            |\n  |-- GET + L402 token ----------\u003e|                            |\n  |   (macaroon:preimage)         |--- verify preimage -------\u003e|\n  |\u003c-- 200 + query results -------|                            |\n```\n\n### Endpoints\n\n| Endpoint | Method | Price | Description |\n|----------|--------|-------|-------------|\n| `/info` | GET | Free | Gateway status, pricing, node info |\n| `/health` | GET | Free | Health check |\n| `/memory/store` | POST | 3 sats | Store a memory |\n| `/memory/query` | GET | 2 sats | Search memories by relevance |\n| `/memory/list` | GET | 1 sat | List memories with filters |\n| `/ln/vendor/{name}` | GET | 3 sats | Vendor reputation report |\n| `/ln/spending` | GET | 2 sats | Spending summary |\n| `/ln/anomaly-check` | POST | 3 sats | Payment anomaly detection |\n| `/ln/preflight` | POST | 3 sats | Pre-flight payment gate |\n| `/ln/trust/{name}` | GET | 2 sats | Vendor trust profile |\n| `/ln/budget` | GET | 1 sat | Budget rules and spending |\n| `/ln/compliance-report` | GET | 10 sats | Compliance report export |\n\n### Phoenixd Setup\n\n1. Download and run [Phoenixd](https://phoenix.acinq.co/server) (listens on `localhost:9740`)\n2. Fund it with ~10,000 sats for initial channel opening\n3. Configure: `~/.lightning-memory/config.json` → `{\"phoenixd_password\": \"\u003cfrom ~/.phoenix/phoenix.conf\u003e\"}`\n4. Start: `lightning-memory-gateway`\n\n### Docker\n\n```bash\nPHOENIXD_PASSWORD=your-password docker compose up\n```\n\n## CLI Commands\n\n```bash\nlightning-memory                  # Start MCP server\nlightning-memory stats            # Memory statistics dashboard\nlightning-memory export json      # Export memories as JSON\nlightning-memory export csv       # Export memories as CSV\nlightning-memory relay-status     # Check Nostr relay connectivity\nlightning-memory-gateway          # Start L402 HTTP gateway\nlightning-memory-manifest         # Generate gateway discovery manifest\n```\n\n## Relay Configuration\n\nDefault relays: `wss://relay.damus.io`, `wss://nos.lol`, `wss://relay.nostr.band`\n\nCustomize in `~/.lightning-memory/config.json`:\n\n```json\n{\n  \"relays\": [\"wss://relay.damus.io\", \"wss://nos.lol\", \"wss://relay.primal.net\"],\n  \"sync_timeout_seconds\": 30,\n  \"max_events_per_sync\": 500\n}\n```\n\n| Relay | Speed | Reliability | Notes |\n|-------|-------|-------------|-------|\n| `wss://relay.damus.io` | Fast | High | Most popular, good uptime |\n| `wss://nos.lol` | Fast | High | Reliable, good NIP-78 support |\n| `wss://relay.nostr.band` | Medium | Medium | Search-focused, may be slow |\n| `wss://relay.primal.net` | Fast | High | Well-maintained |\n| `wss://nostr.wine` | Fast | High | Paid relay, less spam |\n\n## Optional: Semantic Search\n\nAdd ONNX-based semantic similarity search alongside FTS5 keyword search:\n\n```bash\npip install lightning-memory[semantic]\n```\n\nQueries 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.\n\n## Data Storage\n\n```\n~/.lightning-memory/\n  memories.db    # SQLite database\n  keys/\n    private.key  # Nostr private key (chmod 600)\n    public.key   # Nostr public key (your agent identity)\n```\n\n## Roadmap\n\n- [x] Phase 1: MCP server with local SQLite storage\n- [x] Phase 2: Lightning intelligence (vendor reputation, spending summary, anomaly detection)\n- [x] Phase 3: Nostr relay sync (NIP-78, Schnorr signing, bidirectional sync)\n- [x] Phase 4: L402 payment gateway (macaroons, Phoenixd, HTTP gateway)\n- [x] Phase 5: Compliance \u0026 trust (budget enforcement, vendor KYC, community reputation, pre-flight gate)\n- [x] Phase 6: Memory marketplace (gateway discovery, remote L402 queries, gateway client)\n- [x] Phase 7: Agent reliability (semantic search, deduplication, contradiction detection, circuit breakers)\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=singularityjason/lightning-memory\u0026type=Date)](https://star-history.com/#singularityjason/lightning-memory\u0026Date)\n\n## License\n\nMIT\n\n\u003c!-- mcp-name: io.github.singularityjason/lightning-memory --\u003e\n","funding_links":[],"categories":["Projects","Tools"],"sub_categories":["Client reviews and/or comparisons"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityjason%2Flightning-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsingularityjason%2Flightning-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityjason%2Flightning-memory/lists"}