@memoryos-protocol/sdk

TypeScript SDK for the MemoryOS Protocol — user-owned, cryptographically verifiable AI memory.

npm install @memoryos-protocol/sdk

Works in Node.js 18+, Bun, Deno, and modern browsers. Zero ORM, zero framework dependencies.

Quickstart

import { generateKeypair, createAccount, grantPermission, connect } from "@memoryos-protocol/sdk";

const NODE_URL = "http://localhost:3000"; // or https://your-node.memoryos.com

// 1. Generate a keypair (one time — save your private key)
const keypair = generateKeypair();
// keypair.userId     — your permanent identity, derived from your public key
// keypair.publicKey  — share this to create your account
// keypair.privateKey — never share this; proves you own the identity

// 2. Create your account on the node
await createAccount(NODE_URL, keypair);

// 3. Grant your agent permission to read and write memory
const grant = await grantPermission(NODE_URL, keypair, {
  agentId: "my-agent",
  scopes: ["read:*", "write:*"],
});

// 4. Connect — returns a plain object of bound functions
const mem = connect({
  nodeUrl: NODE_URL,
  userId: keypair.userId,
  privateKey: keypair.privateKey,
  grantId: grant.grantId,
});

// 3. Write memory
await mem.write({
  type: "fact",
  payload: { statement: "I'm building the memory layer for AI", tags: ["work"] },
});

// 4. Query memory (semantic search + structured filters)
const results = await mem.query("what is this person building?");

// 5. Export your complete memory (portable, signed)
const snapshot = await mem.export();

Memory types

| Type | Use it for | |---|---| | profile | Name, occupation, language, communication style | | preference | Tool choices, format preferences, workflow settings | | fact | Statements about the user — versioned, tagged | | event | Things that happened — timestamped, with outcome | | summary | Compressed history from long sessions | | embedding | Raw vector data (advanced) |

API

createAccount(nodeUrl, keypair) + grantPermission(nodeUrl, keypair, params)

First-run setup — register your keypair with a node, then authorize your agent.

const keypair = generateKeypair();
await createAccount("http://localhost:3000", keypair);
const grant = await grantPermission("http://localhost:3000", keypair, {
  agentId: "my-agent",                                    // identifies the caller
  scopes: ["read:*", "write:fact", "write:preference"],   // least privilege
  expiresAt: "2027-01-01T00:00:00Z",                      // optional expiry
});
// grant.grantId → pass this to connect()

connect(config) → MemoryOSAPI

Returns a bound API object. Not a class — just a plain object of functions.

const mem = connect({ nodeUrl, userId, privateKey, grantId });

await mem.write(input)          // write a memory object
await mem.query("...")          // semantic + structured search
await mem.get(id)               // fetch a single memory object
await mem.delete(id)            // soft-delete a memory object
await mem.export()              // export full signed snapshot
await mem.import(snapshot)      // import from another node

Individual functions (full control)

import { writeMemory, queryMemory, exportAccount } from "@memoryos-protocol/sdk";

const config = { nodeUrl, userId, privateKey, grantId };

await writeMemory(config, { type: "preference", payload: { key: "language", value: "TypeScript" } });
const results = await queryMemory(config, "what tools does this user prefer?");

Pure builders (great for tests — no mocking needed)

All builders take explicit clock and ID inputs so your tests are deterministic.

import { buildMemoryObject, buildWriteRequest, buildAuthHeader } from "@memoryos-protocol/sdk";

const obj = buildMemoryObject(
  { type: "fact", payload: { statement: "test", tags: [] } },
  userId,
  "fixed-uuid",          // explicit ID — no random in tests
  "2026-01-01T00:00:00Z" // explicit timestamp — no clock in tests
);

Cryptographic identity

import { generateKeypair, deriveUserId, signMessage, verifySignature } from "@memoryos-protocol/sdk";

const keypair = generateKeypair();       // Ed25519 keypair
const userId = deriveUserId(publicKey);  // deterministic — SHA-256 of public key, base58-encoded
const sig = signMessage(privateKey, message);
const valid = verifySignature(publicKey, message, sig);

Running a node

# Self-host a MemoryOS node in one command
docker-compose up

# Or run from source (requires Bun)
git clone https://github.com/memoryos/memoryos
cd memoryos && cp .env.example .env
bun src/index.ts

Design

The SDK is built entirely with pure functions. No classes, no new, no this.

• Pure functions for all builders, crypto, and auth header construction
• Explicit inputs for anything impure (clock, randomness) — tests never need mocking
• Thin impure edges for network calls only
• Full TypeScript — every type exported

The linter (eslint-plugin-functional) enforces this at build time.

License

Apache 2.0 · Protocol Specification