@ilaomianyang/dsh-memory-graph 0.10.0

package/test/schema.mjs

@@ -0,0 +1,256 @@
+/**
+ * Settings-form schema checks.
+ *
+ * The harness draws this plugin's page in 设置 (Settings) from the `Config`
+ * schema it exports: `@deepseek-ai/dsh-settings` keeps only the fields marked
+ * `.volatile()` and serves those as one editable form. Two kinds of rot are
+ * possible and both are silent: a field added to `src/config.js` but not to the
+ * form (invisible setting), and a default that disagrees between the form and
+ * the runtime (the form shows one thing, the plugin does another).
+ *
+ * The drift check below walks every leaf of the schema defaults and demands the
+ * same value from `resolveConfig({})`, so adding a field in only one place fails
+ * here instead of shipping.
+ *
+ * The last three checks are about the split that makes the page possible at all:
+ * a leaf is either volatile (live-editable in Settings) or structural (read once
+ * while activating, so editing it remounts the plugin). `client.js` declares the
+ * page's fields; the two descriptions must agree, or the page shows a knob the
+ * host refuses to write, or misses a knob the host serves.
+ */
+import assert from 'node:assert/strict'
+import path from 'node:path'
+import { Config } from '../src/schema.js'
+import { DEFAULT_SKIP_PATTERNS, resolveConfig, unwrapConfig } from '../src/config.js'
+
+// client.js is a browser bundle; imported under Node it only publishes its
+// field table on globalThis (see the entry-point guard at the bottom of it).
+await import('../client.js')
+const spec = globalThis.__memoryGraphFormSpec
+
+let passed = 0
+const check = (name, fn) => {
+  try {
+    fn()
+    passed += 1
+    console.log(`  ok   ${name}`)
+  } catch (error) {
+    console.log(`  FAIL ${name}: ${error.message}`)
+    process.exitCode = 1
+  }
+}
+
+const walk = (value, prefix = '') => {
+  const leaves = []
+  for (const [key, child] of Object.entries(value)) {
+    const at = prefix === '' ? key : `${prefix}.${key}`
+    if (child !== null && typeof child === 'object' && !Array.isArray(child)) leaves.push(...walk(child, at))
+    else leaves.push([at, child])
+  }
+  return leaves
+}
+
+/** Every leaf node of a schema with its dotted path and its node. */
+const schemaLeaves = (node, prefix = []) => {
+  if (!node) return []
+  if (node.type === 'object') {
+    return Object.entries(node.dict ?? {}).flatMap(([key, child]) => schemaLeaves(child, [...prefix, key]))
+  }
+  return [{ path: prefix.join('.'), node }]
+}
+
+const at = (object, dotted) => dotted.split('.').reduce((node, key) => node?.[key], object)
+
+console.log('schema')
+
+// `Config({})` validates to frozen `{ get() }` refs for every live leaf, so all
+// value comparisons go through `unwrapConfig` — the same seam `src/config.js`
+// uses when the plugin reads its configuration.
+const defaults = unwrapConfig(Config({}))
+
+check('an empty config block is valid and yields the documented defaults', () => {
+  assert.equal(defaults.enabled, true)
+  assert.equal(defaults.vaultDir, '')
+  assert.equal(defaults.extractor.enabled, false)
+  assert.equal(defaults.extractor.transport, 'harness')
+  assert.equal(defaults.extractor.useCurrentModel, true)
+  assert.equal(defaults.extractor.reasoningEffort, '')
+  assert.deepEqual(defaults.capture.skipPatterns, [...DEFAULT_SKIP_PATTERNS])
+})
+
+check('every field the plugin normalises also has a default in the form', () => {
+  const runtime = resolveConfig({})
+  // vaultDir is the one leaf that must differ: the form holds the user's raw
+  // text ('' means "the default vault") while the runtime holds an absolute path.
+  const skip = new Set(['vaultDir'])
+  const drift = []
+  for (const [key, value] of walk(defaults)) {
+    if (skip.has(key)) continue
+    const actual = at(runtime, key)
+    if (JSON.stringify(actual) !== JSON.stringify(value)) {
+      drift.push(`${key}: form ${JSON.stringify(value)} vs runtime ${JSON.stringify(actual)}`)
+    }
+  }
+  assert.deepEqual(drift, [], `settings form and runtime defaults disagree:\n${drift.join('\n')}`)
+})
+
+check('and no runtime default hides behind a missing form field', () => {
+  // The other direction: a knob `src/config.js` understands but the form never
+  // shows is an invisible setting, which is just as bad as a dead one.
+  const runtime = resolveConfig({})
+  const shown = new Set(walk(defaults).map(([key]) => key))
+  const hidden = walk(runtime)
+    .map(([key]) => key)
+    .filter((key) => key !== 'vaultDir' && !shown.has(key))
+  assert.deepEqual(hidden, [])
+})
+
+check('the runtime still fills what the form leaves blank', () => {
+  const runtime = resolveConfig({})
+  assert.equal(runtime.vaultDir, path.join(process.env.USERPROFILE ?? process.env.HOME ?? '', 'dsh-memory'))
+  // A blank model is a real answer in harness mode: `resolveRoute` says what is
+  // missing instead of quietly calling a different model than the user picked.
+  assert.equal(runtime.extractor.model, '')
+  // And http mode keeps its friendly default.
+  assert.equal(resolveConfig({ extractor: { transport: 'http' } }).extractor.model, 'deepseek-chat')
+})
+
+check('the transport union accepts exactly the two documented values', () => {
+  assert.equal(unwrapConfig(Config({ extractor: { transport: 'http' } })).extractor.transport, 'http')
+  assert.equal(unwrapConfig(Config({ extractor: { transport: 'harness' } })).extractor.transport, 'harness')
+  assert.throws(() => Config({ extractor: { transport: 'openai' } }))
+})
+
+check('numeric bounds reject what the runtime would silently clamp', () => {
+  assert.throws(() => Config({ extractor: { maxOutputTokens: 3000.5 } }), /256|multiple|step/)
+  assert.throws(() => Config({ retrieval: { hops: 3 } }))
+  // Values the runtime accepts must be accepted by the form too, or the form
+  // cannot express a config the plugin supports.
+  assert.equal(unwrapConfig(Config({ extractor: { maxOutputTokens: 3000 } })).extractor.maxOutputTokens, 3000)
+  assert.equal(unwrapConfig(Config({ retrieval: { hops: 2 } })).retrieval.hops, 2)
+})
+
+check('the inline key is marked secret so the form can mask it', () => {
+  const json = Config.toJSON()
+  const text = JSON.stringify(json)
+  assert.match(text, /"apiKey"/)
+  assert.match(text, /"secret"/)
+  assert.equal(Object.keys(json.refs ?? {}).length > 0, true, 'a schema with refs is what the Settings form projects')
+})
+
+check('every setting appears in the projected schema', () => {
+  const text = JSON.stringify(Config.toJSON())
+  const names = [
+    'enabled',
+    'vaultDir',
+    'defaultProject',
+    'crossProject',
+    'capture',
+    'userChars',
+    'assistantChars',
+    'includeToolOutput',
+    'minChars',
+    'skipPatterns',
+    'privacy',
+    'useDefaultPatterns',
+    'denyPatterns',
+    'redactEmails',
+    'redactPaths',
+    'extractor',
+    'transport',
+    'useCurrentModel',
+    'provider',
+    'reasoningEffort',
+    'baseUrl',
+    'path',
+    'model',
+    'apiKeyEnv',
+    'apiKey',
+    'maxOutputTokens',
+    'temperature',
+    'timeoutMs',
+    'maxEpisodesPerRun',
+    'retrieval',
+    'limit',
+    'hops',
+    'snippetChars',
+    'timelineLimit',
+  ]
+  const missing = names.filter((name) => !text.includes(`"${name}"`))
+  assert.deepEqual(missing, [])
+})
+
+check('a distilling config round-trips from the form into the runtime', () => {
+  const runtime = resolveConfig(Config({ extractor: { enabled: true, transport: 'harness', reasoningEffort: 'high' } }))
+  assert.equal(runtime.extractor.enabled, true)
+  assert.equal(runtime.extractor.transport, 'harness')
+  assert.equal(runtime.extractor.reasoningEffort, 'high')
+})
+
+// ---------------------------------------------------------------------------
+// The volatile / structural split
+// ---------------------------------------------------------------------------
+
+const leaves = schemaLeaves(Config)
+const live = leaves.filter((leaf) => leaf.node.meta?.volatile === true)
+const structural = leaves.filter((leaf) => leaf.node.meta?.volatile !== true)
+
+check('the live knobs are volatile, which is the only thing 设置 can write', () => {
+  // `volatileForm()` in dsh-settings returns undefined unless some leaf is
+  // volatile, and an undefined form means the entry does not appear in 设置 at
+  // all — this is the check that would have caught the empty settings page.
+  assert.equal(
+    live.length,
+    spec.paths.length,
+    `expected one volatile leaf per page field, found ${live.length} live leaves for ${spec.paths.length} fields`,
+  )
+  assert.equal(
+    structural.length,
+    4,
+    `only enabled / vaultDir / defaultProject / crossProject stay ordinary, found ${structural.length}`,
+  )
+  assert.deepEqual(
+    live.map((leaf) => leaf.path).sort(),
+    [...spec.paths].sort(),
+    'the page and the schema must serve the same live fields',
+  )
+})
+
+check('the structural knobs stay ordinary so a change remounts the plugin', () => {
+  // They are consumed while activating (register tools, mkdir the vault, tag the
+  // session). A live write could not take effect, so they must not be volatile —
+  // and the page must say so instead of offering a switch that does nothing.
+  assert.deepEqual(structural.map((leaf) => leaf.path).sort(), ['crossProject', 'defaultProject', 'enabled', 'vaultDir'])
+  for (const knob of spec.structural) {
+    assert.ok(!spec.paths.includes(knob), `${knob} is structural and must not be on the Settings page`)
+  }
+})
+
+check('the page agrees with the schema about numbers', () => {
+  const byPath = new Map(leaves.map((leaf) => [leaf.path, leaf.node]))
+  for (const section of spec.sections) {
+    for (const field of section.fields) {
+      const node = byPath.get(field.path.join('.'))
+      assert.ok(node, `page field ${field.path.join('.')} is not in the schema`)
+      if (field.type !== 'number') continue
+      const bounds = node.meta ?? {}
+      assert.equal(field.min, bounds.min, `${field.path.join('.')}: page min disagrees with the schema`)
+      assert.equal(field.max, bounds.max, `${field.path.join('.')}: page max disagrees with the schema`)
+    }
+  }
+})
+
+check('every page field is rendered from something the form serves', () => {
+  const seen = new Set()
+  for (const section of spec.sections) {
+    for (const field of section.fields) {
+      const key = field.path.join('.')
+      assert.ok(!seen.has(key), `${key} is rendered twice`)
+      assert.ok(field.label, `${key} has no label`)
+      seen.add(key)
+    }
+  }
+  assert.equal(seen.size, spec.paths.length)
+})
+
+console.log(process.exitCode === 1 ? '\nSOME CHECKS FAILED' : `\nall ${passed} checks passed`)

package/test/smoke.mjs

@@ -0,0 +1,428 @@
+/**
+ * Smoke test: no network, no harness, no dependencies.
+ *   node test/smoke.mjs
+ * Exercises the vault, the redactor, retrieval and the supersede chain.
+ */
+import assert from 'node:assert/strict'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+import { resolveConfig } from '../src/config.js'
+import { createRedactor } from '../src/privacy.js'
+import { createVault, NEAR_DUPLICATE, titleSimilarity } from '../src/vault.js'
+import { searchCards, timelineCards, tokenize } from '../src/search.js'
+import { buildPrompt, parseCards } from '../src/extract.js'
+import { renderGraphHtml } from '../src/graph.js'
+
+const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'memgraph-'))
+const cfg = resolveConfig({ vaultDir: dir, extractor: { enabled: true } })
+const redactor = createRedactor(cfg.privacy)
+const vault = createVault(cfg, redactor)
+
+const results = []
+function check(name, fn) {
+  try {
+    fn()
+    results.push(`  ok   ${name}`)
+  } catch (error) {
+    results.push(`  FAIL ${name}: ${error.message}`)
+    process.exitCode = 1
+  }
+}
+
+/* ------------------------------------------------------------------ redactor */
+check('redacts api keys', () => {
+  const { text, hits } = redactor.redact('key is sk-abcdefghijklmnopqrstuvwxyz012345 and that is it')
+  assert.equal(text.includes('sk-abcdefghij'), false, text)
+  assert.ok(text.includes('[REDACTED]'), text)
+  assert.ok(hits.length > 0)
+})
+check('redacts emails', () => {
+  assert.equal(redactor.redact('mail me at a.b@example.com').text, 'mail me at [email]')
+})
+check('redacts home path', () => {
+  const { text } = redactor.redact(`config in ${os.homedir()}/x/y`)
+  assert.equal(text, 'config in ~/x/y')
+})
+check('leaves normal prose intact', () => {
+  const prose = '我们把存储从 SQLite 换成了纯文本，因为要能 diff。'
+  assert.equal(redactor.redact(prose).text, prose)
+})
+
+/* ------------------------------------------------------------------ tokenize */
+check('tokenize latin + cjk', () => {
+  const tokens = tokenize('记忆图谱 memory graph 用纯文本存储')
+  assert.ok(tokens.includes('memory'), tokens.join(','))
+  assert.ok(tokens.includes('纯文'), tokens.join(','))
+  assert.ok(!tokens.includes('的'), 'stopword should be dropped')
+})
+
+/* ------------------------------------------------------------------ write */
+const { card: storage, deduped: firstDeduped } = await vault.saveCard({
+  kind: 'decision',
+  title: '记忆存储用纯文本而不是 SQLite',
+  body: 'SQLite 要处理锁和二进制合并。纯文本可以直接 grep、直接读、直接备份。',
+  entities: ['memory-graph', 'vault格式', 'sqlite'],
+  confidence: 'user_stated',
+  project: 'memory-graph',
+  source: { kind: 'agent' },
+})
+check('writes a card', () => {
+  assert.equal(firstDeduped, false)
+  assert.match(storage.id, /^c-\d{8}-[0-9a-f]{4}$/)
+})
+
+const { card: again, deduped: secondDeduped } = await vault.saveCard({
+  kind: 'decision',
+  title: '记忆存储用纯文本而不是 SQLite。',
+  body: '短一点的重复内容',
+  entities: ['vault格式'],
+  project: 'memory-graph',
+})
+check('re-confirms an identical card instead of duplicating', () => {
+  assert.equal(secondDeduped, true)
+  assert.equal(again.id, storage.id)
+})
+
+/* ------------------------------------------------- near-duplicate titles */
+check('titleSimilarity scores identical and unrelated titles at the ends', () => {
+  assert.equal(titleSimilarity('检索用 BM25', '检索用 BM25'), 1)
+  assert.equal(titleSimilarity('检索用 BM25', '监控从 Zabbix 换到 Uptime Kuma'), 0)
+  assert.equal(titleSimilarity('', 'anything'), 0)
+  const related = titleSimilarity('蒸馏走独立模型接口', '蒸馏用独立模型接口')
+  assert.ok(related > NEAR_DUPLICATE, `related re-wordings must clear the threshold, got ${related}`)
+})
+
+const reworded = await vault.saveCard({
+  kind: 'decision',
+  title: '记忆存储用纯文本而非 SQLite 数据库',
+  body: '纯文本可以 grep、可以 diff、可以随时删除，也不用处理二进制合并。',
+  entities: ['vault格式'],
+  project: 'memory-graph',
+})
+check('a re-worded title re-confirms the card instead of forking the graph', () => {
+  assert.equal(reworded.deduped, true)
+  assert.equal(reworded.card.id, storage.id)
+  assert.equal(reworded.card.title, storage.title, 'the older wording wins, so ids stay stable')
+  assert.match(reworded.card.body, /grep/, 'a fuller body still lands')
+})
+
+const neighbour = await vault.saveCard({
+  kind: 'decision',
+  title: '监控从 Zabbix 换到 Uptime Kuma',
+  body: '外部拨测换成 Kuma，Zabbix 只留下历史数据。',
+  entities: ['监控'],
+  project: 'memory-graph',
+})
+check('a neighbouring topic in the same project stays its own card', () => {
+  assert.equal(neighbour.deduped, false)
+  assert.notEqual(neighbour.card.id, storage.id)
+})
+
+const twin = await vault.saveCard({
+  kind: 'decision',
+  title: '记忆存储用纯文本不仅不是 SQLite',
+  body: '另一个项目的同名记忆不该被跨项目吞掉。',
+  entities: [],
+  project: 'other-project',
+})
+check('dedupe never crosses projects', () => {
+  assert.equal(twin.deduped, false)
+  assert.equal(twin.card.project, 'other-project')
+})
+
+const reversal = await vault.saveCard({
+  kind: 'decision',
+  title: '监控从 Uptime Kuma 换到 Prometheus + Grafana',
+  body: 'Kuma 只留外部拨测。',
+  entities: ['监控'],
+  project: 'memory-graph',
+  supersedes: [neighbour.card.id],
+})
+check('a reversal that names its predecessor is a new card, not a duplicate', () => {
+  assert.equal(reversal.deduped, false)
+  assert.notEqual(reversal.card.id, neighbour.card.id)
+})
+
+const { card: otherProject } = await vault.saveCard({
+  kind: 'preference',
+  title: '用户希望所有插件零依赖且不依赖构建步骤',
+  body: '不需要 bundler，装到哪个 profile 都能直接跑。',
+  entities: ['dsh插件', '零依赖'],
+  confidence: 'user_stated',
+  project: 'other-project',
+})
+
+const { card: privacy } = await vault.saveCard({
+  kind: 'fact',
+  title: '记忆写入前必须过滤凭据',
+  body: '内置规则覆盖 sk- / ghp_ / 私钥块；命中即替换为 [REDACTED]。',
+  entities: ['vault格式', '隐私边界', 'dsh插件'],
+  confidence: 'user_stated',
+  project: 'memory-graph',
+})
+
+
+/* ------------------------------------------------------------------ supersede */
+const { card: replaced } = await vault.saveCard({
+  kind: 'decision',
+  title: '抽取模型默认关闭',
+  body: '第一版打算默认开启蒸馏。',
+  entities: ['抽取器'],
+  project: 'memory-graph',
+})
+const { card: replacement } = await vault.saveCard({
+  kind: 'decision',
+  title: '抽取模型默认关闭，改用显式调用',
+  body: '默认开启会在用户不知情时产生 API 费用。改成只有 memory_distill 才调用。',
+  entities: ['抽取器', '隐私边界'],
+  project: 'memory-graph',
+  supersedes: [replaced.id],
+})
+
+/* ------------------------------------------------------------------ search */
+const cards = await vault.listCards({ includeRetracted: true })
+const hits = searchCards(cards, '为什么不用 sqlite 存记忆', { limit: 5, hops: 1 })
+check('finds the storage decision', () => {
+  assert.ok(hits.length > 0, 'no hits')
+  assert.equal(hits[0].card.id, storage.id, `got ${hits[0].card.title}`)
+})
+check('keyword search is project-agnostic', () => {
+  const crossHits = searchCards(cards, '零依赖 插件', { limit: 5, hops: 1 })
+  assert.ok(crossHits.some((hit) => hit.card.id === otherProject.id), 'cross-project miss')
+})
+check('entity expansion pulls in a linked neighbour', () => {
+  const linked = searchCards(cards, 'vault格式', { limit: 10, hops: 1 })
+  const ids = linked.map((hit) => hit.card.id)
+  assert.ok(ids.includes(storage.id) && ids.includes(privacy.id), ids.join(','))
+})
+check('superseded card is demoted but still findable', () => {
+  const chain = searchCards(cards, '抽取模型默认关闭', { limit: 5, hops: 0 })
+  const ids = chain.map((hit) => hit.card.id)
+  assert.ok(ids.includes(replacement.id), ids.join(','))
+  const old = cards.find((card) => card.id === replaced.id)
+  assert.equal(old.status, 'superseded')
+  assert.equal(old.supersededBy, replacement.id)
+  assert.ok(old.validTo, 'superseded card needs a valid_to')
+})
+check('no-match query degrades to recency, not an error', () => {
+  const none = searchCards(cards, '完全无关的词组zzz', { limit: 3, hops: 0 })
+  assert.ok(Array.isArray(none))
+})
+
+/* ------------------------------------------------------------------ timeline */
+const timeline = timelineCards(cards, { limit: 10, entity: 'vault格式' })
+check('timeline filters by entity', () => {
+  assert.ok(timeline.length >= 2, String(timeline.length))
+  assert.ok(timeline.every((card) => card.entities.includes('vault格式')))
+})
+
+/* ------------------------------------------------------------------ entities */
+const entities = await vault.listEntities()
+check('one page per entity, with mentions', () => {
+  const vaultFormat = entities.find((entity) => entity.slug === 'vault格式')
+  assert.ok(vaultFormat, entities.map((e) => e.slug).join(','))
+  assert.ok(vaultFormat.mentions.length >= 2, String(vaultFormat.mentions.length))
+})
+check('one entity carries memories from several projects', () => {
+  const hub = entities.find((entity) => entity.slug === 'dsh插件')
+  assert.ok(hub, 'shared entity missing')
+  const touched = new Set(hub.mentions.map((mention) => mention.cardId))
+  const projects = new Set(cards.filter((card) => touched.has(card.id)).map((card) => card.project))
+  assert.ok(projects.size >= 2, [...projects].join(','))
+})
+
+/* ------------------------------------------------------------------ episodes */
+await vault.appendEpisode({ t: '2026-11-02T10:00:00+08:00', project: 'p', session: 's1', turn: 1, user: 'hello there friend', assistant: 'hi' })
+await vault.appendEpisode({ t: '2026-11-02T10:05:00+08:00', project: 'p', session: 's1', turn: 2, user: 'second message', assistant: 'ok' })
+const pending = await vault.readUndistilled(10)
+check('undistilled episodes are read from the cursor', () => {
+  assert.equal(pending.length, 2, String(pending.length))
+})
+await vault.markDistilled(pending)
+const after = await vault.readUndistilled(10)
+check('cursor leaves nothing pending', () => {
+  assert.equal(after.length, 0, String(after.length))
+})
+
+/* ------------------------------------------------------------------ extract parsing */
+check('parses a fenced json reply', () => {
+  const reply = '```json\n{"cards":[{"kind":"fact","title":"存储是纯文本","body":"因为要能 diff。","entities":["vault格式"],"confidence":"user_stated"}]}\n```'
+  const { cards: parsed } = parseCards(reply)
+  assert.equal(parsed.length, 1)
+  assert.equal(parsed[0].kind, 'fact')
+  assert.equal(parsed[0].title, '存储是纯文本')
+})
+check('parses json with prose around it', () => {
+  const { cards: parsed } = parseCards('Sure. {"cards":[]} done.')
+  assert.equal(parsed.length, 0)
+})
+check('survives a non-json reply', () => {
+  const { cards: parsed, skipped } = parseCards('I could not find anything durable.')
+  assert.equal(parsed.length, 0)
+  assert.ok(skipped)
+})
+check('drops invalid kinds and keeps valid ones', () => {
+  const { cards: parsed } = parseCards('{"cards":[{"kind":"garbage","title":"a","body":"b"},{"kind":"open_question","title":"c","body":"d"}]}')
+  assert.equal(parsed.length, 2)
+  assert.equal(parsed[0].kind, 'note')
+  assert.equal(parsed[1].kind, 'open_question')
+})
+check('rejects supersedes ids that are not card ids', () => {
+  const { cards: parsed } = parseCards('{"cards":[{"kind":"fact","title":"a","body":"b","supersedes":["not-an-id","c-20261102-abcd"]}]}')
+  assert.deepEqual(parsed[0].supersedes, ['c-20261102-abcd'])
+})
+const prompt = buildPrompt(pending, cards, 'memory-graph')
+check('prompt carries the transcript and existing ids', () => {
+  assert.equal(prompt.length, 2)
+  assert.ok(prompt[1].content.includes('hello there friend'))
+  assert.ok(prompt[1].content.includes(storage.id), 'existing ids should be offered for supersedes')
+})
+
+/* ------------------------------------------------------------------ config */
+check('a broken skip pattern is dropped instead of disabling capture', () => {
+  const bad = resolveConfig({ capture: { skipPatterns: ['^Real prompt', '[unclosed'] } })
+  assert.deepEqual(bad.capture.skipPatterns, ['^Real prompt'])
+})
+check('injection defaults are present out of the box', () => {
+  const plain = resolveConfig({})
+  assert.equal(plain.capture.skipPatterns.some((p) => p.includes('checkpoint')), true)
+  assert.equal(plain.capture.skipPatterns.some((p) => p.includes('system-reminder')), true)
+})
+
+/* ------------------------------------------------------------------ readme + stats */
+await vault.regenerateReadme()
+const readme = await fsp.readFile(path.join(dir, 'README.md'), 'utf8')
+check('README is generated and links cards', () => {
+  assert.ok(readme.includes('# Memory vault'), readme.slice(0, 120))
+  assert.ok(readme.includes('记忆库'), 'the vault index should be readable in Chinese too')
+  assert.ok(readme.includes(storage.id), 'readme should link cards')
+  assert.ok(readme.includes('## memory-graph'))
+})
+const stats = await vault.stats()
+check('stats count accurately', () => {
+  assert.ok(stats.cards.total >= 5, String(stats.cards.total))
+  assert.ok(stats.cards.superseded >= 1)
+  assert.ok(stats.entities >= 4)
+  assert.ok(stats.projects.includes('memory-graph'))
+  assert.equal(stats.episodes.records, 2)
+})
+
+const gitignore = await fsp.readFile(path.join(dir, '.gitignore'), 'utf8')
+check('the vault carries a .gitignore for its own repo', () => {
+  assert.ok(gitignore.includes('.distill-state.json'), gitignore)
+})
+
+/* ------------------------------------------------------------------ forget */
+await vault.retractCard(privacy.id, 'test retraction')
+const retracted = await vault.getCard(privacy.id)
+const visibleCards = await vault.listCards()
+const retractedHits = searchCards(visibleCards, '凭据 过滤', { limit: 5 })
+check('retract keeps the file and sets status', () => {
+  assert.equal(retracted.status, 'retracted')
+  assert.ok(!retractedHits.some((hit) => hit.card.id === privacy.id), 'retracted card should not surface')
+})
+await vault.purgeCard(privacy.id)
+
+const stillThere = await vault.getCard(privacy.id)
+check('purged card is gone', () => {
+  assert.equal(stillThere, null)
+})
+
+/* ------------------------------------------------------------------ graph */
+const graphOut = await vault.regenerateGraph()
+const graphHtml = await fsp.readFile(graphOut.file, 'utf8')
+const graphCards = await vault.listCards({ includeRetracted: true })
+const graphEntities = await vault.listEntities()
+const graphProjects = await vault.listProjects()
+
+check('regenerateGraph writes graph.html', () => {
+  assert.equal(graphOut.file, path.join(dir, 'graph.html'))
+  assert.equal(graphOut.bytes, Buffer.byteLength(graphHtml, 'utf8'))
+  assert.equal(graphOut.cards, graphCards.length)
+  assert.equal(graphOut.entities, graphEntities.length)
+})
+check('graph.html is a self-contained page', () => {
+  assert.ok(graphHtml.length > 5000, `only ${graphHtml.length} bytes`)
+  assert.ok(graphHtml.startsWith('<!doctype html>'), graphHtml.slice(0, 40))
+  assert.ok(graphHtml.includes('<svg'), 'the canvas should be inline svg')
+  assert.ok(graphHtml.includes('记忆图'), 'the header should name the view')
+})
+check('graph carries every card and entity', () => {
+  for (const card of graphCards) assert.ok(graphHtml.includes(card.id), card.id)
+  for (const entity of graphEntities) assert.ok(graphHtml.includes(entity.slug), entity.slug)
+  for (const label of ['决策', '事实', '待解', '偏好', '记录', '实体']) {
+    assert.ok(graphHtml.includes(label), `the legend should name ${label}`)
+  }
+})
+check('graph loads nothing from the network', () => {
+  for (const bad of ['http://', 'https://', 'src=', '@import', 'url(http']) {
+    assert.equal(graphHtml.includes(bad), false, `graph.html must not contain ${bad}`)
+  }
+})
+
+const inlineScript = graphHtml.match(/<script>([\s\S]*?)<\/script>/)
+const inlineFile = path.join(dir, 'graph-inline.mjs')
+await fsp.writeFile(inlineFile, inlineScript ? inlineScript[1] : '', 'utf8')
+const inlineParse = spawnSync(process.execPath, ['--check', inlineFile], { encoding: 'utf8' })
+check('the inline script parses', () => {
+  assert.ok(inlineScript, 'graph.html should contain one inline script')
+  assert.equal(inlineParse.status, 0, inlineParse.stderr)
+})
+
+const htmlA = renderGraphHtml({
+  cards: graphCards,
+  entities: graphEntities,
+  projects: graphProjects,
+  generatedAt: '2026-11-02T00:00:00+08:00',
+})
+const htmlB = renderGraphHtml({
+  cards: graphCards,
+  entities: graphEntities,
+  projects: graphProjects,
+  generatedAt: '2026-11-03T09:30:00+08:00',
+})
+check('two renders differ only in the timestamp', () => {
+  assert.equal(
+    htmlA.replace('2026-11-02T00:00:00+08:00', 'T'),
+    htmlB.replace('2026-11-03T09:30:00+08:00', 'T'),
+  )
+})
+
+const emptyDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'memgraph-empty-'))
+const emptyCfg = resolveConfig({ vaultDir: emptyDir })
+const emptyVault = createVault(emptyCfg, createRedactor(emptyCfg.privacy))
+const emptyOut = await emptyVault.regenerateGraph()
+const emptyHtml = await fsp.readFile(emptyOut.file, 'utf8')
+check('an empty vault renders a readable page, not a blank one', () => {
+  assert.equal(emptyOut.cards, 0)
+  assert.ok(emptyHtml.includes('记忆库还是空的'), 'the empty state should explain itself')
+  assert.ok(emptyHtml.length > 4000, `only ${emptyHtml.length} bytes`)
+})
+await emptyVault.saveCard({
+  kind: 'fact',
+  title: '只有一张卡片',
+  body: '一张卡片也能画成一张图。',
+  entities: ['孤岛'],
+  confidence: 'verified',
+})
+const singleOut = await emptyVault.regenerateGraph()
+const singleHtml = await fsp.readFile(singleOut.file, 'utf8')
+check('a one-card vault renders its single neuron', () => {
+  assert.equal(singleOut.cards, 1)
+  assert.equal(singleOut.entities, 1)
+  assert.ok(singleHtml.includes('只有一张卡片'))
+  assert.ok(singleHtml.includes('孤岛'))
+})
+await fsp.rm(emptyDir, { recursive: true, force: true })
+
+console.log(results.join('\n'))
+console.log(`\nvault: ${dir}`)
+if (process.exitCode) {
+  console.log('\nSOME CHECKS FAILED')
+} else {
+  console.log(`\nall ${results.length} checks passed`)
+  await fsp.rm(dir, { recursive: true, force: true })
+}