@ilaomianyang/dsh-memory-graph 0.10.0

package/index.js

@@ -0,0 +1,243 @@
+/**
+ * dsh-memory-graph — associative long-term memory for DeepSeek Harness.
+ *
+ * Design in one paragraph: the session log already remembers everything and
+ * gets compacted away. This plugin keeps a second, durable layer outside the
+ * context window: raw episodes (never distilled, never lost), typed memory
+ * cards with temporal validity and a supersede chain, and one page per entity
+ * so separate projects connect through the things they share. Retrieval is
+ * explicit — the agent asks — so nothing is injected into a turn that does not
+ * need it. Storage is plain files under one directory: readable, portable,
+ * greppable, and owned by the user.
+ *
+ * Configuration has two doors. The profile's `cordis.patch.yml` is the durable
+ * record (hand-written, or written by 设置 → 记忆图谱); the fields marked
+ * `.volatile()` in `src/schema.js` can also be edited there while the plugin
+ * runs. A volatile-only write does not remount the plugin: the Loader updates the
+ * live references in place and emits `loader/volatile-update`, and `cfg` below is
+ * refreshed in place so every reader of `cfg.a.b` — capture, tools, extraction,
+ * search — sees the new value on its next call. Structural knobs (`enabled`,
+ * `vaultDir`) stay ordinary on purpose: they are consumed once, so changing one
+ * re-activates the plugin, which is the semantics it needs.
+ */
+import { resolveConfig } from './src/config.js'
+import { createRedactor } from './src/privacy.js'
+import { createVault } from './src/vault.js'
+import { registerTools } from './src/tools.js'
+import { registerCapture } from './src/capture.js'
+import { createGraphHandler, GRAPH_PATH } from './src/graphdata.js'
+import { createDistillHandler, DISTILL_PATH } from './src/distillapi.js'
+import { createPageHandler, PAGE_PATH } from './src/pageapi.js'
+import { createDistillRunner } from './src/distillrun.js'
+import { createAutoDistiller, registerAutoDistill } from './src/auto.js'
+import { extractorServices } from './src/extract.js'
+
+export const name = 'memory-graph'
+export const inject = ['tools']
+
+/**
+ * Settings-form schema.
+ *
+ * The harness draws a plugin's page in 设置 from the schema it exports, and it
+ * builds that schema with its own schemastery. So this one import is the only
+ * dependency the plugin has; it is loaded opportunistically so a checkout that
+ * never ran `npm install` still works — it just has no Settings page and runs on
+ * the defaults in `src/config.js`.
+ */
+let Config
+try {
+  ;({ Config } = await import('./src/schema.js'))
+} catch {
+  Config = undefined
+}
+export { Config }
+
+/**
+ * A redactor whose rules can be replaced while it is in use.
+ *
+ * Handing the plain `createRedactor` result to the vault, the tools and the
+ * extractor would freeze the privacy rules at activation time, because they hold
+ * that object. This wrapper forwards every call to the rules that are current
+ * now, so editing `privacy.*` in 设置 applies to the next string written instead
+ * of the next restart.
+ */
+function createLiveRedactor(cfg) {
+  let current = createRedactor(cfg.privacy)
+  return {
+    redact: (text, where) => current.redact(text, where),
+    get ruleCount() {
+      return current.ruleCount
+    },
+    rebuild() {
+      current = createRedactor(cfg.privacy)
+    },
+  }
+}
+
+export function apply(ctx, config) {
+  const cfg = resolveConfig(config)
+  const redactor = createLiveRedactor(cfg)
+
+  // Re-resolving in place, rather than re-running apply, is what makes a Settings
+  // write land: every consumer holds this one `cfg` object and reads `cfg.a.b` at
+  // call time, so the new values are live with no other file touched. A change to
+  // an ordinary field still remounts the plugin, which is when this listener is
+  // rebuilt against the new activation.
+  ctx.on('loader/volatile-update', () => {
+    try {
+      Object.assign(cfg, resolveConfig(config))
+      redactor.rebuild()
+    } catch {
+      // A half-written config must not break the running plugin: a stale
+      // snapshot is better than a throw on every edit.
+    }
+  })
+
+  if (!cfg.enabled) return
+
+  const vault = createVault(cfg, redactor)
+
+  const log = (level, message) => {
+    try {
+      ctx.logger?.[level]?.(`[memory-graph] ${message}`)
+    } catch {
+      // Logging must never break activation.
+    }
+  }
+
+  ctx.effect(() => {
+    vault
+      .ensure()
+      .then(() => vault.regenerateReadme())
+      .then(() => log('info', `vault ready at ${cfg.vaultDir}`))
+      .catch((error) => log('warn', `vault unavailable at ${cfg.vaultDir}: ${error?.message ?? error}`))
+    return () => {}
+  })
+
+  // One distillation at a time, for the whole plugin. Three callers can ask for
+  // one — the model's tool, the panel's button, and the automatic distiller — and
+  // a distillation spends real model budget while advancing one cursor in the
+  // vault, so they all go through this runner and the second caller is refused
+  // rather than queued.
+  const runner = createDistillRunner({
+    getVault: () => vault,
+    getConfig: () => cfg,
+    getRedactor: () => redactor,
+    getServices: () => extractorServices(ctx),
+    refreshViews: async () => {
+      for (const render of [vault.regenerateReadme, vault.regenerateGraph]) {
+        if (typeof render === 'function') await render.call(vault)
+      }
+    },
+    log,
+  })
+
+  ctx.effect(() => {
+    const disposers = registerTools(ctx, { cfg, vault, redactor, runner })
+    log('info', `${disposers.length} memory tools registered`)
+    return () => {
+      for (const dispose of disposers) {
+        try {
+          dispose()
+        } catch {
+          // Disposal of an already-gone registration is not an error.
+        }
+      }
+    }
+  })
+
+  // The automatic distiller: a tick that decides, never a timer that fires a run.
+  // Both triggers (a threshold of waiting episodes, and "every N minutes") default
+  // to off and are live Settings fields, so the ticker runs whether or not they
+  // are on and simply reads the config each time.
+  ctx.effect(() => {
+    const distiller = createAutoDistiller({ cfg, vault, run: (options) => runner.run(options), log })
+    const stop = registerAutoDistill({ ctx, distiller })
+    log('info', `auto distill ${cfg.auto.enabled ? 'on' : 'off'} (threshold ${cfg.auto.minEpisodes || '—'}, every ${cfg.auto.everyMinutes || '—'} min)`)
+    return () => {
+      try {
+        stop()
+      } catch {
+        // ignore
+      }
+    }
+  })
+
+  ctx.effect(() => {
+    const disposers = registerCapture(ctx, { cfg, vault, redactor })
+    log('info', `episode capture registered (${cfg.capture.enabled ? 'on' : 'off'})`)
+    return () => {
+      for (const dispose of disposers) {
+        try {
+          dispose()
+        } catch {
+          // ignore
+        }
+      }
+    }
+  })
+
+  // The Session memory view's data door: one exact Fetch route on the
+  // authenticated `/api` channel, so the browser sends the cookie it already
+  // holds and Connection rejects anything that is not the owner Peer. Two
+  // deliberate choices here.
+  //
+  // `connection` is optional, not in `inject`: a headless or CLI profile has no
+  // web server and no browser, and the plugin must keep working there — only the
+  // panel is missing. `ctx.inject` keeps the subscription until the service
+  // appears, so a profile that adds the web GUI later still gets the route.
+  //
+  // The disposer is held by this plugin's effect, not by the Connection
+  // service's: uninstalling or disabling the plugin must remove the door.
+  ctx.effect(() => {
+    const disposeInject = ctx.inject(['connection'], (inner) => {
+      const registry = inner.get('connection')?.fetch
+      if (typeof registry?.register !== 'function') {
+        // A build without exact Fetch routes: the plugin keeps working, the tab
+        // explains itself instead of hanging on a request that can never land.
+        log('warn', 'connection.fetch is unavailable; the session memory view has no data route')
+        return () => {}
+      }
+      const disposeRoute = registry.register({
+        path: GRAPH_PATH,
+        methods: ['GET'],
+        requestBody: 'buffered',
+        fetch: createGraphHandler({ getVault: () => vault, getConfig: () => cfg }),
+      })
+      // The button's door. Same distillation the `memory_distill` tool runs,
+      // reached from the panel; POST only, so a page load or a prefetch can never
+      // spend model budget by accident.
+      const disposeDistill = registry.register({
+        path: DISTILL_PATH,
+        methods: ['POST'],
+        requestBody: 'buffered',
+        fetch: createDistillHandler({ getRunner: () => runner }),
+      })
+      // The whole-vault graph, as the page the sidebar panel embeds. GET only and
+      // read-only: it renders from cards already on disk and writes nothing.
+      const disposePage = registry.register({
+        path: PAGE_PATH,
+        methods: ['GET'],
+        requestBody: 'buffered',
+        fetch: createPageHandler({ getVault: () => vault }),
+      })
+      log('info', `session memory view served at ${GRAPH_PATH}, distill at ${DISTILL_PATH}, vault graph page at ${PAGE_PATH}`)
+      return () => {
+        for (const dispose of [disposeRoute, disposeDistill, disposePage]) {
+          try {
+            dispose?.()
+          } catch {
+            // A route already gone is not an error.
+          }
+        }
+      }
+    })
+    return () => {
+      try {
+        disposeInject?.()
+      } catch {
+        // ignore
+      }
+    }
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Memory Graph",
+    "description": "Long-term associative memory in a plain-text vault: episodes, typed cards, entity pages and a timeline. Readable on GitHub, diffable, no database."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "记忆图谱",
+    "description": "以纯文本 vault 保存的长期联想记忆：事件流、带类型的记忆卡片、实体页与时间轴。可直接在 GitHub 阅读、可 diff、不依赖数据库。"
+  }
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@ilaomianyang/dsh-memory-graph",
+  "version": "0.10.0",
+  "type": "module",
+  "author": "ISKING <admin@isking.cc>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilaomianyang/dsh-memory-graph.git"
+  },
+  "homepage": "https://github.com/ilaomianyang/dsh-memory-graph#readme",
+  "bugs": {
+    "url": "https://github.com/ilaomianyang/dsh-memory-graph/issues"
+  },
+  "description": "Long-term associative memory for DeepSeek Harness: a local plain-text vault of raw episodes, typed memory cards and entity pages, configured from 设置 → 记忆图谱, and a Memory tab inside a conversation that draws what that session remembered. No build step; the only dependency is the harness's own schema library, used for the Settings page.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "memory",
+    "long-term-memory",
+    "knowledge-graph",
+    "local-first"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "src/*.js",
+    "test/*.mjs",
+    "eval/*.mjs",
+    "eval/questions.json",
+    "eval/REPORT.md",
+    "cordis.patch.yml",
+    "docs/*.png",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/smoke.mjs && node test/schema.mjs && node test/client.mjs && node test/capture.mjs && node test/tools.mjs && node test/extract.mjs && node test/graphdata.mjs && node test/page.mjs && node test/distillapi.mjs && node test/auto.mjs && node eval/run.mjs",
+    "eval": "node eval/run.mjs",
+    "live": "node test/live.mjs",
+    "live:supersede": "node test/live-supersede.mjs",
+    "check": "node --check index.js",
+    "prepublishOnly": "npm test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": []
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.5"
+  }
+}

package/src/auto.js

@@ -0,0 +1,194 @@
+/**
+ * The automatic distiller: two independently configurable triggers over one tick.
+ *
+ * The rule that matters most is that neither trigger is a timer that fires a run.
+ * A tick only ever *decides*, and the decision is a pure function of the config,
+ * the clock, the last attempt and how many episodes are waiting — so the whole
+ * behaviour can be asserted in tests without waiting a minute or spending a token.
+ *
+ * Why the attempt clock is separate from the vault's `lastRun`: a run that
+ * distilled nothing (an empty vault, a model that returned no cards) must still
+ * arm the gap, or a quiet vault would be re-asked on every tick. `lastAttemptAt`
+ * is therefore written before the call, not after it.
+ */
+import { parseQuietHours } from './config.js'
+
+const MINUTE = 60 * 1000
+
+/** Is `now` inside the quiet window? A window may cross midnight. */
+export function inQuietHours(window, now) {
+  const bounds = parseQuietHours(window)
+  if (bounds === null) return false
+  const date = new Date(now)
+  const minutes = date.getHours() * 60 + date.getMinutes()
+  if (bounds.from === bounds.to) return false
+  // 23:00-08:00 wraps: quiet when at-or-after the start, or before the end.
+  return bounds.from < bounds.to
+    ? minutes >= bounds.from && minutes < bounds.to
+    : minutes >= bounds.from || minutes < bounds.to
+}
+
+/**
+ * Should this tick run a distillation? Pure, so the rules are readable in one
+ * place and testable without a clock.
+ *
+ * @param {object} input
+ * @param {object} input.auto        the `auto` config group
+ * @param {number} input.now         epoch ms
+ * @param {number|null} input.lastAttemptAt  epoch ms of the previous attempt
+ * @param {number} input.pending     undistilled episodes waiting
+ * @returns {{due: boolean, rule: string|null, reason: string}}
+ */
+export function autoDecision({ auto, now, lastAttemptAt = null, startedAt = null, pending = 0 }) {
+  if (auto?.enabled !== true) return { due: false, rule: null, reason: 'auto is off' }
+  if (pending <= 0) return { due: false, rule: null, reason: 'nothing to distill' }
+  if (inQuietHours(auto.quietHours, now)) return { due: false, rule: null, reason: 'quiet hours' }
+
+  // Two different clocks, on purpose:
+  //   * the gap measures time since the last *run* (nothing else);
+  //   * the schedule measures time since the last run, or since the clock was
+  //     started when there has not been one yet.
+  // `null` for either means "not started", and a schedule with no clock is never
+  // overdue — turning a daily schedule on must not spend on the spot. The
+  // threshold rule ignores both clocks: its trigger is the pile, not the time.
+  const sinceRun = lastAttemptAt === null ? null : now - lastAttemptAt
+  const clock = lastAttemptAt ?? startedAt
+  const sinceClock = clock === null ? null : now - clock
+
+  const gap = (auto.minGapMinutes ?? 0) * MINUTE
+  if (gap > 0 && sinceRun !== null && sinceRun < gap) {
+    return { due: false, rule: null, reason: 'the gap between runs has not elapsed' }
+  }
+
+  // Schedule rule: due once `everyMinutes` have passed on its own clock.
+  if ((auto.everyMinutes ?? 0) > 0 && sinceClock !== null && sinceClock >= auto.everyMinutes * MINUTE) {
+    return { due: true, rule: 'schedule', reason: `every ${auto.everyMinutes} minute(s)` }
+  }
+
+  // Threshold rule: enough quiet episodes have piled up.
+  if ((auto.minEpisodes ?? 0) > 0 && pending >= auto.minEpisodes) {
+    return { due: true, rule: 'threshold', reason: `${pending} episode(s) waiting, threshold ${auto.minEpisodes}` }
+  }
+
+  return { due: false, rule: null, reason: 'nothing is due yet' }
+}
+
+/**
+ * The ticker.
+ *
+ * `run` is the shared runner from `src/distillrun.js`, so an automatic run and a
+ * pressed button can never overlap. The state file lives in the vault so an app
+ * restart does not reset the gap and fire a run on every launch.
+ */
+export function createAutoDistiller({ cfg, vault, run, log = () => {}, now = () => Date.now() }) {
+  let loaded = false
+  let lastAttemptAt = null
+  let startedAt = null
+  let lastReport = null
+
+  async function loadState() {
+    if (loaded) return
+    loaded = true
+    try {
+      const state = await vault.readAutoState?.()
+      const attempt = Number(state?.lastAttemptAt)
+      const start = Number(state?.startedAt)
+      lastAttemptAt = Number.isFinite(attempt) && attempt > 0 ? attempt : null
+      startedAt = Number.isFinite(start) && start > 0 ? start : null
+    } catch (error) {
+      log('warn', `auto: could not read .auto-state.json: ${error?.message ?? error}`)
+    }
+  }
+
+  /** One decision, and at most one run. Returns what it decided, for the tests. */
+  async function tick() {
+    const auto = cfg.auto ?? {}
+    await loadState()
+    if (auto.enabled !== true) return { due: false, rule: null, reason: 'auto is off', ran: false }
+
+    let pending = 0
+    try {
+      const batch = await vault.readUndistilled(Math.max(1, auto.minEpisodes ?? 0, cfg.extractor?.maxEpisodesPerRun ?? 40))
+      pending = Array.isArray(batch) ? batch.length : 0
+    } catch (error) {
+      log('warn', `auto: could not count undistilled episodes: ${error?.message ?? error}`)
+      return { due: false, rule: null, reason: 'the vault could not be read', ran: false }
+    }
+
+    const at = now()
+    // Start the schedule's clock when it has none yet (just switched on, or a
+    // fresh install) instead of treating it as overdue: switching a daily
+    // schedule on must not spend before the first interval has even passed. This
+    // is a separate field from `lastAttemptAt` so it does not arm the gap and
+    // delay the threshold rule, which has nothing to do with the clock.
+    if ((auto.everyMinutes ?? 0) > 0 && lastAttemptAt === null && startedAt === null) {
+      startedAt = at
+      try {
+        await vault.writeAutoState?.({ startedAt: at })
+      } catch (error) {
+        log('warn', `auto: could not start the schedule clock: ${error?.message ?? error}`)
+      }
+    }
+
+    const decision = autoDecision({ auto, now: at, lastAttemptAt, startedAt, pending })
+    if (!decision.due) return { ...decision, pending, ran: false }
+
+    // Arm the gap before the call: a slow or failing run must not be retried on
+    // the next tick.
+    lastAttemptAt = at
+    try {
+      await vault.writeAutoState?.({ lastAttemptAt: at })
+    } catch (error) {
+      log('warn', `auto: could not record the attempt: ${error?.message ?? error}`)
+    }
+
+    const report = await run({ project: auto.project ? String(auto.project) : undefined })
+    lastReport = report
+    if (report?.busy === true) {
+      log('info', 'auto: skipped, a distillation is already running')
+    } else if (report?.ok === true) {
+      log(
+        'info',
+        `auto (${decision.rule}): read ${report.episodes} episode(s) → wrote ${report.written} card(s)` +
+          (report.model ? ` · ${report.model}` : ''),
+      )
+    } else {
+      log('warn', `auto (${decision.rule}): ${report?.message ?? report?.reason ?? 'did not run'}`)
+    }
+    return { ...decision, pending, ran: true, report }
+  }
+
+  /** What the ticker knows, for a diagnostics line or a test. */
+  function state() {
+    return { lastAttemptAt, lastReport }
+  }
+
+  return { tick, state }
+}
+
+/**
+ * Wire the ticker to the plugin's lifetime.
+ *
+ * The interval runs even when auto is off — it reads one boolean and returns —
+ * because `auto.enabled` is a live Settings field, and a ticker that only started
+ * when the plugin mounted would never see it switched on.
+ */
+export function registerAutoDistill({ ctx, distiller, intervalMs = 60000 }) {
+  const timer = setInterval(() => {
+    distiller.tick().catch(() => {
+      // tick() already logs its own failures; a rejected promise must not become
+      // an unhandled rejection that takes the host down.
+    })
+  }, intervalMs)
+  // Do not wait a whole interval after activation to notice a rule that is
+  // already due (a restart with a threshold already met).
+  const first = setTimeout(() => {
+    distiller.tick().catch(() => {})
+  }, 5000)
+  if (typeof timer.unref === 'function') timer.unref()
+  if (typeof first.unref === 'function') first.unref()
+  return () => {
+    clearInterval(timer)
+    clearTimeout(first)
+  }
+}