@easynet/agent-memory

面向 Agent 的轻量记忆包。
默认只需要 1 个入口函数：createAgentMemory()。

最小接口

import { createAgentMemory } from "@easynet/agent-memory";

const memory = await createAgentMemory();

// 写入：memorize
await memory.memorize({
  namespace: "user:alice",
  type: "cross_thread",
  content: "用户偏好中文回答，尽量简洁。",
});

// 检索：recall
const { injectedText } = await memory.recall({
  namespace: "user:alice",
  query: "用户偏好",
  topK: 5,
});

console.log(injectedText);

可选能力：

• memorize({ url })：直接摄入本地/远程 PDF、txt、HTML、图片（写入 knowledge）
• retrieveContextForLangChain / writeMemoryForLangChain：LangChain 快捷接入

最简单示例（带详细注释）

import { createAgentMemory } from "@easynet/agent-memory";

async function main() {
  // 1) 创建 memory 实例：
  //    - 不传参数时，会尝试读取 ./config/agent-memory.yaml
  //    - 如果文件不存在，自动退回内存版 in_memory provider
  const memory = await createAgentMemory();

  // 2) 写入长期偏好（cross_thread）：
  //    namespace 是逻辑隔离维度，建议固定命名规范（如 user:{id}）
  await memory.memorize({
    namespace: "user:alice",
    type: "cross_thread",
    content: "用户希望所有输出优先中文。",
    metadata: {
      source: "chat",
      tags: ["preference", "language"],
    },
  });

  // 3) 写入知识（knowledge）：
  await memory.memorize({
    namespace: "project:demo",
    type: "knowledge",
    content: "Demo API 统一使用 Bearer Token 鉴权。",
  });

  // 4) 检索上下文：
  //    recall 会返回可直接拼进 prompt 的 injectedText
  const result = await memory.recall({
    namespace: "project:demo",
    query: "这个项目如何鉴权？",
    topK: 3,
    budgetTokens: 400,
  });

  console.log("traceId:", result.traceId);
  console.log("context:\\n", result.injectedText);
}

main().catch(console.error);

最简单 YAML（推荐先用这个）

config/agent-memory.yaml

# 最小配置：单一 in_memory provider（进程内存，重启后数据丢失）
providers:
  - id: default
    type: in_memory

router:
  # 所有读写都走 default provider
  defaultProvider: default
  rules: []

policy:
  # 允许写入三类记忆
  allowedWriteTypes: [thread, cross_thread, knowledge]
  # 单类型最多保留多少条（超过后由策略裁剪）
  maxItemsPerType: 20

observability:
  # 是否记录 recall trace（建议开发期开，生产按需）
  trace: false

privacy:
  # 写入前移除敏感 metadata 字段
  forbiddenMetadataKeys: [password, api_key, secret, token]

SQLite YAML（本地持久化）

providers:
  - id: default
    type: sqlite
    options:
      # SQLite 文件路径；相对路径以该 YAML 所在目录为基准
      dbPath: ./data/agent-memory.db

router:
  defaultProvider: default
  rules: []

policy:
  allowedWriteTypes: [thread, cross_thread, knowledge]
  maxItemsPerType: 50

observability:
  trace: true

依赖说明：

• type: sqlite 需要安装 better-sqlite3
• URL 摄入 PDF 需要安装 pdf-parse
• type: mem0 需要安装 mem0ai

扩展 Provider（extension）

支持从外部 npm 包或本地模块加载自定义 provider。

providers:
  - id: ext
    type: extension
    options:
      package: "@your-scope/agent-memory-provider-foo" # 也可用 ./relative/path/to/provider.mjs
      exportName: createMemoryProvider            # 可选，默认 createMemoryProvider
      options:
        anyKey: anyValue

router:
  defaultProvider: ext
  rules: []

扩展导出约定：

• 函数导出：createMemoryProvider({ providerId, options }) => MemoryProvider
• 或默认导出 class，构造参数同上
• 返回对象需实现 write/query/delete