mnemosyne-sdk

Orpheus lost Eurydice because he looked back. Mnemosyne, titaness of memory, is the one who kept her name. This package family is the instrument of that preservation: adapters, SDKs, and runtimes that let AI agents store, recall, and forget without ever looking at the wrong thing at the wrong time.

Typed JavaScript/TypeScript client for the Mnemosyne memory substrate. Container-scoped storage, hybrid BM25+vector recall, async/sync APIs, full TypeScript definitions. Talks to any Mnemosyne endpoint over HTTPS.

Install

npm install @mnemosyne-eurydice/sdk
# or
pnpm add @mnemosyne-eurydice/sdk
# or
yarn add @mnemosyne-eurydice/sdk

Quick start

import { Mnemosyne } from "@mnemosyne-eurydice/sdk";

const mn = new Mnemosyne({
  apiKey: process.env.MNEMOSYNE_API_KEY!,
  // baseUrl defaults to https://api.mnemosyne.geasslabs.xyz
});

await mn.add("The dock-A camera lost calibration at 14:32 UTC", {
  containerTag: "fleet-ops",
});

const results = await mn.search("when did dock A fail?", {
  containerTag: "fleet-ops",
  limit: 5,
});
for (const r of results) {
  console.log(`${r.score.toFixed(3)}  ${r.content}`);
}

Framework adapters

| Adapter | Import | Peer dep | |---|---|---| | Vercel AI SDK | import { MnemosyneVercelAdapter } from "@mnemosyne-eurydice/sdk/vercel" (in dedicated package) | ai@^3 | | LangChain.js | import { MnemosyneChatHistory } from "@mnemosyne-eurydice/langchain" | langchain@^0.2 |

The framework adapters live in their own dedicated packages (@mnemosyne-eurydice/langchain, @mnemosyne-eurydice/vercel-ai, etc.). This package stays framework-agnostic.

API

// Add a memory
const memory: Memory = await mn.add(content: string, options?: AddOptions);

// Search memories
const results: SearchResult[] = await mn.search(query: string, options?: SearchOptions);

// Get / delete
const one: Memory = await mn.get(memoryId: string);
const ok: boolean = await mn.delete(memoryId: string);

// Profile
const profile: Profile = await mn.getProfile(containerTag: string);

Error handling

import {
  MnemosyneError,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ServerError,
  ValidationError,
} from "@mnemosyne-eurydice/sdk";

try {
  await mn.add("...");
} catch (e) {
  if (e instanceof RateLimitError) {
    await new Promise((r) => setTimeout(r, (e.retryAfter ?? 1) * 1000));
    return retry();
  }
  if (e instanceof AuthenticationError) {
    // bad API key
  }
  if (e instanceof MnemosyneError) {
    // generic fallback
  }
  throw e;
}

Configuration

| Env var | Description | Default | |---|---|---| | MNEMOSYNE_API_KEY | API key (overridden by constructor) | - | | MNEMOSYNE_BASE_URL | Server URL | https://api.mnemosyne.geasslabs.xyz |

License

MIT © Geass Labs. The Mnemosyne engine this SDK talks to is licensed under the Mnemosyne Source-Available License v1.0. See NOTICE for the dual-license arrangement.

Links

• Homepage: https://mnemosyne.geasslabs.xyz
• Documentation: https://docs.geasslabs.xyz/mnemosyne-sdk
• Repository: https://github.com/synet-systems/mnemosyne
• Issues: https://github.com/synet-systems/mnemosyne/issues
• Changelog: CHANGELOG.md