Skip to content

memory-demo.md

Latest commit

 

History

History
152 lines (117 loc) · 6.06 KB

memory-demo.md

File metadata and controls

152 lines (117 loc) · 6.06 KB
Raw

The memory demo — hash · store · recall, in ten minutes

The foundation every pipeline runs on, demonstrated live. Three primitives replace a trusted memory stack:

  1. hash — a Filecoin PieceCID is the hash of the bytes: recall can't lie
  2. store — Filecoin Onchain Cloud holds the blob and keeps proving it on-chain (PDP)
  3. recall-by-hash — Clawdi memory holds a ~400-byte receipt; retrieval is search → download → cryptographic validation

The one secret in the system — the wallet key that pays for storage — lives in the Clawdi vault and resolves in memory per invocation. No agent sees it; rotation is one command.

Who does what

flowchart LR
    subgraph TEAM["Your agent team"]
        direction TB
        CC["Claude Code / Codex"]
        OC["OpenClaw<br/><i>hosted</i>"]
        HM["Hermes<br/><i>local, on cron</i>"]
    end

    subgraph CLAWDI["Clawdi — one brain for every agent"]
        direction TB
        MEM["<b>Shared memory</b><br/>the index — tiny receipts,<br/>small &amp; curated"]
        VAULT["<b>Vault</b><br/>one wallet secret,<br/>one rotation point"]
    end

    subgraph FIL["Filecoin — the provable warehouse"]
        direction TB
        BLOB["<b>Knowledge blobs</b><br/>address = hash of the bytes"]
        PDP["<b>PDP</b><br/>on-chain proof<br/>it's still stored"]
    end

    TEAM ==>|"remember · recall"| MEM
    MEM ==>|"receipt points at the hash"| BLOB
    TEAM -->|"store &amp; fetch<br/>(key never seen)"| VAULT
    VAULT -.->|"signs invisibly,<br/>pays in USDFC"| BLOB
    BLOB --- PDP
Loading

The agents work; Clawdi keeps the small things every agent shares (receipts and the one secret); Filecoin keeps the heavy things in a form where trust is unnecessary — the address is the hash, and the proof of storage is public.

What actually happens

flowchart TB
    subgraph RT["Agent runtime (any agent)"]
        AG["agent session / cron tick<br/><i>skills: memory-researcher · memory-consolidator</i>"]
        WR["foc-cli wrapper<br/><i>ephemeral per-invocation config, wiped on exit</i>"]
    end

    subgraph CP["Clawdi control plane"]
        ENV["foc-cli config<br/>keyRef: clawdi:FILECOIN_PRIVATE_KEY<br/><i>a reference, never the key</i>"]
        RES["foc-cli resolves per command<br/><i>into memory, never to disk</i>"]
        VLT[("Vault<br/>FILECOIN_PRIVATE_KEY")]
        IDX[("Clawdi memory<br/>RESEARCH-NOTE + FILECOIN-MEMORY receipts")]
    end

    subgraph FOC["Filecoin Onchain Cloud — Calibration testnet"]
        CLI["foc-cli<br/><i>Synapse SDK</i>"]
        WS["Warm Storage upload<br/>→ <b>PieceCID</b> + PDP dataset"]
        DL["download by PieceCID<br/><b>SDK validates bytes == hash</b>"]
    end

    AG -->|"1 · write memory candidate"| WR
    WR --> RES
    ENV --> RES
    VLT -.->|"secret, in memory only"| RES
    RES -->|"2 · key in child env"| CLI
    CLI -->|"3 · signed upload"| WS
    AG -->|"4 · index receipt"| IDX
    IDX -->|"5 · any agent: memory_search"| AG
    WS --> DL
    DL -->|"6 · recall: bytes verified against CID"| AG
Loading
Claim Proven by
No agent ever sees the wallet key The proof ladder: config holds keyRef not privateKey, plus the negative test (provider off PATH ⇒ KEY_REF_PROVIDER_MISSING)
Memory can't be silently corrupted foc-cli download: bytes validated against the PieceCID before returning
Storage is durable without trust the dataset's public PDP scanner page — on-chain, continuously challenged

The run sheet

Setup complete per setup.md. Every command runs from the repo root.

Beat 1 — setup is boring; that's the point.

foc-cli wallet balance --json   # keySource "keyRef" — the config holds a reference, safe on a projector

That file is the only configuration in the system. It's a pointer, not a secret — rotation means one vault command, and nothing here changes.

Beat 2 — store a memory.

echo '{"topic":"live-demo","finding":"memory you can prove"}' > /tmp/live-memory.json
foc-cli upload /tmp/live-memory.json --copies 1 --json   # → pieceCid, then index the receipt

Open the printed scanner URL. The piece sits on a public PDP dataset, provably held by a real provider. The receipt in Clawdi memory is ~400 bytes; the blob could be gigabytes.

Beat 3 — recall it.

clawdi memory search "FILECOIN-MEMORY live-demo" --json   # → the receipt
foc-cli download <pieceCid> --out /tmp/recalled.json       # bytes validate against the CID

Search found the receipt; download fetched the bytes; the SDK validated every byte against the hash, and a plain HTTP fetch from the provider's public URL was compared byte-for-byte. Two independent paths, one hash — no memory API to trust anywhere.

Beat 4 — prove the security claim.

foc-cli wallet balance --json   # keySource "keyRef" + the derived address

Land on the negative test: same command, empty environment file — it fails. The vault reference is the only thing authenticating, and the grep gate shows no raw key anywhere.

Beat 5 — close on rotation. Rotate: one vault command; every agent picks it up on its next invocation. Revoke: one more. One secret, one rotation point, provable memory on top.

Consolidation and lineage

Consolidation merges raw notes into a better blob, stores it, and writes a receipt whose parents field names the old PieceCID. Old CIDs never change — the memory's history is an audit trail, not a mutable table. A pipeline runs this same loop on a schedule: pipelines.md.

Reset (run the demo fresh)

clawdi vault rm FILECOIN_PRIVATE_KEY --global
foc-cli wallet init --auto --force   # switch off the vault reference (testnet key)
clawdi memory search "FILECOIN-MEMORY" --json   # then clawdi memory rm <id> per receipt
foc-cli dataset terminate <dataSetId>    # optional: stop the PDP service

Remove every receipt if you terminate the dataset — a receipt pointing at a terminated dataset makes a later recall fail. Stored blobs stay retrievable until the dataset terminates; that immutability is part of the story.