@easbot/memory 0.3.37 → 0.3.39

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 (44) hide show
  1. package/README.en.md +124 -81
  2. package/README.md +45 -30
  3. package/dist/chunks/{chunk-YUWHNHAY.mjs → chunk-7RA6RQGC.mjs} +1 -1
  4. package/dist/chunks/{chunk-FZ3RTYIJ.mjs → chunk-HTBMVZF7.mjs} +11 -11
  5. package/dist/chunks/{chunk-AEAMQDNV.mjs → chunk-IPUFIEKC.mjs} +6 -6
  6. package/dist/chunks/{chunk-QAEIHJOF.cjs → chunk-KWSPFECY.cjs} +5 -5
  7. package/dist/chunks/{chunk-4G4FSAFY.cjs → chunk-SAGLLJTU.cjs} +1 -1
  8. package/dist/chunks/{chunk-ISYAE6B7.cjs → chunk-SEKBFDEC.cjs} +12 -12
  9. package/dist/chunks/cli-handler-HUTXCEXM.cjs +1 -0
  10. package/dist/chunks/cli-handler-TUILJT7W.mjs +1 -0
  11. package/dist/chunks/{consolidate-OOAMW7XW.mjs → consolidate-JMXYI3NF.mjs} +1 -1
  12. package/dist/chunks/{consolidate-IKQVVWIQ.cjs → consolidate-TYCVXZFF.cjs} +1 -1
  13. package/dist/chunks/{doctor-ZGHICE2Q.mjs → doctor-3W3MVUZF.mjs} +1 -1
  14. package/dist/chunks/{doctor-N6HHFR6Y.cjs → doctor-GRS3CZWD.cjs} +1 -1
  15. package/dist/chunks/{extract-7DQ6OV34.cjs → extract-IKAJ3GHK.cjs} +1 -1
  16. package/dist/chunks/{extract-AJY2ETKE.mjs → extract-XT6HBENH.mjs} +1 -1
  17. package/dist/chunks/{forget-NIBBY6FG.mjs → forget-2OAYPXCB.mjs} +1 -1
  18. package/dist/chunks/{forget-4KGLTQ5Q.cjs → forget-GXJPG4P4.cjs} +1 -1
  19. package/dist/chunks/{graph-4K56ZAVL.mjs → graph-2AL2R3KO.mjs} +1 -1
  20. package/dist/chunks/{graph-OG23VZZM.cjs → graph-LJYAUA3C.cjs} +1 -1
  21. package/dist/chunks/{init-HWR4SD6N.mjs → init-M5CEJUEY.mjs} +1 -1
  22. package/dist/chunks/{init-UQTPANNI.cjs → init-OFCTBJGM.cjs} +1 -1
  23. package/dist/chunks/{mcp-ONIMP7FB.cjs → mcp-OKBJHIXH.cjs} +1 -1
  24. package/dist/chunks/{mcp-ZWZYH52C.mjs → mcp-OWOAIP2Z.mjs} +1 -1
  25. package/dist/chunks/{recall-KZRYTTWA.cjs → recall-K3DU2S23.cjs} +1 -1
  26. package/dist/chunks/{recall-BRXHJPR4.mjs → recall-ZEDO4S5I.mjs} +1 -1
  27. package/dist/chunks/{remember-GLOJH457.cjs → remember-FR7JL2ZC.cjs} +1 -1
  28. package/dist/chunks/{remember-3XSYCWKK.mjs → remember-TEAHLG4E.mjs} +1 -1
  29. package/dist/chunks/{status-SW5BUHJ3.mjs → status-BGRJ224S.mjs} +1 -1
  30. package/dist/chunks/{status-POX2GWSQ.cjs → status-KLQSENQX.cjs} +1 -1
  31. package/dist/chunks/stdio-server-EEWPIACW.mjs +1 -0
  32. package/dist/chunks/{stdio-server-W52CMVJO.cjs → stdio-server-ME6A6STR.cjs} +1 -1
  33. package/dist/chunks/{sync-EE4ZD3WB.mjs → sync-2D3E4DPE.mjs} +1 -1
  34. package/dist/chunks/{sync-I423W5G7.cjs → sync-QZCZXNNN.cjs} +1 -1
  35. package/dist/cli.cjs +1 -1
  36. package/dist/cli.mjs +1 -1
  37. package/dist/index.cjs +35 -25
  38. package/dist/index.d.cts +132 -50
  39. package/dist/index.d.ts +132 -50
  40. package/dist/index.mjs +35 -25
  41. package/package.json +11 -11
  42. package/dist/chunks/cli-handler-JHSDGJHK.mjs +0 -1
  43. package/dist/chunks/cli-handler-USK4CPAU.cjs +0 -1
  44. package/dist/chunks/stdio-server-3A3H4YJ7.mjs +0 -1
package/README.en.md CHANGED
@@ -2,17 +2,17 @@
2
2
 
3
3
  [中文](./README.md) | English
4
4
 
5
- Long-term memory library for the EASBOT ecosystem, providing per-agent fact storage, hybrid search, KG scope filtering, and a 9-op unified execution interface.
5
+ Long-term memory library for the EASBOT ecosystem (v0.4.0). Provides layered memory, three-tier KG scope isolation, a unified 10-op dispatch, hybrid search and observable governance.
6
6
 
7
7
  ## Version
8
8
 
9
- v0.3.37
9
+ v0.3.39
10
10
  ## Features (v0.4.0)
11
11
 
12
- - **9 op unified entry** — `recall / remember / forget / extract / consolidate / graph_query / status / doctor / init`; MCP / CLI / Agent Tool share the same `executeOp(name, args, ctx)`.
13
- - **Per-agent isolation + KG scope filtering** — each KG node carries `owner_agent_id`; scope ∈ `{agent_only, shared_only, both}`; MCP defaults to `agent_only`, trusted local may use `both`. `agentId` is **optional** for `graph_query` / `status` / `doctor` / `init` (defaults to `'default'`, see ADR 0068 P0-A reversal).
14
- - **Layered memory** — short-term / writable self-memory / long-term history; hybrid search (FTS + vector + graph).
15
- - **Observability** — 9 op fully routed through `Log.create({ service })` English structured logs; `status` / `doctor` provide offline diagnostics.
12
+ - **10 op unified entry** (ADR 0069 +1 `sync`) — `recall / remember / forget / extract / consolidate / sync / graph_query / status / doctor / init`; MCP / CLI / Agent Tool share the same `executeOp(name, args, ctx)`.
13
+ - **Three-tier KG scope isolation** — each node carries `owner_agent_id`; scope ∈ `{agent_only, shared_only, both}`; MCP defaults to `agent_only`, trusted local may use `both`. `agentId` is **optional** for `graph_query` / `status` / `doctor` / `init`, falling back to `'default'` (ADR 0068 P0-A reversal).
14
+ - **Layered memory** — short-term / writable self-memory / long-term history; **hybrid search** (FTS + vector + graph).
15
+ - **Observability** — all 10 ops route through `Log.create({ service })` English structured logs; `status` / `doctor` provide offline diagnostics.
16
16
  - **i18n** — `zh-CN` / `en-US` locales; `@easbot/memory` API logs stay English, copy goes through `t()`.
17
17
  - **Portable** — pure TS 6.x; depends on `better-sqlite3` (transitive via `@easbot/database`) + `@easbot/database` (sync facade) + `@easbot/types` / `@easbot/utils` (decision 0036 unified facade; do not directly require `better-sqlite3` / `@modelcontextprotocol/sdk`).
18
18
  - **Three-package unified backend support** (decision 0036 / 0049 / 0051 / 0052): database goes through `@easbot/database` `createSyncSqliteConnection`; MCP goes through `@easbot/mcp` `ToolRegistry` + `createAndStartStdioServer`; CLI output goes through `@easbot/terminal` `printHuman` + `emitJsonOk` + `COMMANDS_HELP` single source of truth.
@@ -25,7 +25,7 @@ pnpm add @easbot/memory
25
25
 
26
26
  ## Usage
27
27
 
28
- ### 9 op entry
28
+ ### 10 op entry
29
29
 
30
30
  ```typescript
31
31
  import { executeOp } from '@easbot/memory';
@@ -89,30 +89,45 @@ await executeOp(
89
89
 
90
90
  ### KG scope three tiers
91
91
 
92
+ > **2026-09-23 PR-2 sync**: the `graph_query` v0.5 schema was simplified (aligned with `note.graph_query`):
93
+ >
94
+ > - The **agent tool main path** accepts only `nodeId` (numeric) + optional `maxEdgesPerNode` (default 20 / max 100)
95
+ > - The 8 fields `query / nodeId / type / depth / maxNodes / scope / relation / maxEdgesPerNode` go through the CLI `easbot memory graph query`
96
+ > - `depth / maxNodes` are hardcoded in the service (depth=2 / maxNodes=100) and not exposed by the agent tool
97
+ > - `scope / type / relation` go through the CLI (fine-grained filtering)
98
+ > - Agent tool `maxEdgesPerNode` fix: the service zod schema `graphQueryParamsSchema` declared this field in PR-2 (its earlier absence caused `.strict()` to reject it → recall/graph_query failures in agent context)
99
+
92
100
  ```typescript
93
- // Only this Agent's nodes (default; MCP entry enforces)
101
+ // Agent tool main path (v0.5+): query neighbors by numeric nodeId
94
102
  await executeOp(
95
103
  'graph_query',
96
- { agentId: 'agent-1', kind: 'nodes', scope: 'agent_only' },
104
+ { nodeId: 12, maxEdgesPerNode: 20 },
105
+ { agentId: 'agent-1', isTrustedLocal: true },
106
+ );
107
+
108
+ // CLI path (v0.4.1+, kept for compatibility): name fuzzy match + scope/type/relation filters
109
+ await executeOp(
110
+ 'graph_query',
111
+ { query: 'TS', scope: 'agent_only', type: 'class', depth: 2 },
97
112
  { agentId: 'agent-1', isTrustedLocal: true },
98
113
  );
99
114
 
100
115
  // Only shared nodes
101
116
  await executeOp(
102
117
  'graph_query',
103
- { agentId: 'agent-1', kind: 'nodes', scope: 'shared_only' },
118
+ { query: 'TS', scope: 'shared_only' },
104
119
  { agentId: 'agent-1', isTrustedLocal: true },
105
120
  );
106
121
 
107
122
  // This Agent + shared (trusted local only; MCP entry rejects)
108
123
  await executeOp(
109
124
  'graph_query',
110
- { agentId: 'agent-1', kind: 'nodes', scope: 'both' },
125
+ { query: 'TS', scope: 'both' },
111
126
  { agentId: 'agent-1', isTrustedLocal: true },
112
127
  );
113
128
 
114
129
  // v0.4.1+: omitting agentId → fallback 'default', global KG view (trusted local only)
115
- await executeOp('graph_query', { kind: 'nodes', scope: 'both' }, { isTrustedLocal: true });
130
+ await executeOp('graph_query', { query: 'TS', scope: 'both' }, { isTrustedLocal: true });
116
131
  ```
117
132
 
118
133
  ### Markdown render
@@ -122,19 +137,20 @@ import { renderOperationMarkdown } from '@easbot/memory';
122
137
  const md = await renderOperationMarkdown('recall', recallResult, { toolName: 'memory_recall' });
123
138
  ```
124
139
 
125
- ## 9 op manifest
126
-
127
- | op | trusted local only | agentId | purpose |
128
- | ------------- | -------------------- | ----------------------------------------- | ------------------------------------------------------------- |
129
- | `recall` | ❌ | ✅ required | Hybrid search (FTS + vector + graph) |
130
- | `remember` | ❌ | ✅ required | Persist a self-memory fact |
131
- | `forget` | ❌ | ✅ required | Delete by factId / category / time window (supports `dryRun`) |
132
- | `extract` | ❌ | ✅ required | Aggregate facts / KG nodes for a sessionId |
133
- | `consolidate` | ✅ | ✅ required | dedup → archive pipeline |
134
- | `graph_query` | ❌ (scope=both → ✅) | ⚠️ optional, defaults to `'default'` | KG nodes / edges / BFS neighbors |
135
- | `status` | ❌ | ⚠️ optional, defaults to global aggregate | System status snapshot |
136
- | `doctor` | ✅ | ⚠️ optional, defaults to whole-DB scan | Data integrity checks (supports `repair`) |
137
- | `init` | ✅ | ⚠️ optional, defaults to `'default'` | Initialize workspace (supports `force`) |
140
+ ## 10 op manifest
141
+
142
+ | op | trusted local only | agentId | purpose |
143
+ | ------------- | -------------------- | ----------------------------------------- | ----------------------------------------------------------------------------- |
144
+ | `recall` | ❌ | ✅ required | Hybrid search (FTS + vector + graph) |
145
+ | `remember` | ❌ | ✅ required | Persist a self-memory fact |
146
+ | `forget` | ❌ | ✅ required | Delete by factId / category / time window (supports `dryRun`) |
147
+ | `extract` | ❌ | ✅ required | Extract facts from a session |
148
+ | `consolidate` | ✅ | ✅ required | Consolidate / dedup / summarize |
149
+ | `sync` | ✅ | ✅ required | db → .md fallback generation (idempotent) + active/ stale-file archival (30d) |
150
+ | `graph_query` | ❌ (scope=both → ✅) | ⚠️ optional, defaults to `'default'` | KG nodes / edges / neighbors queries |
151
+ | `status` | ❌ | ⚠️ optional, defaults to global aggregate | System status snapshot |
152
+ | `doctor` | ✅ | ⚠️ optional, defaults to whole-DB scan | Data integrity checks (supports `repair`) |
153
+ | `init` | ✅ | ⚠️ optional, defaults to `'default'` | Initialize workspace (supports `force`) |
138
154
 
139
155
  **P0-A reversal note** (since v0.4.1):
140
156
 
@@ -144,11 +160,29 @@ Four ops — `graph_query` / `status` / `doctor` / `init` — have made `agentId
144
160
  - `status` without agentId → cross-agent aggregate stats (no longer single-agent view)
145
161
  - `doctor` / `init` without agentId → default agent = `'default'`, aligned with status / graph_query semantics
146
162
 
147
- **Local-only operations** (`consolidate`, `doctor`, `init`) reject non-trusted callers; remote / multi-tenant contexts must not invoke them.
163
+ ### `recall` snippet truncation (2026-10-13)
164
+
165
+ `snippet` is a **truncated copy** for preview only; the full body lives in `hit.content` (decision 0086 v2). Historically `SUBSTR(mf.content, 1, 200)` hardcoded the length in the SQL literal; it is now unified under `@easbot/database`'s source of truth and **pulled back to an internal parameter**:
166
+
167
+ | Layer | Owner | Default | Semantics |
168
+ | ------------------- | ----------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------ |
169
+ | service layer | internal (`RecallParams.snippetMaxChars`) | `2000` (= `SQL_TEXT_LIMIT_MAX`) | **Defense cap** — keeps a single fact from bloating the result set |
170
+ | op schema | **not exposed** | — | LLMs should not decide server-side truncation length; `.strict()` rejects this field |
171
+ | format/render layer | each renderer applies its own `slice` | scenario-specific | **Display decision** — terminal / CLI previews are usually far shorter than the cap |
172
+
173
+ ```typescript
174
+ // Service-internal / programmatic calls may pass it (still clamped)
175
+ await recall(ctx, { query: '...', maxResults: 10, snippetMaxChars: 800 });
176
+
177
+ // LLM / MCP / agent tool passing it fails immediately (unknown field)
178
+ await executeOp('recall', { query: '...', snippetMaxChars: 800 }, ctx); // ❌ throws
179
+ ```
180
+
181
+ **Constraint**: whatever is passed goes through `resolveSqlTextLimit` and is clamped to `[1, SQL_TEXT_LIMIT_MAX]` — **the defense cannot be bypassed**. The default was raised from the hardcoded 200 to 2000: 200 chars is only ≈ 133 tokens in Chinese, not enough information to support a summary (see `@easbot/llm`'s `SummaryProvider` for the summary chain).
148
182
 
149
183
  ## API categories
150
184
 
151
- ### services (9 op business layer)
185
+ ### services (10 op business layer)
152
186
 
153
187
  ```typescript
154
188
  import {
@@ -164,7 +198,7 @@ import {
164
198
  } from '@easbot/memory/services';
165
199
  ```
166
200
 
167
- ### operations (9 op registry + executeOp)
201
+ ### operations (10 op registry + executeOp)
168
202
 
169
203
  ```typescript
170
204
  import { executeOp, OP_REGISTRY, ALL_OPS } from '@easbot/memory/operations';
@@ -176,65 +210,72 @@ import { executeOp, OP_REGISTRY, ALL_OPS } from '@easbot/memory/operations';
176
210
  import { renderOperationMarkdown } from '@easbot/memory/format/render';
177
211
  ```
178
212
 
179
- ### hooks (4 hook types)
180
-
181
- ```typescript
182
- import type {
183
- PreCompactHook,
184
- SessionStartHook,
185
- SessionEndHook,
186
- PostToolFailureHook,
187
- } from '@easbot/memory/hooks';
188
- ```
189
-
190
213
  ### plugin (plugin / hook / tool)
191
214
 
192
215
  `@easbot/memory` ships an installable plugin following the `@easbot/plugin` contract:
193
- 3 lifecycle hooks and 1 `memory` tool. The implementation lives in `src/plugin/`, and
216
+ 4 lifecycle hooks and 1 `memory` tool. The implementation lives in `src/plugin/`, and
194
217
  every symbol is **imported from the package root** (no subpath exports).
195
218
 
219
+ > **Distribution form (2026-11-18 decision)**: the memory plugin does **not** go into the host's `INTERNAL_PLUGINS`;
220
+ > it is installed via marketplace — all 4 hooks (context recall / pre-compaction cleanup /
221
+ > tool-failure fallback / end-of-loop extraction) plus 1 `memory` tool are fully effective.
222
+ > The tool carries its own `isEnabled` (`MemoryCache.exists()` — based solely on L2 config presence);
223
+ > the host only forwards it, and no agent-side module config decides availability any more.
224
+ > Uninstalling the plugin disables memory.
225
+
226
+ > **Session-level events (ADR 0159)**: memory does **not** register `session.start` / `session.end`
227
+ > handlers — session records do not persist the agent identity (`protocolMetadata.agentId` only
228
+ > exists in the LLM-layer `ToolContext`), so those events cannot provide the `agentId` memory needs;
229
+ > registering them would create dangling handlers that never do anything. Session-level memory
230
+ > extraction stays on `loop.end` (end of one conversation turn).
231
+
196
232
  ```typescript
197
233
  import {
198
234
  MemoryPlugin,
199
235
  MEMORY_PLUGIN_MANIFEST,
200
236
  MEMORY_HOOK_EVENTS,
237
+ MEMORY_FRAGMENT_MAX_TOKENS,
201
238
  MemoryPluginHook,
202
239
  createMemoryHookMatchers,
203
240
  MemoryTool,
204
241
  } from '@easbot/memory';
205
242
  ```
206
243
 
207
- | Export | Description |
208
- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
209
- | `MemoryPlugin` / `default` / `Plugin` | Plugin entry, returns `Promise<PluginDefinition>` |
210
- | `MEMORY_PLUGIN_MANIFEST` | Manifest mirroring `plugin.json` (`name` / `version` / `entry` / `capabilities`) |
211
- | `MEMORY_HOOK_EVENTS` | 3 dotted events: `context.build.before` / `session.compacting` / `tool.failure` |
212
- | `MemoryPluginHook` | `HookInfo` shape (host built-in registration path) |
213
- | `createMemoryHookMatchers()` | `HookMatcher[]` shape (plugin registration path) |
214
- | `MemoryTool` | `ToolDefinition`: flat `args` map (`operation` + per-op params), `execute` returns a string |
215
- | `MEMORY_TOOL_OPS` | 7 ops: `recall` / `remember` / `update` / `forget` / `extract` / `graph_query` / `status` |
216
- | `MEMORY_TOOL_ARGS` | Flat parameter schema, field-by-field aligned with the host built-in memory tool |
244
+ | Export | Description |
245
+ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
246
+ | `MemoryPlugin` / `default` / `Plugin` | Plugin entry, returns `Promise<PluginDefinition>` |
247
+ | `MEMORY_PLUGIN_MANIFEST` | Manifest mirroring `plugin.json` (`name` / `version` / `entry` / `capabilities`) |
248
+ | `MEMORY_HOOK_EVENTS` | 4 dotted events: `context.collect` / `session.compacting` / `tool.failure` / `loop.end` (the latter carries long-term memory extraction) |
249
+ | `MEMORY_FRAGMENT_MAX_TOKENS` | **Absolute** cap (`1200` tokens) for the whole rendered fragment — content is rendered in full, then truncated by `TruncateContent` with the full text saved to disk (agent can read it back) |
250
+ | `MemoryPluginHook` | `HookInfo` shape (for hosts that prefer the built-in hook registration path) |
251
+ | `createMemoryHookMatchers()` | `HookMatcher[]` shape (plugin registration path) |
252
+ | `MemoryTool` | `ToolDefinition`: `args` is a **discriminated union** (7 op branches keyed by `operation`), `execute` returns a `ToolResult` (`{ output, title, metadata }`) |
253
+ | `MEMORY_TOOL_OPS` | 7 ops: `recall` / `remember` / `update` / `forget` / `extract` / `graph_query` / `status` |
254
+ | `MEMORY_TOOL_ARGS` | Full parameter schema (`z.discriminatedUnion('operation', [...])`), field-by-field aligned with the host built-in memory tool |
217
255
 
218
256
  #### Tool parameter contract (aligned with the host built-in tool)
219
257
 
220
258
  The plugin tool `args` match the host built-in `packages/agent/src/tool/memory.ts`
221
- field by field: `operation` selects the op, and the remaining flat parameters are
222
- shared across ops (the host `packages/agent/src/plugin/plugin.ts` enforces
223
- `z.object(args)`, so a discriminated union is not available).
224
-
225
- | Op | Effective parameters |
226
- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
227
- | `recall` | `query` (required) / `limit` (default 10, max 100) / `category` / `minImportance` / `maxEdgesPerNode` / `includeGraph` / `includeShared` |
228
- | `remember` | `content` (required) / `category` / `importance` (1-10) / `tags` |
229
- | `update` | `factId` (required) plus at least one of `content` / `category` / `importance` / `tags` |
230
- | `forget` | `factId` (required) / `dryRun` / `force` |
231
- | `extract` | `lastN` (default 10) / `fromMessageId` |
232
- | `graph_query` | `query` or `nodeId` (one required) / `maxDepth` (default 2, max 5) / `maxNodes` (default 100, max 500) / `maxEdgesPerNode` |
233
- | `status` | no extra parameters |
234
-
235
- Op-specific required fields, ranges and mutual exclusions are validated a second
236
- time inside the plugin (`parseOperationParams`); validation failures return a
237
- structured error instead of throwing.
259
+ field by field, and now share its **shape** as well: a discriminated union
260
+ `z.discriminatedUnion('operation', [...])` with one branch per op. Each branch
261
+ declares only that op's parameters and is `.strict()` (undeclared fields are
262
+ rejected). The host (`packages/agent/src/plugin/plugin.ts`) forwards a **full zod
263
+ schema as-is** (it is no longer flattened into a shape map), so per-op required
264
+ fields, ranges and cross-field rules are expressed by the schema itself — no
265
+ secondary validation inside the plugin is needed.
266
+
267
+ | Op | Effective parameters |
268
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
269
+ | `recall` | `query` (required) / `limit` (default 10) / `category` / `minImportance` (1-10, inclusive) / `maxEdgesPerNode` (default 10, 1-100) / `includeGraph` / `includeShared` |
270
+ | `remember` | `content` (required) / `category` (required) / `importance` (required, 1-10) / `tags` |
271
+ | `update` | `factId` (required) plus at least one of `content` / `category` / `importance` / `tags` |
272
+ | `forget` | `factId` (required) / `dryRun` (default false) / `force` (default false) |
273
+ | `extract` | `lastN` (default 10) / `fromMessageId` |
274
+ | `graph_query` | `query` (required, node name fragment) / `maxDepth` (default 2) / `maxNodes` (default 100) / `maxEdgesPerNode` (default 10) / `relation` / `type` |
275
+ | `status` | no extra parameters |
276
+
277
+ Tool return values are uniformly `ToolResult` (`{ output, title, metadata }`): `output` goes back
278
+ to the model, while `title` / `metadata` are consumed by the host UI and statistics.
238
279
 
239
280
  #### Distribution artifact generation
240
281
 
@@ -314,6 +355,7 @@ easbot-memory remember --content <text> --category <c> --importance <1-10>
314
355
  easbot-memory forget [--fact-id <id>] [--dry-run]
315
356
  easbot-memory extract --session <sessionId> [--last-n <n>]
316
357
  easbot-memory consolidate [--window-days <n>]
358
+ easbot-memory sync [--window-days <n>] [--dry-run] [--json]
317
359
  easbot-memory graph [--query <q>] [--node-id <id>]
318
360
  easbot-memory config [--json]
319
361
  easbot-memory mcp
@@ -444,22 +486,22 @@ easbot memory mcp # starts MCP stdio server
444
486
  ```typescript
445
487
  import { MemoryStdioServer } from '@easbot/memory';
446
488
 
447
- // Start 9 tool MCP stdio server (callable by Cline / Claude Code / Continue)
448
- // v0.4.0: start signature simplified — no `system` param needed (handlers dispatch via executeOp)
489
+ // Start the 10-tool MCP stdio server (callable by Cline / Claude Code / Continue)
490
+ // v0.4.0: start signature simplified — no `memorySystem` param needed (handlers dispatch via executeOp)
449
491
  await MemoryStdioServer.start({
450
492
  name: 'easbot-memory',
451
493
  version: '0.4.0',
452
494
  description: 'EASBot memory MCP server',
453
495
  });
454
496
 
455
- // List 9 tool names
497
+ // List the 10 tool names (ADR 0069 +1 sync)
456
498
  const tools = MemoryStdioServer.getToolNames();
457
- // ['memory_recall', 'memory_remember', 'memory_forget', ...]
499
+ // ['memory_recall', 'memory_remember', 'memory_forget', 'memory_extract', 'memory_consolidate', 'memory_sync', 'memory_graph_query', 'memory_status', 'memory_doctor', 'memory_init']
458
500
  ```
459
501
 
460
- **9 tool manifest** (1:1 with `OP_REGISTRY`):
502
+ **10 tool manifest** (1:1 with `OP_REGISTRY`):
461
503
 
462
- - `memory_recall` / `memory_remember` / `memory_forget` / `memory_extract` / `memory_consolidate` / `memory_graph_query` / `memory_status` / `memory_doctor` / `memory_init`
504
+ - `memory_recall` / `memory_remember` / `memory_forget` / `memory_extract` / `memory_consolidate` / `memory_sync` / `memory_graph_query` / `memory_status` / `memory_doctor` / `memory_init`
463
505
 
464
506
  ### handleMemoryCli delegation
465
507
 
@@ -487,16 +529,17 @@ After `remember` commits the db transaction, it **best-effort** renders the fact
487
529
  - Future integration: `note` tool may watch memory .md changes for cross-reference updates
488
530
  - Resilience: file IO failure **never blocks** db writes (consistent with v0.3)
489
531
 
490
- ### Path schema
532
+ ### Path schema (v0.5.1+ feedback fix)
491
533
 
492
534
  ```
493
- {workspaceDir}/.easbot/knowledge/memory/{category}/{YYYY-MM}/mem_{id}.md
535
+ {workspaceDir}/.easbot/memory/active/{category}/{YYYY-MM-DD}.md
494
536
  ```
495
537
 
496
538
  - One directory per **category** (`task_context` / `workflow` / `user_preference` / ...)
497
- - One directory per **createdAt month** (avoid packing too many files per month)
498
- - File name = `fact.id` (globally unique)
539
+ - One file per **createdAt local date** (one file per day, append mode, shared by multiple facts)
540
+ - File name = `{YYYY-MM-DD}.md` (no longer contains fact.id)
499
541
  - `memory_facts.file_path` stores a **workspaceDir-relative POSIX path**
542
+ - Archive path (ADR 0069 sync): `{workspaceDir}/.easbot/memory/archive/{YYYY-MM}/{category}/{YYYY-MM-DD}.md` (flat structure)
500
543
 
501
544
  ### Markdown template
502
545
 
@@ -554,16 +597,16 @@ Default storage: `$XDG_DATA_HOME/easbot/memory.db`
554
597
 
555
598
  ## Decisions and migration
556
599
 
600
+ - ADR 0069 (v0.5+ memory sync op: two-stage pipeline — idempotent db → .md fallback generation + active/ stale archival): `docs/decisions/0069-memory-sync-op.md`
557
601
  - ADR 0068 (v0.4.1 P0-A reversal: agentId becomes optional for `graph_query` / `status` / `doctor` / `init`, defaulting to `'default'`): `docs/decisions/0068-p0a-agent-id-optional.md`
558
602
  - ADR 0060 (v0.5+ fact → .md sync restoration): `docs/decisions/0060-memory-fact-file-sync-restore.md`
559
- - ADR 0055 / 0056 / 0057 (v0.4 decisions): `docs/decisions/00NN-*.md`
560
- - v0.4 cleanup log: `.easbot/knowledge/tasks/memory-v04-refactor/`
561
- - Migration script: `pnpm migrate:v04` (BC-01 ~ BC-12 dry-run + apply)
603
+ - ADR 0055 / 0056 / 0057 (v0.4 decisions): `.easbot/protocol.json` and `docs/decisions/00NN-*.md`
604
+ - Migration scripts: `scripts/migrate/{scan,apply,review}.ts` + `scripts/db-backup.ts` (v0.3 → v0.4 `owner_agent_id` column + default scope = agent_only)
562
605
  - CI guards (v0.4 stage 5 three-package unified backend support):
563
606
  - `scripts/check-database-facade.sh` (forbid directly requiring `better-sqlite3` / `node:sqlite` / `createRequire`)
564
607
  - `scripts/check-mcp-facade.sh` (forbid directly importing `@modelcontextprotocol/sdk`)
565
608
  - `scripts/check-terminal-facade.sh` (CLI output goes through `@easbot/terminal` + `COMMANDS_HELP` single source of truth)
566
- - `scripts/check-cmd-i18n-coverage.sh` (zh-CN / / en-US dual-locale consistency + switch-case routing validation)
609
+ - `scripts/check-cmd-i18n-coverage.sh` (zh-CN / en-US dual-locale consistency + switch-case routing validation)
567
610
  - L-M13 / L-M14 / L-M15 lessons: `.easbot/knowledge/tasks/memory-v04-refactor/findings.md`
568
611
 
569
612
  ## Development
package/README.md CHANGED
@@ -6,7 +6,7 @@ EASBOT 生态系统的长期记忆管理库(v0.4.0)。提供分层记忆、K
6
6
 
7
7
  ## 版本
8
8
 
9
- v0.3.37
9
+ v0.3.39
10
10
  ## 特性(v0.4.0)
11
11
 
12
12
  - **10 op 统一入口**(ADR 0069 +1 sync):`recall / remember / forget / extract / consolidate / sync / graph_query / status / doctor / init`,MCP / CLI / Agent Tool 三端共享。
@@ -25,7 +25,7 @@ pnpm add @easbot/memory
25
25
 
26
26
  ## 使用示例
27
27
 
28
- ### 9 op 入口
28
+ ### 10 op 入口
29
29
 
30
30
  ```typescript
31
31
  import { executeOp } from '@easbot/memory';
@@ -137,7 +137,7 @@ import { renderOperationMarkdown } from '@easbot/memory';
137
137
  const md = await renderOperationMarkdown('recall', recallResult, { toolName: 'memory_recall' });
138
138
  ```
139
139
 
140
- ## 9 op 清单
140
+ ## 10 op 清单
141
141
 
142
142
  | op | trusted local only | agentId | 用途 |
143
143
  | ------------- | --------------------- | ----------------------------- | ------------------------------------------------------------- |
@@ -202,49 +202,64 @@ import { renderOperationMarkdown } from '@easbot/memory/format/render';
202
202
 
203
203
  ### 插件(plugin / hook / tool)
204
204
 
205
- `@easbot/memory` 按 `@easbot/plugin` 契约提供可安装插件:3 个生命周期 hook 与 1 个 `memory` 工具。
205
+ `@easbot/memory` 按 `@easbot/plugin` 契约提供可安装插件:4 个生命周期 hook 与 1 个 `memory` 工具。
206
206
  实现位于 `src/plugin/`,所有符号**统一从包根入口导入**(不提供 subpath 导出)。
207
207
 
208
+ > **分发形态(2026-11-18 决策)**:memory 插件**不进宿主 `INTERNAL_PLUGINS`**,走 marketplace 安装 ——
209
+ > 4 个 hook(上下文召回 / 压缩前整理 / 工具失败兜底 / 一轮对话结束提炼)+ 1 个 `memory` 工具全量生效。
210
+ > 工具自带 `isEnabled`(`MemoryCache.exists()` —— 只看 L2 配置是否存在),宿主仅透传,
211
+ > 不再由 agent 侧模块配置决定;卸载插件即关闭记忆能力。
212
+
213
+ > **会话级事件的取舍(ADR 0159)**:memory **不**注册 `session.start` / `session.end` handler ——
214
+ > 会话记录不持久化 agent 身份(`protocolMetadata.agentId` 只存在于 LLM 层 `ToolContext`),
215
+ > 这两个事件拿不到 memory 所需的 `agentId`,注册即为悬空 handler(运行时恒定空跑)。
216
+ > 会话级的记忆固化继续由 `loop.end`(一轮对话结束)承担。
217
+
208
218
  ```typescript
209
219
  import {
210
220
  MemoryPlugin,
211
221
  MEMORY_PLUGIN_MANIFEST,
212
222
  MEMORY_HOOK_EVENTS,
223
+ MEMORY_FRAGMENT_MAX_TOKENS,
213
224
  MemoryPluginHook,
214
225
  createMemoryHookMatchers,
215
226
  MemoryTool,
216
227
  } from '@easbot/memory';
217
228
  ```
218
229
 
219
- | 导出 | 说明 |
220
- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
221
- | `MemoryPlugin` / `default` / `Plugin` | 插件入口,返回 `Promise<PluginDefinition>` |
222
- | `MEMORY_PLUGIN_MANIFEST` | `plugin.json` 对应的清单(`name` / `version` / `entry` / `capabilities`) |
223
- | `MEMORY_HOOK_EVENTS` | 3 个点分事件:`context.build.before` / `session.compacting` / `tool.failure` |
224
- | `MemoryPluginHook` | `HookInfo` 形态(宿主内置注册路径) |
225
- | `createMemoryHookMatchers()` | `HookMatcher[]` 形态(插件注册路径) |
226
- | `MemoryTool` | `ToolDefinition`:`args` 为扁平 map(`operation` + 各 op 参数),`execute` 返回字符串 |
227
- | `MEMORY_TOOL_OPS` | 7 个 op:`recall` / `remember` / `update` / `forget` / `extract` / `graph_query` / `status` |
228
- | `MEMORY_TOOL_ARGS` | 扁平参数 schema(与宿主内置 memory 工具逐字段对齐) |
230
+ | 导出 | 说明 |
231
+ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
232
+ | `MemoryPlugin` / `default` / `Plugin` | 插件入口,返回 `Promise<PluginDefinition>` |
233
+ | `MEMORY_PLUGIN_MANIFEST` | `plugin.json` 对应的清单(`name` / `version` / `entry` / `capabilities`) |
234
+ | `MEMORY_HOOK_EVENTS` | 4 个点分事件:`context.collect` / `session.compacting` / `tool.failure` / `loop.end`(`loop.end` 承载长期记忆提炼) |
235
+ | `MEMORY_FRAGMENT_MAX_TOKENS` | memory 片段整体渲染的绝对上限(`1200` token)—— 全量渲染后交 `TruncateContent` 整体截断,超限完整内容落盘(agent 可读回) |
236
+ | `MemoryPluginHook` | `HookInfo` 形态(供偏好 builtin hook 注册路径的宿主使用) |
237
+ | `createMemoryHookMatchers()` | `HookMatcher[]` 形态(插件注册路径) |
238
+ | `MemoryTool` | `ToolDefinition`:`args` 为 **discriminated union**(按 `operation` 判别 7 个 op 分支),`execute` 返回 `ToolResult`(`{ output, title, metadata }`) |
239
+ | `MEMORY_TOOL_OPS` | 7 个 op:`recall` / `remember` / `update` / `forget` / `extract` / `graph_query` / `status` |
240
+ | `MEMORY_TOOL_ARGS` | 完整参数 schema(`z.discriminatedUnion('operation', [...])`,与宿主内置 memory 工具逐字段对齐) |
229
241
 
230
242
  #### 工具参数契约(对齐宿主内置工具)
231
243
 
232
- 插件工具的 `args` 与宿主内置 `packages/agent/src/tool/memory.ts` **逐字段一致**:
233
- `operation` 决定本次调用的 op,其余参数按 op 语义共享(扁平 map,宿主
234
- `packages/agent/src/plugin/plugin.ts` 会强制 `z.object(args)`,不支持判别联合)。
235
-
236
- | op | 生效参数 |
237
- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
238
- | `recall` | `query`(必填)/ `limit`(默认 10,上限 100)/ `category` / `minImportance` / `maxEdgesPerNode` / `includeGraph` / `includeShared` |
239
- | `remember` | `content`(必填)/ `category` / `importance`(1-10)/ `tags` |
240
- | `update` | `factId`(必填)+ `content` / `category` / `importance` / `tags`(至少一项) |
241
- | `forget` | `factId`(必填)/ `dryRun` / `force` |
242
- | `extract` | `lastN`(默认 10)/ `fromMessageId` |
243
- | `graph_query` | `query` 或 `nodeId`(二者其一必填)/ `maxDepth`(默认 2,上限 5)/ `maxNodes`(默认 100,上限 500)/ `maxEdgesPerNode` |
244
- | `status` | 无额外参数 |
245
-
246
- op 专属的必填 / 取值范围 / 互斥约束由插件侧做**二次校验**(`parseOperationParams`),
247
- 校验失败返回结构化错误而非抛异常。
244
+ 插件工具的 `args` 与宿主内置 `packages/agent/src/tool/memory.ts` **逐字段一致**,
245
+ 且**形态同为判别联合**:`z.discriminatedUnion('operation', [...])`,每个 op 一个分支,
246
+ 分支内只声明该 op 的参数(`.strict()` 拒绝未声明字段)。宿主
247
+ `packages/agent/src/plugin/plugin.ts` 对**完整 zod schema 原样下发**(不再压平成扁平
248
+ shape map),因此 per-op 的必填 / 取值范围 / 跨字段约束**由 schema 直接表达**,
249
+ 无需插件侧二次校验。
250
+
251
+ | op | 生效参数 |
252
+ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
253
+ | `recall` | `query`(必填)/ `limit`(默认 10)/ `category` / `minImportance`(1-10,闭区间)/ `maxEdgesPerNode`(默认 10,1-100)/ `includeGraph` / `includeShared` |
254
+ | `remember` | `content`(必填)/ `category`(必填)/ `importance`(必填,1-10)/ `tags` |
255
+ | `update` | `factId`(必填)+ `content` / `category` / `importance` / `tags`(至少一项) |
256
+ | `forget` | `factId`(必填)/ `dryRun` / `force` |
257
+ | `extract` | `lastN`(默认 10)/ `fromMessageId` |
258
+ | `graph_query` | `query`(必填,节点名片段)/ `maxDepth`(默认 2)/ `maxNodes`(默认 100)/ `maxEdgesPerNode`(默认 10)/ `relation` / `type` |
259
+ | `status` | 无额外参数 |
260
+
261
+ 工具返回值统一为 `ToolResult`(`{ output, title, metadata }`):`output` 回传模型,
262
+ `title` / `metadata` 供宿主 UI 与统计消费。
248
263
 
249
264
  #### 分发产物自动生成
250
265
 
@@ -1 +1 @@
1
- import {f}from'./chunk-HX3TV7FD.mjs';import {Log,errorMeta}from'@easbot/utils';import {renderLines,printHuman,emitJsonError,emitJsonOk,formatKnowledgeDoctor,formatKnowledgeStatus,formatKnowledgeInit}from'@easbot/terminal';var w=Log.create({service:"memory.cli"}),v=[{i18nKey:"cli.cmd.init.description",name:"init",description:"Initialize memory workspace (.easbot/memory.db)",group:"lifecycle"},{i18nKey:"cli.cmd.status.description",name:"status",description:"Show memory state / db stats / facts by category",group:"lifecycle"},{i18nKey:"cli.cmd.doctor.description",name:"doctor",description:"Run health checks (backend, FTS, schema, lock)",group:"lifecycle"},{i18nKey:"cli.cmd.recall.description",name:"recall",description:"Hybrid search (FTS + vector) over memory facts",group:"memory"},{i18nKey:"cli.cmd.remember.description",name:"remember",description:"Persist a new memory fact (with dedup + KG extraction)",group:"memory"},{i18nKey:"cli.cmd.forget.description",name:"forget",description:"Delete memory facts (factId / category / timeRange / dryRun)",group:"memory"},{i18nKey:"cli.cmd.sync.description",name:"sync",description:"Sync facts to .md files (idempotent) and archive expired active files (default 30 days)",group:"memory"},{i18nKey:"cli.cmd.extract.description",name:"extract",description:"Extract facts from a session (sessionId + lastN)",group:"session"},{i18nKey:"cli.cmd.consolidate.description",name:"consolidate",description:"Run consolidation pipeline (extract \u2192 dedup \u2192 archive)",group:"session"},{i18nKey:"cli.cmd.graph.description",name:"graph",description:"KG query (nodes / edges / neighbors with scope \u4E09\u6863)",group:"graph"},{i18nKey:"cli.cmd.config.description",name:"config",description:"Show / validate memory configuration (dry-read)",group:"external"},{i18nKey:"cli.cmd.mcp.description",name:"mcp",description:"Start stdio MCP server (exposes 10 memory tools)",group:"external"}];function g(l,t){let e=v.filter(s=>s.group===l);return renderLines({title:t,flat:e.map(s=>`$ easbot-memory ${s.name.padEnd(14)} ${s.description}`)})}function j(){let l=[renderLines({title:"easbot-memory \xB7 Memory & Knowledge Module for EASBot",flat:["Usage: easbot-memory <command> [options]"]}),"",g("lifecycle","Commands (lifecycle):"),"",g("memory","Commands (memory):"),"",g("session","Commands (session):"),"",g("graph","Commands (graph query):"),"",g("external","External:")];printHuman(l);}function C(){j(),printHuman(["",renderLines({title:"Global flags & invocation",flat:["--cwd <dir> --config <path> --log-level <L> --print-logs --debug","Standalone CLI: easbot-memory <command>","Agent CLI: easbot memory <command>"]})]);}async function M(){try{let{Llm:l}=await import('./llm-BRSMYENV.mjs'),{MemoryCache:t}=await import('./cache-U5YYUDWO.mjs'),e=await t.getMemoryJson();l.init({models:{embedding:e?.embedding_model??void 0,graph:e?.graph_model??void 0}});}catch(l){w.warn("Llm init failed; Llm-related features will be disabled",{error:errorMeta(l)});}}async function U(l,t){let [e,...s]=l;t?.cwd??process.cwd();let c=t?.agentId??"default";if(!e)return C(),{code:0,handled:true,command:null};await M();let m=s.includes("--json");try{switch(e){case "init":{let{parseInitOptions:i,runInit:a}=await import('./init-HWR4SD6N.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory init [--force] [--json]"),{code:0,handled:!0,command:e};let o=await a({...n,agentId:c});if(n.json)emitJsonOk(o,{command:e});else {let r=o;printHuman([formatKnowledgeInit({packageName:"memory",configPath:r.configPath??r.dbPath,backend:"better-sqlite3",schemaVersion:r.schemaVersion,extras:{dbPath:r.dbPath,migrationsApplied:r.migrationsApplied,tablesCreated:r.tablesCreated,durationMs:`${r.durationMs}ms`}})],{title:"init memory workspace",boxed:!0});}return {code:0,handled:!0,command:e}}case "recall":{let{parseRecallOptions:i,runRecall:a,formatRecallText:n}=await import('./recall-BRXHJPR4.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory recall --query <q> [--limit <n>] [--category <c>] [--min-importance <n>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:`recall (agentId=${c??"default"})`}),{code:0,handled:!0,command:e}}case "remember":{let{parseRememberOptions:i,runRemember:a,formatRememberText:n}=await import('./remember-3XSYCWKK.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory remember --content <text> --category <c> --importance <1-10> [--tag <t>] [--session <s>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"remember (persist fact)"}),{code:0,handled:!0,command:e}}case "forget":{let{parseForgetOptions:i,runForget:a,formatForgetText:n}=await import('./forget-NIBBY6FG.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory forget (--fact-id <id> | --category <c> | --from <ISO> --to <ISO>) [--max-delete <n>] [--dry-run] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"forget (delete facts)"}),{code:0,handled:!0,command:e}}case "extract":{let{parseExtractOptions:i,runExtract:a,formatExtractText:n}=await import('./extract-AJY2ETKE.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory extract --session <sessionId> [--last-n <n>] [--from-msg <id>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"extract (from session)"}),{code:0,handled:!0,command:e}}case "consolidate":{let{parseConsolidateOptions:i,runConsolidate:a,formatConsolidateText:n}=await import('./consolidate-OOAMW7XW.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory consolidate [--window-days <n>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"consolidate (pipeline)"}),{code:0,handled:!0,command:e}}case "sync":{let{parseSyncOptions:i,runSync:a,formatSyncText:n}=await import('./sync-EE4ZD3WB.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory sync [--window-days <n>] [--dry-run] [--json]"),console.log("Two-stage pipeline: (A) db \u2192 .md (idempotent skip on existing), (B) archive active/ files older than windowDays."),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"sync (db \u2192 .md + archive)"}),{code:0,handled:!0,command:e}}case "graph":{let{parseGraphOptions:i,runGraph:a,formatGraphText:n}=await import('./graph-4K56ZAVL.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory graph [--query <q>] [--node-id <id>] [--max-depth <n>] [--max-nodes <n>] [--max-edges-per-node <n>] [--json]\n (note: `--depth` is an alias for `--max-depth`; old `--kind` / `--start-node` / `--scope` flags removed since service schema is strict)"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"graph_query"}),{code:0,handled:!0,command:e}}case "status":{let{parseStatusOptions:i,runStatus:a}=await import('./status-SW5BUHJ3.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory status [--json]"),{code:0,handled:!0,command:e};let o=await a({...n,agentId:c});return n.json?emitJsonOk(o,{command:e}):printHuman([formatKnowledgeStatus(K(o))],{title:"memory status",boxed:!0}),{code:0,handled:!0,command:e}}case "doctor":{let{parseDoctorOptions:i,runDoctor:a}=await import('./doctor-ZGHICE2Q.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory doctor [--repair] [--json]"),{code:0,handled:!0,command:e};let o=await a({...n});return n.json?emitJsonOk(o,{command:e}):printHuman([formatKnowledgeDoctor(R(o))],{title:"memory doctor",boxed:!0}),{code:0,handled:!0,command:e}}case "config":{let{parseConfigOptions:i,runConfig:a,formatConfigText:n}=await import('./config-5P7O45FH.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory config [--json]"),{code:0,handled:!0,command:e};let r=a(o);return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"memory config"}),{code:0,handled:!0,command:e}}case "mcp":{let{parseMcpOptions:i,runMcp:a}=await import('./mcp-ZWZYH52C.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory mcp [start]"),console.log("Start a stdio MCP server exposing 10 memory tools:"),console.log(" recall / remember / forget / extract / consolidate"),console.log(" graph_query / status / doctor / init / sync"),{code:0,handled:!0,command:e};let o=await a(n);return n.json?emitJsonOk(o,{command:e}):printHuman([`memory mcp started (tools: ${o.tools.length})`],{title:"memory mcp server"}),{code:0,handled:!0,command:e}}default:return m?emitJsonError(e??"__unknown__",`Unknown command: ${e}`):(console.error(`Unknown command: ${e}`),console.error("Run `easbot-memory --help` for available commands.")),{code:2,handled:!1,command:null}}}catch(i){let a=errorMeta(i);w.error("memory CLI command failed",{command:e,error:a});let n=t?.cwd??f().worktree;return m?emitJsonError(e??"__unknown__",a.message):console.error(`[memory] ${n} :: ${e} failed: ${a.message}`),{code:1,handled:true,command:e}}}function K(l){let t=l;return {packageName:"memory",rootDir:t.workspaceDir??"",configPath:t.configPath??"",configExists:typeof t.configExists=="boolean"?t.configExists:true,dbPath:t.dbPath??"",dbExists:typeof t.dbExists=="boolean"?t.dbExists:true,dbSize:typeof t.dbSize=="number"?t.dbSize:void 0,indexState:t.indexState,schemaVersion:typeof t.schemaVersion=="number"?t.schemaVersion:void 0,extractionVersion:typeof t.extractionVersion=="number"?t.extractionVersion:void 0,lastSyncAt:t.lastSyncAt,vectorEnabled:typeof t.vectorEnabled=="boolean"?t.vectorEnabled:void 0,embeddingDims:typeof t.embeddingDims=="number"?t.embeddingDims:void 0,llm:t.llm??{initialized:false,capabilities:{}},backend:t.backend,healthy:typeof t.healthy=="boolean"?t.healthy:true,recommendation:t.recommendation,dbStats:(()=>{let e=t.dbStats;if(e&&typeof e=="object"&&Object.keys(e).length>0)return {...e};let s=t.integrityStats;if(s&&typeof s=="object"&&Object.keys(s).length>0)return {...s}})(),extras:(()=>{let e={};if(typeof t.agentId=="string"&&(e.agent_id=t.agentId),typeof t.ftsAvailable=="boolean"&&(e.fts_available=t.ftsAvailable?"yes":"no"),t.factsByCategory&&typeof t.factsByCategory=="object"){let s=t.factsByCategory;for(let[u,c]of Object.entries(s))typeof c=="number"&&c>0&&(e[`facts/${u}`]=c);}if(t.meta&&typeof t.meta=="object")for(let[s,u]of Object.entries(t.meta))e[`meta/${s}`]=u===void 0?"\u2205":u;return Object.keys(e).length>0?e:void 0})()}}function R(l){let t=l,e=Array.isArray(t.checks)?t.checks:[],s=t.integrityStats,u=t.backendAvailable,c=s?{...s}:void 0;return {packageName:"memory",healthy:typeof t.healthy=="boolean"?t.healthy:false,durationMs:typeof t.durationMs=="number"?t.durationMs:0,checks:e.map(m=>({code:typeof m.code=="string"?m.code:"",severity:m.severity??"info",name:typeof m.name=="string"?m.name:"",message:typeof m.message=="string"?m.message:"",durationMs:typeof m.durationMs=="number"?m.durationMs:void 0,details:m.details})),dbStats:c,backendAvailable:u}}export{v as a,j as b,C as c,U as d,R as e};
1
+ import {f}from'./chunk-HX3TV7FD.mjs';import {Log,errorMeta}from'@easbot/utils';import {renderLines,printHuman,emitJsonError,emitJsonOk,formatKnowledgeDoctor,formatKnowledgeStatus,formatKnowledgeInit}from'@easbot/terminal';var w=Log.create({service:"memory.cli"}),v=[{i18nKey:"cli.cmd.init.description",name:"init",description:"Initialize memory workspace (.easbot/memory.db)",group:"lifecycle"},{i18nKey:"cli.cmd.status.description",name:"status",description:"Show memory state / db stats / facts by category",group:"lifecycle"},{i18nKey:"cli.cmd.doctor.description",name:"doctor",description:"Run health checks (backend, FTS, schema, lock)",group:"lifecycle"},{i18nKey:"cli.cmd.recall.description",name:"recall",description:"Hybrid search (FTS + vector) over memory facts",group:"memory"},{i18nKey:"cli.cmd.remember.description",name:"remember",description:"Persist a new memory fact (with dedup + KG extraction)",group:"memory"},{i18nKey:"cli.cmd.forget.description",name:"forget",description:"Delete memory facts (factId / category / timeRange / dryRun)",group:"memory"},{i18nKey:"cli.cmd.sync.description",name:"sync",description:"Sync facts to .md files (idempotent) and archive expired active files (default 30 days)",group:"memory"},{i18nKey:"cli.cmd.extract.description",name:"extract",description:"Extract facts from a session (sessionId + lastN)",group:"session"},{i18nKey:"cli.cmd.consolidate.description",name:"consolidate",description:"Run consolidation pipeline (extract \u2192 dedup \u2192 archive)",group:"session"},{i18nKey:"cli.cmd.graph.description",name:"graph",description:"KG query (nodes / edges / neighbors with scope \u4E09\u6863)",group:"graph"},{i18nKey:"cli.cmd.config.description",name:"config",description:"Show / validate memory configuration (dry-read)",group:"external"},{i18nKey:"cli.cmd.mcp.description",name:"mcp",description:"Start stdio MCP server (exposes 10 memory tools)",group:"external"}];function g(l,t){let e=v.filter(s=>s.group===l);return renderLines({title:t,flat:e.map(s=>`$ easbot-memory ${s.name.padEnd(14)} ${s.description}`)})}function j(){let l=[renderLines({title:"easbot-memory \xB7 Memory & Knowledge Module for EASBot",flat:["Usage: easbot-memory <command> [options]"]}),"",g("lifecycle","Commands (lifecycle):"),"",g("memory","Commands (memory):"),"",g("session","Commands (session):"),"",g("graph","Commands (graph query):"),"",g("external","External:")];printHuman(l);}function C(){j(),printHuman(["",renderLines({title:"Global flags & invocation",flat:["--cwd <dir> --config <path> --log-level <L> --print-logs --debug","Standalone CLI: easbot-memory <command>","Agent CLI: easbot memory <command>"]})]);}async function M(){try{let{Llm:l}=await import('./llm-BRSMYENV.mjs'),{MemoryCache:t}=await import('./cache-U5YYUDWO.mjs'),e=await t.getMemoryJson();l.init({models:{embedding:e?.embedding_model??void 0,graph:e?.graph_model??void 0}});}catch(l){w.warn("Llm init failed; Llm-related features will be disabled",{error:errorMeta(l)});}}async function U(l,t){let [e,...s]=l;t?.cwd??process.cwd();let c=t?.agentId??"default";if(!e)return C(),{code:0,handled:true,command:null};await M();let m=s.includes("--json");try{switch(e){case "init":{let{parseInitOptions:i,runInit:a}=await import('./init-M5CEJUEY.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory init [--force] [--json]"),{code:0,handled:!0,command:e};let o=await a({...n,agentId:c});if(n.json)emitJsonOk(o,{command:e});else {let r=o;printHuman([formatKnowledgeInit({packageName:"memory",configPath:r.configPath??r.dbPath,backend:"better-sqlite3",schemaVersion:r.schemaVersion,extras:{dbPath:r.dbPath,migrationsApplied:r.migrationsApplied,tablesCreated:r.tablesCreated,durationMs:`${r.durationMs}ms`}})],{title:"init memory workspace",boxed:!0});}return {code:0,handled:!0,command:e}}case "recall":{let{parseRecallOptions:i,runRecall:a,formatRecallText:n}=await import('./recall-ZEDO4S5I.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory recall --query <q> [--limit <n>] [--category <c>] [--min-importance <n>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:`recall (agentId=${c??"default"})`}),{code:0,handled:!0,command:e}}case "remember":{let{parseRememberOptions:i,runRemember:a,formatRememberText:n}=await import('./remember-TEAHLG4E.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory remember --content <text> --category <c> --importance <1-10> [--tag <t>] [--session <s>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"remember (persist fact)"}),{code:0,handled:!0,command:e}}case "forget":{let{parseForgetOptions:i,runForget:a,formatForgetText:n}=await import('./forget-2OAYPXCB.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory forget (--fact-id <id> | --category <c> | --from <ISO> --to <ISO>) [--max-delete <n>] [--dry-run] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"forget (delete facts)"}),{code:0,handled:!0,command:e}}case "extract":{let{parseExtractOptions:i,runExtract:a,formatExtractText:n}=await import('./extract-XT6HBENH.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory extract --session <sessionId> [--last-n <n>] [--from-msg <id>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"extract (from session)"}),{code:0,handled:!0,command:e}}case "consolidate":{let{parseConsolidateOptions:i,runConsolidate:a,formatConsolidateText:n}=await import('./consolidate-JMXYI3NF.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory consolidate [--window-days <n>] [--json]"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"consolidate (pipeline)"}),{code:0,handled:!0,command:e}}case "sync":{let{parseSyncOptions:i,runSync:a,formatSyncText:n}=await import('./sync-2D3E4DPE.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory sync [--window-days <n>] [--dry-run] [--json]"),console.log("Two-stage pipeline: (A) db \u2192 .md (idempotent skip on existing), (B) archive active/ files older than windowDays."),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"sync (db \u2192 .md + archive)"}),{code:0,handled:!0,command:e}}case "graph":{let{parseGraphOptions:i,runGraph:a,formatGraphText:n}=await import('./graph-2AL2R3KO.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory graph [--query <q>] [--node-id <id>] [--max-depth <n>] [--max-nodes <n>] [--max-edges-per-node <n>] [--json]\n (note: `--depth` is an alias for `--max-depth`; old `--kind` / `--start-node` / `--scope` flags removed since service schema is strict)"),{code:0,handled:!0,command:e};let r=await a({...o,agentId:c});return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"graph_query"}),{code:0,handled:!0,command:e}}case "status":{let{parseStatusOptions:i,runStatus:a}=await import('./status-BGRJ224S.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory status [--json]"),{code:0,handled:!0,command:e};let o=await a({...n,agentId:c});return n.json?emitJsonOk(o,{command:e}):printHuman([formatKnowledgeStatus(K(o))],{title:"memory status",boxed:!0}),{code:0,handled:!0,command:e}}case "doctor":{let{parseDoctorOptions:i,runDoctor:a}=await import('./doctor-3W3MVUZF.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory doctor [--repair] [--json]"),{code:0,handled:!0,command:e};let o=await a({...n});return n.json?emitJsonOk(o,{command:e}):printHuman([formatKnowledgeDoctor(R(o))],{title:"memory doctor",boxed:!0}),{code:0,handled:!0,command:e}}case "config":{let{parseConfigOptions:i,runConfig:a,formatConfigText:n}=await import('./config-5P7O45FH.mjs'),o=i(s);if(o.help)return console.log("Usage: easbot-memory config [--json]"),{code:0,handled:!0,command:e};let r=a(o);return o.json?emitJsonOk(r,{command:e}):printHuman([n(r)],{title:"memory config"}),{code:0,handled:!0,command:e}}case "mcp":{let{parseMcpOptions:i,runMcp:a}=await import('./mcp-OWOAIP2Z.mjs'),n=i(s);if(n.help)return console.log("Usage: easbot-memory mcp [start]"),console.log("Start a stdio MCP server exposing 10 memory tools:"),console.log(" recall / remember / forget / extract / consolidate"),console.log(" graph_query / status / doctor / init / sync"),{code:0,handled:!0,command:e};let o=await a(n);return n.json?emitJsonOk(o,{command:e}):printHuman([`memory mcp started (tools: ${o.tools.length})`],{title:"memory mcp server"}),{code:0,handled:!0,command:e}}default:return m?emitJsonError(e??"__unknown__",`Unknown command: ${e}`):(console.error(`Unknown command: ${e}`),console.error("Run `easbot-memory --help` for available commands.")),{code:2,handled:!1,command:null}}}catch(i){let a=errorMeta(i);w.error("memory CLI command failed",{command:e,error:a});let n=t?.cwd??f().worktree;return m?emitJsonError(e??"__unknown__",a.message):console.error(`[memory] ${n} :: ${e} failed: ${a.message}`),{code:1,handled:true,command:e}}}function K(l){let t=l;return {packageName:"memory",rootDir:t.workspaceDir??"",configPath:t.configPath??"",configExists:typeof t.configExists=="boolean"?t.configExists:true,dbPath:t.dbPath??"",dbExists:typeof t.dbExists=="boolean"?t.dbExists:true,dbSize:typeof t.dbSize=="number"?t.dbSize:void 0,indexState:t.indexState,schemaVersion:typeof t.schemaVersion=="number"?t.schemaVersion:void 0,extractionVersion:typeof t.extractionVersion=="number"?t.extractionVersion:void 0,lastSyncAt:t.lastSyncAt,vectorEnabled:typeof t.vectorEnabled=="boolean"?t.vectorEnabled:void 0,embeddingDims:typeof t.embeddingDims=="number"?t.embeddingDims:void 0,llm:t.llm??{initialized:false,capabilities:{}},backend:t.backend,healthy:typeof t.healthy=="boolean"?t.healthy:true,recommendation:t.recommendation,dbStats:(()=>{let e=t.dbStats;if(e&&typeof e=="object"&&Object.keys(e).length>0)return {...e};let s=t.integrityStats;if(s&&typeof s=="object"&&Object.keys(s).length>0)return {...s}})(),extras:(()=>{let e={};if(typeof t.agentId=="string"&&(e.agent_id=t.agentId),typeof t.ftsAvailable=="boolean"&&(e.fts_available=t.ftsAvailable?"yes":"no"),t.factsByCategory&&typeof t.factsByCategory=="object"){let s=t.factsByCategory;for(let[u,c]of Object.entries(s))typeof c=="number"&&c>0&&(e[`facts/${u}`]=c);}if(t.meta&&typeof t.meta=="object")for(let[s,u]of Object.entries(t.meta))e[`meta/${s}`]=u===void 0?"\u2205":u;return Object.keys(e).length>0?e:void 0})()}}function R(l){let t=l,e=Array.isArray(t.checks)?t.checks:[],s=t.integrityStats,u=t.backendAvailable,c=s?{...s}:void 0;return {packageName:"memory",healthy:typeof t.healthy=="boolean"?t.healthy:false,durationMs:typeof t.durationMs=="number"?t.durationMs:0,checks:e.map(m=>({code:typeof m.code=="string"?m.code:"",severity:m.severity??"info",name:typeof m.name=="string"?m.name:"",message:typeof m.message=="string"?m.message:"",durationMs:typeof m.durationMs=="number"?m.durationMs:void 0,details:m.details})),dbStats:c,backendAvailable:u}}export{v as a,j as b,C as c,U as d,R as e};