> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Use MemoClaw from TypeScript via the official SDK or CLI.

MemoClaw ships an official TypeScript SDK inside the [`memoclaw`](https://www.npmjs.com/package/memoclaw) package. The same package also contains the CLI, so you get both programmatic access and terminal commands from a single install. Use it anywhere Node.js 18+, Bun, or modern Edge runtimes run.

<Tip>
  Prefer a no-code setup for OpenClaw agents? Install [memoclaw-hooks](/openclaw-hooks) alongside the SDK so your agent auto-stores and recalls memories during each session.
</Tip>

## Installation

```bash theme={null}
npm install memoclaw
# or
pnpm add memoclaw
# or
yarn add memoclaw
```

## Authentication

MemoClaw uses wallet-based identity. Set `MEMOCLAW_PRIVATE_KEY` (hex string with `0x` prefix) so the client can sign free-tier auth headers and x402 payments.

```bash theme={null}
export MEMOCLAW_PRIVATE_KEY=0xyourprivatekey
```

Every wallet gets **100 free paid-endpoint calls**. After that, calls fall back to x402 payments ($0.005–$0.01 per request depending on the endpoint).

## Initialize the client

```typescript theme={null}
import { MemoClawClient } from "memoclaw";

const client = new MemoClawClient({
  // optional overrides
  // baseUrl: "http://localhost:8787",
  // privateKey: "0x...", // defaults to MEMOCLAW_PRIVATE_KEY
});
```

## Quick Example

<Steps>
  <Step title="Store a memory">
    ```typescript theme={null}
    const created = await client.store({
      content: "User prefers dark mode and vim keybindings",
      importance: 0.8,
      metadata: { tags: ["preferences", "editor"] },
    });
    console.log(created.id);
    ```
  </Step>

  <Step title="Recall memories">
    ```typescript theme={null}
    const memories = await client.recall({
      query: "editor preferences",
      limit: 5,
    });

    for (const m of memories.memories) {
      console.log(`[${(m.similarity * 100).toFixed(0)}%] ${m.content}`);
    }
    ```

    Output:

    ```
    [87%] User prefers dark mode and vim keybindings
    ```
  </Step>

  <Step title="Update and delete">
    ```typescript theme={null}
    await client.update(created.id, { importance: 0.95 });
    await client.delete(created.id);
    ```
  </Step>
</Steps>

## Ingest a conversation

Extract facts automatically from conversation history and auto-create relations.

```typescript theme={null}
const result = await client.ingest({
  messages: [
    { role: "user", content: "I prefer dark mode and use vim. My timezone is PST." },
    { role: "assistant", content: "Got it! I'll remember those preferences." },
  ],
  auto_relate: true,
});

console.log(
  `Extracted ${result.facts_extracted} facts, created ${result.relations_created} relations`,
);
```

## Error handling

```typescript theme={null}
import { MemoClawClient, MemoClawError } from "memoclaw";

const client = new MemoClawClient();

try {
  await client.delete("nonexistent-id");
} catch (err) {
  if (err instanceof MemoClawError) {
    console.log(`Error ${err.status}: ${err.message}`);
  }
}
```

## Available methods

| Method                           | Description                          |
| -------------------------------- | ------------------------------------ |
| `store(opts)`                    | Store a single memory                |
| `storeBatch(memories)`           | Store up to 100 memories             |
| `recall(opts)`                   | Semantic search                      |
| `list(opts?)`                    | List memories with pagination        |
| `update(id, opts)`               | Update a memory                      |
| `delete(id)`                     | Delete a memory                      |
| `ingest(opts)`                   | Auto-extract facts from conversation |
| `extract(messages, opts?)`       | Extract structured facts via LLM     |
| `consolidate(opts?)`             | Merge similar memories               |
| `suggested(opts?)`               | Get proactive memory suggestions     |
| `createRelation(id, opts)`       | Create a relationship                |
| `listRelations(id)`              | List relationships                   |
| `deleteRelation(id, relationId)` | Delete a relationship                |
| `status()`                       | Check remaining free-tier calls      |

## Configuration options

```typescript theme={null}
const client = new MemoClawClient({
  privateKey: "0x...",              // defaults to MEMOCLAW_PRIVATE_KEY
  baseUrl: "https://api.memoclaw.com", // override for staging/local
  timeout: 60_000,                   // request timeout in ms
});
```

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore every REST endpoint.
  </Card>

  <Card title="Authentication" icon="lock" href="/get-started/authentication">
    Learn how wallet signatures and x402 payments work.
  </Card>
</CardGroup>