@xiangyixie/dsh-superagent 0.12.0 → 0.14.0

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.
@@ -0,0 +1,587 @@
1
+ /**
2
+ * User-level memory for dsh-superagent.
3
+ *
4
+ * `memory.js` answers "what did the last run learn about this task". That is a
5
+ * run notebook: it is ranked against one goal and it is meant to age out. This
6
+ * module answers a different question — "who is this person, what do they want,
7
+ * and why did we choose this before" — and it has to survive across unrelated
8
+ * tasks, so it is stored apart and read apart:
9
+ *
10
+ * - Three categories, three files: `facts` (durable technical context such as
11
+ * the stack or the environment), `preferences` (how the user wants work done)
12
+ * and `decisions` (a choice plus what was rejected, why, and how to undo it).
13
+ * A search opens one category file, so a fact can never be returned as a
14
+ * preference just because the words match.
15
+ * - A decision is only stored when it has a choice and a reason. A conclusion
16
+ * without its rationale teaches the next run nothing, so the reason is part
17
+ * of the record and part of every digest line.
18
+ * - Everything is redacted before it is written, by default: credentials,
19
+ * emails, phone numbers, and usernames inside home paths. The profile is meant
20
+ * to be readable by a future model, not to be a copy of the user's secrets.
21
+ * - Forgetting is a real deletion: the matching lines are removed from the file
22
+ * under a lock and the file is replaced. There is no tombstone to leak the
23
+ * value back through a later search. Three filters are supported — a key, a
24
+ * run id, and a time range — and at least one is required, so a bare "forget"
25
+ * cannot wipe the profile by accident.
26
+ *
27
+ * The module is off by default (`memoryUserProfile: false`): unless the operator
28
+ * enables it, nothing here is constructed, no directory is created, and the
29
+ * existing run notebook behaves exactly as before. It has no dependencies and
30
+ * reuses `memory.js` primitives (redaction, slug keys, tokenising, scoring) so
31
+ * both layers agree on what a key is and how relevance is measured.
32
+ *
33
+ * @module dsh-superagent/user-memory
34
+ */
35
+ import { randomBytes } from 'node:crypto'
36
+ import fsp from 'node:fs/promises'
37
+ import path from 'node:path'
38
+ import { acquireFileLock } from './lock.js'
39
+ import { cleanText, normalizeTags, scoreEntry, slugKey } from './memory.js'
40
+
41
+ /** The three categories, in the order a digest prints them. */
42
+ export const USER_MEMORY_CATEGORIES = Object.freeze(['fact', 'preference', 'decision'])
43
+
44
+ /** One file per category, so a search can never read across categories. */
45
+ const CATEGORY_FILES = Object.freeze({
46
+ fact: 'facts.jsonl',
47
+ preference: 'preferences.jsonl',
48
+ decision: 'decisions.jsonl',
49
+ })
50
+
51
+ /** Longest value kept per decision field. A decision is a sentence, not a log. */
52
+ const MAX_CHOICE_CHARS = 200
53
+ const MAX_REJECTED_CHARS = 160
54
+ const MAX_REASON_CHARS = 240
55
+ const MAX_ROLLBACK_CHARS = 200
56
+
57
+ /** File-level limits; crossing either one, or `maxEntries`, triggers compaction. */
58
+ const MAX_FILE_BYTES = 128 * 1024
59
+ const MAX_FILE_LINES = 400
60
+
61
+ /** How long a writer waits for another process's lock before failing open. */
62
+ const LOCK_RETRIES = 10
63
+ const LOCK_RETRY_DELAY_MS = 50
64
+
65
+ /** Defaults; a profile is long-lived, so it expires far more slowly than a run note. */
66
+ export const USER_MEMORY_DEFAULTS = Object.freeze({
67
+ maxEntries: 200,
68
+ maxAgeDays: 365,
69
+ digestEntries: 8,
70
+ digestChars: 1200,
71
+ })
72
+
73
+ const USER_MEMORY_FENCE = /```user-memory[^\n]*\n([\s\S]*?)```/i
74
+
75
+ /**
76
+ * Redact the shapes that identify a person but are not secrets in the API-key
77
+ * sense: phone numbers. The credential, email and home-path rules live in
78
+ * `memory.redact`, which `cleanText` applies after this step.
79
+ *
80
+ * @param {unknown} value - text that may contain a phone number.
81
+ * @returns {string} the text with phone numbers replaced by a marker.
82
+ */
83
+ export function redactPhones(value) {
84
+ if (typeof value !== 'string') return ''
85
+ return value
86
+ // Mainland Chinese mobile numbers, with or without a +86 prefix.
87
+ .replace(/(?<!\d)(?:\+?86[-\s]?)?1[3-9]\d{9}(?!\d)/g, '[redacted-phone]')
88
+ // Grouped international numbers such as +1 415 555 0100.
89
+ .replace(/(?<!\d)\+?\d{1,3}[-\s]\d{3,4}[-\s]\d{4}(?!\d)/g, '[redacted-phone]')
90
+ }
91
+
92
+ /**
93
+ * One bounded, redacted line. Applied to every field of every user-level
94
+ * record, so a caller cannot bypass redaction by writing a decision instead of
95
+ * a note.
96
+ *
97
+ * @param {unknown} value - source text.
98
+ * @param {number} [limit] - maximum characters.
99
+ * @returns {string} a clean single line.
100
+ */
101
+ export function sanitizeUserText(value, limit) {
102
+ return cleanText(redactPhones(String(value ?? '')), limit)
103
+ }
104
+
105
+ function categoryOf(value) {
106
+ const text = typeof value === 'string' ? value.trim().toLowerCase() : ''
107
+ if (text === 'facts') return 'fact'
108
+ if (text === 'preferences') return 'preference'
109
+ if (text === 'decisions') return 'decision'
110
+ return USER_MEMORY_CATEGORIES.includes(text) ? text : null
111
+ }
112
+
113
+ /**
114
+ * The searchable projection of a decision. Scoring works on `key`, `tags` and
115
+ * `text`, so a decision has to present its rationale as its text: a search for
116
+ * "sqlite" must find the decision that rejected it, not only the choice.
117
+ *
118
+ * @param {object} record - a decision record.
119
+ * @returns {string} key and rationale joined into one line.
120
+ */
121
+ function decisionText(record) {
122
+ return [record.choice, record.rejected, record.reason, record.rollback].filter(Boolean).join('; ')
123
+ }
124
+
125
+ function normalizeRecord(category, item) {
126
+ if (!item || typeof item !== 'object') return null
127
+ const tags = normalizeTags(item.tags)
128
+ if (category === 'decision') {
129
+ const choice = sanitizeUserText(item.choice, MAX_CHOICE_CHARS)
130
+ const rejected = sanitizeUserText(item.rejected, MAX_REJECTED_CHARS)
131
+ const reason = sanitizeUserText(item.reason, MAX_REASON_CHARS)
132
+ const rollback = sanitizeUserText(item.rollback, MAX_ROLLBACK_CHARS)
133
+ // A decision without its rationale is exactly the note this module exists
134
+ // to avoid, so it is refused rather than stored as a bare conclusion.
135
+ if (!choice || !reason) return null
136
+ const key = slugKey(item.key) || slugKey(choice) || `decision-${randomBytes(3).toString('hex')}`
137
+ return { key, category, choice, rejected, reason, rollback, tags }
138
+ }
139
+ const text = sanitizeUserText(item.text)
140
+ if (!text) return null
141
+ const key = slugKey(item.key) || slugKey(text.slice(0, 48)) || `${category}-${randomBytes(3).toString('hex')}`
142
+ return { key, category, text, tags }
143
+ }
144
+
145
+ function tsOf(record) {
146
+ const value = Date.parse(record?.ts ?? '')
147
+ return Number.isFinite(value) ? value : 0
148
+ }
149
+
150
+ function msOf(value) {
151
+ if (value === undefined || value === null || value === '') return null
152
+ if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null
153
+ if (typeof value === 'number') return Number.isFinite(value) ? value : null
154
+ const parsed = Date.parse(String(value))
155
+ return Number.isFinite(parsed) ? parsed : null
156
+ }
157
+
158
+ /**
159
+ * Resolve raw lines into live records: a newer record with the same key wins,
160
+ * and records older than the TTL are ignored. There is no tombstone here —
161
+ * forgetting rewrites the file — so this is only supersession plus age.
162
+ *
163
+ * @param {object[]} records - parsed lines.
164
+ * @param {{ now?: number, maxAgeDays?: number }} [options] - clock and TTL.
165
+ * @returns {object[]} active records, newest first.
166
+ */
167
+ export function effectiveUserRecords(records, { now = Date.now(), maxAgeDays = USER_MEMORY_DEFAULTS.maxAgeDays } = {}) {
168
+ const active = new Map()
169
+ const ordered = records
170
+ .map((record, index) => ({ record, index }))
171
+ .filter(({ record }) => record && typeof record === 'object' && typeof record.key === 'string')
172
+ .sort((a, b) => (tsOf(a.record) - tsOf(b.record)) || (a.index - b.index))
173
+ for (const { record, index } of ordered) active.set(record.key, { record, index })
174
+ const cutoff = maxAgeDays > 0 ? now - maxAgeDays * 86400000 : -Infinity
175
+ return [...active.values()]
176
+ .filter(({ record }) => tsOf(record) >= cutoff)
177
+ .sort((a, b) => (tsOf(b.record) - tsOf(a.record)) || (b.index - a.index))
178
+ .map(({ record }) => record)
179
+ }
180
+
181
+ /**
182
+ * Pull the fenced `user-memory` block out of an aggregator report.
183
+ *
184
+ * The block is removed whether or not it parses, because it is plugin syntax
185
+ * the user did not ask to see. A malformed block is reported through `error`
186
+ * so the run record can say why nothing was stored.
187
+ *
188
+ * @param {unknown} text - final report.
189
+ * @returns {{ report: string, found: boolean, error?: string, block: { facts: object[], preferences: object[], decisions: object[] } }}
190
+ */
191
+ export function extractUserMemoryBlock(text) {
192
+ const empty = { facts: [], preferences: [], decisions: [] }
193
+ if (typeof text !== 'string' || !text) return { report: typeof text === 'string' ? text : '', found: false, block: empty }
194
+ const match = USER_MEMORY_FENCE.exec(text)
195
+ if (!match) return { report: text, found: false, block: empty }
196
+ const report = `${text.slice(0, match.index)}${text.slice(match.index + match[0].length)}`
197
+ .replace(/\n{3,}/g, '\n\n')
198
+ .trim()
199
+ let parsed
200
+ try {
201
+ parsed = JSON.parse(match[1].trim())
202
+ } catch {
203
+ return { report, found: true, error: 'the user-memory block was not valid JSON', block: empty }
204
+ }
205
+ const list = key => (Array.isArray(parsed?.[key]) ? parsed[key] : [])
206
+ const block = { facts: list('facts'), preferences: list('preferences'), decisions: list('decisions') }
207
+ if (block.facts.length + block.preferences.length + block.decisions.length === 0) {
208
+ return { report, found: true, error: 'the user-memory block had no usable entry', block }
209
+ }
210
+ return { report, found: true, block }
211
+ }
212
+
213
+ /**
214
+ * Build the user-level profile bound to one state root.
215
+ *
216
+ * @param {string} root - absolute state directory (`<root>/user-memory` is used).
217
+ * @param {object} [options] - collaborators.
218
+ * @param {(message: string) => void} [options.warn] - diagnostic sink.
219
+ * @param {() => number} [options.now] - clock, injectable for tests.
220
+ */
221
+ export function createUserMemory(root, { warn = () => {}, now = () => Date.now() } = {}) {
222
+ const dir = path.join(root, 'user-memory')
223
+ const fileOf = category => path.join(dir, CATEGORY_FILES[category])
224
+ const lockOf = category => path.join(dir, `${category}.lock`)
225
+ /** Per-category write chain, so two records in this process cannot interleave. */
226
+ const chains = new Map()
227
+
228
+ async function initDir() {
229
+ await fsp.mkdir(dir, { recursive: true })
230
+ const ignore = path.join(dir, '.gitignore')
231
+ try {
232
+ await fsp.access(ignore)
233
+ } catch {
234
+ await fsp.writeFile(ignore, '*\n', 'utf8')
235
+ }
236
+ }
237
+
238
+ function serialize(category, task) {
239
+ const previous = chains.get(category) ?? Promise.resolve()
240
+ const next = previous.catch(() => {}).then(task)
241
+ chains.set(category, next.catch(() => {}))
242
+ return next
243
+ }
244
+
245
+ async function readRecords(category) {
246
+ let text
247
+ try {
248
+ text = await fsp.readFile(fileOf(category), 'utf8')
249
+ } catch (error) {
250
+ if (error?.code === 'ENOENT') return { records: [], bad: 0, bytes: 0 }
251
+ throw error
252
+ }
253
+ const records = []
254
+ let bad = 0
255
+ for (const line of text.split('\n')) {
256
+ const trimmed = line.trim()
257
+ if (!trimmed) continue
258
+ try {
259
+ const parsed = JSON.parse(trimmed)
260
+ if (parsed && typeof parsed === 'object') records.push(parsed)
261
+ else bad++
262
+ } catch {
263
+ bad++
264
+ }
265
+ }
266
+ return { records, bad, bytes: Buffer.byteLength(text, 'utf8') }
267
+ }
268
+
269
+ /** Rewrite one category file with an exact set of records, under its lock. */
270
+ async function rewriteLocked(category, records) {
271
+ const file = fileOf(category)
272
+ const body = records.map(record => `${JSON.stringify(record)}\n`).join('')
273
+ const tmp = path.join(dir, `.${category}.${process.pid}.${Date.now()}.tmp`)
274
+ await fsp.writeFile(tmp, body, 'utf8')
275
+ await fsp.rename(tmp, file)
276
+ }
277
+
278
+ async function compactLocked(category, { maxEntries, maxAgeDays }) {
279
+ try {
280
+ const { records } = await readRecords(category)
281
+ const keep = effectiveUserRecords(records, { now: now(), maxAgeDays })
282
+ .slice(0, maxEntries)
283
+ .reverse()
284
+ await rewriteLocked(category, keep)
285
+ return true
286
+ } catch (error) {
287
+ warn(`cannot compact user memory category "${category}": ${error?.message ?? error}`)
288
+ return false
289
+ }
290
+ }
291
+
292
+ async function appendLocked(category, records) {
293
+ if (records.length === 0) return 0
294
+ const file = fileOf(category)
295
+ await initDir()
296
+ const body = records.map(record => `${JSON.stringify(record)}\n`).join('')
297
+ const handle = await fsp.open(file, 'a')
298
+ try {
299
+ await handle.write(body)
300
+ } finally {
301
+ await handle.close()
302
+ }
303
+ return records.length
304
+ }
305
+
306
+ /**
307
+ * Write a batch into one category. Exposed through the per-category helpers
308
+ * below so a caller cannot pass a category that has no file.
309
+ */
310
+ async function writeCategory(category, entries, { runId = null, maxEntries = USER_MEMORY_DEFAULTS.maxEntries, maxAgeDays = USER_MEMORY_DEFAULTS.maxAgeDays } = {}) {
311
+ const normalized = (Array.isArray(entries) ? entries : [])
312
+ .map(item => normalizeRecord(category, item))
313
+ .filter(Boolean)
314
+ if (normalized.length === 0) return { written: 0, reason: 'no usable entry' }
315
+ return serialize(category, async () => {
316
+ await initDir()
317
+ const release = await acquireFileLock(lockOf(category), {
318
+ now,
319
+ retries: LOCK_RETRIES,
320
+ retryDelayMs: LOCK_RETRY_DELAY_MS,
321
+ })
322
+ if (!release) warn(`user memory category "${category}" is locked by another process; appended without compaction`)
323
+ try {
324
+ const ts = new Date(now()).toISOString()
325
+ const batch = normalized.map(entry => ({
326
+ v: 1,
327
+ id: randomBytes(4).toString('hex'),
328
+ ts,
329
+ runId: runId ?? null,
330
+ ...entry,
331
+ }))
332
+ const written = await appendLocked(category, batch)
333
+ let bytes = 0
334
+ try {
335
+ bytes = (await fsp.stat(fileOf(category))).size
336
+ } catch {
337
+ // A missing stat only means compaction cannot be sized this round.
338
+ }
339
+ const { records } = await readRecords(category)
340
+ const total = records.length + batch.length
341
+ if (release && (bytes > MAX_FILE_BYTES || total > MAX_FILE_LINES || total > maxEntries)) {
342
+ await compactLocked(category, { maxEntries, maxAgeDays })
343
+ }
344
+ return { written, reason: null }
345
+ } finally {
346
+ await release?.()
347
+ }
348
+ })
349
+ }
350
+
351
+ /** Search one category. Never reads another category's file. */
352
+ async function recallCategory(category, {
353
+ query = '',
354
+ tags = [],
355
+ maxEntries = USER_MEMORY_DEFAULTS.digestEntries,
356
+ maxAgeDays = USER_MEMORY_DEFAULTS.maxAgeDays,
357
+ } = {}) {
358
+ const at = now()
359
+ const { records } = await readRecords(category)
360
+ const entries = effectiveUserRecords(records, { now: at, maxAgeDays })
361
+ const wanted = normalizeTags(tags)
362
+ const text = typeof query === 'string' ? query : ''
363
+ const searching = text.trim().length > 0 || wanted.length > 0
364
+ const scored = entries.map(record => {
365
+ const view = category === 'decision'
366
+ ? { key: record.key, tags: record.tags, ts: record.ts, text: decisionText(record) }
367
+ : record
368
+ return { record, ...scoreEntry(view, { query: text, tags: wanted, now: at }) }
369
+ })
370
+ const hits = searching ? scored.filter(item => item.keyword > 0 || item.tag > 0) : scored
371
+ hits.sort((a, b) => b.score - a.score)
372
+ return {
373
+ category,
374
+ searching,
375
+ total: entries.length,
376
+ matched: hits.length,
377
+ entries: hits.slice(0, Math.max(1, maxEntries)).map(({ record, score, keyword, tag, ageDays, matchedTerms }) => ({
378
+ key: record.key,
379
+ category,
380
+ ...(category === 'decision'
381
+ ? {
382
+ choice: record.choice ?? '',
383
+ rejected: record.rejected ?? '',
384
+ reason: record.reason ?? '',
385
+ rollback: record.rollback ?? '',
386
+ }
387
+ : { text: record.text ?? '' }),
388
+ tags: normalizeTags(record.tags),
389
+ score,
390
+ keyword,
391
+ tag,
392
+ ageDays,
393
+ matchedTerms,
394
+ source: { runId: record.runId ?? null, ts: record.ts ?? null },
395
+ })),
396
+ }
397
+ }
398
+
399
+ return {
400
+ root,
401
+ dir,
402
+ fileOf,
403
+
404
+ /** Create the directory and make it git-invisible even inside a repository. */
405
+ async init() {
406
+ await initDir()
407
+ },
408
+
409
+ /**
410
+ * Record one fact, preference or decision.
411
+ * @param {object} options - `category` plus the fields that category needs.
412
+ */
413
+ async record({ category, entry, runId = null, maxEntries, maxAgeDays } = {}) {
414
+ const key = categoryOf(category)
415
+ if (!key) return { written: 0, reason: `category must be one of ${USER_MEMORY_CATEGORIES.join(', ')}` }
416
+ return writeCategory(key, [entry], { runId, maxEntries, maxAgeDays })
417
+ },
418
+
419
+ /**
420
+ * Store the three lists of a parsed `user-memory` block.
421
+ * @param {{ runId: string, block: { facts?: object[], preferences?: object[], decisions?: object[] }, maxEntries?: number, maxAgeDays?: number }} options - block.
422
+ * @returns {Promise<{ fact: number, preference: number, decision: number, skipped: number }>}
423
+ */
424
+ async writeBlock({ runId = null, block = {}, maxEntries, maxAgeDays } = {}) {
425
+ const result = { fact: 0, preference: 0, decision: 0, skipped: 0 }
426
+ const jobs = [
427
+ ['fact', block.facts],
428
+ ['preference', block.preferences],
429
+ ['decision', block.decisions],
430
+ ]
431
+ for (const [category, items] of jobs) {
432
+ if (!Array.isArray(items) || items.length === 0) continue
433
+ const written = await writeCategory(category, items, { runId, maxEntries, maxAgeDays })
434
+ result[category] += written.written
435
+ result.skipped += items.length - written.written
436
+ }
437
+ return result
438
+ },
439
+
440
+ /**
441
+ * Search one category.
442
+ * @param {{ category: string, query?: string, tags?: unknown, maxEntries?: number, maxAgeDays?: number }} options - query.
443
+ */
444
+ async recall({ category, query = '', tags = [], maxEntries, maxAgeDays } = {}) {
445
+ const key = categoryOf(category)
446
+ if (!key) return { category: null, searching: false, total: 0, matched: 0, entries: [], reason: 'unknown category' }
447
+ return recallCategory(key, { query, tags, maxEntries, maxAgeDays })
448
+ },
449
+
450
+ /**
451
+ * Bounded, category-labelled digest for prompts. Facts, preferences and
452
+ * decisions are printed under separate headings, and a decision line always
453
+ * carries what was rejected, why, and how to roll back.
454
+ *
455
+ * @param {{ query?: string, maxEntries?: number, maxChars?: number, maxAgeDays?: number, categories?: string[] }} [options] - digest.
456
+ * @returns {Promise<string>} digest text, or an empty string.
457
+ */
458
+ async digest({
459
+ query = '',
460
+ maxEntries = USER_MEMORY_DEFAULTS.digestEntries,
461
+ maxChars = USER_MEMORY_DEFAULTS.digestChars,
462
+ maxAgeDays = USER_MEMORY_DEFAULTS.maxAgeDays,
463
+ categories = USER_MEMORY_CATEGORIES,
464
+ } = {}) {
465
+ const wanted = categories.map(categoryOf).filter(Boolean)
466
+ const headings = { fact: 'Facts', preference: 'Preferences', decision: 'Decisions (with rationale)' }
467
+ const sections = []
468
+ const share = Math.max(120, Math.floor(maxChars / Math.max(1, wanted.length)))
469
+ for (const category of wanted) {
470
+ const recalled = await recallCategory(category, { query, maxEntries, maxAgeDays })
471
+ let items = recalled.entries
472
+ if (items.length === 0 && recalled.searching) {
473
+ // An unfamiliar goal must not hide who the user is: fall back to the
474
+ // newest entries, exactly as the run notebook does.
475
+ const { records } = await readRecords(category)
476
+ items = effectiveUserRecords(records, { now: now(), maxAgeDays })
477
+ .slice(0, maxEntries)
478
+ .map(record => ({
479
+ ...record,
480
+ ageDays: (now() - tsOf(record)) / 86400000,
481
+ }))
482
+ }
483
+ if (items.length === 0) continue
484
+ const lines = []
485
+ let used = 0
486
+ for (const item of items.slice(0, maxEntries)) {
487
+ const age = Number.isFinite(item.ageDays) ? `${Math.max(0, Math.floor(item.ageDays))}d` : '?'
488
+ const body = category === 'decision'
489
+ ? `chose ${item.choice}; rejected ${item.rejected || 'nothing recorded'}; `
490
+ + `why ${item.reason}; rollback ${item.rollback || 'not recorded'}`
491
+ : item.text
492
+ const line = `- [${age}] ${category} ${item.key} `
493
+ + `(run ${item.source?.runId ?? item.runId ?? 'manual'}, `
494
+ + `${String(item.source?.ts ?? item.ts ?? '').slice(0, 10)}): ${body}`
495
+ if (used + line.length + 1 > share) break
496
+ lines.push(line)
497
+ used += line.length + 1
498
+ }
499
+ if (lines.length > 0) sections.push(`${headings[category]}:\n${lines.join('\n')}`)
500
+ }
501
+ const text = sections.join('\n\n')
502
+ return text.length > maxChars ? `${[...text].slice(0, Math.max(0, maxChars - 1)).join('')}…` : text
503
+ },
504
+
505
+ /**
506
+ * Physical deletion. At least one filter is required, and only matching
507
+ * lines are rewritten away — there is no tombstone left behind, so a later
508
+ * search cannot observe the deleted value.
509
+ *
510
+ * @param {{ key?: string, runId?: string, before?: string | number | Date, after?: string | number | Date, category?: string }} [options] - filters.
511
+ * @returns {Promise<{ deleted: number, categories: string[], reason: string | null }>}
512
+ */
513
+ async forget({ key, runId, before, after, category } = {}) {
514
+ const slug = key === undefined || key === null || key === '' ? null : slugKey(key)
515
+ const run = typeof runId === 'string' && runId.trim() ? runId.trim() : null
516
+ const from = msOf(after)
517
+ const to = msOf(before)
518
+ if (!slug && !run && from === null && to === null) {
519
+ return { deleted: 0, categories: [], reason: 'a key, a run id, or a time range is required' }
520
+ }
521
+ if ((after !== undefined && from === null) || (before !== undefined && to === null)) {
522
+ return { deleted: 0, categories: [], reason: 'before/after must be a date or a timestamp' }
523
+ }
524
+ const targets = category ? [categoryOf(category)].filter(Boolean) : [...USER_MEMORY_CATEGORIES]
525
+ if (targets.length === 0) return { deleted: 0, categories: [], reason: 'unknown category' }
526
+ const match = record => {
527
+ if (slug && record.key !== slug) return false
528
+ if (run && record.runId !== run) return false
529
+ const ts = tsOf(record)
530
+ if (from !== null && ts < from) return false
531
+ if (to !== null && ts > to) return false
532
+ return true
533
+ }
534
+ let deleted = 0
535
+ const touched = []
536
+ for (const target of targets) {
537
+ const count = await serialize(target, async () => {
538
+ await initDir()
539
+ const release = await acquireFileLock(lockOf(target), {
540
+ now,
541
+ retries: LOCK_RETRIES,
542
+ retryDelayMs: LOCK_RETRY_DELAY_MS,
543
+ })
544
+ if (!release) warn(`user memory category "${target}" is locked by another process; deleting without hands-off compaction`)
545
+ try {
546
+ const { records } = await readRecords(target)
547
+ const keep = records.filter(record => !match(record))
548
+ const removed = records.length - keep.length
549
+ if (removed > 0) await rewriteLocked(target, keep)
550
+ return removed
551
+ } finally {
552
+ await release?.()
553
+ }
554
+ })
555
+ if (count > 0) {
556
+ deleted += count
557
+ touched.push(target)
558
+ }
559
+ }
560
+ return { deleted, categories: touched, reason: null }
561
+ },
562
+
563
+ /**
564
+ * Every live record in one category, newest first.
565
+ * @param {{ category: string, limit?: number, maxAgeDays?: number }} options - read.
566
+ */
567
+ async list({ category, limit = 50, maxAgeDays = USER_MEMORY_DEFAULTS.maxAgeDays } = {}) {
568
+ const key = categoryOf(category)
569
+ if (!key) return { category: null, entries: [], total: 0, path: dir }
570
+ const { records } = await readRecords(key)
571
+ const entries = effectiveUserRecords(records, { now: now(), maxAgeDays })
572
+ return { category: key, entries: entries.slice(0, limit), total: entries.length, path: fileOf(key) }
573
+ },
574
+
575
+ /** Active counts per category, for status lines and tests. */
576
+ async stats({ maxAgeDays = USER_MEMORY_DEFAULTS.maxAgeDays } = {}) {
577
+ const counts = {}
578
+ for (const category of USER_MEMORY_CATEGORIES) {
579
+ const { records } = await readRecords(category)
580
+ counts[category] = effectiveUserRecords(records, { now: now(), maxAgeDays }).length
581
+ }
582
+ return { ...counts, total: counts.fact + counts.preference + counts.decision, path: dir }
583
+ },
584
+
585
+ defaults: USER_MEMORY_DEFAULTS,
586
+ }
587
+ }