memories sdk
- Repo stars 27
- License Apache-2.0
- Author repo memories
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @webrenew · Apache-2.0
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Required · Vendor-specific
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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`
```ts
import { MemoriesClient } from "@memories.sh/core"
const client = new MemoriesClient({
apiKey: [REDACTED:credential],
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`
```ts
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
Sections and files
Listed in source order.
sections -> Workflow → Quick Start → @memories.sh/core → @memories.sh/ai-sdk → Decision Guide → Reference Files
terms -> Use the SDK packages when an application needs memories.sh programmatically. · 1. Pick the integration surface: - Use @memories.sh/core for backend routes, workers, cron jobs, and non-AI-SDK agents.
files/cmd -> @memories.sh/core · @memories.sh/ai-sdk · generateText · streamText · memories-cli · memories-mcp · MEMORIES_API_KEY · tenantId
body sha256 -> 3c30f54e7b11
Workflow
Pick the integration surface: Use
@memories.sh/corefor backend routes, workers, cron jobs, and non-AI-SDK agents. Use@memories.sh/ai-sdkforgenerateText,streamText, middleware, or tool loops built onai. If the task is about the CLI or MCP configuration, switch tomemories-cliormemories-mcp. Set scope before writing code:Decision Guide
Need direct typed access from your own backend code: use
MemoriesClientNeed automatic context injection into prompts or messages: usememoriesMiddlewareNeed the model to read or write memory explicitly through tools: usememoriesToolsNeed to manage stored skill files or procedure fragments: useclient.skills.*or the AI SDK skill-file tools Need tenant, key, or embedding usage administration: useclient.management.*Reference Files
references/core.md: direct client methods, transport choices, errors, management APIs, and skill-file APIsreferences/ai-sdk.md: middleware, tools, preload, post-finish persistence, and query extraction patternsreferences/scoping.md: tenant/user/project scoping rules, server-side safety, and debugging checklist