Documentation

Memora SDK Docs

Add verifiable execution history to any agent. Install the SDK, register an agent, and start recording signed events in minutes.

Open Console View GitHub

Install

The SDK is published on npm as @smritheon/memora-core.

1npm install @smritheon/memora-core

Quickstart

This is the fastest path from zero setup to a visible Memora event in the console. Use hosted mode unless you already run your own gateway.

Create an agent in the console and keep the generated agent ID handy.
Generate an API key under Agents → Credentials for that agent.
Choose your write policy: Workspace → Settings sets the provenance backend and Agent → Write policy sets integrity mode.
Install the SDK, set the environment variables below, and paste the quickstart example into a small script.
Run the script, then open Activity or Investigations in the console to confirm your first event arrived.

1import { Memora } from "@smritheon/memora-core";
2
3const memora = new Memora({
4  agentId: process.env.MEMORA_AGENT_ID!,
5  apiKey: process.env.MEMORA_API_KEY!,
6  // Self-hosted: add baseUrl: process.env.MEMORA_BASE_URL
7});
8
9await memora.trace("hello-world", async (trace) => {
10  await trace.event("task_started", {
11    task: "Generate report",
12  });
13
14  await trace.event("task_completed", {
15    status: "success",
16  });
17});

1MEMORA_AGENT_ID=your-agent-id
2MEMORA_API_KEY=your-api-key
3npx tsx agent.ts

Self-hosted users: pass baseUrl: process.env.MEMORA_BASE_URL to point at your gateway instance.

What success looks like

After the script runs, you should see a new event under /app/activity. Open it to inspect the recorded payload, hashes, and replay state.

Provider examples

These examples show Memora wrapping a real provider call so you can record the requested provider, model, and request or response hashes alongside the event.

Memora records the provider metadata you send and the resulting encrypted receipt fields. It does not prove that a closed provider actually used the requested model unless that provider also supplies a signed receipt or attestation.

OpenAI Responses API

receipt()

Use this when you want a provider-specific receipt for a single LLM call and a clean execution ID you can inspect later in the console or CLI.

1import OpenAI from "openai";
2import { Memora } from "@smritheon/memora-core";
3
4const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });
5const memora = new Memora({
6  agentId: process.env.MEMORA_AGENT_ID!,
7  apiKey: process.env.MEMORA_API_KEY!,
8});
9
10const receipt = await memora.receipt("openai-responses", async () => {
11  const response = await openai.responses.create({
12    model: process.env.OPENAI_MODEL ?? "gpt-4.1-mini",
13    input: "Summarize the execution receipt concept in two sentences.",
14  });
15
16  return {
17    outputText: response.output_text,
18    provider: "openai",
19    model: response.model,
20  };
21});
22
23console.log(receipt.execution_id);

Anthropic Messages API

receipt()

Use the same pattern for Anthropic calls: wrap the provider request, return the response text you need, and let Memora persist the encrypted receipt fields.

1import Anthropic from "@anthropic-ai/sdk";
2import { Memora } from "@smritheon/memora-core";
3
4const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
5const memora = new Memora({
6  agentId: process.env.MEMORA_AGENT_ID!,
7  apiKey: process.env.MEMORA_API_KEY!,
8});
9
10const receipt = await memora.receipt("anthropic-messages", async () => {
11  const response = await anthropic.messages.create({
12    model: process.env.ANTHROPIC_MODEL ?? "claude-3-5-sonnet-latest",
13    max_tokens: 240,
14    messages: [{ role: "user", content: "Summarize the execution receipt concept in two sentences." }],
15  });
16
17  return {
18    outputText: response.content[0]?.type === "text" ? response.content[0].text : "",
19    provider: "anthropic",
20    model: response.model,
21  };
22});
23
24console.log(receipt.execution_id);

Environment variables

Set these in your agent runtime. The hosted tier needs only agent ID and API key.

1MEMORA_AGENT_ID=your-agent-id
2MEMORA_API_KEY=your-api-key

Self-hosted: add MEMORA_BASE_URL pointing to your gateway.

Core concepts

A short glossary of terms you will see throughout the SDK and console.

Agent

A named entity that emits execution events. Register it in the console and assign API credentials.

API Key

A per-agent secret that authenticates writes. Create one under Agents → Credentials in the console.

Event

A structured record of agent activity — signed, countersigned, and anchored for later verification.

Replay

A deterministic reconstruction of an execution trace from its event chain. Verifiable without the original runtime.

Batch

A grouped set of events anchored together. Useful for high-frequency agents that need lower per-event cost.

Integrity Backend

Where events are anchored. Standard (default): signed records in Supabase, no external chain. Hedera: HCS ordering plus optional on-chain contract checkpoint. Base: planned. Chosen in Workspace → Settings → External anchoring; signing level is per-agent in Agent → Write policy. The SDK is transport-only.

SDK APIs

Three entry points for recording execution. Pick the one that matches your use case.

memora.trace()

Wraps a multi-step workflow in a signed execution trace. Each trace.event() call creates a linked record. Use this for pipelines and end-to-end lineage.

1await memora.trace("pipeline-run", async (trace) => {
2  await trace.event("data_fetched", { rows: 1200 });
3  await trace.event("model_invoked", { model: "gpt-4o" });
4  await trace.event("output_written", { path: "/results/report.csv" });
5});

memora.wrap()

Records a single function call with input and output attached. Use this when you need provenance for one operation, not a full trace.

1const result = await memora.wrap(
2  "classify-intent",
3  async () => {
4    return await llm.classify(userMessage);
5  },
6  { input: userMessage }
7);

memora.tool()

Wraps a tool function for agent frameworks. Returns a provenance-instrumented version that records each invocation. Works with LangGraph, CrewAI, and similar runtimes.

1const tools = [
2  memora.tool("search_web", async (args) => {
3    const results = await webSearch(args.query);
4    return results;
5  }),
6];
7
8// Pass tools array to your agent framework

Framework integrations

Memora works beside your orchestration layer — not inside it. Use trace(), wrap(), or tool() with the patterns below.

Plain Node.js

wrap() + trace()

Portfolio risk analysis on any async TypeScript function.

1const analyse = memora.wrap("portfolio-risk", analysePortfolioRisk);
2const report = await analyse(portfolio);

LangGraph

wrap()

Credit-risk Q&A through a StateGraph without changing graph internals.

1const invoke = memora.wrap("langgraph-run", (state) => graph.invoke(state));
2const result = await invoke(initialState);

LangChain

wrap() + tool()

Runnable chain classification and agent tool-call provenance.

1const classify = memora.wrap("langchain-classify", (input) => chain.invoke(input));
2const search = memora.tool("search_docs", searchDocs);

Temporal

tool()

Payment pipeline — risk assessment and settlement as provenance-wrapped activities.

1export const assessRisk = memora.tool("assess-risk", assessTransactionRisk);
2export const processPayment = memora.tool("process-payment", processPayment);

Dapr

wrap()

Microservice payment flow via Dapr sidecar invokes.

1const runPayment = memora.wrap("dapr-payment-flow", async (orderId) => {
2  const risk = await invokeDapr("assessRisk", { orderId });
3  return invokeDapr("settlePayment", { orderId });
4});

CrewAI / Python

REST

Python agents write via gateway POST /v1/events — no PyPI Memora SDK required.

1requests.post(f"{MEMORA_BASE_URL}/v1/events", headers=headers, json=payload)

Replay verification

After an event is written, anyone can independently verify its execution chain — without trusting the original runtime.

Write the event

Call trace(), wrap(), or tool() in your agent. The SDK signs the event and submits it to the gateway.

Open Activity or Investigations

Go to /app/activity or /app/investigations in the console. Events appear within seconds of anchoring.

Click Verify Replay

The web verifier checks operator signature, parent linkage, commit path, and batch proof.

Result is persisted

Verification results are stored. Re-opening the same event shows the last result and timestamp.

Web vs CLI verifier

The console verifier checks indexed provenance. For audit scenarios, run memora replay verify in the CLI — it performs deeper checks including raw sequence order, signer timeline reconstruction, and off-chain signature verification.

Deployment modes

Provenance backend and integrity mode are configured in the console. The indexer enforces policy on every write — agents do not pick commit path via SDK or environment variables. Self-hosted operators configure Hedera capability via env, but workspace and agent settings drive what each write requires.

Setting	Where	Values
External anchoring	Workspace → Settings	Standard (default), Hedera
Integrity mode	Agent → Write policy	standard, attested, verified

Standard

available

Default. Signed & Merkle-batched records in Supabase. No external chain, no wallet required. Suitable for most deployments and regulated environments.

Hedera

available

Optional trust upgrade. HCS ordered anchoring with optional on-chain contract checkpoint. Requires Hedera operator credentials and an HCS topic.

Base

planned

Base L2 anchoring, planned for a future release. The SDK will not need changes when this ships.

Troubleshooting

Event not appearing in console

Confirm MEMORA_AGENT_ID matches an agent registered under Agents. Writes to unknown agents are rejected.

Invalid API key

Regenerate the key from Agents → Credentials. Pass it as apiKey — not writeSecret, which is legacy.

Gateway unreachable

For self-hosted setups, set MEMORA_BASE_URL to your gateway (default port 8787) and confirm the gateway process is running.

Replay status: unknown

The event is indexed but not yet verified. Run memora replay verify in the CLI or open Investigations in the console.

Storage read failure

The key broker may be down, or the requesting wallet is not the registered agent owner. Check KEY_BROKER_BASE_URL and wallet address.

400: agent_signer rejected

Agents in standard integrity mode reject agent_signer and agent_signature fields. Switch the agent to attested or verified mode in Agent → Write policy, or remove signer fields from the payload.

Links

Jump into the console, browse integrations, or explore the source.

Console Integrations GitHub