Shared LLM Memory over Calimero

Priscilla - EthRome Hackathon 2025 project – distributed, peer-to-peer storage for multiple LLM agents.

We are building a network where several language models – running inside browsers (WASM Web‑LLM), inside trusted execution environments, or on private nodes – can share a persistent short-term memory without leaking their private prompts or secrets to the other participants. Calimero gives us a sovereign subnet with event-driven communication, while each node hosts a Rust → WASM contract that stores state and emits events over websockets. External LLM clients listen to those events, compute locally, and then push new knowledge back into the shared ledger.

Live deployment

• /home – blended dashboard for all roles
• /p-admin – admin console to seed rounds and secrets
• /player-one – interface for the questioning agent
• /player-two – interface for the answering agent + Web-LLM
• Calimero node 1 – sovereign subnet endpoint
• Calimero node 2 – mirrored peer
• Merobox workflow dashboard – inspect contexts and events

Vision

• Distributed memory – The conversation/game state is replicated across Calimero nodes with deterministic WASM logic (ChatState) and peer-to-peer storage.
• LLM collaboration – Each agent (browser, iExec TEE, private server) plugs into the same memory via websocket subscriptions and event-driven flows.
• Privacy-preserving hints – Secrets stay inside the LLM runtime; the contract only stores references/metadata and the secret is only fetched on demand by the answering agent.
• Composable compute – Any client that honours the contract API can react to events, generate answers, and persist results back to Calimero.

Repository layout

• logic/ – Rust smart contract compiled to WASM (Calimero state + events)
• app/ – React + Vite frontend with role-specific routes (/home, /p-admin, /player-one, /player-two)
• workflows/ – Merobox workflow to bootstrap a two-node Calimero network
• docs/ – Architecture diagram(s) and hackathon collateral

Prerequisites

• Node.js + pnpm (or npm/yarn if you adapt the scripts)
• Rust toolchain with WASM target: rustup target add wasm32-unknown-unknown
• Optional: wasm-opt for smaller binaries

Contract (Rust → WASM)

pnpm run logic:build

Optional cleanup:

pnpm run logic:clean

Capabilities

• create_game(admin, player_one, player_two) – reset the round and register actors.
• set_secret(requester, secret) – admin-only; stores a single-word secret.
• submit_question(player, content) – player one asks a natural language question.
• submit_answer(player, content, guess) – player two replies (optional guess).
• messages(offset, limit) – fetches stored conversation history (bounded by max_messages).
• game_info() – returns metadata (stage, participants, storage usage).
• get_secret(requester) – authorized roles can read the secret (used by the LLM).
• debug_reveal_secret() – helper for local testing.

Events emitted: GameCreated, SecretSet, MessageAdded, SecretGuessed, StageChanged, HistoryCleared.

Artifacts land in logic/res/:

• kv_store.wasm – compiled contract
• abi.json – input for frontend code generation

Frontend (React + Vite)

cd app
pnpm install
pnpm build          # production bundle
pnpm dev            # Vite dev server on localhost:5173

Routes:

• /home – full control panel (admin + players + event stream)
• /p-admin – management tools only
• /player-one – question interface for the guessing agent
• /player-two – event feed and Web-LLM trigger for the answering agent

Web-LLM integration

We stream Phi-3-mini-4k-instruct-q4f16_1-MLC via @mlc-ai/web-llm.
The first visit downloads the model (hundreds of MB). Afterwards, the browser cache serves it locally, so replies are fully client-side.

Event-driven development workflow

The root script wires everything together:

pnpm run app:dev

• Vite dev server for the frontend.
• logic:watch (via chokidar): watches logic/res/**/*.
  • When abi.json changes → runs app:generate-client.
  • When a .wasm changes → copies it into node data dirs via logic:sync.

Key scripts:

Script	Description
logic:build	Compiles Rust contract to WASM
logic:watch	Watches logic/res/**/* for ABI/WASM changes
logic:sync	Copies updated WASM into data/calimero-node-*
app:generate-client	Runs @calimero-network/abi-codegen
app:dev	Runs watchers + Vite dev server

ABI codegen

pnpm run app:generate-client

Regenerates the TypeScript client in app/src/api from logic/res/abi.json. This runs automatically when the watcher detects ABI changes.

Merobox workflow (local two-node network)

pnpm run network:bootstrap

workflows/workflow-example.yml installs the contract on node 1, creates a context, invites node 2, and executes a full game flow (create game → set secret → question → answer) before fetching history and cleaning up. Node data lives under data/.

Typical development loop

1. pnpm run app:dev – start watchers and Vite.
2. Edit contract (logic/src/lib.rs) and rebuild using pnpm run logic:build.
3. Watcher copies WASM and regenerates the ABI client if needed.
4. Exercise the new flow via /home or the role-specific routes.

Troubleshooting

• Missing tools? Install at repo root:

  pnpm add -D concurrently chokidar-cli

• ABI codegen version mismatch? Scripts pin @calimero-network/abi-codegen@0.1.1.

• Need a clean slate? pnpm run logic:clean + restart the Merobox workflow.

---

EthRome 2025 takeaway: this repo demonstrates how Calimero’s sovereign subnets, event-driven architecture, and WebAssembly contracts let multiple autonomous LLM agents share a synchronized memory while keeping their private knowledge siloed. Plug different compute providers (local browser, private server, iExec TEEs) into the websocket stream and you have a distributed swarm of models collaborating over the same state.