dsh-memory-ledger 0.0.0-stage → 1.0.1

package/store.js

@@ -0,0 +1,895 @@
+/**
+ * File-backed ledger for the `dsh-memory-ledger` DSH bundle.
+ *
+ * Two kinds of record live in one JSON file per scope:
+ *
+ * - `fact`   — a stable user or project setting ("I am an author", "pen name is X").
+ * - `lesson` — a verified problem -> solution pair worth reusing instead of
+ *              re-burning tokens on the same investigation.
+ *
+ * It also keeps mechanically captured *incidents*: signatures of failed tool
+ * calls. Repeats of one signature are counted without any model involvement,
+ * so a recurring failure becomes visible in the prompt even before the model
+ * decides to write a lesson about it.
+ *
+ * Retrieval is a classic vector-space model: BM25 term scoring plus a
+ * TF-IDF sparse vector cosine over the same terms. Terms are ASCII words and
+ * CJK character bigrams, so Chinese works without a tokenizer. This is not a
+ * neural embedding — see `docs/DETAIL.md`.
+ *
+ * Everything here is plain data in, plain data out, so `test/store.test.mjs`
+ * can exercise it without a Harness.
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** Schema version of the on-disk file. */
+export const FILE_VERSION = 2
+
+/** Retrieval modes accepted by {@link MemoryStore.search}. */
+export const SEARCH_MODES = ['hybrid', 'keyword', 'vector']
+
+/** Maximum characters of one stored title, body and message kept in the file. */
+const MAX_TITLE = 200
+const MAX_BODY = 4000
+const MAX_MESSAGE = 300
+const MAX_REASON = 400
+
+const KINDS = new Set(['fact', 'lesson'])
+
+function emptyState() {
+  return { version: FILE_VERSION, entries: [], incidents: [] }
+}
+
+function nowIso() {
+  return new Date().toISOString()
+}
+
+function clampText(value, limit) {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (text.length <= limit) return text
+  return `${text.slice(0, limit - 1)}…`
+}
+
+function truncate(value, limit) {
+  const text = String(value ?? '')
+  if (text.length <= limit) return text
+  return `${text.slice(0, Math.max(0, limit - 1))}…`
+}
+
+/**
+ * Split text into retrieval terms: ASCII words of two or more characters and
+ * CJK character bigrams (single characters when a run is one character long).
+ * @param {unknown} value Any text.
+ * @returns {string[]} Terms in order of appearance.
+ */
+export function tokenize(value) {
+  const text = String(value ?? '').toLowerCase()
+  const terms = []
+  for (const match of text.matchAll(/[a-z0-9][a-z0-9_.\-+]{1,}/gu)) terms.push(match[0])
+  for (const match of text.matchAll(/[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]+/gu)) {
+    const run = match[0]
+    if (run.length === 1) {
+      terms.push(run)
+      continue
+    }
+    for (let index = 0; index < run.length - 1; index += 1) terms.push(run.slice(index, index + 2))
+  }
+  return terms
+}
+
+/**
+ * Parse a free-form tag list ("filesystem, powershell") into normalized tags.
+ * @param {unknown} value Comma, newline, or whitespace separated tags.
+ * @returns {string[]} Unique lowercase tags.
+ */
+export function parseTags(value) {
+  if (Array.isArray(value)) return [...new Set(value.flatMap(item => parseTags(item)))]
+  if (typeof value !== 'string') return []
+  return [...new Set(
+    value
+      .split(/[,，;；\s]+/u)
+      .map(tag => tag.trim().toLowerCase())
+      .filter(tag => tag.length > 0 && tag.length <= 40),
+  )]
+}
+
+/**
+ * Collapse an error message into a stable signature so that the same failure
+ * reported with different ids, numbers, paths, or quoting counts as one
+ * incident.
+ * @param {string} tool Tool name that failed.
+ * @param {string} message Error text as the model saw it.
+ * @returns {{ signature: string, normalized: string }}
+ */
+export function signatureOf(tool, message) {
+  const normalized = String(message ?? '')
+    .toLowerCase()
+    .replace(/[a-f0-9]{8,}/gu, '<hex>')
+    .replace(/\b\d+(?:[.:]\d+)*\b/gu, '<n>')
+    .replace(/(?:[a-z]:)?[\\/][^\s'"`,;]+/giu, '<path>')
+    .replace(/["'`][^"'`]{0,120}["'`]/gu, '<q>')
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .slice(0, 160)
+  const signature = createHash('sha1')
+    .update(`${String(tool ?? '')}\u0000${normalized}`)
+    .digest('hex')
+    .slice(0, 10)
+  return { signature, normalized }
+}
+
+/** Sort entries the way the prompt wants them: pinned, then proven, then fresh. */
+function compareEntries(a, b) {
+  if (Boolean(a.pinned) !== Boolean(b.pinned)) return a.pinned ? -1 : 1
+  const occurrences = (b.occurrences ?? 0) - (a.occurrences ?? 0)
+  if (occurrences !== 0) return occurrences
+  return String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? ''))
+}
+
+function scoreSubstring(entry, terms) {
+  const title = String(entry.title ?? '').toLowerCase()
+  const key = String(entry.key ?? '').toLowerCase()
+  const body = String(entry.body ?? '').toLowerCase()
+  const tags = (entry.tags ?? []).join(' ').toLowerCase()
+  let score = 0
+  for (const term of terms) {
+    let hit = 0
+    if (title.includes(term)) hit += 4
+    if (key.includes(term)) hit += 4
+    if (tags.includes(term)) hit += 3
+    if (body.includes(term)) hit += 1
+    if (hit === 0) return 0
+    score += hit
+  }
+  return score
+}
+
+/**
+ * Normalize the provenance block of one entry: which project it was recorded
+ * from, in which session, and when.
+ * @param {unknown} raw
+ * @returns {{ cwd: string, label: string, sessionId: string, at: string } | null}
+ */
+function normalizeOrigin(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  const source = /** @type {Record<string, unknown>} */ (raw)
+  const cwd = typeof source.cwd === 'string' ? source.cwd.trim() : ''
+  const label = typeof source.label === 'string' ? source.label.trim() : ''
+  if (cwd === '' && label === '') return null
+  return {
+    cwd,
+    label: label !== '' ? label : cwd,
+    sessionId: typeof source.sessionId === 'string' ? source.sessionId : '',
+    at: typeof source.at === 'string' ? source.at : nowIso(),
+  }
+}
+
+/**
+ * Normalize one stored entry, tolerating files written by an older version or
+ * edited by hand.
+ * @param {Record<string, unknown>} raw Entry as read from disk.
+ * @returns {Record<string, unknown> | null} Normalized entry, or null when unusable.
+ */
+function normalizeEntry(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  const kind = KINDS.has(String(raw.kind)) ? String(raw.kind) : 'fact'
+  const title = clampText(raw.title, MAX_TITLE)
+  if (title === '') return null
+  return {
+    id: typeof raw.id === 'string' && raw.id !== '' ? raw.id : `m_${randomUUID().slice(0, 8)}`,
+    kind,
+    title,
+    body: clampText(raw.body, MAX_BODY),
+    key: typeof raw.key === 'string' ? raw.key.trim().toLowerCase() : '',
+    tags: parseTags(raw.tags),
+    pinned: raw.pinned === true,
+    archived: raw.archived === true,
+    occurrences: Number.isFinite(raw.occurrences) ? Math.max(0, Math.trunc(raw.occurrences)) : 0,
+    reason: clampText(raw.reason, MAX_REASON),
+    origin: normalizeOrigin(raw.origin),
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : nowIso(),
+    updatedAt: typeof raw.updatedAt === 'string' ? raw.updatedAt : nowIso(),
+  }
+}
+
+function normalizeIncident(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  if (typeof raw.signature !== 'string' || raw.signature === '') return null
+  return {
+    signature: raw.signature,
+    tool: typeof raw.tool === 'string' ? raw.tool : 'unknown',
+    normalized: typeof raw.normalized === 'string' ? raw.normalized : '',
+    message: clampText(raw.message, MAX_MESSAGE),
+    count: Number.isFinite(raw.count) ? Math.max(1, Math.trunc(raw.count)) : 1,
+    handled: raw.handled === true,
+    firstSeenAt: typeof raw.firstSeenAt === 'string' ? raw.firstSeenAt : nowIso(),
+    lastSeenAt: typeof raw.lastSeenAt === 'string' ? raw.lastSeenAt : nowIso(),
+  }
+}
+
+/** Term statistics over one corpus. */
+function buildCorpus(documents) {
+  const df = new Map()
+  const perDocument = new Map()
+  let totalLength = 0
+  for (const document of documents) {
+    const tf = new Map()
+    for (const term of document.terms) tf.set(term, (tf.get(term) ?? 0) + 1)
+    perDocument.set(document.id, { tf, length: document.terms.length })
+    for (const term of tf.keys()) df.set(term, (df.get(term) ?? 0) + 1)
+    totalLength += document.terms.length
+  }
+  return {
+    df,
+    perDocument,
+    size: documents.length,
+    averageLength: documents.length === 0 ? 0 : totalLength / documents.length,
+  }
+}
+
+/** BM25 score of one document against query terms. */
+function bm25(queryTerms, corpus, id) {
+  const document = corpus.perDocument.get(id)
+  if (document === undefined) return 0
+  const k1 = 1.2
+  const b = 0.75
+  let score = 0
+  for (const term of queryTerms) {
+    const documentFrequency = corpus.df.get(term) ?? 0
+    if (documentFrequency === 0) continue
+    const frequency = document.tf.get(term) ?? 0
+    if (frequency === 0) continue
+    const idf = Math.log(1 + (corpus.size - documentFrequency + 0.5) / (documentFrequency + 0.5))
+    const denominator = frequency + k1 * (1 - b + b * (document.length / (corpus.averageLength || 1)))
+    score += idf * ((frequency * (k1 + 1)) / denominator)
+  }
+  return score
+}
+
+/** Unit TF-IDF vector of one document. */
+function unitVector(tf, df, size) {
+  const weights = new Map()
+  let squared = 0
+  for (const [term, frequency] of tf) {
+    const idf = Math.log(1 + size / (1 + (df.get(term) ?? 0)))
+    const weight = (1 + Math.log(frequency)) * idf
+    if (weight <= 0) continue
+    weights.set(term, weight)
+    squared += weight * weight
+  }
+  const norm = Math.sqrt(squared)
+  if (norm === 0) return weights
+  for (const [term, weight] of weights) weights.set(term, weight / norm)
+  return weights
+}
+
+/** Cosine similarity of two sparse unit vectors. */
+function cosine(left, right) {
+  let score = 0
+  for (const [term, weight] of left) {
+    const other = right.get(term)
+    if (other !== undefined) score += weight * other
+  }
+  return score
+}
+
+/**
+ * Terms that carry no retrieval signal. Chinese bigram tokenization turns
+ * function words into terms ("一个", "怎么", "这个"), and a small ledger has
+ * too few documents for IDF to discount them, so they are removed explicitly.
+ */
+export const STOP_TERMS = new Set([
+  '怎么', '么在', '什么', '这个', '那个', '一个', '一下', '一些', '我们', '你们',
+  '他们', '她们', '它们', '可以', '就是', '不是', '还是', '因为', '所以', '但是',
+  '不过', '如果', '那么', '这样', '那样', '时候', '现在', '需要', '应该', '已经',
+  '没有', '是否', '如何', '为什', '么样', '怎样', '这些', '那些', '以及', '并且',
+  '或者', '而且', '然后', '其实', '而是', '只是', '仍然', '仍然', '非常', '比较',
+  'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'are', 'was',
+  'were', 'not', 'but', 'you', 'your', 'its', 'has', 'have', 'had', 'can',
+  'will', 'would', 'should', 'could', 'about', 'then', 'than', 'them', 'they',
+  'there', 'here', 'when', 'what', 'which', 'who', 'how', 'why', 'all', 'any',
+  'each', 'few', 'more', 'most', 'other', 'some', 'such', 'only', 'own',
+  'same', 'too', 'very', 'via', 'per', 'out', 'off',
+])
+
+/**
+ * Terms of one text with the no-signal ones removed.
+ * @param {unknown} value Any text.
+ * @returns {string[]}
+ */
+export function contentTerms(value) {
+  return tokenize(value).filter(term => !STOP_TERMS.has(term))
+}
+
+/**
+ * Field-weighted terms of one entry: a title or key hit means far more than a
+ * body hit, so those fields are repeated before the corpus statistics are
+ * built. This is what keeps a paraphrase from matching a long body on one
+ * incidental bigram.
+ * @param {Record<string, unknown>} entry
+ * @returns {string[]}
+ */
+function documentTerms(entry) {
+  const title = contentTerms(`${entry.title}`)
+  const key = contentTerms(`${entry.key ?? ''}`)
+  const tags = contentTerms((Array.isArray(entry.tags) ? entry.tags : []).join(' '))
+  const body = contentTerms(`${entry.body ?? ''}`)
+  return [...title, ...title, ...title, ...key, ...key, ...key, ...tags, ...tags, ...body]
+}
+
+/**
+ * Whether one entry passes a query's structural filters.
+ * @param {Record<string, unknown>} entry
+ * @param {object} [query]
+ * @returns {boolean}
+ */
+export function entryMatches(entry, query = {}) {
+  if (query.includeArchived !== true && entry.archived === true) return false
+  if ((query.kind === 'fact' || query.kind === 'lesson') && entry.kind !== query.kind) return false
+  const requiredTags = parseTags(query.tags)
+  if (requiredTags.length > 0 && !requiredTags.every(tag => entry.tags.includes(tag))) return false
+  return true
+}
+
+/**
+ * Rank entries against a query in one shared corpus.
+ *
+ * `mode` selects the ranking: `keyword` requires every query word to appear
+ * and scores with BM25 plus exact substring hits, `vector` is TF-IDF cosine
+ * only, `hybrid` mixes both. An empty query keeps the stable
+ * pinned/proven/recent order.
+ *
+ * Takes the whole candidate set, so callers that combine several ledgers get
+ * comparable scores instead of one scale per file.
+ *
+ * @param {Array<Record<string, unknown>>} entries Candidates already filtered.
+ * @param {object} [query]
+ * @param {string} [query.text]
+ * @param {number} [query.limit]
+ * @param {'hybrid'|'keyword'|'vector'} [query.mode]
+ * @returns {Array<Record<string, unknown>>} Entries with `_score` and `_vector`.
+ */
+export function rankEntries(entries, query = {}) {
+  const limit = Math.min(Math.max(Math.trunc(query.limit ?? 10) || 10, 1), 50)
+  const mode = SEARCH_MODES.includes(String(query.mode)) ? String(query.mode) : 'hybrid'
+  const rawQuery = String(query.text ?? '').trim()
+
+  if (rawQuery === '') {
+    return [...entries]
+      .sort(compareEntries)
+      .slice(0, limit)
+      .map(entry => ({ ...entry, _score: 0, _vector: 0 }))
+  }
+
+  const filteredQuery = contentTerms(rawQuery)
+  const queryTerms = filteredQuery.length > 0 ? filteredQuery : tokenize(rawQuery)
+  const words = rawQuery.toLowerCase().split(/\s+/u).filter(Boolean)
+  const documents = entries.map(entry => ({ id: entry.id, terms: documentTerms(entry) }))
+  const corpus = buildCorpus(documents)
+  const queryVector = unitVector(
+    queryTerms.reduce((tf, term) => {
+      tf.set(term, (tf.get(term) ?? 0) + 1)
+      return tf
+    }, new Map()),
+    corpus.df,
+    corpus.size,
+  )
+
+  let bestLexical = 0
+  const scored = entries.map(entry => {
+    const haystack = `${entry.title} ${entry.key} ${entry.tags.join(' ')} ${entry.body}`.toLowerCase()
+    const matchesEveryWord = words.length === 0 || words.every(word => haystack.includes(word))
+    const lexical = mode === 'vector'
+      ? 0
+      : (mode === 'keyword' && !matchesEveryWord)
+        ? 0
+        : bm25(queryTerms, corpus, entry.id) + scoreSubstring(entry, words)
+    const document = corpus.perDocument.get(entry.id)
+    const vector = mode === 'keyword'
+      ? 0
+      : document === undefined
+        ? 0
+        : cosine(queryVector, unitVector(document.tf, corpus.df, corpus.size))
+    if (lexical > bestLexical) bestLexical = lexical
+    return { entry, lexical, vector }
+  })
+
+  return scored
+    .filter(item => item.lexical > 0 || item.vector > 0.01)
+    .map(item => {
+      const normalizedLexical = bestLexical === 0 ? 0 : item.lexical / bestLexical
+      const score = mode === 'vector'
+        ? item.vector
+        : mode === 'keyword'
+          ? normalizedLexical
+          : 0.6 * item.vector + 0.4 * normalizedLexical
+      return {
+        ...item.entry,
+        _score: Number(score.toFixed(4)),
+        _vector: Number(item.vector.toFixed(4)),
+      }
+    })
+    .sort((a, b) => b._score - a._score || compareEntries(a, b))
+    .slice(0, limit)
+}
+
+/**
+ * One memory ledger owned by one file.
+ *
+ * The file is re-read when its modification time changes, so an edit made by
+ * hand (or by a second Harness process) shows up without a restart.
+ */
+export class MemoryStore {
+  /**
+   * @param {object} options
+   * @param {string} options.file Absolute path of the JSON file.
+   * @param {string} [options.scope] Scope label this file represents.
+   * @param {string} [options.label] Human label (a project's directory path).
+   * @param {{ warn?: (message: string) => void }} [options.logger]
+   */
+  constructor({ file, scope = 'user', slug = '', label = '', logger = null }) {
+    this.file = file
+    this.scope = scope
+    this.slug = slug
+    this.label = label
+    this.logger = logger
+    this.state = emptyState()
+    this.mtime = -1
+    this.load()
+  }
+
+  /** Read the file, keeping a corrupt copy instead of silently dropping it. */
+  load() {
+    try {
+      if (!existsSync(this.file)) {
+        this.state = emptyState()
+        this.mtime = -1
+        return
+      }
+      const text = readFileSync(this.file, 'utf8')
+      const parsed = JSON.parse(text)
+      if (typeof parsed?.slug === 'string' && parsed.slug !== '') this.slug = parsed.slug
+      if (typeof parsed?.label === 'string' && parsed.label !== '') this.label = parsed.label
+      const entries = Array.isArray(parsed?.entries)
+        ? parsed.entries.map(normalizeEntry).filter(Boolean)
+        : []
+      const incidents = Array.isArray(parsed?.incidents)
+        ? parsed.incidents.map(normalizeIncident).filter(Boolean)
+        : []
+      this.state = { version: FILE_VERSION, entries, incidents }
+      this.mtime = statSync(this.file).mtimeMs
+    } catch (error) {
+      const backup = `${this.file}.corrupt-${Date.now()}.json`
+      try {
+        if (existsSync(this.file)) renameSync(this.file, backup)
+        this.logger?.warn?.(`[dsh-memory-ledger] unreadable ledger moved to ${backup}: ${error instanceof Error ? error.message : String(error)}`)
+      } catch {
+        /* keep going with an empty ledger */
+      }
+      this.state = emptyState()
+      this.mtime = -1
+    }
+  }
+
+  /** Re-read the file when another writer changed it. */
+  ensureFresh() {
+    try {
+      if (!existsSync(this.file)) return
+      if (statSync(this.file).mtimeMs !== this.mtime) this.load()
+    } catch {
+      /* a transient stat failure keeps the in-memory copy */
+    }
+  }
+
+  /** Write the ledger atomically (temp file + rename). */
+  save() {
+    mkdirSync(dirname(this.file), { recursive: true })
+    const temporary = `${this.file}.${process.pid}.tmp`
+    const payload = {
+      version: FILE_VERSION,
+      ...(this.slug === '' ? {} : { slug: this.slug }),
+      ...(this.label === '' ? {} : { label: this.label }),
+      entries: this.state.entries,
+      incidents: this.state.incidents,
+    }
+    writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+    renameSync(temporary, this.file)
+    try {
+      this.mtime = statSync(this.file).mtimeMs
+    } catch {
+      this.mtime = -1
+    }
+  }
+
+  /** @returns {string} Absolute ledger path. */
+  get path() {
+    return this.file
+  }
+
+  /** @returns {Array<Record<string, unknown>>} Live entries, normalized. */
+  entries() {
+    this.ensureFresh()
+    return this.state.entries
+  }
+
+  /** @returns {Array<Record<string, unknown>>} Live incidents, normalized. */
+  incidents() {
+    this.ensureFresh()
+    return this.state.incidents
+  }
+
+  /**
+   * List this ledger's entries, optionally ranked by a query.
+   *
+   * `mode` selects the ranking: `keyword` is BM25 plus exact substring
+   * matching, `vector` is TF-IDF cosine only, `hybrid` mixes both. An empty
+   * query keeps the stable pinned/proven/recent order.
+   *
+   * @param {object} [query]
+   * @param {string} [query.text] Free-form query.
+   * @param {'fact'|'lesson'} [query.kind]
+   * @param {string[]|string} [query.tags] Tags that must all be present.
+   * @param {boolean} [query.includeArchived]
+   * @param {number} [query.limit]
+   * @param {string} [query.mode] One of {@link SEARCH_MODES}.
+   * @returns {Array<Record<string, unknown>>} Matching entries with `_score` and `_vector`.
+   */
+  list(query = {}) {
+    this.ensureFresh()
+    return rankEntries(this.state.entries.filter(entry => entryMatches(entry, query)), query)
+  }
+
+  /**
+   * Read one entry by id.
+   * @param {string} id
+   * @returns {Record<string, unknown> | undefined}
+   */
+  get(id) {
+    this.ensureFresh()
+    return this.state.entries.find(entry => entry.id === id)
+  }
+
+  /**
+   * Create or update one entry.
+   *
+   * The target is the entry with `id`, otherwise the entry with the same
+   * `kind` and `key` (which is how a changed setting replaces its old value
+   * instead of piling up a second copy).
+   *
+   * @param {object} input
+   * @returns {{ entry: Record<string, unknown>, updated: boolean }}
+   */
+  upsert(input) {
+    this.ensureFresh()
+    const kind = KINDS.has(String(input.kind)) ? String(input.kind) : null
+    if (kind === null) throw new Error(`kind must be "fact" or "lesson", received "${String(input.kind)}"`)
+    const title = clampText(input.title, MAX_TITLE)
+    if (title === '') throw new Error('title must be a non-empty single line')
+    const key = typeof input.key === 'string' ? input.key.trim().toLowerCase() : ''
+
+    let target
+    if (typeof input.id === 'string' && input.id !== '') {
+      target = this.state.entries.find(entry => entry.id === input.id)
+      if (target === undefined) throw new Error(`no memory entry with id "${input.id}"`)
+    } else if (key !== '') {
+      target = this.state.entries.find(entry => entry.kind === kind && entry.key === key)
+    }
+
+    const updated = target !== undefined
+    if (updated) {
+      target.kind = kind
+      target.title = title
+      if (input.body !== undefined) target.body = clampText(input.body, MAX_BODY)
+      if (input.key !== undefined) target.key = key
+      if (input.tags !== undefined) target.tags = parseTags(input.tags)
+      if (input.pinned !== undefined) target.pinned = input.pinned === true
+      if (input.archived !== undefined) target.archived = input.archived === true
+      if (input.reason !== undefined) target.reason = clampText(input.reason, MAX_REASON)
+      // Provenance is where the entry was FIRST recorded; a later edit from
+      // another project does not rewrite that history.
+      if (input.origin !== undefined && target.origin == null) target.origin = normalizeOrigin(input.origin)
+      target.updatedAt = nowIso()
+    } else {
+      target = {
+        id: `m_${randomUUID().slice(0, 8)}`,
+        kind,
+        title,
+        body: clampText(input.body, MAX_BODY),
+        key,
+        tags: parseTags(input.tags),
+        pinned: input.pinned === true,
+        archived: false,
+        occurrences: 0,
+        reason: clampText(input.reason, MAX_REASON),
+        origin: normalizeOrigin(input.origin),
+        createdAt: nowIso(),
+        updatedAt: nowIso(),
+      }
+      this.state.entries.unshift(target)
+    }
+
+    if (target.kind === 'lesson') this.markIncidentsHandled(target)
+    this.save()
+    return { entry: target, updated }
+  }
+
+  /**
+   * Apply a partial edit to one entry, keeping its id and its scope.
+   *
+   * Only the fields present in `fields` change; everything else survives, so
+   * a rename does not silently drop a body or a tag list.
+   *
+   * @param {string} id Entry id.
+   * @param {{ kind?: string, title?: string, body?: string, key?: string,
+   *   tags?: string|string[], pinned?: boolean, archived?: boolean,
+   *   reason?: string }} [fields]
+   * @returns {Record<string, unknown>} The updated entry.
+   */
+  patch(id, fields = {}) {
+    this.ensureFresh()
+    const entry = this.state.entries.find(item => item.id === id)
+    if (entry === undefined) throw new Error(`no memory entry with id "${id}"`)
+    if (fields.kind !== undefined) {
+      if (!KINDS.has(String(fields.kind))) throw new Error(`kind must be "fact" or "lesson", received "${String(fields.kind)}"`)
+      entry.kind = String(fields.kind)
+    }
+    if (fields.title !== undefined) {
+      const title = clampText(fields.title, MAX_TITLE)
+      if (title === '') throw new Error('title must be a non-empty single line')
+      entry.title = title
+    }
+    if (fields.body !== undefined) entry.body = clampText(fields.body, MAX_BODY)
+    if (fields.key !== undefined) entry.key = typeof fields.key === 'string' ? fields.key.trim().toLowerCase() : ''
+    if (fields.tags !== undefined) entry.tags = parseTags(fields.tags)
+    if (fields.pinned !== undefined) entry.pinned = fields.pinned === true
+    if (fields.archived !== undefined) entry.archived = fields.archived === true
+    if (fields.reason !== undefined) entry.reason = clampText(fields.reason, MAX_REASON)
+    entry.updatedAt = nowIso()
+    this.save()
+    return entry
+  }
+
+  /**
+   * Archive (default) or delete one entry.
+   * @param {string} id
+   * @param {boolean} [hard] Delete instead of archiving.
+   * @returns {{ id: string, hard: boolean, title: string }}
+   */
+  forget(id, hard = false) {
+    this.ensureFresh()
+    const index = this.state.entries.findIndex(entry => entry.id === id)
+    if (index === -1) throw new Error(`no memory entry with id "${id}"`)
+    const entry = this.state.entries[index]
+    if (hard === true) {
+      this.state.entries.splice(index, 1)
+    } else {
+      entry.archived = true
+      entry.updatedAt = nowIso()
+    }
+    this.save()
+    return { id, hard: hard === true, title: entry.title }
+  }
+
+  /**
+   * Count one failed tool call under its signature.
+   * @param {string} tool Failing tool name.
+   * @param {string} message Error text as the model saw it.
+   * @returns {{ signature: string, count: number, created: boolean, message: string }}
+   */
+  recordIncident(tool, message) {
+    this.ensureFresh()
+    const { signature, normalized } = signatureOf(tool, message)
+    const existing = this.state.incidents.find(incident => incident.signature === signature)
+    if (existing !== undefined) {
+      existing.count += 1
+      existing.lastSeenAt = nowIso()
+      if (normalized !== '') existing.normalized = normalized
+      return { signature, count: existing.count, created: false, message: existing.message }
+    }
+    const incident = {
+      signature,
+      tool: typeof tool === 'string' && tool !== '' ? tool : 'unknown',
+      normalized,
+      message: clampText(message, MAX_MESSAGE),
+      count: 1,
+      handled: false,
+      firstSeenAt: nowIso(),
+      lastSeenAt: nowIso(),
+    }
+    this.state.incidents.unshift(incident)
+    return { signature, count: 1, created: true, message: incident.message }
+  }
+
+  /**
+   * Treat incidents a saved lesson plausibly explains as handled.
+   * @param {Record<string, unknown>} lesson The saved lesson.
+   */
+  markIncidentsHandled(lesson) {
+    const haystack = `${lesson.title} ${lesson.body} ${(lesson.tags ?? []).join(' ')}`.toLowerCase()
+    for (const incident of this.state.incidents) {
+      if (incident.handled) continue
+      const tool = String(incident.tool).toLowerCase()
+      if (tool !== '' && haystack.includes(tool)) incident.handled = true
+    }
+  }
+
+  /**
+   * Drop the oldest low-signal incidents beyond `max`, and forget incidents
+   * older than `maxAgeDays`.
+   * @param {{ max?: number, maxAgeDays?: number }} [options]
+   */
+  pruneIncidents(options = {}) {
+    const max = Math.max(5, Math.trunc(options.max ?? 40) || 40)
+    const maxAgeMs = Math.max(1, Math.trunc(options.maxAgeDays ?? 60) || 60) * 86_400_000
+    const cutoff = Date.now() - maxAgeMs
+    this.state.incidents = this.state.incidents
+      .filter(incident => {
+        const seen = Date.parse(incident.lastSeenAt)
+        return Number.isNaN(seen) || seen >= cutoff
+      })
+      .sort((a, b) => b.count - a.count || String(b.lastSeenAt).localeCompare(String(a.lastSeenAt)))
+      .slice(0, max)
+    this.save()
+  }
+
+  /** @returns {{ facts: number, lessons: number, incidents: number, pending: number }} */
+  stats() {
+    this.ensureFresh()
+    const facts = this.state.entries.filter(entry => entry.kind === 'fact' && !entry.archived).length
+    const lessons = this.state.entries.filter(entry => entry.kind === 'lesson' && !entry.archived).length
+    const pending = this.state.incidents.filter(incident => !incident.handled).length
+    return { facts, lessons, incidents: this.state.incidents.length, pending }
+  }
+
+  /**
+   * Render the prompt section for the current ledger.
+   * @param {object} [options]
+   * @param {number} [options.maxChars] Hard character budget for the section.
+   * @param {number} [options.maxLessons] Lessons to surface at most.
+   * @param {number} [options.incidentThreshold] Repeat count that makes an incident worth surfacing.
+   * @param {boolean} [options.includeUsageHint]
+   * @param {boolean} [options.markProject] Tag entries contributed by a project ledger.
+   * @returns {string} Section text, or '' when the ledger is empty.
+   */
+  renderPromptSection(options = {}) {
+    this.ensureFresh()
+    return renderPromptSection(this.state, { ...options, scope: this.scope })
+  }
+}
+
+/**
+ * Render the hard-constraint section from ledger state. Pure: no file access.
+ *
+ * A fact becomes a constraint when it is pinned or when its key is listed in
+ * `constraintKeys`. Constraints are phrased as requirements and deliberately
+ * carry no body text, so the same fact does not pay for its words twice.
+ *
+ * @param {{ entries: Array<Record<string, unknown>> }} state
+ * @param {object} [options]
+ * @param {string|string[]} [options.constraintKeys] Keys that make a fact a constraint.
+ * @param {number} [options.maxChars] Hard character budget.
+ * @param {boolean} [options.markProject] Tag entries contributed by a project ledger.
+ * @returns {string}
+ */
+export function renderConstraints(state, options = {}) {
+  const maxChars = Math.max(80, Math.trunc(options.maxChars ?? 300) || 300)
+  const keys = new Set(parseTags(options.constraintKeys))
+  const markProject = options.markProject !== false
+  const entries = Array.isArray(state?.entries) ? state.entries : []
+  const facts = entries
+    .filter(entry => entry.kind === 'fact' && !entry.archived)
+    .filter(entry => entry.pinned === true || (entry.key !== '' && keys.has(entry.key)))
+    .sort(compareEntries)
+  if (facts.length === 0) return ''
+
+  const lines = []
+  let used = 0
+  const push = (line) => {
+    const length = line.length + 1
+    if (used + length > maxChars) return false
+    lines.push(line)
+    used += length
+    return true
+  }
+
+  push('## 必须遵守的用户设定（优先级高于任何默认署名、风格或模板）')
+  push('以下是用户明确设定过的硬性要求。与它们冲突的默认做法、模板示例或历史习惯一律作废；拿不准时按这里执行。')
+  for (const fact of facts) {
+    const projectTag = markProject && fact.scope === 'project' ? '（本项目）' : ''
+    // Title only: the detailed body already travels in the memory section.
+    if (!push(`- ${projectTag}${fact.title}`)) break
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Render the prompt section from ledger state. Pure: no file access.
+ * @param {{ entries: Array<Record<string, unknown>>, incidents: Array<Record<string, unknown>> }} state
+ * @param {object} [options] Same options as {@link MemoryStore.renderPromptSection}.
+ * @returns {string}
+ */
+export function renderPromptSection(state, options = {}) {
+  const maxChars = Math.max(200, Math.trunc(options.maxChars ?? 1600) || 1600)
+  const maxLessons = Math.max(1, Math.trunc(options.maxLessons ?? 8) || 8)
+  const incidentThreshold = Math.max(2, Math.trunc(options.incidentThreshold ?? 2) || 2)
+  const includeUsageHint = options.includeUsageHint !== false
+  const markProject = options.markProject !== false
+
+  const entries = Array.isArray(state?.entries) ? state.entries : []
+  const facts = entries
+    .filter(entry => entry.kind === 'fact' && !entry.archived)
+    .sort(compareEntries)
+  const lessons = entries
+    .filter(entry => entry.kind === 'lesson' && !entry.archived)
+    .sort(compareEntries)
+    .slice(0, maxLessons)
+  const incidents = (Array.isArray(state?.incidents) ? state.incidents : [])
+    .filter(incident => !incident.handled && (incident.count ?? 0) >= incidentThreshold)
+    .sort((a, b) => (b.count ?? 0) - (a.count ?? 0))
+    .slice(0, 5)
+
+  if (facts.length === 0 && lessons.length === 0 && incidents.length === 0) return ''
+
+  const lines = []
+  let used = 0
+  const push = (line) => {
+    const length = line.length + 1
+    if (used + length > maxChars) return false
+    lines.push(line)
+    used += length
+    return true
+  }
+
+  const projectTag = (entry) => (markProject && entry.scope === 'project' ? '（本项目）' : '')
+  const hasProject = [...facts, ...lessons].some(entry => entry.scope === 'project')
+
+  push('## 长期记忆（跨会话，由 dsh-memory-ledger 注入）')
+  push(
+    hasProject
+      ? '下面是你此前为用户保存的既定事实与已验证经验；标注「本项目」的条目只属于当前工作目录。把它们当作前提，不要重新询问；若与用户当次的明确指令冲突，以当次指令为准，并立刻用 memory_save 更新记忆。'
+      : '下面是你此前为用户保存的既定事实与已验证经验。把它们当作前提，不要重新询问；若与用户当次的明确指令冲突，以当次指令为准，并立刻用 memory_save 更新记忆。',
+  )
+
+  if (facts.length > 0) {
+    push('')
+    push('### 用户设定（长期有效）')
+    let kept = 0
+    for (const fact of facts) {
+      const label = fact.key !== '' ? `[${fact.key}] ` : ''
+      const detail = fact.body !== '' ? `：${truncate(fact.body.replace(/\s+/gu, ' '), 160)}` : ''
+      if (push(`- ${label}${projectTag(fact)}${fact.title}${detail}`)) kept += 1
+    }
+    if (kept === 0) push('- （设定过多，已省略；用 memory_search 查看）')
+  }
+
+  if (lessons.length > 0) {
+    push('')
+    push('### 已验证经验（先照做，别重新试错）')
+    let kept = 0
+    for (const lesson of lessons) {
+      const repeat = (lesson.occurrences ?? 0) > 1 ? `（已遇 ${lesson.occurrences} 次）` : ''
+      const detail = lesson.body !== '' ? ` → ${truncate(lesson.body.replace(/\s+/gu, ' '), 180)}` : ''
+      if (push(`- ${projectTag(lesson)}${lesson.title}${repeat}${detail}`)) kept += 1
+    }
+    if (kept === 0) push('- （经验过多，已省略；用 memory_search 查看）')
+  }
+
+  if (incidents.length > 0) {
+    push('')
+    push('### 重复失败预警（尚无已记录的解法）')
+    for (const incident of incidents) {
+      const text = truncate(String(incident.message ?? incident.normalized ?? '').replace(/\s+/gu, ' '), 130)
+      if (!push(`- ${incident.tool}：${text}（同类失败 ${incident.count} 次）→ 先 memory_search 查是否已有解法，再决定重试；解决后用 memory_save 记成 lesson`)) break
+    }
+  }
+
+  if (includeUsageHint) {
+    push('')
+    push('维护约定：用户给出新的稳定设定时，用 memory_save(kind="fact", key="<槽位>") 写入或覆盖；把某个故障真正修好后，用 memory_save(kind="lesson") 记录成因与解法（默认记进本项目，需要跨项目复用时传 scope="user"）。检索全部记忆用 memory_search。')
+  }
+
+  return lines.join('\n')
+}