@ilaomianyang/dsh-memory-graph 0.10.4 → 0.11.0

package/src/tools.js

@@ -1,5 +1,5 @@
 /**
- * The model-facing surface. Seven small tools, all explicit.
+ * The model-facing surface. Eight small tools, all explicit.
  *
  * Nothing here runs on its own: retrieval only happens when the agent decides
  * to ask, which keeps memory out of the context (and out of the attention
@@ -8,6 +8,7 @@
 import path from 'node:path'
 import { searchCards, timelineCards } from './search.js'
 import { distill, extractorServices, resolveRoute } from './extract.js'
+import { runBackfill, defaultSessionsDir } from './history.js'
 import { CARD_KINDS, CONFIDENCE, slugify } from './vault.js'
 
 const OUTPUT_SCHEMA = { type: 'object', additionalProperties: true }
@@ -530,5 +531,55 @@ export function registerTools(ctx, { cfg, vault, redactor, runner = null }) {
     }),
   )
 
+  /* --------------------------------------------------------------- backfill */
+  disposers.push(
+    ctx.tools.register({
+      name: 'memory_backfill',
+      description:
+        '把「安装插件之前的」会话历史一次性导入记忆库。采集只在宿主运行时看得见当轮对话，所以新装的记忆库一开始是空的；这个工具回放磁盘上的历史会话文件（~/.dsh/sessions 下的 session.v4.jsonl.zstd），走的是与实时采集完全相同的过滤与脱敏逻辑，因此回填出来的情节和实时采集的是同一种记录。可重复执行：已经导入过的轮次会跳过，只补新的部分；时间戳用会话文件里的原始时间，所以历史落在时间轴的正确位置。默认只统计不写库（dryRun），确认后再真正导入。',
+      parameters: {
+        type: 'object',
+        properties: {
+          dryRun: { type: 'boolean', description: '只统计会导入多少条，不写库。默认 true。' },
+          limit: { type: 'integer', minimum: 0, description: '最多回填多少个会话，按最近修改时间优先。0 = 全部。默认 0。' },
+          sessionsDir: {
+            type: 'string',
+            description: '会话存储目录。省略则用环境变量 DSH_HOME 下的 sessions，再退到 ~/.dsh/sessions。',
+          },
+        },
+        additionalProperties: false,
+      },
+      output: { schema: OUTPUT_SCHEMA, render: (args, value) => json(args, value.text ?? value) },
+      async execute(args) {
+        const dryRun = args.dryRun !== false
+        const report = await runBackfill({
+          cfg,
+          vault,
+          redactor,
+          dir: args.sessionsDir ?? defaultSessionsDir(),
+          limit: args.limit ?? 0,
+          dryRun,
+        })
+
+        const lines = [
+          `${dryRun ? '试运行' : '已导入'}：会话目录 ${report.dir}（解码器 ${report.decoder}）`,
+          `扫描 ${report.scanned} / 共找到 ${report.found} 个会话，用时 ${(report.ms / 1000).toFixed(1)}s`,
+          `${dryRun ? '将写入' : '已写入'} ${report.imported} 条情节；已存在跳过 ${report.duplicates} 条${report.malformed > 0 ? `；坏行 ${report.malformed} 条` : ''}${report.failed > 0 ? `；读不了 ${report.failed} 个会话` : ''}`,
+        ]
+        if (report.exhausted) lines.push('达到单次读取上限，剩下的会话下次再跑即可（已导入的会自动跳过）。')
+        if (report.sessions.length > 0) {
+          lines.push('贡献最多的会话：')
+          for (const session of report.sessions.slice(0, 5)) {
+            lines.push(`  ${session.id}  ${session.project}  ${session.episodes} 条${session.duplicates > 0 ? `（跳过 ${session.duplicates}）` : ''}`)
+          }
+        }
+        if (report.imported > 0 && !dryRun) {
+          lines.push('这些情节还没有变成卡片：蒸馏一次（memory_distill 或设置页的「蒸馏一次」）才会进入检索层。')
+        }
+        return { ...report, text: lines.join('\n') }
+      },
+    }),
+  )
+
   return disposers
 }

package/src/turns.js

@@ -0,0 +1,265 @@
+/**
+ * Turn assembly: live events and a replayed session file go through one reducer.
+ *
+ * Two things must never be implemented twice. First, what counts as a message a
+ * person actually typed — the harness pushes runtime snapshots, skill catalogs,
+ * sampled time and compaction checkpoints down the same channel, sometimes
+ * tagged `user`. Second, the truncation and redaction applied before anything
+ * touches disk. If the live listener and the history importer had separate
+ * copies of either, they would drift and the drift would be silent: a leaked
+ * snapshot on one side, a lost message on the other.
+ *
+ * So the filter lives here. The callers only decide *when* a turn is closed and
+ * *what timestamp* its episode carries.
+ */
+import { nowIso } from './vault.js'
+
+/** Assistant text is context, not the record; a handful of parts is plenty. */
+const MAX_ASSISTANT_PARTS = 6
+
+function collectText(node, depth = 0, seen = new Set(), out = []) {
+  if (node === null || node === undefined || depth > 4) return out
+  if (typeof node === 'string') return out
+  if (Array.isArray(node)) {
+    for (const item of node) collectText(item, depth + 1, seen, out)
+    return out
+  }
+  if (typeof node !== 'object') return out
+  if (seen.has(node)) return out
+  seen.add(node)
+
+  if (node.type === 'text' && typeof node.text === 'string') {
+    out.push(node.text)
+    return out
+  }
+  for (const key of ['content', 'message', 'text', 'parts', 'blocks']) {
+    if (key in node) collectText(node[key], depth + 1, seen, out)
+  }
+  return out
+}
+
+export function eventText(event) {
+  const parts = collectText(event?.data)
+  return parts.join('\n').replace(/\n{3,}/g, '\n\n').trim()
+}
+
+export function truncate(text, max) {
+  const value = String(text ?? '').trim()
+  if (value.length <= max) return value
+  return `${value.slice(0, max)}…`
+}
+
+/**
+ * Delimited harness blocks come off before any pattern is consulted.
+ *
+ * They are the one kind of injection whose extent is knowable, so removing them
+ * keeps the person's own words when a real message happens to carry one — the
+ * alternative (dropping the whole message) loses the part that was worth
+ * keeping. Undelimited blocks (a runtime snapshot) are handled by the patterns.
+ */
+export function stripInjectedBlocks(text) {
+  return String(text ?? '')
+    .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/gi, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/** The project a session belongs to: the last segment of the cwd it started in. */
+export function projectOf(session, fallback) {
+  const cwd = session?.header?.cwd ?? session?.meta?.cwd ?? session?.cwd
+  if (typeof cwd === 'string' && cwd.trim() !== '') {
+    // Both separators, whatever platform this is running on: the path comes from
+    // the session header, which may well have been written on the other OS.
+    const parts = cwd.replace(/[\\/]+$/, '').split(/[\\/]/)
+    const base = parts[parts.length - 1] ?? ''
+    if (base !== '') return base
+  }
+  return fallback
+}
+
+/** The same shape as vault's nowIso(), for an arbitrary instant. */
+export function isoAt(ms) {
+  const d = new Date(ms)
+  const pad = (n) => String(n).padStart(2, '0')
+  const offset = -d.getTimezoneOffset()
+  const sign = offset >= 0 ? '+' : '-'
+  const abs = Math.abs(offset)
+  return (
+    `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}` +
+    `T${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}` +
+    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`
+  )
+}
+
+/**
+ * Feed it events in order; it hands back finished episodes.
+ *
+ * `push()` returns an array because one event can close two turns: a user
+ * message that arrives while the previous turn never closed flushes that one
+ * first, then opens the next.
+ */
+export function createTurnAssembler({ cfg, redactor }) {
+  const buffers = new Map()
+
+  // Both the switch and the skip list are editable while the plugin runs (they
+  // are `.volatile()` in the schema), so neither is baked in here: the switch is
+  // read per event, and the compiled rules are rebuilt only when the list's text
+  // actually changes — a `new RegExp` on every token would be pure waste.
+  let skipKey
+  let skipRules = []
+
+  function compiledSkipRules() {
+    const list = cfg.capture.skipPatterns ?? []
+    const key = list.join('\u0000')
+    if (key !== skipKey) {
+      skipKey = key
+      skipRules = list.flatMap((pattern) => {
+        try {
+          return [new RegExp(pattern, 'i')]
+        } catch {
+          return []
+        }
+      })
+    }
+    return skipRules
+  }
+
+  /** True when the "user" side is really a harness injection, not a person typing. */
+  const injected = (text) => text !== '' && compiledSkipRules().some((re) => re.test(text))
+
+  function openBuffer(sessionId, project) {
+    let buffer = buffers.get(sessionId)
+    if (!buffer) {
+      buffer = {
+        project: project ?? cfg.defaultProject,
+        user: '',
+        assistant: [],
+        tools: 0,
+        turn: null,
+        at: null,
+      }
+      buffers.set(sessionId, buffer)
+    }
+    return buffer
+  }
+
+  function finish(sessionId, at) {
+    const buffer = buffers.get(sessionId)
+    if (!buffer) return null
+    buffers.delete(sessionId)
+
+    const toolCount = buffer.tools
+    const user = truncate(buffer.user, cfg.capture.userChars)
+    const assistant = truncate(buffer.assistant.join('\n'), cfg.capture.assistantChars)
+
+    // Every episode is anchored to something the user actually said. A turn with
+    // no user side is context noise, and one too short to mean anything — such as
+    // "ok" — would only fill the vault with lines the extractor cannot use.
+    if (user === '' || user.length + assistant.length < cfg.capture.minChars) return null
+
+    // The turn's own clock when the log carries one (a replayed session, or a
+    // turn flushed a minute late), otherwise now: the timeline should say when
+    // it happened, not when it was written down.
+    const stamp = at ?? buffer.at
+    const when = typeof stamp === 'string' ? stamp : stamp === null || stamp === undefined ? nowIso() : isoAt(stamp)
+
+    return {
+      t: when,
+      project: buffer.project,
+      session: sessionId,
+      turn: buffer.turn,
+      user: redactor.redact(user).text,
+      assistant: redactor.redact(assistant).text,
+      ...(cfg.capture.includeToolOutput && toolCount > 0 ? { tools: toolCount } : {}),
+    }
+  }
+
+  return {
+    /**
+     * @param {{sessionId: string, project?: string, event: object}} input
+     * @returns {object[]} episodes that are finished and ready to append
+     */
+    push({ sessionId, project, event }) {
+      if (!cfg.capture.enabled) return []
+      const type = event?.type
+      const at = Number.isFinite(event?.time) ? event.time : null
+      const done = []
+
+      if (type === 'turn/end') {
+        const buffer = buffers.get(sessionId)
+        if (!buffer) return done
+        if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+        const episode = finish(sessionId, at)
+        if (episode) done.push(episode)
+        return done
+      }
+
+      if (type !== 'user/message' && type !== 'assistant/message' && type !== 'tool/result') return done
+
+      if (type === 'user/message') {
+        // The harness delivers runtime snapshots, skill catalogs, sampled time,
+        // approval notices and compaction checkpoints through the same channel as
+        // the person typing — and not always with a telling `source.kind`: a real
+        // runtime snapshot has arrived here tagged `user` (it was captured as if
+        // the person had typed it). So provenance can only *add* a skip, never
+        // veto the patterns; both are consulted, and delimited blocks come off
+        // first so a message that merely carried a reminder keeps its own words.
+        const kind = event?.data?.source?.kind
+        const text = stripInjectedBlocks(eventText(event))
+        const synthetic = (typeof kind === 'string' && kind !== 'user') || text === '' || injected(text)
+        if (synthetic) return done
+
+        const open = buffers.get(sessionId)
+        if (open && (open.user !== '' || open.assistant.length > 0)) {
+          // A turn that never closed (interrupted, or an older harness): keep it.
+          const episode = finish(sessionId, at)
+          if (episode) done.push(episode)
+        }
+
+        const buffer = openBuffer(sessionId, project)
+        buffer.user = text
+        buffer.turn = typeof event?.data?.turn === 'number' ? event.data.turn : buffer.turn
+        if (at !== null) buffer.at = at
+        return done
+      }
+
+      const buffer = openBuffer(sessionId, project)
+      if (at !== null) buffer.at = at
+
+      if (type === 'assistant/message') {
+        const text = eventText(event)
+        if (text !== '' && buffer.assistant.length < MAX_ASSISTANT_PARTS) buffer.assistant.push(text)
+        if (typeof event?.data?.turn === 'number') buffer.turn = event.data.turn
+        return done
+      }
+
+      buffer.tools += 1
+      return done
+    },
+
+    /** Close one session's open turn. Returns the episode, or null if it was noise. */
+    flush(sessionId, at) {
+      return finish(sessionId, at ?? undefined)
+    },
+
+    /** Close every open turn (shutdown, or the end of a replayed file). */
+    flushAll(at) {
+      const out = []
+      for (const sessionId of [...buffers.keys()]) {
+        const episode = finish(sessionId, at ?? undefined)
+        if (episode) out.push(episode)
+      }
+      return out
+    },
+
+    /** True when this session has an open turn — a hint for the timer bookkeeping. */
+    isOpen(sessionId) {
+      return buffers.has(sessionId)
+    },
+
+    forget(sessionId) {
+      buffers.delete(sessionId)
+    },
+  }
+}

package/src/vault.js

@@ -301,9 +301,19 @@ export function createVault(cfg, redactor) {
 
   /* ------------------------------------------------------------ episodes */
 
+  /**
+   * Append one episode to the day it happened.
+   *
+   * The date in the filename is the record's own `t`, not "now": a backfilled
+   * session from last month belongs in last month's file, or the vault listing
+   * would claim that three months of history happened today. A record without a
+   * parseable timestamp falls back to today.
+   */
   async function appendEpisode(record) {
     await ensure()
-    const file = path.join(P.episodes, `${today()}.jsonl`)
+    const stamp = typeof record?.t === 'string' ? record.t.slice(0, 10) : ''
+    const day = /^\d{4}-\d{2}-\d{2}$/.test(stamp) ? stamp : today()
+    const file = path.join(P.episodes, `${day}.jsonl`)
     const line = `${JSON.stringify(record)}\n`
     await withLock(`episode:${file}`, () => fsp.appendFile(file, line, 'utf8'))
     // Keep projects.json honest even before the first card is distilled.
@@ -402,7 +412,7 @@ export function createVault(cfg, redactor) {
     return {
       id: data.id,
       kind: data.kind ?? 'note',
-      title: data.title ?? '(untitled)',
+      title: data.title ?? '（无标题 untitled）',
       project: data.project ?? cfg.defaultProject,
       entities: Array.isArray(data.entities) ? data.entities : [],
       created: data.created ?? nowIso(),
@@ -503,15 +513,15 @@ export function createVault(cfg, redactor) {
         await touchProject(project)
         const why = duplicate.exact
           ? ''
-          : ` (near-duplicate ${duplicate.score.toFixed(2)} of "${String(input.title ?? '').trim()}")`
-        await audit('card', `re-confirmed ${existing.id} "${existing.title}"${why}`)
+          : ` （近似重复 near-duplicate ${duplicate.score.toFixed(2)}，对着 "${String(input.title ?? '').trim()}"）`
+        await audit('card', `再次确认 ${existing.id} "${existing.title}"${why}`)
         return { card: existing, deduped: true }
       }
 
       const card = {
         id: input.id ?? newCardId(),
         kind: CARD_KINDS.includes(input.kind) ? input.kind : 'note',
-        title: String(input.title ?? '').trim().slice(0, 160) || '(untitled)',
+        title: String(input.title ?? '').trim().slice(0, 160) || '（无标题 untitled）',
         project,
         entities: [...new Set((input.entities ?? []).map((e) => slugify(e)))].filter(Boolean),
         created: input.created ?? stamp,
@@ -538,10 +548,10 @@ export function createVault(cfg, redactor) {
         old.validTo = card.validFrom
         old.supersededBy = card.id
         await writeAtomic(cardPath(old), renderCard(old))
-        await audit('card', `${old.id} superseded by ${card.id}`)
+        await audit('card', `${old.id} 已被 ${card.id} 替换（superseded）`)
       }
 
-      await audit('card', `wrote ${card.id} [${card.kind}] "${card.title}" (${card.project})`)
+      await audit('card', `写入 ${card.id} [${card.kind}] "${card.title}" (${card.project})`)
       return { card, deduped: false }
     })
   }
@@ -552,10 +562,10 @@ export function createVault(cfg, redactor) {
       if (!card) return null
       card.status = 'retracted'
       card.validTo = card.validTo ?? today()
-      card.body = `${card.body}\n\n<!-- retracted: ${String(reason ?? 'no reason given').slice(0, 200)} -->`
+      card.body = `${card.body}\n\n<!-- 已撤回 retracted: ${String(reason ?? '没有给出原因 · no reason given').slice(0, 200)} -->`
       await writeAtomic(cardPath(card), renderCard(card))
       invalidate()
-      await audit('card', `retracted ${id}${reason ? ` (${reason})` : ''}`)
+      await audit('card', `已撤回 ${id}${reason ? ` (${reason})` : ''}`)
       return card
     })
   }
@@ -566,7 +576,7 @@ export function createVault(cfg, redactor) {
       if (!card) return false
       await fsp.rm(card.file, { force: true })
       invalidate()
-      await audit('card', `purged ${id}`)
+      await audit('card', `已彻底删除 ${id}（purged）`)
       return true
     })
   }

package/test/history.mjs

@@ -0,0 +1,249 @@
+/**
+ * History test: replay a session file the way the store actually laid it out,
+ * and check what reaches the vault.   node test/history.mjs
+ *
+ * The fixture `test/fixtures/session.v4.jsonl.zstd` is a real zstd frame holding
+ * real event shapes, so the decompression path is exercised rather than mocked.
+ * It was produced once with:
+ *
+ *   node -e "… zlib.zstdCompressSync(JSON.stringify(events).split…)"   (node >= 22.15)
+ *
+ * and holds three turns: one real, one that is only a runtime snapshot, and one
+ * with a `<system-reminder>` wrapped around the person's own words.
+ */
+import assert from 'node:assert/strict'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { resolveConfig } from '../src/config.js'
+import { createRedactor } from '../src/privacy.js'
+import { createVault } from '../src/vault.js'
+import { isoAt } from '../src/turns.js'
+import { createReplay, importSession, listSessions, runBackfill } from '../src/history.js'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const fixture = path.join(here, 'fixtures', 'session.v4.jsonl.zstd')
+
+const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'memgraph-hist-'))
+const cfg = resolveConfig({ vaultDir: dir })
+const redactor = createRedactor(cfg.privacy)
+const vault = createVault(cfg, redactor)
+
+/** An empty store laid out exactly like ~/.dsh/sessions. */
+async function makeStore(name = 'store') {
+  const root = path.join(dir, name)
+  return root
+}
+
+async function plant(root, { group = '--G-TempProject-Test--', id = 'session-history-fixture', file = fixture, mtime } = {}) {
+  const target = path.join(root, group, id)
+  await fsp.mkdir(target, { recursive: true })
+  const copy = path.join(target, 'session.v4.jsonl.zstd')
+  await fsp.copyFile(file, copy)
+  if (mtime) await fsp.utimes(copy, mtime, mtime)
+  return copy
+}
+
+const results = []
+async function check(name, fn) {
+  try {
+    await fn()
+    results.push(`  ok   ${name}`)
+  } catch (error) {
+    results.push(`  FAIL ${name}: ${error.message}`)
+    process.exitCode = 1
+  }
+}
+
+/* ------------------------------------------------------------------ store */
+
+const store = await makeStore()
+await plant(store)
+await plant(store, { group: '--G-Article2--', id: 'session-older', mtime: new Date(Date.now() - 86_400_000) })
+
+await check('the store is walked two levels deep, newest directory first', async () => {
+  const found = await listSessions(store)
+  assert.equal(found.length, 2, `expected 2 sessions, got ${found.length}`)
+  assert.equal(found[0].dirName, 'session-history-fixture')
+  assert.equal(found[1].dirName, 'session-older')
+  assert.ok(found[0].size > 0)
+})
+
+await check('a missing directory reports nothing instead of throwing', async () => {
+  const found = await listSessions(path.join(dir, 'nope'))
+  assert.deepEqual(found, [])
+})
+
+/* ----------------------------------------------------------------- replay */
+
+await check('a real turn is replayed, a runtime snapshot is not', () => {
+  const seen = new Set()
+  const replay = createReplay({ cfg, redactor, seen })
+  replay.feed(JSON.stringify({ type: 'session', id: 'session-x', cwd: 'C:\\TempProject\\历史项目' }))
+  replay.feed(
+    JSON.stringify({
+      type: 'user/message',
+      time: 1793170060000,
+      data: { content: [{ type: 'text', text: '我们决定把记忆存成纯文本 vault，每一轮对话追加一条情节。' }], source: { kind: 'user' } },
+    }),
+  )
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170090000, data: { turn: 1 } }))
+  replay.feed(
+    JSON.stringify({
+      type: 'user/message',
+      time: 1793170100000,
+      data: {
+        content: [{ type: 'text', text: 'Current runtime context. This snapshot supersedes earlier snapshots.' }],
+        source: { kind: 'user' },
+      },
+    }),
+  )
+  replay.feed(JSON.stringify({ type: 'assistant/message', time: 1793170110000, data: { content: [{ type: 'text', text: '收到。' }] } }))
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170120000, data: { turn: 2 } }))
+  const report = replay.finish()
+
+  assert.equal(report.episodes.length, 1, 'only the turn a person typed should survive')
+  assert.equal(report.episodes[0].turn, 1)
+  assert.ok(report.episodes[0].user.includes('纯文本 vault'))
+  assert.equal(report.closedTurns, 2)
+})
+
+await check('a reminder inside a real message is stripped, not the message', () => {
+  const replay = createReplay({ cfg, redactor, seen: new Set() })
+  replay.feed(
+    JSON.stringify({
+      type: 'user/message',
+      time: 1793170060000,
+      data: {
+        content: [{ type: 'text', text: '<system-reminder>sampled time</system-reminder>把记忆图谱的面板改成中文。' }],
+        source: { kind: 'user' },
+      },
+    }),
+  )
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170090000, data: { turn: 3 } }))
+  const [episode] = replay.finish().episodes
+  assert.ok(episode, 'the message should survive')
+  assert.ok(!episode.user.includes('system-reminder'), 'the reminder must be gone')
+  assert.equal(episode.user, '把记忆图谱的面板改成中文。')
+})
+
+await check('the timestamp is the turn’s own, not the day of the import', () => {
+  const replay = createReplay({ cfg, redactor, seen: new Set() })
+  replay.feed(
+    JSON.stringify({
+      type: 'user/message',
+      time: 1793170060000,
+      data: { content: [{ type: 'text', text: '这段历史发生在上个月，应该落在上个月的时间轴上。' }], source: { kind: 'user' } },
+    }),
+  )
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170090000, data: { turn: 1 } }))
+  const [episode] = replay.finish().episodes
+  assert.equal(episode.t, isoAt(1793170090000))
+  assert.ok(episode.t.startsWith('2026-'), `expected a 2026 date, got ${episode.t}`)
+})
+
+await check('a secret in replayed text is redacted before it is stored', () => {
+  const replay = createReplay({ cfg, redactor, seen: new Set() })
+  replay.feed(
+    JSON.stringify({
+      type: 'user/message',
+      time: 1793170060000,
+      data: {
+        content: [{ type: 'text', text: '出问题就写信给 someone@example.com，别贴密钥 sk-live-abcdefghijklmnopqrstuvwx。' }],
+        source: { kind: 'user' },
+      },
+    }),
+  )
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170090000, data: { turn: 1 } }))
+  const [episode] = replay.finish().episodes
+  assert.ok(!episode.user.includes('someone@example.com'), `email leaked: ${episode.user}`)
+  assert.ok(!episode.user.includes('sk-live-abcdefghijklmnopqrstuvwx'), `secret leaked: ${episode.user}`)
+})
+
+await check('a corrupt line is counted, not thrown', () => {
+  const replay = createReplay({ cfg, redactor, seen: new Set() })
+  replay.feed('{not json')
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170090000, data: { turn: 1 } }))
+  const report = replay.finish()
+  assert.equal(report.malformed, 1)
+  assert.equal(report.episodes.length, 0)
+})
+
+await check('a turn already in the vault is skipped', () => {
+  const seen = new Set(['session-y#1'])
+  const replay = createReplay({ cfg, redactor, seen })
+  replay.feed(JSON.stringify({ type: 'session', id: 'session-y' }))
+  replay.feed(
+    JSON.stringify({
+      type: 'user/message',
+      time: 1793170060000,
+      data: { content: [{ type: 'text', text: '这一轮已经在记忆库里了，不该再写一遍。' }], source: { kind: 'user' } },
+    }),
+  )
+  replay.feed(JSON.stringify({ type: 'turn/end', time: 1793170090000, data: { turn: 1 } }))
+  const report = replay.finish()
+  assert.equal(report.episodes.length, 0)
+  assert.equal(report.duplicates, 1)
+})
+
+/* ------------------------------------------------------------------- file */
+
+await check('the real zstd frame is decompressed into the vault', async () => {
+  const [entry] = await listSessions(store)
+  const report = await importSession({ entry, cfg, vault, redactor, seen: new Set() })
+  assert.equal(report.id, 'session-history-fixture')
+  assert.equal(report.project, '历史项目', 'the project comes from the session header')
+  assert.equal(report.truncated, false)
+  assert.equal(report.episodes, 2, `expected 2 usable turns, got ${report.episodes}`)
+
+  const stats = await vault.stats()
+  assert.equal(stats.episodes.records, 2, 'both turns should be on disk')
+  assert.deepEqual(stats.projects, ['历史项目'], 'the project file is touched too')
+})
+
+await check('a second run imports nothing twice', async () => {
+  const report = await runBackfill({ cfg, vault, redactor, dir: store })
+  assert.equal(report.found, 2)
+  assert.equal(report.imported, 0, `re-imported ${report.imported} episodes`)
+  assert.ok(report.duplicates >= 2, `expected the two known turns, got ${report.duplicates}`)
+  const stats = await vault.stats()
+  assert.equal(stats.episodes.records, 2, 'the vault must not have grown')
+})
+
+/* -------------------------------------------------------------- dry run */
+
+await check('a dry run reports without writing', async () => {
+  // Its own vault: the dedupe key is the session id inside the file, so a
+  // second vault is what proves the dry run *would* have written these turns.
+  const freshDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'memgraph-dry-'))
+  const freshCfg = resolveConfig({ vaultDir: freshDir })
+  const freshVault = createVault(freshCfg, createRedactor(freshCfg.privacy))
+  const fresh = await makeStore('dry')
+  await plant(fresh)
+
+  const report = await runBackfill({ cfg: freshCfg, vault: freshVault, redactor, dir: fresh, dryRun: true })
+  assert.equal(report.dryRun, true)
+  assert.equal(report.imported, 2, 'it should still say what it would import')
+  assert.equal((await freshVault.stats()).episodes.records, 0, 'a dry run must not write')
+
+  // And the same run without the flag does write those two.
+  const real = await runBackfill({ cfg: freshCfg, vault: freshVault, redactor, dir: fresh })
+  assert.equal(real.imported, 2)
+  assert.equal((await freshVault.stats()).episodes.records, 2)
+})
+
+await check('the limit takes the newest sessions first', async () => {
+  const report = await runBackfill({ cfg, vault, redactor, dir: store, limit: 1, dryRun: true })
+  assert.equal(report.scanned, 1)
+  assert.equal(report.sessions[0].id, 'session-history-fixture')
+})
+
+let failed = 0
+for (const line of results) {
+  if (line.includes('FAIL')) failed += 1
+}
+console.log(results.join('\n'))
+console.log(failed === 0 ? `\nall ${results.length} checks passed` : `\n${failed} of ${results.length} checks failed`)
+if (failed === 0) process.exitCode = 0

package/test/tools.mjs

@@ -57,8 +57,9 @@ async function call(name, args) {
 }
 
 /* ------------------------------------------------------------------ shape */
-check('registers the eight memory tools', () => {
+check('registers the nine memory tools', () => {
   assert.deepEqual([...byName.keys()].sort(), [
+    'memory_backfill',
     'memory_distill',
     'memory_forget',
     'memory_get',