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

# TypeScript SDK Reference

> Full reference for the @moorcheh-ai/memanto TypeScript SDK.

# TypeScript SDK Reference

The `@moorcheh-ai/memanto` SDK for Node.js / TypeScript boots a local Memanto server on demand via `uvx` and exposes an ergonomic client.

## Prerequisites

* **Node.js 20+**
* **`uvx` on PATH** — install [uv](https://docs.astral.sh/uv/getting-started/installation/) (which ships `uvx`)

## Installation

```bash theme={null}
npm install @moorcheh-ai/memanto
```

## Quick Start

```ts theme={null}
import { Memanto } from "@moorcheh-ai/memanto";

const memanto = new Memanto({
  agentId: "my-agent",
  apiKey: process.env.MOORCHEH_API_KEY,
});

await memanto.remember({ content: "Alex prefers oat milk." });

const { memories } = await memanto.recall({ query: "what does Alex drink?" });
console.log(memories);

const { answer } = await memanto.answer({ question: "Does Alex drink dairy?" });
console.log(answer);

await memanto.close();
```

On the first call, the SDK:

1. Picks a free port and spawns `uvx memanto serve --port <port>`.
2. Polls `/health` until the server is ready.
3. Creates the agent (if `autoCreate` is enabled — default `true`) and activates a session.
4. Sends the request with the session token attached.

When `close()` is called (or the Node process exits), the server is sent `SIGTERM`.

## `Memanto` Client

### Constructor

```ts theme={null}
new Memanto(options: MemantoOptions)
```

| Option            | Type      | Default     | Description                                                   |
| ----------------- | --------- | ----------- | ------------------------------------------------------------- |
| `agentId`         | `string`  | —           | **Required.** Agent identifier.                               |
| `apiKey`          | `string`  | —           | Moorcheh API key, passed to the server as `MOORCHEH_API_KEY`. |
| `autoCreate`      | `boolean` | `true`      | Create the agent if it does not exist.                        |
| `baseUrl`         | `string`  | —           | Use an already-running server URL instead of spawning one.    |
| `port`            | `number`  | auto        | Bind the spawned server to this port.                         |
| `host`            | `string`  | `127.0.0.1` | Bind host.                                                    |
| `uvxPath`         | `string`  | `uvx`       | Override the path to `uvx`.                                   |
| `packageSpec`     | `string`  | `memanto`   | Package spec for `uvx`. Use `memanto==0.2.3` to pin.          |
| `healthTimeoutMs` | `number`  | `60000`     | Health-check timeout.                                         |
| `verbose`         | `boolean` | `false`     | Stream server logs to the parent process.                     |

### Memory Write Methods

```ts theme={null}
await memanto.remember({ content, type?, title?, confidence?, tags?, source?, provenance? })
await memanto.batchRemember(items[])         // up to 100 items
await memanto.extractMemories({ messages, dryRun?, maxMemories?, aiModel? })
await memanto.uploadFile({ path, filename? }) // .pdf, .docx, .xlsx, .json, .txt, .csv, .md
await memanto.deleteMemory(memoryId)
```

### Memory Read Methods

```ts theme={null}
await memanto.recall({ query, limit?, minSimilarity?, type? })
await memanto.recallAsOf({ asOf, limit?, type? })        // point-in-time
await memanto.recallChangedSince({ since, limit?, type? }) // what changed after
await memanto.recallRecent({ limit?, type? })               // newest-first
await memanto.answer({ question, limit?, threshold?, temperature?, aiModel?, kioskMode? })
```

### Analysis Methods

```ts theme={null}
await memanto.dailySummary({ date?, outputPath? })
await memanto.generateConflicts({ date? })
await memanto.listConflicts({ date? })
await memanto.resolveConflict({ conflictIndex, action, date?, manualContent?, manualType? })
```

`action` is one of: `keep_old | keep_new | keep_both | remove_both | manual`.

### Agent & Session Lifecycle

```ts theme={null}
await memanto.listAgents()
await memanto.getAgent()
await memanto.createAgent({ pattern?, description? })
await memanto.deleteAgent()
await memanto.deactivate()    // end session, next call rebootstraps
await memanto.status()        // current session info
await memanto.close()         // stop the spawned server
```

### Diagnostics

```ts theme={null}
import { doctor } from "@moorcheh-ai/memanto";

const result = await doctor();
if (!result.uvxAvailable) {
  console.error(result.hint);
}
```

## Framework Integrations

The SDK ships pre-built memory tools for three agent frameworks, each behind its own subpath import so unused framework code never enters your bundle:

| Framework       | Import                        | Docs                                                     |
| --------------- | ----------------------------- | -------------------------------------------------------- |
| Vercel AI SDK   | `@moorcheh-ai/memanto/ai-sdk` | [Vercel AI SDK Integration](/integrations/vercel-ai-sdk) |
| Mastra          | `@moorcheh-ai/memanto/mastra` | [Mastra Integration](/integrations/mastra)               |
| OpenAI Node SDK | `@moorcheh-ai/memanto/openai` | [OpenAI Integration](/integrations/openai)               |

Each exposes `recallMemory`, `rememberMemory`, and `answerMemory` tools backed by this same `Memanto` client. The corresponding framework package (`ai`, `@mastra/core`, or `openai`) plus `zod` are optional peer dependencies — install only the ones you use.

## Versioning

The npm package version tracks the matching PyPI release. Pin the server version with:

```ts theme={null}
new Memanto({
  packageSpec: "memanto==0.2.3",
  // ...
});
```

## License

MIT