@aipack-ai/memory 1.1.5 → 1.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +83 -14
  2. package/dist/index.d.ts +2 -2
  3. package/package.json +3 -3
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
- # aipack-memory
1
+ # @aipack-ai/memory
2
2
 
3
3
  > aipack 持久化记忆插件：**capture → compress → index → recall/inject → consolidate**
4
4
  >
5
- > 参考 [rohitg00/agentmemory](https://github.com/rohitg00/agentmemory)，为 [aipack](../aipack) 提供「跨会话长期记忆」能力。
5
+ > 参考 [rohitg00/agentmemory](https://github.com/rohitg00/agentmemory)，为 [aipack](../../README.md) 提供「跨会话长期记忆」能力。
6
6
 
7
7
  ## 特性
8
8
 
@@ -19,19 +19,19 @@
19
19
  ## 安装
20
20
 
21
21
  ```bash
22
- pnpm add aipack-memory
22
+ pnpm add @aipack-ai/memory
23
23
  # 或
24
- npm install aipack-memory
24
+ npm install @aipack-ai/memory
25
25
  ```
26
26
 
27
- `aipack` 为 peer 依赖，需同时安装。
27
+ `@aipack-ai/agent` 为 peer 依赖，需同时安装。
28
28
 
29
29
  ## 快速接入
30
30
 
31
31
  ### aipack.config.js
32
32
 
33
33
  ```js
34
- import { createMemoryPlugin } from 'aipack-memory';
34
+ import { createMemoryPlugin } from '@aipack-ai/memory';
35
35
 
36
36
  const mem = createMemoryPlugin({
37
37
  baseDir: '~/.aipack/memory', // 记忆存储目录
@@ -54,7 +54,7 @@ export default {
54
54
  ### 编程式 API
55
55
 
56
56
  ```typescript
57
- import { createMemoryPlugin, InMemoryStore } from 'aipack-memory';
57
+ import { createMemoryPlugin, InMemoryStore } from '@aipack-ai/memory';
58
58
 
59
59
  const store = new InMemoryStore();
60
60
  const mem = createMemoryPlugin({ store });
@@ -148,6 +148,15 @@ BM25 tokenizer 支持：
148
148
  | `ttlMs` | `number` | — | 捕获记忆 TTL（ms） |
149
149
  | `onEvent` | `MemoryEventSink` | — | 捕获失败事件接收器 |
150
150
 
151
+ ### InjectionOptions
152
+
153
+ | 选项 | 类型 | 默认 | 说明 |
154
+ | ---------------- | -------------------------------- | ----- | ------------------------------------------- |
155
+ | `maxMemories` | `number` | `5` | 注入 top-K 上限 |
156
+ | `minScore` | `number` | `0.1` | 最低相关度阈值（本地阈值，不写回 retriever）|
157
+ | `queryTransform` | `(latestUserText: string) => string` | — | 对检索 query 做变换（如只取最后一句提问） |
158
+ | `onRecall` | `(ids: string[]) => void \| Promise<void>` | — | 命中后的回调（插件层装配为 `store.touchRecall`） |
159
+
151
160
  ## Agent 工具
152
161
 
153
162
  插件自动注册 4 个 Agent 可调用工具（带输入校验与 limit 裁剪）：
@@ -159,10 +168,70 @@ BM25 tokenizer 支持：
159
168
  | `list_memories` | `limit?` | 列出最近记忆（limit ≤ 200） |
160
169
  | `delete_memory` | `id` | 删除一条记忆 |
161
170
 
171
+ 工具选项（`createMemoryTools(store, options)`）：
172
+
173
+ | 选项 | 类型 | 默认 | 说明 |
174
+ | ------------- | -------- | ---- | ----------------------------- |
175
+ | `listLimit` | `number` | `20` | `list_memories` 默认返回上限 |
176
+ | `searchLimit` | `number` | `5` | `search_memory` 默认返回上限 |
177
+ | `saveTtlMs` | `number` | — | `save_memory` 保存记忆的 TTL |
178
+
179
+ > 通过 `createMemoryPlugin({ toolTtlMs })` 即可把该值透传给 `save_memory`。
180
+
181
+ ## 过期、统计与事件
182
+
183
+ ### TTL 过期
184
+
185
+ 三种粒度：
186
+
187
+ | 粒度 | 配置 | 说明 |
188
+ | ---------- | ------------------------------------------- | -------------------------------------------- |
189
+ | 库级 | `new FileMemoryStore({ maxAge })` | 按 `updatedAt` 判定，加载时惰性清理 |
190
+ | 捕获记忆 | `createMemoryPlugin({ captureTtlMs })` | 换算为 `expiresAt`，prune 时清理 |
191
+ | 工具保存 | `createMemoryPlugin({ toolTtlMs })` | 同上，作用于 `save_memory` |
192
+
193
+ `save({ ttlMs })` 时 `expiresAt = createdAt + ttlMs`，优先于显式传入的 `expiresAt`。
194
+
195
+ ### 统计快照（`store.stats()`）
196
+
197
+ | 字段 | 说明 |
198
+ | -------------------- | ---------------------------- |
199
+ | `count` | 记忆总数 |
200
+ | `embeddingCount` | 带向量的条目数 |
201
+ | `bySource` | 按 `capture` / `tool` / `consolidation` 计数 |
202
+ | `avgConfidence` | 平均置信度（0..1） |
203
+ | `recallTotal` | 检索注入总次数 |
204
+ | `lastRecalledAt` | 最近一次被检索注入的时间 |
205
+ | `lastConsolidatedAt` | 最近一次合并时间（驱动增量候选窗口）|
206
+
207
+ ### 事件监控（`onEvent`）
208
+
209
+ `onEvent` 可接收以下 `MemoryEvent`；默认行为是只把失败类事件打印到 `console.warn`：
210
+
211
+ | type | 触发时机 | 关键字段 |
212
+ | --------------------- | ------------ | ------------------------- |
213
+ | `store:load` | 记忆库加载完 | `loaded` / `skipped` / `ms` |
214
+ | `store:corrupt` | 文件损坏 | `file` |
215
+ | `embedding:error` | 向量化失败 | `id?` / `error` |
216
+ | `capture:failed` | 捕获失败 | `sessionKey?` / `error` |
217
+ | `consolidate:failed` | 合并失败 | `error` |
218
+ | `consolidate` | 合并完成 | `merged` / `pruned` / `ms` |
219
+ | `prune` | 修剪完成 | `removed` |
220
+
221
+ ```typescript
222
+ const mem = createMemoryPlugin({
223
+ onEvent(event) {
224
+ if (event.type === 'consolidate') {
225
+ console.log(`合并 ${event.merged} 条，修剪 ${event.pruned} 条，耗时 ${event.ms}ms`);
226
+ }
227
+ },
228
+ });
229
+ ```
230
+
162
231
  ## 自定义 Embedder
163
232
 
164
233
  ```typescript
165
- import { createMemoryPlugin, type Embedder } from 'aipack-memory';
234
+ import { createMemoryPlugin, type Embedder } from '@aipack-ai/memory';
166
235
 
167
236
  // 示例：接入 ollama embedding
168
237
  const ollamaEmbedder: Embedder = {
@@ -187,7 +256,7 @@ const mem = createMemoryPlugin({
187
256
  ## 自定义 LLM 摘要
188
257
 
189
258
  ```typescript
190
- import { createMemoryPlugin, type SummarizeFn } from 'aipack-memory';
259
+ import { createMemoryPlugin, type SummarizeFn } from '@aipack-ai/memory';
191
260
 
192
261
  const summarize: SummarizeFn = async ({ userMessage, assistantContent }) => {
193
262
  // 调用你的 LLM 压缩对话
@@ -265,17 +334,17 @@ interface MemoryEntry {
265
334
 
266
335
  ```bash
267
336
  # 构建
268
- pnpm --filter aipack build # 先构建框架（peer 依赖）
269
- pnpm --filter aipack-memory build # 构建插件
337
+ pnpm --filter @aipack-ai/agent build # 先构建框架（peer 依赖）
338
+ pnpm --filter @aipack-ai/memory build # 构建插件
270
339
 
271
340
  # 类型检查
272
- pnpm --filter aipack-memory typecheck
341
+ pnpm --filter @aipack-ai/memory typecheck
273
342
 
274
343
  # 单元测试（node:test，覆盖 tokenizer/BM25/向量索引/双路检索/合并器/存储/并发）
275
- pnpm --filter aipack-memory test
344
+ pnpm --filter @aipack-ai/memory test
276
345
 
277
346
  # 运行往返验证脚本（不依赖真实 LLM / API Key）
278
- pnpm --filter aipack-memory example
347
+ pnpm --filter @aipack-ai/memory example
279
348
  ```
280
349
 
281
350
  ## License
package/dist/index.d.ts CHANGED
@@ -3,7 +3,7 @@ import { BaseExtension, RuntimeHooks, ExtensionContext, BaseTransformer, Context
3
3
  export { ContextTransformer, Extension, Tool, ToolResult } from '@aipack-ai/agent';
4
4
 
5
5
  /**
6
- * aipack-memory - 核心类型定义
6
+ * @aipack-ai/memory - 核心类型定义
7
7
  *
8
8
  * 记忆条目、存储契约、检索结果、Embedder 与摘要函数接口。
9
9
  * 不依赖任何外部实现，是整个插件的类型基础。
@@ -21,7 +21,7 @@ interface MemoryEntry {
21
21
  content: string;
22
22
  /** 关键词 / 概念标签（用于 BM25 索引与展示） */
23
23
  concepts: string[];
24
- /** 置信度 0..1（捕获默认 0.6，摘要 0.8，合并后累加并截断到 1，可衰减） */
24
+ /** 置信度 0..1（捕获默认 0.6，摘要 0.8，合并取 max + 0.05 小奖励后截断到 1） */
25
25
  confidence: number;
26
26
  /** 来源 */
27
27
  source: MemorySource;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aipack-ai/memory",
3
- "version": "1.1.5",
3
+ "version": "1.1.6",
4
4
  "description": "aipack 持久化记忆插件：capture → compress → index → recall/inject → consolidate",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -29,14 +29,14 @@
29
29
  "node": ">=18.0.0"
30
30
  },
31
31
  "peerDependencies": {
32
- "@aipack-ai/agent": "1.1.5"
32
+ "@aipack-ai/agent": "1.1.6"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@types/node": "^20.12.0",
36
36
  "tsup": "^8.5.1",
37
37
  "typescript": "^5.5.0",
38
38
  "tsx": "^4.16.0",
39
- "@aipack-ai/agent": "1.1.5"
39
+ "@aipack-ai/agent": "1.1.6"
40
40
  },
41
41
  "scripts": {
42
42
  "build": "tsup",