npm package: @memoryos-protocol/sdk
Description: TypeScript SDK for the MemoryOS Protocol — user-owned AI memory
Latest version: 0.1.0

# @memoryos-protocol/sdk

TypeScript SDK for the [MemoryOS Protocol](https://github.com/memoryos/memoryos) — user-owned, cryptographically verifiable AI memory.

```bash
npm install @memoryos-protocol/sdk
```

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

---

## Quickstart

```typescript
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.

```typescript
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.

```typescript
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)

```typescript
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.

```typescript
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

```typescript
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

```bash
# 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](https://github.com/memoryos/memoryos/blob/main/PROTOCOL.md)