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 (which ships uvx)

Installation

npm install @moorcheh-ai/memanto

Quick Start

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:

Picks a free port and spawns uvx memanto serve --port <port>.
Polls /health until the server is ready.
Creates the agent (if autoCreate is enabled — default true) and activates a session.
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

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

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

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

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

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

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
Mastra	`@moorcheh-ai/memanto/mastra`	Mastra Integration
OpenAI Node SDK	`@moorcheh-ai/memanto/openai`	OpenAI Integration

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:

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

License

MIT

​TypeScript SDK Reference

​Prerequisites

​Installation

​Quick Start

​Memanto Client

​Constructor

​Memory Write Methods

​Memory Read Methods

​Analysis Methods

​Agent & Session Lifecycle

​Diagnostics

​Framework Integrations

​Versioning

​License