@easynet/agent-memory

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

最小接口

``ts
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 快捷接入

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

`ts
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

`yaml


最小配置：单一 in_memory provider（进程内存，重启后数据丢失）

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

SQLite YAML（本地持久化）

`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。

`yaml
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`