Memora

Verifiable long-term memory for AI agents — encrypted payloads off-chain, canonical ordering on Hedera Consensus Service (HCS), permissions and memory refs on Hedera EVM, and a TypeScript SDK + reference web app so builders can write, query, read, and cryptographically verify agent memory.

For hackathon judges (quick map)

Criterion	Where to look
Innovation	Why this needs Hedera · What’s new for the ecosystem
Feasibility	Problem & domain · Lean scope
Execution	What we shipped (MVP) · Proof scripts · Run the stack
Integration	Hedera services used
Success	Impact & metrics we optimize for
Validation	Feedback & traction
Pitch	Elevator pitch · MVP feature list

Elevator pitch

AI agents need memory that survives sessions, stays private (ciphertext only on IPFS), and can be proven (hash + ordering + on-chain permission). Memora uses HCS for tamper-evident, ordered commits, a MemoraRegistry contract on Hedera for agent ownership and delegates, and a key broker that only releases decryption keys after an on-chain permission check. v0.2 adds execution lineage (mission_id, parents, event types) inside the encrypted payload for timelines and replay.

Problem & domain

Problem: Agent memory today is usually siloed in vendor databases — hard to verify ordering, integrity, or who was allowed to read it.
Domain: AI agents (LLM tools, autonomous workflows) that must anchor outputs and context to a neutral, ordered ledger without putting plaintext on-chain.
Why Web3: You need immutable ordering + transparent permission rules that any auditor or second party can reason about; a centralized DB alone does not provide the same verifiability story.

Why this needs Hedera (not Web2 alone)

Capability	Role of Hedera
Ordered, timestamped commits	HCS topic — every memory commit is a message; sequence = canonical order.
Permissioned reads	EVM registry — owner/delegate checks before keys are released.
Composability	Same network for consensus + smart contracts; Hashio / ecosystem RPC.

IPFS (or any object store) holds ciphertext only; Hedera anchors what was committed, when, and in what order; the contract anchors who controls the agent.

What’s new for the Hedera ecosystem

Agent-native memory protocol with a published SDK (@smritheon/memora-core on npm) and documented REST/write path via the indexer.
HCS + EVM split of concerns: HCS for high-throughput ordered commits; EVM for registry and access semantics — a pattern teams can extend (missions, marketplace, HTS ideas in Roadmap).
Reference Agent Console (apps/web) — wallet-connected UX for agents, memories, verification, missions/tasks (application layer on top of the same protocol).

Hedera integration

Service	Usage
Hedera Consensus Service (HCS)	`TopicMessageSubmitTransaction` on a dedicated topic; payload is a structured MemoryCommit (e.g. `memory_id`, `cid_ciphertext`, `payload_hash`, agent scope). Subscriber backfills sequence / consensus timestamp into the indexer.
Hedera EVM (Smart Contracts)	MemoraRegistry.sol — agent registration, `commitMemory`, ownership; key broker reads owner / delegate before releasing AES keys.
Operator account	Indexer uses Hedera operator ID/key for HCS submit and contract calls (testnet in demos).

Ecosystem / adjacent: IPFS pinning (e.g. Pinata), Supabase as rebuildable index, Key Broker as permissioned key release (keys never stored on-chain).

What we shipped (MVP)

End-to-end write path: encrypt → pin ciphertext → HCS commit → registry tx → register key with broker → indexer persists row.
Read path: challenge/response + on-chain permission → decrypt → re-hash and verify against committed payload_hash.
SDK — MemoraClient: write, query, read, verify (packages/sdk, docs/SDK-MEMORA-CORE.md).
CLI — write / query / read / verify / tamper-test (packages/cli).
Indexer — HCS subscriber + contract-driven index + POST /write (packages/indexer).
Key broker — register keys, challenge auth, registry check (packages/key-broker).
Web app — Next.js Memora Agent Console: dashboard, agents, memories, read/decrypt flows, missions/tasks UX, /docs (apps/web).
Lineage (v0.2) — optional mission_id, event_type, parent links in payload; see docs/MISSION-AND-ONCHAIN.md.

MVP feature list (pitch checklist)

Write verifiable, encrypted memory for an agent ID (indexed + on-chain refs).
Query memories with HCS sequence ordering integrity.
Read with wallet (owner/delegate) and verify payload hash against commitment.
Tamper resistance — modified ciphertext fails verification/read (demo script).
Delegates — grant/revoke read access via contract; broker enforces (demo script).
Developer UX — npm SDK, CLI, and hosted-style docs path in the web app.

Proof scripts (screenshot-ready)

Run from repo root with indexer + key-broker up and .env configured (see Local setup).

Script	Proves
`pnpm run demo:write`	Full write: `memory_id`, CID, `payload_hash`, HCS seq/time, contract tx.
`pnpm run demo:query`	Listing ordered by `hcs_sequence`.
`pnpm run demo:read`	Decrypt + hash verify (requires `PRIVATE_KEY` = owner or delegate).
`pnpm run demo:verify`	On-chain ref + tx hash checks.
`pnpm run demo:tamper`	Tampered ciphertext → verify/read fails.
`pnpm run demo:delegate`	Delegate reads OK; after revoke → 403 (`DELEGATE_PRIVATE_KEY` required).

Same commands work as pnpm run proof:*. Contract tests: pnpm --filter @memora/contracts run test. Full test: pnpm test.

Impact & metrics

Memora is designed to:

Increase meaningful Hedera usage — every memory write hits HCS + EVM (ongoing agent workloads → recurring transactions, not one-off mints).
Support new accounts — agents map to owners/delegates on Hedera-compatible wallets; console onboarding flows connect testnet wallets.
Grow verifiable AI narratives — ordered commits are a hook for audits, replay, and cross-agent coordination (missions/tasks in the app layer).

Hackathon note: Treat demo script output and console screen recordings as primary evidence; production TPS / MAU numbers belong post-launch.

Validation & traction

Technical validation: Proof scripts above + contract tests; judges can run locally against testnet.
Product validation (intended cycles): SDK consumers + Agent Console users → feedback on read latency, delegate flows, mission UX; iterate on Roadmap.
Traction (fill in for your submission): early adopters, hackathon user tests, partner conversations — add quotes, counts, or trial signups here.

Lean scope (hackathon MVP)

Building block	Hypothesis
HCS + registry	Agents need ordered, attestable commits without plaintext on-chain.
Key broker	Keys off-chain, rules on-chain — simple story for judges and auditors.
SDK + CLI	Developers integrate in minutes, not weeks.
Console	Non-crypto teammates can see the protocol working (wallet, memories, verify).

Go-to-market (directional): OSS SDK + hosted indexer/broker tier; vertical AI agent teams needing compliance-friendly memory; expand to task marketplace / mission flows already sketched in-repo.

Design & UX (execution)

Web app: Next.js, wallet connect for Hedera testnet, server-side calls to indexer/broker/IPFS (no secrets in browser).
Accessibility: Prefer semantic landmarks, labels on interactive controls, meaningful alt text on branded assets in the marketing shell; continue hardening with audits post-hackathon.
Important design calls: Ciphertext on IPFS; commits on HCS; permissions on EVM; index rebuildable from chain — clear separation for security reviews.

Architecture (Phase 1 + v0.2 lineage)

flowchart LR
  subgraph app [App / SDK / CLI]
    W[Write]
    R[Read]
  end
  subgraph services [Memora services]
    I[Indexer]
    K[Key Broker]
  end
  subgraph storage [Storage & chain]
    P[IPFS ciphertext]
    H[HCS topic]
    C[MemoraRegistry EVM]
    D[(Supabase index)]
  end
  W --> I
  I --> P
  I --> H
  I --> C
  I --> K
  I --> D
  R --> I
  R --> K
  K --> C

IPFS: AES-256-GCM ciphertext only.
HCS: Canonical ordering and commit payload.
Registry: Agent + memory ref + tx trail.
Supabase: Queryable mirror; rebuild from HCS + contract.

Monorepo structure

packages/
  contracts/    # MemoraRegistry.sol — Hardhat, Hedera testnet deploy
  indexer/      # HCS subscribe + contract events → Supabase; REST + POST /write
  key-broker/   # Challenge/response; on-chain permission before key release
  sdk/          # @smritheon/memora-core — MemoraClient
  cli/          # memora write | query | read | verify | tamper-test
  shared/       # Types, canonicalization, crypto
apps/
  web/          # Next.js Agent Console + marketing/docs routes
  agent-runtime/# Optional agent worker integration
supabase/migrations/
examples/       # Sample JSON payloads

Prerequisites

Node.js >= 18 · pnpm 9
Hedera testnet account (portal.hedera.com)
Supabase project
Pinata (or compatible) JWT for IPFS writes

Local setup

Install
```
pnpm install
```
Environment — copy .env.example → .env and set at minimum:
- HEDERA_OPERATOR_ID, HEDERA_OPERATOR_KEY, HEDERA_EVM_RPC_URL (e.g. Hashio testnet)
- HCS_TOPIC_ID, MEMORA_REGISTRY_CONTRACT_ID (after topic + deploy)
- SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, PINATA_JWT
- KEY_BROKER_BASE_URL, INDEXER_BASE_URL (local: e.g. http://localhost:3000, http://localhost:3001)
Supabase — run migrations in order via SQL Editor:
- supabase/migrations/00001_initial_schema.sql
- supabase/migrations/00002_lineage.sql
- supabase/migrations/00003_memora_app_console.sql (Agent Console tables)
Deploy contract — cd packages/contracts && pnpm run deploy → set MEMORA_REGISTRY_CONTRACT_ID.

Run services

pnpm run dev   # key-broker :3000 + indexer :3001 (see package.json)

Web app (separate port recommended)
```
cd apps/web && cp .env.example .env.local
PORT=3002 pnpm dev
```
Connect a Hedera testnet wallet; explore agents, memories, read/decrypt.

First write registers the agent on-chain via the indexer — no separate registration step.

5-line SDK integration

import { MemoraClient } from "@smritheon/memora-core";

const client = new MemoraClient({
  indexerBaseUrl: process.env.INDEXER_BASE_URL!,
  keyBrokerBaseUrl: process.env.KEY_BROKER_BASE_URL!,
});

const receipt = await client.write({
  agentId: "my-agent",
  contentType: "application/json",
  content: { summary: "Meeting notes", decisions: ["Ship Memora"] },
});
const list = await client.query({ agentId: "my-agent" });

Read (wallet signs challenge):

const payload = await client.read(
  memoryId,
  (msg) => wallet.signMessage(msg),
  wallet.address
);

More: packages/sdk/README.md, docs/SDK-MEMORA-CORE.md, packages/sdk/SPEC.md.

CLI

pnpm run build
node packages/cli/dist/cli.js write --agent my-agent --file examples/payload.json
node packages/cli/dist/cli.js query --agent my-agent
node packages/cli/dist/cli.js read --memory <memory_id>
node packages/cli/dist/cli.js verify --memory <memory_id>
node packages/cli/dist/cli.js tamper-test --memory <memory_id>

Env vars (abbreviated)

Variable	Role
`HEDERA_NETWORK`	`testnet` / `mainnet`
`HEDERA_OPERATOR_ID` / `HEDERA_OPERATOR_KEY`	HCS + contract signer
`HEDERA_EVM_RPC_URL`	EVM JSON-RPC (e.g. Hashio)
`HCS_TOPIC_ID`	Memory commit topic
`MEMORA_REGISTRY_CONTRACT_ID`	Deployed registry
`PINATA_JWT`	IPFS pin
`SUPABASE_*`	Index + key metadata
`PRIVATE_KEY`	CLI read (owner/delegate)

Roadmap (beyond this hackathon)

Shared / multi-agent task memory modes
Richer mission snapshots and marketplace-style skill capsules
HTS-aligned licensing / token-gated key release (speculative)
Hosted Memora Cloud (managed indexer + broker)
Wrapped keys from broker (replace raw key over TLS for production)

Legacy Builders note (baseline → delta)

If you evaluate delta from baseline: compare product scope (SDK, CLI, console, missions/tasks), Hedera depth (HCS + registry + broker enforcement), robustness (proof/tamper/delegate scripts, tests), and validation (runnable demos, docs). Adjust scores against your recorded starting snapshot.

Production caution

Phase 1 Key Broker returns raw AES keys over TLS for simplicity. Production should use wrapped keys or enclave-backed delivery.

License & package

Private monorepo; SDK package name: @smritheon/memora-core. Publishing notes: docs/SHIPPING-SDK.md.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
apps		apps
docs		docs
examples		examples
packages		packages
scripts		scripts
supabase/migrations		supabase/migrations
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.npmrc		.npmrc
Dockerfile.web		Dockerfile.web
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
skills-lock.json		skills-lock.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Memora

For hackathon judges (quick map)

Elevator pitch

Problem & domain

Why this needs Hedera (not Web2 alone)

What’s new for the Hedera ecosystem

Hedera integration

What we shipped (MVP)

MVP feature list (pitch checklist)

Proof scripts (screenshot-ready)

Impact & metrics

Validation & traction

Lean scope (hackathon MVP)

Design & UX (execution)

Architecture (Phase 1 + v0.2 lineage)

Monorepo structure

Prerequisites

Local setup

5-line SDK integration

CLI

Env vars (abbreviated)

Roadmap (beyond this hackathon)

Legacy Builders note (baseline → delta)

Production caution

License & package

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Memora

For hackathon judges (quick map)

Elevator pitch

Problem & domain

Why this needs Hedera (not Web2 alone)

What’s new for the Hedera ecosystem

Hedera integration

What we shipped (MVP)

MVP feature list (pitch checklist)

Proof scripts (screenshot-ready)

Impact & metrics

Validation & traction

Lean scope (hackathon MVP)

Design & UX (execution)

Architecture (Phase 1 + v0.2 lineage)

Monorepo structure

Prerequisites

Local setup

5-line SDK integration

CLI

Env vars (abbreviated)

Roadmap (beyond this hackathon)

Legacy Builders note (baseline → delta)

Production caution

License & package

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages