@memories.sh/core

Typed core client for the memories.sh hosted MCP API.

Install

npm install @memories.sh/core

Requires Node.js >= 20.

Quick Start

import { MemoriesClient } from "@memories.sh/core"

const client = new MemoriesClient({
  apiKey: process.env.MEMORIES_API_KEY,
  tenantId: "acme-prod",
  userId: "user_123",
})

await client.memories.add({
  content: "Acme Enterprise plan includes SSO and audit logs.",
  type: "fact",
  tags: ["pricing", "sales"],
  projectId: "dashboard",
})

const context = await client.context.get({
  query: "SSO plan details",
  projectId: "dashboard",
  userId: "user_123",
  mode: "all",
  limit: 8,
})
console.log(context.memories.map((m) => m.content))

apiKey can be passed directly or set via MEMORIES_API_KEY.

Scoping Model

Use one API key and scope requests at runtime:

• tenantId: routes to a tenant/customer database (tenant_id in MCP tool args)
• userId: per-user memory scope inside that tenant (user_id in MCP tool args)
• projectId: optional per-project filter on read/write operations

Recommended pattern for SaaS apps:

• Set tenantId to workspace/org/account id
• Set userId to end-user id
• Keep one server-side API key for your backend

API Surface

MemoriesClient exposes:

• context.get(input?: { query?: string; userId?: string; tenantId?: string; projectId?: string; mode?: "all" | "working" | "long_term" | "rules_only"; limit?: number; includeRules?: boolean })
• memories.add(input)
• memories.search(query, options?)
• memories.list(options?)
• memories.edit(id, updates)
• memories.forget(id)
• management.keys.get()
• management.keys.create({ expiresAt })
• management.keys.revoke()
• management.tenants.list()
• management.tenants.upsert(input)
• management.tenants.disable(tenantId)
• buildSystemPrompt({ rules, memories })

Copy-Paste: MemoriesClient.management.*

import { MemoriesClient } from "@memories.sh/core"

const client = new MemoriesClient({
  apiKey: process.env.MEMORIES_API_KEY,
  baseUrl: "https://memories.sh",
  transport: "sdk_http",
})

const keyStatus = await client.management.keys.get()
const rotatedKey = await client.management.keys.create({
  expiresAt: "2027-01-01T00:00:00.000Z",
})
const revoked = await client.management.keys.revoke()

const tenantMappings = await client.management.tenants.list()
const upsertedTenant = await client.management.tenants.upsert({
  tenantId: "acme-prod",
  mode: "provision",
})
const disabledTenant = await client.management.tenants.disable("acme-prod")

void [keyStatus, rotatedKey, revoked, tenantMappings, upsertedTenant, disabledTenant]

context.get mode behavior:

• all (default): rules + working + long_term
• working: rules + working
• long_term: rules + long_term
• rules_only: rules only

Legacy signature is still supported:

await client.context.get("auth patterns", { projectId: "dashboard", limit: 10 })

Types are exported for all inputs and outputs (MemoryRecord, ContextResult, MutationResult, etc.).

Error Handling

MemoriesClientError includes typed metadata:

• type (auth_error, validation_error, rate_limit_error, network_error, ...)
• errorCode
• status
• retryable
• details

import { MemoriesClient, MemoriesClientError } from "@memories.sh/core"

const client = new MemoriesClient({ apiKey: process.env.MEMORIES_API_KEY, tenantId: "acme-prod" })

try {
  await client.memories.search("checkout issues")
} catch (error) {
  if (error instanceof MemoriesClientError) {
    console.error(error.type, error.errorCode, error.status, error.message)
  }
}

Base URL

Default base URL is https://memories.sh.

Override with baseUrl if needed:

new MemoriesClient({
  apiKey: process.env.MEMORIES_API_KEY,
  baseUrl: "https://your-domain.com",
  tenantId: "acme-prod",
})

Transport

The client supports two transports:

• sdk_http (recommended): calls /api/sdk/v1/* endpoints
• mcp: calls JSON-RPC over /api/mcp

Default behavior is auto:

• if baseUrl ends with /api/mcp, the client uses mcp
• otherwise, it uses sdk_http

new MemoriesClient({
  apiKey: process.env.MEMORIES_API_KEY,
  baseUrl: "https://your-domain.com",
  transport: "sdk_http", // optional; defaults to auto
})

Documentation

Full docs: memories.sh/docs

License

Apache 2.0