memories-sdk

name: memories-sdk description: "Build against the memories.sh SDK packages in application code. Use when working with @memories.sh/core or @memories.sh/ai-sdk, including: (1) Initializing MemoriesClient, (2) Reading, writing, searching, or editing memories from backend code, route handlers, workers, or scripts, (3) Integrating memories with the Vercel AI SDK via memoriesMiddleware, memoriesTools, preloadContext, or createMemoriesOnFinish, (4) Choosing and applying tenantId / userId / projectId scoping, (5) Managing SDK skill files or management APIs, or (6) Debugging memories SDK usage in TypeScript or JavaScript applications. Use memories-cli for CLI workflows, memories-mcp for MCP setup, and memories-dev for monorepo internals."

memories-sdk

Use the SDK packages when an application needs memories.sh programmatically. Prefer @memories.sh/core for direct typed API access and @memories.sh/ai-sdk only when the caller already uses the Vercel AI SDK.

Workflow

1. Pick the integration surface:
   • Use @memories.sh/core for backend routes, workers, cron jobs, and non-AI-SDK agents.
   • Use @memories.sh/ai-sdk for generateText, streamText, middleware, or tool loops built on ai.
   • If the task is about the CLI or MCP configuration, switch to memories-cli or memories-mcp.
2. Set scope before writing code:
   • Keep MEMORIES_API_KEY server-side.
   • tenantId selects the tenant or workspace database.
   • userId narrows memory to a user inside that tenant.
   • projectId narrows reads and writes to a product area, repo, or feature slice.
3. Use the narrowest pattern that solves the task:
   • Direct CRUD or context lookup: MemoriesClient
   • Automatic prompt injection: memoriesMiddleware
   • Agent loops with explicit memory tools: memoriesTools and memoriesSystemPrompt
   • Fetch once and reuse: preloadContext
   • Persist after completion: createMemoriesOnFinish
4. Verify the integration:
   • Confirm the same scope is used on both reads and writes.
   • Catch MemoriesClientError.
   • Do not expose the API key to browser-only code.

Quick Start

@memories.sh/core

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

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

const context = await client.context.get({
  query: "billing architecture",
  projectId: "dashboard",
  mode: "all",
  strategy: "hybrid",
  limit: 8,
})

await client.memories.add({
  content: "Enterprise billing uses Stripe invoices.",
  type: "fact",
  projectId: "dashboard",
  tags: ["billing"],
})

@memories.sh/ai-sdk

import { generateText, stepCountIs, wrapLanguageModel } from "ai"
import { openai } from "@ai-sdk/openai"
import {
  memoriesMiddleware,
  memoriesSystemPrompt,
  memoriesTools,
} from "@memories.sh/ai-sdk"

const model = wrapLanguageModel({
  model: openai("gpt-4o"),
  middleware: memoriesMiddleware({
    tenantId: "acme-prod",
    userId: "user_123",
    projectId: "dashboard",
  }),
})

const result = await generateText({
  model,
  system: memoriesSystemPrompt(),
  tools: memoriesTools({
    tenantId: "acme-prod",
    userId: "user_123",
    projectId: "dashboard",
  }),
  stopWhen: stepCountIs(5),
  prompt: "Summarize prior decisions about billing.",
})

console.log(result.text)

Decision Guide

• Need direct typed access from your own backend code: use MemoriesClient
• Need automatic context injection into prompts or messages: use memoriesMiddleware
• Need the model to read or write memory explicitly through tools: use memoriesTools
• Need to manage stored skill files or procedure fragments: use client.skills.* or the AI SDK skill-file tools
• Need tenant, key, or embedding usage administration: use client.management.*
• Need internals of the memories monorepo or server endpoints: use memories-dev

Reference Files

• references/core.md: direct client methods, transport choices, errors, management APIs, and skill-file APIs
• references/ai-sdk.md: middleware, tools, preload, post-finish persistence, and query extraction patterns
• references/scoping.md: tenant/user/project scoping rules, server-side safety, and debugging checklist