@easynet/agent-memory 1.0.46 → 1.0.48

package/README.md

@@ -1,92 +1,20 @@
 # @easynet/agent-memory
 
-面向 Agent 的轻量记忆包。  
-默认入口：`createAgentMemory()`。
+## Introduction
 
-## 最小接口
+`@easynet/agent-memory` adds memory storage and recall for agents. It supports common scopes such as `thread`, `cross_thread`, and `knowledge`, and registers the memory client into the default `AgentContext`.
 
-```ts
-import { createAgentMemory } from "@easynet/agent-memory";
+## API Reference
 
-const memory = await createAgentMemory();
+| API | What it does | Minimal usage |
+| --- | --- | --- |
+| `createAgentMemory` | Create a memory client and register it into `AgentContext`. | `const memory = await createAgentMemory({ configPath: "./memory.yaml" })` |
 
-// 写入：memorize
-await memory.memorize({
-  namespace: "user:alice",
-  type: "cross_thread",
-  content: "用户偏好中文回答，尽量简洁。",
-});
+## Usage
 
-// 检索：recall
-const { injectedText } = await memory.recall({
-  namespace: "user:alice",
-  query: "用户偏好",
-  topK: 5,
-});
-
-console.log(injectedText);
-```
-
-## Memory Type 关键字
-
-- Canonical keyword：`thread`、`cross_thread`、`knowledge`
-- 推荐始终写 canonical keyword
-
-可选能力：
-- `memorize({ url })`：直接摄入本地/远程 PDF、txt、HTML、图片（写入 `knowledge`）
-
-## 最简单示例（带详细注释）
-
-```ts
-import { createAgentMemory } from "@easynet/agent-memory";
-
-async function main() {
-  // 1) 创建 memory 实例：
-  //    - 不传参数时，会尝试读取 ./config/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/memory.yaml`
+Create `config/memory.yaml`:
 
 ```yaml
-# 最小配置：单一 in_memory provider（进程内存，重启后数据丢失）
 providers:
   - id: default
     type: in_memory
@@ -97,132 +25,82 @@ memoryTypes:
   thread: { providerId: default, allowWrite: true, maxItems: 20 }
   cross_thread: { providerId: default, allowWrite: true, maxItems: 20 }
   knowledge: { providerId: default, allowWrite: true, maxItems: 20 }
-
-observability:
-  # 是否记录 recall trace（建议开发期开，生产按需）
-  trace: false
-
-privacy:
-  # 写入前移除敏感 metadata 字段
-  forbiddenMetadataKeys: [password, api_key, secret, token]
 ```
 
-## SQLite YAML（本地持久化）
+Initialize and use memory:
 
-```yaml
-providers:
-  - id: default
-    type: sqlite
-    options:
-      # SQLite 文件路径；相对路径以该 YAML 所在目录为基准
-      dbPath: ./data/agent-memory.db
-
-defaultProvider: default
-
-memoryTypes:
-  thread: { providerId: default, allowWrite: true, maxItems: 50 }
-  cross_thread: { providerId: default, allowWrite: true, maxItems: 50 }
-  knowledge: { providerId: default, allowWrite: true, maxItems: 50 }
-
-observability:
-  trace: true
-```
-
-## 分层配置（按 memory type）
-
-当你希望 `thread / cross_thread / knowledge` 各自有独立设置时，推荐使用 `memoryTypes`：
-
-```yaml
-providers:
-  - id: default
-    type: in_memory
-  - id: docs
-    type: sqlite
-    options:
-      dbPath: ./data/docs.db
-
-defaultProvider: default
-
-memoryTypes:
-  thread:
-    allowWrite: false
-  cross_thread:
-    maxItems: 20
-    budgetTokens: 500
-  knowledge:
-    providerId: docs
-    maxItems: 8
-    budgetTokens: 900
-```
+```ts
+import { createAgentMemory } from "@easynet/agent-memory";
 
-说明：
-- `memoryTypes.*.providerId` 决定该类型路由到哪个 provider
-- `memoryTypes.*.allowWrite` 控制该类型是否允许写入
-- `memoryTypes.*.maxItems / budgetTokens` 控制该类型召回裁剪预算
+const memory = await createAgentMemory({
+  configPath: "./config/memory.yaml",
+});
 
-## LlamaIndex / Sqlite-Vec YAML（内置类型）
+await memory.memorize("user:alice", "cross_thread", "Prefers concise English answers.");
 
-```yaml
-providers:
-  - id: knowledge
-    type: llamaindex
-    options: {}
-  - id: longterm
-    type: sqlite_vec
-    options:
-      dbPath: ./data/long-term.sqlite
-      dimensions: 1024
-
-defaultProvider: knowledge
+const result = await memory.recall({
+  namespace: "user:alice",
+  query: "language preference",
+  topK: 5,
+});
 
-memoryTypes:
-  thread:
-    providerId: knowledge
-  cross_thread:
-    providerId: longterm
-  knowledge:
-    providerId: knowledge
+console.log(result.injectedText);
 ```
 
-依赖说明：
-- `type: sqlite` 需要安装 `better-sqlite3`
-- `type: sqlite_vec` 需要安装 `better-sqlite3`，并提供 provider ctor（推荐：`overrides.providerCtors.sqliteVec`，或在 `stores[].config` 设置 `package` + `exportName`）
-- `type: llamaindex` 需要安装 `llamaindex`，并提供 provider ctor（推荐：`overrides.providerCtors.llamaindex`，或在 `stores[].config` 设置 `package` + `exportName`）
-- URL 摄入 PDF 需要安装 `pdf-parse`
-- `type: mem0` 需要安装 `mem0ai`
-
-## 扩展 Provider（extension）
+### YAML config
 
-支持从外部 npm 包或本地模块加载自定义 provider。
-也可以直接复用 `@easynet/agent-memory` 已导出的 provider（如 `InMemoryStoreProvider` / `SqliteStoreProvider` / `RAGProvider` / `Mem0Provider`）。
+Example `config/memory.yaml`:
 
 ```yaml
-providers:
-  # 复用当前包内置导出（无需单独安装 provider 包）
-  - id: builtin
-    type: extension
-    options:
-      package: "@easynet/agent-memory"
-      exportName: InMemoryStoreProvider
-
-  # 或加载外部自定义 provider
-  - id: ext
-    type: extension
-    options:
-      package: "@your-scope/agent-memory-provider-foo" # 也可用 ./relative/path/to/provider.mjs
-      exportName: createMemoryProvider            # 可选，默认 createMemoryProvider
-      options:
-        anyKey: anyValue
-
-defaultProvider: ext
-
-memoryTypes:
-  thread: { providerId: ext }
-  cross_thread: { providerId: ext }
-  knowledge: { providerId: ext }
+apiVersion: easynet.world/v1
+kind: MemoryConfig
+metadata:
+  name: agent-memory-default
+spec:
+  memory:
+    thread:
+      store:
+        type: in_memory
+      allowWrite: true
+      maxItems: 20
+      sessionCompaction:
+        enabled: true
+        maxTokens: 3000
+        keepRecentTurns: 12
+        summaryKey: __session_summary__
+        checkEveryTurns: 3
+
+    cross_thread:
+      store:
+        type: in_memory
+      allowWrite: true
+      maxItems: 20
+
+    knowledge:
+      store:
+        type: in_memory
+      allowWrite: true
+      maxItems: 20
+
+  observability:
+    trace: false
+
+  privacy:
+    forbiddenMetadataKeys:
+      - password
+      - api_key
+      - secret
+      - token
 ```
 
-扩展导出约定：
-- 函数导出：`createMemoryProvider({ providerId, options }) => MemoryProvider`
-- 或默认导出 class，构造参数同上
-- 返回对象需实现 `write/query/delete`
+Explanation:
+
+- `spec.memory.thread`: short-term conversational memory.
+- `spec.memory.cross_thread`: long-term user or session memory across conversations.
+- `spec.memory.knowledge`: knowledge storage for reusable facts and documents.
+- `store.type`: backend type, such as `in_memory`.
+- `allowWrite`: whether this memory scope can accept writes.
+- `maxItems`: maximum number of recalled items kept per scope.
+- `sessionCompaction`: optional summarization of long thread history.
+- `observability.trace`: enable recall tracing for debugging.
+- `privacy.forbiddenMetadataKeys`: metadata keys that should be stripped before storage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easynet/agent-memory",
-  "version": "1.0.46",
+  "version": "1.0.48",
   "description": "Unified memory layer for LangChain / LangGraph / DeepAgents",
   "type": "module",
   "main": "dist/src/index.js",