dsh-memory-ledger 0.0.0-stage → 1.0.0

package/ledger.js

@@ -0,0 +1,352 @@
+/**
+ * Multi-scope ledger for the `dsh-memory-ledger` bundle.
+ *
+ * Two scopes exist:
+ *
+ * - `user`    — `<dataDir>/memory.json`: settings and lessons that hold
+ *               everywhere (the person, not the project).
+ * - `project` — `<dataDir>/projects/<slug>.json`: one file per working
+ *               directory, keyed by its path so two checkouts never mix.
+ *
+ * The hub loads the files lazily, keeps the per-file stores alive for the
+ * process, and combines them for the prompt section, the tools, and the UI.
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { MemoryStore, entryMatches, rankEntries, renderConstraints, renderPromptSection } from './store.js'
+
+/** Scopes a caller may address explicitly. */
+export const SCOPES = ['user', 'project']
+
+/**
+ * Stable, human-scannable file name for one working directory.
+ * @param {string} cwd Absolute working directory.
+ * @returns {string} `<readable-basename>-<hash8>`.
+ */
+export function projectSlug(cwd) {
+  const text = String(cwd ?? '').trim()
+  const readable = basename(text.replace(/[\\/]+$/u, ''))
+    .replace(/[^A-Za-z0-9._-]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, 32)
+  const hash = createHash('sha1').update(text.toLowerCase()).digest('hex').slice(0, 8)
+  return `${readable === '' ? 'project' : readable}-${hash}`
+}
+
+/** Merge two incident lists by signature, summing repeats. */
+function mergeIncidents(lists) {
+  const merged = new Map()
+  for (const list of lists) {
+    for (const incident of list) {
+      const existing = merged.get(incident.signature)
+      if (existing === undefined) {
+        merged.set(incident.signature, { ...incident, handled: incident.handled === true })
+        continue
+      }
+      existing.count += incident.count
+      existing.handled = existing.handled && incident.handled === true
+      if (String(incident.lastSeenAt) > String(existing.lastSeenAt)) existing.lastSeenAt = incident.lastSeenAt
+    }
+  }
+  return [...merged.values()]
+}
+
+/**
+ * All ledgers for one data directory.
+ */
+export class LedgerHub {
+  /**
+   * @param {object} options
+   * @param {string} options.dir Data directory.
+   * @param {{ warn?: (message: string) => void }} [options.logger]
+   */
+  constructor({ dir, logger = null }) {
+    this.dir = dir
+    this.logger = logger
+    this.stores = new Map()
+  }
+
+  /** @returns {string} Path of the user-scope ledger. */
+  get userPath() {
+    return join(this.dir, 'memory.json')
+  }
+
+  /** @returns {string} Directory holding per-project ledgers. */
+  get projectsDir() {
+    return join(this.dir, 'projects')
+  }
+
+  /** @returns {MemoryStore} The user-scope ledger. */
+  user() {
+    let store = this.stores.get('user')
+    if (store === undefined) {
+      store = new MemoryStore({ file: this.userPath, scope: 'user', logger: this.logger })
+      this.stores.set('user', store)
+    }
+    return store
+  }
+
+  /**
+   * The ledger for one working directory.
+   * @param {string} cwd Absolute working directory.
+   * @returns {MemoryStore}
+   */
+  project(cwd) {
+    const slug = projectSlug(cwd)
+    let store = this.stores.get(slug)
+    if (store === undefined) {
+      store = new MemoryStore({
+        file: join(this.projectsDir, `${slug}.json`),
+        scope: 'project',
+        slug,
+        label: cwd,
+        logger: this.logger,
+      })
+      this.stores.set(slug, store)
+    }
+    return store
+  }
+
+  /**
+   * Every project ledger on disk, for the UI.
+   * @returns {Array<{ slug: string, label: string, file: string, facts: number, lessons: number }>}
+   */
+  projects() {
+    const rows = []
+    try {
+      if (!existsSync(this.projectsDir)) return rows
+      for (const name of readdirSync(this.projectsDir)) {
+        if (!name.endsWith('.json')) continue
+        const file = join(this.projectsDir, name)
+        try {
+          const parsed = JSON.parse(readFileSync(file, 'utf8'))
+          const entries = Array.isArray(parsed?.entries) ? parsed.entries : []
+          rows.push({
+            slug: typeof parsed?.slug === 'string' ? parsed.slug : name.replace(/\.json$/u, ''),
+            label: typeof parsed?.label === 'string' ? parsed.label : name.replace(/\.json$/u, ''),
+            file,
+            facts: entries.filter(entry => entry.kind === 'fact' && entry.archived !== true).length,
+            lessons: entries.filter(entry => entry.kind === 'lesson' && entry.archived !== true).length,
+          })
+        } catch {
+          /* a corrupt project file shows up as unreadable, not fatal */
+        }
+      }
+    } catch {
+      /* no projects directory yet */
+    }
+    return rows.sort((a, b) => a.label.localeCompare(b.label))
+  }
+
+  /**
+   * Combine the user ledger with one project ledger for the prompt section.
+   * @param {string | undefined} cwd The session's working directory.
+   * @param {object} [options] Render options forwarded to the store.
+   * @returns {string}
+   */
+  renderFor(cwd, options = {}) {
+    const user = this.user()
+    const scopes = [{ store: user, scope: 'user' }]
+    if (typeof cwd === 'string' && cwd.trim() !== '') {
+      scopes.push({ store: this.project(cwd), scope: 'project' })
+    }
+    const entries = scopes.flatMap(({ store, scope }) =>
+      store.entries().map(entry => ({ ...entry, scope })))
+    const incidents = mergeIncidents(scopes.map(({ store }) => store.incidents()))
+    return renderPromptSection({ entries, incidents }, options)
+  }
+
+  /**
+   * Combine the user ledger with one project ledger for the hard-constraint
+   * section.
+   * @param {string | undefined} cwd The session's working directory.
+   * @param {object} [options] Render options forwarded to the store.
+   * @returns {string}
+   */
+  renderConstraintsFor(cwd, options = {}) {
+    const user = this.user()
+    const entries = user.entries().map(entry => ({ ...entry, scope: 'user' }))
+    if (typeof cwd === 'string' && cwd.trim() !== '') {
+      for (const entry of this.project(cwd).entries()) entries.push({ ...entry, scope: 'project' })
+    }
+    return renderConstraints({ entries }, options)
+  }
+
+  /**
+   * Search across scopes.
+   * @param {object} query
+   * @param {string} [query.text]
+   * @param {'fact'|'lesson'} [query.kind]
+   * @param {string} [query.tags]
+   * @param {number} [query.limit]
+   * @param {string} [query.mode] `hybrid` | `keyword` | `vector`.
+   * @param {string} [query.scope] `auto` | `user` | `project` | `all`.
+   * @param {string} [query.cwd] Session working directory, for `project` and `auto`.
+   * @param {boolean} [query.includeArchived]
+   * @returns {Array<Record<string, unknown>>} Ranked entries with `scope` and `_score`.
+   */
+  search(query = {}) {
+    const scope = ['auto', 'user', 'project', 'all'].includes(String(query.scope))
+      ? String(query.scope)
+      : 'auto'
+    const limit = Math.min(Math.max(Math.trunc(query.limit ?? 10) || 10, 1), 50)
+    const cwd = typeof query.cwd === 'string' ? query.cwd.trim() : ''
+    const targets = []
+    if (scope === 'user' || scope === 'auto' || scope === 'all') {
+      targets.push({ store: this.user(), scope: 'user', label: '' })
+    }
+    if ((scope === 'project' || scope === 'auto' || scope === 'all') && cwd !== '') {
+      const store = this.project(cwd)
+      targets.push({ store, scope: 'project', label: cwd })
+    }
+    if (scope === 'all' && cwd === '') {
+      for (const row of this.projects()) {
+        const store = this.stores.get(row.slug)
+          ?? new MemoryStore({ file: row.file, scope: 'project', slug: row.slug, label: row.label, logger: this.logger })
+        this.stores.set(row.slug, store)
+        targets.push({ store, scope: 'project', label: row.label })
+      }
+    }
+    if (targets.length === 0) return []
+
+    // One candidate pool, one corpus: scores stay comparable across ledgers.
+    const candidates = []
+    for (const target of targets) {
+      for (const entry of target.store.entries()) {
+        if (!entryMatches(entry, query)) continue
+        candidates.push({ ...entry, scope: target.scope, project: target.scope === 'project' ? target.label : '' })
+      }
+    }
+    return rankEntries(candidates, { text: query.text, mode: query.mode, limit: query.limit ?? limit })
+  }
+
+  /**
+   * Write one entry into a scope.
+   * @param {object} input
+   * @param {'user'|'project'} [input.scope]
+   * @param {string} [input.cwd]
+   * @returns {{ entry: Record<string, unknown>, updated: boolean, scope: string }}
+   */
+  upsert(input) {
+    const cwd = typeof input.cwd === 'string' ? input.cwd.trim() : ''
+    let scope = SCOPES.includes(String(input.scope)) ? String(input.scope) : ''
+    if (scope === '') scope = input.kind === 'lesson' && cwd !== '' ? 'project' : 'user'
+    if (scope === 'project' && cwd === '') scope = 'user'
+    const store = scope === 'project' ? this.project(cwd) : this.user()
+    const result = store.upsert(input)
+    return { ...result, scope }
+  }
+
+  /**
+   * Find the store that owns one entry id, loading project ledgers as needed.
+   * @param {string} id
+   * @returns {{ store: MemoryStore, scope: string } | undefined}
+   */
+  locate(id) {
+    for (const store of [this.user(), ...this.liveProjects()]) {
+      if (store.get(id) !== undefined) return { store, scope: store.scope }
+    }
+    for (const row of this.projects()) {
+      let store = this.stores.get(row.slug)
+      if (store === undefined) {
+        store = new MemoryStore({ file: row.file, scope: 'project', slug: row.slug, label: row.label, logger: this.logger })
+        this.stores.set(row.slug, store)
+      }
+      if (store.get(id) !== undefined) return { store, scope: 'project' }
+    }
+    return undefined
+  }
+
+  /**
+   * Edit one entry in place, wherever it lives.
+   * @param {string} id Entry id.
+   * @param {object} [fields] Partial fields, see {@link MemoryStore.patch}.
+   * @returns {{ entry: Record<string, unknown>, scope: string }}
+   */
+  patch(id, fields = {}) {
+    const found = this.locate(id)
+    if (found === undefined) throw new Error(`no memory entry with id "${id}" in any scope`)
+    return { entry: found.store.patch(id, fields), scope: found.scope }
+  }
+
+  /**
+   * Archive or delete one entry wherever it lives.
+   * @param {string} id Entry id.
+   * @param {boolean} [hard]
+   * @returns {{ id: string, hard: boolean, title: string, scope: string }}
+   */
+  forget(id, hard = false) {
+    const found = this.locate(id)
+    if (found === undefined) throw new Error(`no memory entry with id "${id}" in any scope`)
+    const removed = found.store.forget(id, hard)
+    return { ...removed, scope: found.scope }
+  }
+
+  /** @returns {MemoryStore[]} Project stores already loaded in this process. */
+  liveProjects() {
+    return [...this.stores.entries()].filter(([key]) => key !== 'user').map(([, store]) => store)
+  }
+
+  /**
+   * The complete view the UI renders. Without a working directory it shows the
+   * user ledger plus every project ledger on disk.
+   * @param {string} [cwd] Session working directory.
+   * @param {object} [query] Extra search options (`text`, `kind`, `mode`, `scope`, `includeArchived`).
+   * @returns {Record<string, unknown>}
+   */
+  snapshot(cwd = '', query = {}) {
+    const user = this.user()
+    const current = typeof cwd === 'string' && cwd.trim() !== '' ? this.project(cwd) : undefined
+    const projects = this.projects()
+    const projectStores = []
+    if (current !== undefined) {
+      projectStores.push(current)
+    } else {
+      for (const row of projects) {
+        const store = this.stores.get(row.slug)
+          ?? new MemoryStore({ file: row.file, scope: 'project', slug: row.slug, label: row.label, logger: this.logger })
+        this.stores.set(row.slug, store)
+        projectStores.push(store)
+      }
+    }
+
+    const useSearch = typeof query.text === 'string' && query.text.trim() !== ''
+    const includeArchived = query.includeArchived === true
+    const visible = (entry) => includeArchived || entry.archived !== true
+    const entries = useSearch
+      ? this.search({ ...query, cwd, scope: query.scope ?? (cwd === '' ? 'all' : 'auto'), limit: query.limit ?? 50 })
+      : [
+          ...user.entries().filter(visible)
+            .map(entry => ({ ...entry, scope: 'user', project: '', _score: 0 })),
+          ...projectStores.flatMap(store => store.entries()
+            .filter(visible)
+            .map(entry => ({ ...entry, scope: 'project', project: store.label, _score: 0 }))),
+        ].sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)))
+
+    return {
+      version: 1,
+      generatedAt: new Date().toISOString(),
+      mode: query.mode ?? 'hybrid',
+      filtered: useSearch,
+      cwd: cwd || '',
+      user: {
+        path: user.path,
+        stats: user.stats(),
+        incidents: user.incidents().filter(incident => !incident.handled),
+      },
+      project: current === undefined
+        ? null
+        : {
+            slug: current.slug,
+            label: current.label,
+            path: current.path,
+            stats: current.stats(),
+            incidents: current.incidents().filter(incident => !incident.handled),
+          },
+      projects,
+      entries,
+    }
+  }
+}

package/locale/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "Memory ledger",
+    "description": "Keeps standing user settings (identity, pen name, preferences) and verified problem-to-solution lessons on two levels — user-wide and per project — injects a bounded summary into every session, mixes BM25 with TF-IDF vector retrieval, and counts repeated tool failures mechanically. The left-sidebar Memory panel lists, searches, and archives the same ledger.",
+    "detail": "docs/DETAIL.md"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "title": "记忆册",
+    "description": "把用户的长期设定（身份、笔名、偏好）与已验证的问题→解法分「用户 / 本项目」两级记在本地 JSON 里，每轮注入一份有字数上限的摘要；检索用 BM25 + TF-IDF 向量混合，机械统计重复出现的工具失败。左侧栏「记忆册」面板可浏览、搜索、归档。",
+    "detail": "docs/DETAIL.md"
+  }
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "dsh-memory-ledger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Persistent memory for DeepSeek Harness: standing settings and verified problem→solution lessons, separated per project, injected into every session, with a left-sidebar panel, hybrid BM25+vector search, provenance, and an unrecorded-setting reminder.",
+  "type": "module",
+  "main": "index.js",
+  "icon": "./icon.svg",
+  "author": "巴西鲜橙",
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "memory",
+    "agent-memory",
+    "context",
+    "lessons",
+    "provenance",
+    "hybrid-search",
+    "vector-search",
+    "sidebar"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "store.js",
+    "ledger.js",
+    "reminder.js",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "docs",
+    "icon.svg",
+    "README.md",
+    "README-zh.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.2-rc.1 <0.3.0-0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-layout"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node --test test/store.test.mjs"
+  }
 }

package/reminder.js

@@ -0,0 +1,83 @@
+/**
+ * "Did the user just state a standing setting?" — a rule-based detector with
+ * no model call, so the reminder costs nothing until it actually fires.
+ *
+ * The detector is deliberately generous: a false positive only produces one
+ * short reminder line asking the agent to consider recording it, while a false
+ * negative silently loses the whole point of the plugin.
+ */
+
+/** Chinese markers of a standing statement (identity, pen name, policy). */
+const ZH_PATTERNS = [
+  /我(是|叫|的)(名字|笔名|署名|昵称|身份|职业|工作|习惯|偏好)/u,
+  /我的?(笔名|署名|名字|昵称|身份|职业|单位|公司|项目|团队)/u,
+  /(以后|今后|从此|之后)(都)?(用|叫|署|按|写|要)/u,
+  /(记住|记一下|记下来|记一下|别忘了|请记|帮我记)/u,
+  /(统一|一律|全部)(用|署|按|改名)/u,
+  /(不要|别再|禁止|不许)(用|叫|写|按|再)/u,
+  /(默认|习惯|偏好)(用|是|按|为)/u,
+  /(署名|落款|笔名)/u,
+]
+
+/** English markers of the same. */
+const EN_PATTERN = /\b(i am|i'm|my name is|my pen name|call me|remember that|remember this|from now on|always use|never use|we use|our project uses|default to)\b/iu
+
+/** Phrases that keep a question-with-a-marker in scope. */
+const IMPERATIVE = /(记住|记一下|记下来|别忘了|请记|帮我记|from now on|remember that|remember this)/u
+
+/**
+ * Whether one inbox message is a genuine user statement rather than injected
+ * context. Plugin-injected reminders contain words like 笔名/署名 themselves,
+ * so without this guard the reminder would re-trigger itself forever.
+ * @param {{ role?: string, source?: { kind?: string } }} message
+ * @returns {boolean}
+ */
+export function isUserStatement(message) {
+  if (message?.role !== 'user') return false
+  const kind = message?.source?.kind
+  if (typeof kind !== 'string' || kind === '') return true
+  // Every producer-owned kind (plugin, plugin:<name>, tool, time-context, …)
+  // is synthetic context, not something the human typed.
+  return kind === 'user'
+}
+
+/**
+ * Whether one user message looks like a statement of a standing setting.
+ * @param {string} text The message text.
+ * @returns {boolean}
+ */
+export function looksLikeSetting(text) {
+  const value = String(text ?? '').trim()
+  if (value.length < 4) return false
+  const sample = value.slice(0, 2000)
+  const hit = ZH_PATTERNS.some(pattern => pattern.test(sample)) || EN_PATTERN.test(sample)
+  if (!hit) return false
+  // A pure question is not a statement: "我的笔名是什么？" must not trigger.
+  const endsAsQuestion = /[?？]\s*$/u.test(sample)
+  return !(endsAsQuestion && !IMPERATIVE.test(sample))
+}
+
+/**
+ * Whether one user message commands recording explicitly. Such a message is
+ * still worth reminding about, but the reminder says less.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function asksToRemember(text) {
+  return IMPERATIVE.test(String(text ?? ''))
+}
+
+/**
+ * Build the reminder injected into the agent's inbox.
+ * @param {string} quote The user sentence that looked like a setting.
+ * @returns {string}
+ */
+export function reminderText(quote) {
+  const sample = String(quote ?? '').replace(/\s+/gu, ' ').trim().slice(0, 90)
+  return [
+    '【记忆提醒 · dsh-memory-ledger】',
+    `上一轮用户说过一句可能是长期设定的话：「${sample}」`,
+    '如果它确实是稳定设定（身份、笔名、署名、语言、技术栈、格式偏好），现在就调用 memory_save 记录：能归到固定槽位的传 key（如 pen_name），并在 reason 里写明为什么记。',
+    '如果只是这一轮的临时要求，忽略本提示；不要因为这条提示回复用户，也不要反复提醒。',
+  ].join('\n')
+}