@try-works/dsh-memory 0.1.19 → 0.1.20

package/src/summarize.js

@@ -1,195 +1,195 @@
-// Session summarization: the CAPTURE stage turns raw session material into durable
-// notes. The instructions below are deliberately durable (they are the contract the
-// store relies on), and parsing is lenient so a model that ignores the format still
-// degrades to a deterministic fallback instead of writing noise.
-
-/** Marker a model returns when a session holds nothing worth remembering. */
-export const NO_DURABLE = 'NO_DURABLE_CONTENT'
-
-/** Durable capture instructions: what durable memory is, and what it is not. */
-export const SUMMARY_INSTRUCTIONS = [
-  'You are the CAPTURE stage of a long-term memory system for a coding agent.',
-  'You receive the raw material of ONE work session. Reply with durable notes only.',
-  '',
-  'FORMAT (strict):',
-  '- Markdown bullet points, one fact per bullet. No preamble, no headings, no code fences.',
-  '- 5-12 bullets, together under 1200 characters.',
-  '- Each bullet: "- **<short label>:** <the fact>"',
-  '- If a bullet is time-bound, lead with the date: "- **2026-09-30 - <label>:** <fact>"',
-  '- Name concrete identifiers when they matter: file paths, commands, ids, config keys, versions.',
-  '- Add one clause of why when a decision was made.',
-  '',
-  'KEEP (durable):',
-  '- decisions and their rationale; constraints, gotchas, surprises',
-  '- chosen dependencies, conventions and architecture, with the reason they won',
-  '- user preferences, standing rules, corrections',
-  '- environment facts: paths, services, ports, versions, where credentials live',
-  '- which modules or subsystems the session actually worked in, and what each one does',
-  '- whether a fact is durable (a decision, a convention) or perishable (what is running now)',
-  '- verified outcomes and results',
-  '- unresolved problems and agreed next steps',
-  '',
-  'DROP (never store):',
-  '- tool calls, command mechanics, retries, build/scan output',
-  '- code blocks, diffs and file dumps (name the file instead)',
-  '- a bare list of file paths: they are given for context, so name only the ones that matter',
-  '- status updates, acknowledgements, pleasantries, restatements',
-  '- anything that is only meaningful inside a single turn',
-  '',
-  'RULES:',
-  '- Never invent facts. Compress only what the material shows.',
-  '- Prefer durable statements over narration of what the agent did.',
-  '- If the session holds nothing durable, reply with exactly: ' + NO_DURABLE,
-  '  That is a common and correct answer. Never manufacture a bullet to avoid an empty reply.',
-].join('\n')
-
-/** Clip one message to a head+tail window so a single huge message cannot dominate. */
-export function clip(text, max = 600) {
-  const value = String(text == null ? '' : text).replace(/\s+/g, ' ').trim()
-  if (value.length <= max) return value
-  const head = Math.max(1, Math.floor(max * 0.7))
-  const tail = Math.max(0, max - head - 3)
-  return value.slice(0, head) + '...' + (tail > 0 ? value.slice(value.length - tail) : '')
-}
-
-/** Gist of an assistant message: its first meaningful line, clipped. */
-/**
- * Gist of an assistant message: the substance of what it reported.
- *
- * Taking the first line was wrong for research and analysis work. Those answers open with a
- * one-line status ("Analysis complete.") and put every finding in the body, so the capture
- * pipeline saw the announcement and none of the substance - the exact material the memory
- * system exists to keep. The gist now skips a bare status opener and carries the following
- * content, so a report reaches the summarizer as findings rather than as a headline.
- */
-export function gist(text, max = 240) {
-  const value = String(text == null ? '' : text)
-  const lines = value.split('\n').map((raw) => raw.replace(/^[#>*\-\s]+/, '').trim())
-  const meaningful = lines.filter((line) => line.length >= 12)
-  if (meaningful.length === 0) return clip(value, max)
-  // A short opener that only announces completion is a headline, not the content.
-  const OPENER = /^(analysis complete|done|finished|completed|all done|i(\x27ve| have) (finished|completed)|summary[:\s]|here(\x27s| is) (a|the) (summary|report|analysis))/i
-  const start = (meaningful.length > 1 && OPENER.test(meaningful[0])) ? 1 : 0
-  // Prefer the first two meaningful lines so a heading plus its substance both survive.
-  const picked = meaningful.slice(start, start + 2).join(' ')
-  return clip(picked === '' ? meaningful[0] : picked, max)
-}
-
-/** Build the single summarization prompt from bounded session candidates. */
-export function buildSummaryPrompt(candidates = {}, meta = {}) {
-  const lines = [
-    SUMMARY_INSTRUCTIONS,
-    '',
-    '--- SESSION ---',
-    'Title: ' + (candidates.title || candidates.sessionId || 'untitled'),
-    'Date: ' + (meta.date || candidates.date || ''),
-    'Cwd: ' + (candidates.cwd || ''),
-    'Events: ' + (candidates.eventCount == null ? 0 : candidates.eventCount)
-      + '   Tool calls: ' + (candidates.toolCallCount == null ? 0 : candidates.toolCallCount),
-  ]
-  if (candidates.goals && candidates.goals.length) lines.push('Goals: ' + candidates.goals.join(' | '))
-  if (candidates.userTurns && candidates.userTurns.length) {
-    lines.push('', '--- USER TURNS (' + candidates.userTurns.length + ') ---')
-    for (const turn of candidates.userTurns) lines.push('- ' + turn)
-  }
-  if (candidates.assistantGists && candidates.assistantGists.length) {
-    lines.push('', '--- ASSISTANT GISTS (' + candidates.assistantGists.length + ') ---')
-    for (const item of candidates.assistantGists) lines.push('- ' + item)
-  }
-  if (candidates.files && candidates.files.length) {
-    lines.push('', '--- FILES THE SESSION WORKED IN (' + candidates.files.length + ') ---')
-    for (const file of candidates.files) lines.push('- ' + file)
-  }
-  if (candidates.checkpoints && candidates.checkpoints.length) {
-    lines.push('', '--- COMPACTION CHECKPOINTS ---')
-    for (const item of candidates.checkpoints) lines.push('- ' + item)
-  }
-  return lines.join('\n')
-}
-
-/**
- * Leniently read bullets out of a model reply.
- * @returns {{ bullets: string[], none: boolean }} normalized bullet lines.
- */
-export function parseSummary(text, { maxBullets = 16, maxChars = 2000 } = {}) {
-  const source = String(text == null ? '' : text).trim()
-  if (source === '') return { bullets: [], none: true, reason: 'empty-reply' }
-  if (source.toUpperCase().includes(NO_DURABLE)) return { bullets: [], none: true, reason: 'no-durable' }
-  const bullets = []
-  let total = 0
-  for (const raw of source.replace(/\x60\x60\x60[\s\S]*?\x60\x60\x60/g, '').split('\n')) {
-    const line = raw.trim()
-    if (!/^[-*+]\s+/.test(line)) continue
-    const bullet = '- ' + line.replace(/^[-*+]\s+/, '').trim()
-    if (bullet.length <= 3) continue
-    if (total + bullet.length > maxChars && bullets.length > 0) break
-    bullets.push(bullet)
-    total += bullet.length + 1
-    if (bullets.length >= maxBullets) break
-  }
-  return bullets.length === 0 ? { bullets: [], none: true, reason: 'unparseable' } : { bullets, none: false }
-}
-
-/** Deterministic notes used when the summarizer is unavailable or unusable. */
-export function fallbackBullets(candidates = {}, { maxBullets = 8, maxChars = 1000 } = {}) {
-  const bullets = []
-  let total = 0
-  const push = (label, fact) => {
-    const body = clip(fact, 220)
-    if (body === '') return
-    const bullet = '- **' + label + ':** ' + body
-    if (total + bullet.length > maxChars && bullets.length > 0) return
-    bullets.push(bullet)
-    total += bullet.length + 1
-  }
-  const date = candidates.date ? String(candidates.date).slice(0, 10) + ' - ' : ''
-  for (const goal of (candidates.goals || []).slice(0, 2)) push(date + 'goal', goal)
-  const turns = (candidates.userTurns || []).slice(-6)
-  for (const turn of turns) { if (bullets.length >= maxBullets) break; push(date + 'request', turn) }
-  for (const item of (candidates.checkpoints || []).slice(-2)) { if (bullets.length >= maxBullets) break; push(date + 'checkpoint', item) }
-  return bullets.slice(0, maxBullets)
-}
-
-/**
- * Summarize one session through the given llm, falling back deterministically.
- * @returns {Promise<{ bullets: string[], source: 'llm'|'fallback'|'none', error?: string }>}
- */
-export async function summarizeSession(llm, candidates = {}, meta = {}, options = {}) {
-  const config = { maxBullets: 16, maxChars: 2000, fallback: true, ...options }
-  const deterministic = () => {
-    const bullets = fallbackBullets(candidates, config)
-    return bullets.length === 0 ? { bullets: [], source: 'none' } : { bullets, source: 'fallback' }
-  }
-  if (typeof llm !== 'function') return deterministic()
-  let reply
-  try {
-    reply = await llm(buildSummaryPrompt(candidates, meta))
-  } catch (error) {
-    if (!config.fallback) throw error
-    const result = deterministic()
-    // A thrown call is a failure even when the fallback salvaged bullets from the material.
-    return { ...result, reason: result.bullets.length ? undefined : 'error', error: String((error && error.message) || error) }
-  }
-  const parsed = parseSummary(reply, config)
-  // The REASON matters downstream: 'no-durable' is a settled conclusion, while an empty or
-  // unparseable reply is a FAILURE that deserves another attempt. Collapsing both into
-  // 'none' is how a failed summary got permanently marked as handled.
-  if (parsed.none) return { bullets: [], source: 'none', reason: parsed.reason }
-  return { bullets: parsed.bullets, source: 'llm' }
-}
-
-/** Clip a markdown block, preserving line structure (clip() flattens whitespace). */
-export function clipBlock(text, max) {
-  const value = String(text == null ? '' : text)
-  if (value.length <= max) return value
-  const head = Math.max(1, Math.floor(max * 0.6))
-  const tail = Math.max(0, max - head - 6)
-  return value.slice(0, head) + '\n...\n' + (tail > 0 ? value.slice(value.length - tail) : '')
-}
-
-/** Render one dated summary section for a digest file. */
-export function renderSummarySection(bullets, { stamp, source = 'llm' } = {}) {
-  const lines = ['## ' + (stamp || new Date().toISOString()) + ' - summary (' + source + ')']
-  for (const bullet of bullets) lines.push(bullet)
-  return lines.join('\n') + '\n'
-}
+// Session summarization: the CAPTURE stage turns raw session material into durable
+// notes. The instructions below are deliberately durable (they are the contract the
+// store relies on), and parsing is lenient so a model that ignores the format still
+// degrades to a deterministic fallback instead of writing noise.
+
+/** Marker a model returns when a session holds nothing worth remembering. */
+export const NO_DURABLE = 'NO_DURABLE_CONTENT'
+
+/** Durable capture instructions: what durable memory is, and what it is not. */
+export const SUMMARY_INSTRUCTIONS = [
+  'You are the CAPTURE stage of a long-term memory system for a coding agent.',
+  'You receive the raw material of ONE work session. Reply with durable notes only.',
+  '',
+  'FORMAT (strict):',
+  '- Markdown bullet points, one fact per bullet. No preamble, no headings, no code fences.',
+  '- 5-12 bullets, together under 1200 characters.',
+  '- Each bullet: "- **<short label>:** <the fact>"',
+  '- If a bullet is time-bound, lead with the date: "- **2026-09-30 - <label>:** <fact>"',
+  '- Name concrete identifiers when they matter: file paths, commands, ids, config keys, versions.',
+  '- Add one clause of why when a decision was made.',
+  '',
+  'KEEP (durable):',
+  '- decisions and their rationale; constraints, gotchas, surprises',
+  '- chosen dependencies, conventions and architecture, with the reason they won',
+  '- user preferences, standing rules, corrections',
+  '- environment facts: paths, services, ports, versions, where credentials live',
+  '- which modules or subsystems the session actually worked in, and what each one does',
+  '- whether a fact is durable (a decision, a convention) or perishable (what is running now)',
+  '- verified outcomes and results',
+  '- unresolved problems and agreed next steps',
+  '',
+  'DROP (never store):',
+  '- tool calls, command mechanics, retries, build/scan output',
+  '- code blocks, diffs and file dumps (name the file instead)',
+  '- a bare list of file paths: they are given for context, so name only the ones that matter',
+  '- status updates, acknowledgements, pleasantries, restatements',
+  '- anything that is only meaningful inside a single turn',
+  '',
+  'RULES:',
+  '- Never invent facts. Compress only what the material shows.',
+  '- Prefer durable statements over narration of what the agent did.',
+  '- If the session holds nothing durable, reply with exactly: ' + NO_DURABLE,
+  '  That is a common and correct answer. Never manufacture a bullet to avoid an empty reply.',
+].join('\n')
+
+/** Clip one message to a head+tail window so a single huge message cannot dominate. */
+export function clip(text, max = 600) {
+  const value = String(text == null ? '' : text).replace(/\s+/g, ' ').trim()
+  if (value.length <= max) return value
+  const head = Math.max(1, Math.floor(max * 0.7))
+  const tail = Math.max(0, max - head - 3)
+  return value.slice(0, head) + '...' + (tail > 0 ? value.slice(value.length - tail) : '')
+}
+
+/** Gist of an assistant message: its first meaningful line, clipped. */
+/**
+ * Gist of an assistant message: the substance of what it reported.
+ *
+ * Taking the first line was wrong for research and analysis work. Those answers open with a
+ * one-line status ("Analysis complete.") and put every finding in the body, so the capture
+ * pipeline saw the announcement and none of the substance - the exact material the memory
+ * system exists to keep. The gist now skips a bare status opener and carries the following
+ * content, so a report reaches the summarizer as findings rather than as a headline.
+ */
+export function gist(text, max = 240) {
+  const value = String(text == null ? '' : text)
+  const lines = value.split('\n').map((raw) => raw.replace(/^[#>*\-\s]+/, '').trim())
+  const meaningful = lines.filter((line) => line.length >= 12)
+  if (meaningful.length === 0) return clip(value, max)
+  // A short opener that only announces completion is a headline, not the content.
+  const OPENER = /^(analysis complete|done|finished|completed|all done|i(\x27ve| have) (finished|completed)|summary[:\s]|here(\x27s| is) (a|the) (summary|report|analysis))/i
+  const start = (meaningful.length > 1 && OPENER.test(meaningful[0])) ? 1 : 0
+  // Prefer the first two meaningful lines so a heading plus its substance both survive.
+  const picked = meaningful.slice(start, start + 2).join(' ')
+  return clip(picked === '' ? meaningful[0] : picked, max)
+}
+
+/** Build the single summarization prompt from bounded session candidates. */
+export function buildSummaryPrompt(candidates = {}, meta = {}) {
+  const lines = [
+    SUMMARY_INSTRUCTIONS,
+    '',
+    '--- SESSION ---',
+    'Title: ' + (candidates.title || candidates.sessionId || 'untitled'),
+    'Date: ' + (meta.date || candidates.date || ''),
+    'Cwd: ' + (candidates.cwd || ''),
+    'Events: ' + (candidates.eventCount == null ? 0 : candidates.eventCount)
+      + '   Tool calls: ' + (candidates.toolCallCount == null ? 0 : candidates.toolCallCount),
+  ]
+  if (candidates.goals && candidates.goals.length) lines.push('Goals: ' + candidates.goals.join(' | '))
+  if (candidates.userTurns && candidates.userTurns.length) {
+    lines.push('', '--- USER TURNS (' + candidates.userTurns.length + ') ---')
+    for (const turn of candidates.userTurns) lines.push('- ' + turn)
+  }
+  if (candidates.assistantGists && candidates.assistantGists.length) {
+    lines.push('', '--- ASSISTANT GISTS (' + candidates.assistantGists.length + ') ---')
+    for (const item of candidates.assistantGists) lines.push('- ' + item)
+  }
+  if (candidates.files && candidates.files.length) {
+    lines.push('', '--- FILES THE SESSION WORKED IN (' + candidates.files.length + ') ---')
+    for (const file of candidates.files) lines.push('- ' + file)
+  }
+  if (candidates.checkpoints && candidates.checkpoints.length) {
+    lines.push('', '--- COMPACTION CHECKPOINTS ---')
+    for (const item of candidates.checkpoints) lines.push('- ' + item)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Leniently read bullets out of a model reply.
+ * @returns {{ bullets: string[], none: boolean }} normalized bullet lines.
+ */
+export function parseSummary(text, { maxBullets = 16, maxChars = 2000 } = {}) {
+  const source = String(text == null ? '' : text).trim()
+  if (source === '') return { bullets: [], none: true, reason: 'empty-reply' }
+  if (source.toUpperCase().includes(NO_DURABLE)) return { bullets: [], none: true, reason: 'no-durable' }
+  const bullets = []
+  let total = 0
+  for (const raw of source.replace(/\x60\x60\x60[\s\S]*?\x60\x60\x60/g, '').split('\n')) {
+    const line = raw.trim()
+    if (!/^[-*+]\s+/.test(line)) continue
+    const bullet = '- ' + line.replace(/^[-*+]\s+/, '').trim()
+    if (bullet.length <= 3) continue
+    if (total + bullet.length > maxChars && bullets.length > 0) break
+    bullets.push(bullet)
+    total += bullet.length + 1
+    if (bullets.length >= maxBullets) break
+  }
+  return bullets.length === 0 ? { bullets: [], none: true, reason: 'unparseable' } : { bullets, none: false }
+}
+
+/** Deterministic notes used when the summarizer is unavailable or unusable. */
+export function fallbackBullets(candidates = {}, { maxBullets = 8, maxChars = 1000 } = {}) {
+  const bullets = []
+  let total = 0
+  const push = (label, fact) => {
+    const body = clip(fact, 220)
+    if (body === '') return
+    const bullet = '- **' + label + ':** ' + body
+    if (total + bullet.length > maxChars && bullets.length > 0) return
+    bullets.push(bullet)
+    total += bullet.length + 1
+  }
+  const date = candidates.date ? String(candidates.date).slice(0, 10) + ' - ' : ''
+  for (const goal of (candidates.goals || []).slice(0, 2)) push(date + 'goal', goal)
+  const turns = (candidates.userTurns || []).slice(-6)
+  for (const turn of turns) { if (bullets.length >= maxBullets) break; push(date + 'request', turn) }
+  for (const item of (candidates.checkpoints || []).slice(-2)) { if (bullets.length >= maxBullets) break; push(date + 'checkpoint', item) }
+  return bullets.slice(0, maxBullets)
+}
+
+/**
+ * Summarize one session through the given llm, falling back deterministically.
+ * @returns {Promise<{ bullets: string[], source: 'llm'|'fallback'|'none', error?: string }>}
+ */
+export async function summarizeSession(llm, candidates = {}, meta = {}, options = {}) {
+  const config = { maxBullets: 16, maxChars: 2000, fallback: true, ...options }
+  const deterministic = () => {
+    const bullets = fallbackBullets(candidates, config)
+    return bullets.length === 0 ? { bullets: [], source: 'none' } : { bullets, source: 'fallback' }
+  }
+  if (typeof llm !== 'function') return deterministic()
+  let reply
+  try {
+    reply = await llm(buildSummaryPrompt(candidates, meta))
+  } catch (error) {
+    if (!config.fallback) throw error
+    const result = deterministic()
+    // A thrown call is a failure even when the fallback salvaged bullets from the material.
+    return { ...result, reason: result.bullets.length ? undefined : 'error', error: String((error && error.message) || error) }
+  }
+  const parsed = parseSummary(reply, config)
+  // The REASON matters downstream: 'no-durable' is a settled conclusion, while an empty or
+  // unparseable reply is a FAILURE that deserves another attempt. Collapsing both into
+  // 'none' is how a failed summary got permanently marked as handled.
+  if (parsed.none) return { bullets: [], source: 'none', reason: parsed.reason }
+  return { bullets: parsed.bullets, source: 'llm' }
+}
+
+/** Clip a markdown block, preserving line structure (clip() flattens whitespace). */
+export function clipBlock(text, max) {
+  const value = String(text == null ? '' : text)
+  if (value.length <= max) return value
+  const head = Math.max(1, Math.floor(max * 0.6))
+  const tail = Math.max(0, max - head - 6)
+  return value.slice(0, head) + '\n...\n' + (tail > 0 ? value.slice(value.length - tail) : '')
+}
+
+/** Render one dated summary section for a digest file. */
+export function renderSummarySection(bullets, { stamp, source = 'llm' } = {}) {
+  const lines = ['## ' + (stamp || new Date().toISOString()) + ' - summary (' + source + ')']
+  for (const bullet of bullets) lines.push(bullet)
+  return lines.join('\n') + '\n'
+}