@0xkaleab/lumera-mcp

Permanent, verifiable memory for AI agents on Lumera Cascade.

An MCP server (and library) that lets any agent archive notes and files to decentralized storage, search them, recall them from any device, and prove on-chain that what came back is exactly what was stored.

Quick start

Claude Code:

claude mcp add lumera -- npx -y @0xkaleab/lumera-mcp

Codex:

codex mcp add lumera -- npx -y @0xkaleab/lumera-mcp

Codex gives a server 30 seconds to start, and the first run downloads the package. If it times out, give it longer in ~/.codex/config.toml:

[mcp_servers.lumera]
command = "npx"
args = ["-y", "@0xkaleab/lumera-mcp"]
startup_timeout_sec = 120

Claude Desktop or ChatGPT Desktop:

npx @0xkaleab/lumera-mcp install claude-desktop
npx @0xkaleab/lumera-mcp install chatgpt-desktop

This adds the server to the app's config, keeps everything else in it, and saves the old file as .bak. It writes the full path to your npx and a PATH that finds your Node, because desktop apps don't load your shell (a bare npx fails under nvm, fnm or Volta). Add --network mainnet to spend real LUME. ChatGPT Desktop shares its config with Codex, so install codex does the same. Restart the app afterwards.

Cursor, OpenHuman, or any other MCP client:

{
  "mcpServers": {
    "lumera": {
      "command": "npx",
      "args": ["-y", "@0xkaleab/lumera-mcp"]
    }
  }
}

Desktop apps often don't see your shell's PATH. If the server won't start, use the absolute path from which npx as command, and add "env": { "PATH": "<that directory>:/usr/bin:/bin" } so npx can find node.

Then ask your agent to create a Lumera wallet, and send LUME to the address it gives you. Ask it to show the wallet any time you need the address or balance again.

Wallet

Saving costs LUME, paid from your own Lumera wallet. Without one the server is read-only: status, fees, search and on-chain verification still work.

lumera_create_wallet makes a new wallet and saves its 24-word recovery phrase to ~/.lumera-mcp/mnemonic, readable only by you. The phrase never appears in chat. That file is the only copy, so back it up: lose it and the wallet's LUME is gone. Anyone who can read it controls the wallet, so keep the balance small.

To use a wallet you already have, put its mnemonic in that file instead (or point LUMERA_MNEMONIC_FILE at another one), then restart the server.

The default network is testnet; set LUMERA_NETWORK=mainnet in the server's env to spend real LUME.

Tools

| Tool | Costs LUME | | | --- | --- | --- | | lumera_remember | yes | Save a note (Markdown). Content that looks like a secret is refused. | | lumera_upload_file | yes | Save one local file. | | lumera_archive_file | yes | Save 2–20 local files, one Cascade action each. All paths are checked before anything is spent. | | lumera_save_chat | yes | Save a chat transcript as Markdown, verbatim. In OpenHuman, Claude Code and Codex it reads the current conversation itself. Other clients pass messages. | | lumera_search_memories | no | Search saved memories by keyword or tag. | | lumera_recall | no | Download and check against the on-chain BLAKE3 hash. | | lumera_verify | no | Show the on-chain record. | | lumera_estimate_cost | no | Fee for some text or bytes. | | lumera_network_status | no | Chain, SuperNodes, pricing, wallet. | | lumera_create_wallet | no | Create the wallet that pays for saving, if there isn't one. | | lumera_show_wallet | no | The wallet's address (to top it up), balance, and recovery phrase file. | | lumera_sync_from_chain | no | Rebuild the local index on a new machine. |

File tools take absolute paths (~ is fine) and refuse credential and key files (.ssh, .env, *.pem, wallets…).

lumera_save_chat saves exactly what was said, with no redaction, so choose what you save. In OpenHuman, Claude Code and Codex it reads the transcript the app keeps on disk, so the agent doesn't retype anything:

• Which conversation: the one you're in. thread picks another by its ID (or the start of it) or part of its title, and app reads a different app's history, e.g. an OpenHuman chat from Claude Code.
• What's in it: your messages (including ones sent while the agent was working), replies, thinking, tool calls and their full output, and !/slash commands. Left out: the app's system prompt and injected context, sub-agent internals, and bookkeeping. Codex stores its reasoning encrypted, so only its reasoning summaries are saved.
• Size: a long coding session can be large, mostly tool output. Anything over LUMERA_MAX_UPLOAD_MB is refused before anything is spent.

Other clients pass the conversation as messages; without them the tool refuses rather than guess which chat you meant.

Configuration

| Variable | Default | | | --- | --- | --- | | LUMERA_NETWORK | testnet | testnet or mainnet | | LUMERA_MNEMONIC_FILE | $LUMERA_DATA_DIR/mnemonic | File holding the wallet's mnemonic. lumera_create_wallet writes here. | | LUMERA_MNEMONIC | | The mnemonic itself. Overrides the file. | | LUMERA_DATA_DIR | ~/.lumera-mcp | Local memory index and recalled files | | LUMERA_MAX_UPLOAD_MB | 25 | Largest single file | | LUMERA_RETENTION_DAYS | 3650 | Days until each new action's expiration time | | LUMERA_GAS_PRICE | 0.025ulume | | | LUMERA_DEBUG | | Set to 1 to see the SDK's step-by-step logs on stderr | | OPENHUMAN_DIR | ~/.openhuman | Where lumera_save_chat finds OpenHuman's transcripts | | CLAUDE_CONFIG_DIR | ~/.claude | Where it finds Claude Code's | | CODEX_HOME | ~/.codex | Where it finds Codex's (Codex doesn't pass this to servers, so set it in the server's env if you moved it) |

Library

import { createLumeraMcpServer, archiveFiles, retrieve } from "@0xkaleab/lumera-mcp";

// Mount the tools on your own transport
await createLumeraMcpServer().connect(transport);

// Or call Lumera directly
const [outcome] = await archiveFiles([{ bytes, fileName: "report.pdf" }], { source: "mcp", isPublic: false });
const { bytes: back, verified } = await retrieve(outcome.ok ? outcome.entry.actionId : "");

Good to know

• Cascade storage is permanent. It can't be deleted.
• private (the default) restricts downloads to this wallet. It does not encrypt the content.
• The local index is a convenience. The chain is the source of truth, so lumera_sync_from_chain rebuilds it.

Requires Node.js 20.19+ or 22.12+.

License

MIT

vendor/lumera-sdk is the CommonJS build of @lumera-protocol/sdk-js 0.4.1, MIT, © Lumera Protocol (see its LICENSE). It ships inside this package because npm only has 0.3.0, whose LEP-5 Merkle tree makes SuperNodes reject most uploads.