memory-sdk

AgentLink Memory API 客户端：使用 API Key 对 /api/agent/v1/memories 进行 CRUD 与列表/搜索，并对 /api/agent/v1/process 进行 Chat 补全（含流式），适用于 Node 与浏览器。

获取 API Key

在 Memory 设置页 的「API Key」区域创建 Key，格式为 mix_ 开头。请求时需在请求头中携带：Authorization: Bearer <key> 或 X-Api-Key: <key>，本 SDK 使用 Bearer 方式。

安装

npm install memory-sdk

浏览器示例

仓库内提供 example.html，在浏览器中填写 API Key 即可体验列表、搜索、创建、更新、删除。也可通过 CDN 直接使用：

<script type="module">
  import { MemoryClient } from 'https://cdn.jsdelivr.net/npm/memory-sdk/dist/index.mjs';
  const client = new MemoryClient({ apiKey: 'mix_xxx' });
  const list = await client.list();
  console.log(list);
</script>

使用

连接官方站（默认）

不传 baseUrl 时，默认请求 https://www.mixlab.top/api。

import { MemoryClient } from 'memory-sdk';

const client = new MemoryClient({ apiKey: 'mix_xxx' });

// 列表
const list = await client.list();
const filtered = await client.list({ category: '笔记', limit: 20, offset: 0 });

// 搜索
const results = await client.search('关键词', 50);

// 单条
const one = await client.get('memory-id'); // 404 时为 null

// 创建
const created = await client.create({
  source: 'https://example.com',
  category: '阅读',
  content: '内容摘要',
  tags: ['tag1'],
});

// 更新
const updated = await client.update(created.id, { content: '更新后的内容' });

// 删除
await client.delete(created.id);

// Chat 补全（非流式）
const res = await client.process({
  messages: [{ role: 'user', content: '今天学了 Next.js' }],
});
console.log(res.choices[0].message.content);

// Chat 补全（流式）
for await (const chunk of await client.processStream({
  messages: [{ role: 'user', content: '你好' }],
})) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
}

Chat 补全（process）

client.process() 与 client.processStream() 对应服务端 POST /api/agent/v1/process，鉴权与 Memory 相同（同一 API Key）。

• process(options)：非流式，返回 ProcessResponse（OpenAI chat.completion 风格）。不传 response_format 时，服务端使用内置 systemPrompt 与 Memory 五字段 schema 整理最后一条 user 内容并返回 JSON。
• processStream(options)：流式，返回 AsyncIterable<ProcessChunk>，可逐 chunk 取 choices[0].delta.content。
• 可选参数：model、temperature、response_format（{ type: 'json_object' } | { type: 'text' }）、llm（{ apiUrl, apiKey, model? } 覆盖后端 LLM）。
• 非 2xx 时解析 { error: { message } } 并抛出 Error。

自建或同源

传入 baseUrl 即可：

• 自建服务：baseUrl: 'https://your-domain.com/api'
• 浏览器同源：baseUrl: window.location.origin + '/api'

const client = new MemoryClient({
  apiKey: 'mix_xxx',
  baseUrl: 'https://your-domain.com/api',
});

类型

import type {
  Memory,
  CreatePayload,
  UpdatePayload,
  ListParams,
  ProcessMessage,
  ProcessOptions,
  ProcessResponse,
  ProcessChunk,
} from 'memory-sdk';
import { DEFAULT_BASE_URL } from 'memory-sdk';

API

Memory CRUD

• list(params?: ListParams): Promise<Memory[]> — 列表，支持 category、source、tag、limit、offset
• search(q: string, limit?: number): Promise<Memory[]> — 关键词搜索
• get(id: string): Promise<Memory | null> — 按 id 获取，404 返回 null
• create(payload: CreatePayload): Promise<Memory> — 创建（source、category、content 必填）
• update(id: string, payload: UpdatePayload): Promise<Memory> — 更新
• delete(id: string): Promise<void> — 删除

Chat 补全（process）

• process(options: ProcessOptions): Promise<ProcessResponse> — 非流式补全
• processStream(options: ProcessOptions): Promise<AsyncIterable<ProcessChunk>> — 流式补全

非 2xx 响应会解析 { error?: string } 或 { error: { message } } 并抛出 Error。