@try-works/dsh-memory 0.1.19 → 0.1.20

package/src/index.js

@@ -1,94 +1,115 @@
-// dsh-memory plugin entry (Cordis). Config/settings, store lifecycle, the ctx.memory
-// service, memory_* tools, and the deep host hooks (capture/consolidate/inject/sync).
-import { Config } from './config.js'
-import { resolveConfig } from './defaults.js'
-import { MemoryStore } from './store.js'
-import { search } from './search.js'
-import { remember } from './remember.js'
-import { associate, listWorkspaces, resolveKeyFor } from './workspace.js'
-import { pendingDigests } from './capture.js'
-import { migrateToLayered } from './layers.js'
-import { writeSystemDoc } from './system-doc.js'
-import { readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-/** The plugin version, read from its own manifest; never fatal if it cannot be read. */
-function readPluginVersion() {
-  try {
-    const manifest = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
-    return JSON.parse(readFileSync(manifest, 'utf8')).version ?? 'unknown'
-  } catch { return 'unknown' }
-}
-const PLUGIN_VERSION = readPluginVersion()
-
-/**
- * The capabilities registerTools needs, taken from the host in ONE place.
- *
- * This used to be an inline object literal, and the wiring test wrote its own COPY of it. A copy
- * drifts: the test's version was missing `recover`, so a tool wired to nothing passed every test
- * and failed the moment a real session called it. Deriving both from the host object means the
- * test cannot describe a wiring the plugin does not have.
- */
-export function hostExtras(host) {
-  return {
-    syncNow: host.syncNow,
-    consolidate: host.consolidate,
-    refresh: host.refresh,
-    status: host.status,
-    recover: host.recover,
-    rerankSearch: host.rerankSearch,
-    workspaceOf: host.workspaceOf,
-    historyOf: host.historyOf,
-    injectionMaxChars: host.injectionMaxChars,
-    tasksNow: host.tasksNow,
-    tasksRestore: host.tasksRestore,
-    schedulePath: host.schedulePath,
-  }
-}
-export const name = 'dsh-memory'
-import { registerTools } from './tools.js'
-import { wireHost } from './host.js'
-
-export const inject = ['tools']
-export { Config }
-
-export function apply(ctx, config = {}) {
-  const cfg = resolveConfig(config)
-  const store = new MemoryStore(cfg)
-
-  try {
-    store.ensureLayout()
-    // Layered storage landed after the first stores existed: move any entries still sitting
-    // in a single layer file into per-topic files and rebuild its index. Idempotent.
-    store.syncGitBlock()
-    const moved = migrateToLayered(store.root)
-    if (moved > 0) ctx.logger.info('dsh-memory: moved ' + moved + ' entr(ies) into per-topic files')
-    // Regenerate the manual for the machinery on every boot, so it can never describe a
-    // version of the plugin that no longer exists.
-    writeSystemDoc(store.root, { cfg, version: PLUGIN_VERSION })
-  } catch (error) { ctx.logger.warn('dsh-memory: could not prepare memory store at ' + store.root + ': ' + (error && error.message)) }
-
-  ctx.provide('memory', {
-    get root() { return store.root },
-    status: () => store.status(),
-    search: (query, opts) => search(store, query, opts),
-    remember: (opts) => remember(store, opts),
-    workspaces: () => listWorkspaces(store),
-    associate: (opts) => associate(store, opts),
-    resolveKey: (input) => resolveKeyFor(store.root, input),
-    pending: () => pendingDigests(store).length,
-    consolidate: (agent, opts) => host.consolidate(agent, opts),
-    workspaceOf: (agent) => host.workspaceOf(agent),
-    historyOf: (agent, opts) => host.historyOf(agent, opts),
-  })
-
-  const host = wireHost(ctx, store, cfg)
-  registerTools(ctx, store, hostExtras(host))
-
-  ctx.on('settings/document-updated', () => { ctx.logger.debug('dsh-memory: settings changed') })
-
-  ctx.effect(() => { store.dispose() })
-
-  return host
-}
+// dsh-memory plugin entry (Cordis). Config/settings, store lifecycle, the ctx.memory
+// service, memory_* tools, and the deep host hooks (capture/consolidate/inject/sync).
+import { Config } from './config.js'
+import { resolveConfig } from './defaults.js'
+import { MemoryStore } from './store.js'
+import { search } from './search.js'
+import { remember } from './remember.js'
+import { associate, listWorkspaces, resolveKeyFor } from './workspace.js'
+import { pendingDigests } from './capture.js'
+import { migrateToLayered } from './layers.js'
+import { writeSystemDoc } from './system-doc.js'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The plugin version, read from its own manifest; never fatal if it cannot be read. */
+function readPluginVersion() {
+  try {
+    const manifest = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
+    return JSON.parse(readFileSync(manifest, 'utf8')).version ?? 'unknown'
+  } catch { return 'unknown' }
+}
+const PLUGIN_VERSION = readPluginVersion()
+
+/**
+ * The capabilities registerTools needs, taken from the host in ONE place.
+ *
+ * This used to be an inline object literal, and the wiring test wrote its own COPY of it. A copy
+ * drifts: the test's version was missing `recover`, so a tool wired to nothing passed every test
+ * and failed the moment a real session called it. Deriving both from the host object means the
+ * test cannot describe a wiring the plugin does not have.
+ */
+export function hostExtras(host) {
+  return {
+    syncNow: host.syncNow,
+    consolidate: host.consolidate,
+    refresh: host.refresh,
+    status: host.status,
+    recover: host.recover,
+    rerankSearch: host.rerankSearch,
+    workspaceOf: host.workspaceOf,
+    historyOf: host.historyOf,
+    injectionMaxChars: host.injectionMaxChars,
+    tasksNow: host.tasksNow,
+    tasksRestore: host.tasksRestore,
+    schedulePath: host.schedulePath,
+  }
+}
+export const name = 'dsh-memory'
+import { registerTools } from './tools.js'
+import { wireHost } from './host.js'
+
+export const inject = ['tools']
+export { Config }
+
+export function apply(ctx, config = {}) {
+  const cfg = resolveConfig(config)
+  /**
+   * Re-read volatile fields when the loader commits a configuration change.
+   *
+   * resolveConfig UNWRAPS a volatile reference into a plain value and is called once, here, at
+   * load. That snapshot never moves - so a git origin typed into Settings was written to the
+   * profile file, committed into the running fiber by the loader, and still never reached this
+   * instance: memory_sync answered synced:false with no remote added and no error to explain it.
+   *
+   * The contract is documented and this code already half-knew it: volatile fields parse to a
+   * reference rather than a value, and the cookbook says to read it when STARTING an operation
+   * (docs/cookbook/adding-a-settings-card.md). Mutating cfg IN PLACE is what makes that true here,
+   * because every consumer reads cfg.<field> at call time instead of capturing it.
+   */
+  ctx.on('loader/volatile-update', () => {
+    try {
+      const next = resolveConfig(config)
+      for (const key of Object.keys(next)) cfg[key] = next[key]
+    } catch (error) {
+      ctx.logger.warn('dsh-memory: could not re-read configuration: ' + (error && error.message))
+    }
+  })
+  const store = new MemoryStore(cfg)
+
+  try {
+    store.ensureLayout()
+    // Layered storage landed after the first stores existed: move any entries still sitting
+    // in a single layer file into per-topic files and rebuild its index. Idempotent.
+    store.syncGitBlock()
+    const moved = migrateToLayered(store.root)
+    if (moved > 0) ctx.logger.info('dsh-memory: moved ' + moved + ' entr(ies) into per-topic files')
+    // Regenerate the manual for the machinery on every boot, so it can never describe a
+    // version of the plugin that no longer exists.
+    writeSystemDoc(store.root, { cfg, version: PLUGIN_VERSION })
+  } catch (error) { ctx.logger.warn('dsh-memory: could not prepare memory store at ' + store.root + ': ' + (error && error.message)) }
+
+  ctx.provide('memory', {
+    get root() { return store.root },
+    status: () => store.status(),
+    search: (query, opts) => search(store, query, opts),
+    remember: (opts) => remember(store, opts),
+    workspaces: () => listWorkspaces(store),
+    associate: (opts) => associate(store, opts),
+    resolveKey: (input) => resolveKeyFor(store.root, input),
+    pending: () => pendingDigests(store).length,
+    consolidate: (agent, opts) => host.consolidate(agent, opts),
+    workspaceOf: (agent) => host.workspaceOf(agent),
+    historyOf: (agent, opts) => host.historyOf(agent, opts),
+  })
+
+  const host = wireHost(ctx, store, cfg)
+  registerTools(ctx, store, hostExtras(host))
+
+  ctx.on('settings/document-updated', () => { ctx.logger.debug('dsh-memory: settings changed') })
+
+  ctx.effect(() => { store.dispose() })
+
+  return host
+}

package/src/inject.js

@@ -1,108 +1,108 @@
-// Session-start injection text: goal + working head + recent learnings + footer,
-// char-capped and scope-aware.
-import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { layerDir } from './store.js'
-import { buildLedger } from './ledger.js'
-import { readLayerTopics } from './layers.js'
-import { freshnessMarker, readState } from './state.js'
-import { readWorking, workingMarker } from './working.js'
-import { relevanceQuery, selectEntries } from './select.js'
-
-export function buildInjectionText(store, { scope = 'global', key, goal, maxChars = 3600, subagent = false } = {}) {
-  const dir = layerDir(store.root, scope, key)
-  // Working memory is the AGENT's intent (task, recent activity, next steps); repository
-  const ledger = buildLedger(store.root)
-  const prefix = scope === 'global' ? 'global/' : 'workspaces/' + key + '/'
-  // The pools are LISTED here and CHOSEN later, because choosing needs the question, and the
-  // question comes from working memory - which is read below.
-  const learningPool = ledger.filter((e) => e.file.startsWith(prefix) && e.layer === 'learning')
-  const decisionPool = ledger.filter((e) => e.file.startsWith(prefix) && e.layer === 'decision')
-  // state (state.md) is the repository's. Different owners, different lifetimes: a repository
-  const workingMemory = scope === 'workspace' ? readWorking(store.root, scope, key) : undefined
-  // What this turn is about, from the agent's own live task - see relevanceQuery for why the
-  // task outranks the goal.
-  const query = relevanceQuery(workingMemory, goal)
-  const learned = selectEntries(store, learningPool, query, 5, { scope, key })
-  const learnings = learned.entries
-  const learningsRelevant = learned.relevant
-  const decisions = selectEntries(store, decisionPool, query, 5, { scope, key }).entries
-  const parts = ['## DSH memory context']
-  if (goal) parts.push('### Goal\n' + goal)
-  // Workspace state goes FIRST and is never buried: it is the overview, and its value
-  // depends on the reader knowing how current it is. A stale section is shown WITH its age
-  // rather than hidden, so it reads as something to check instead of something to trust.
-  if (scope === 'workspace') {
-    const state = readState(store.root, key)
-    if (state && state.sections.length > 0) {
-      const lines = state.sections.slice(0, 8).map((section) => {
-        const marker = freshnessMarker(section.verdict, section.ageMs)
-        const body = section.content.split(String.fromCharCode(10)).slice(0, 3).join(' ')
-        return '- **' + section.name + '**' + marker + (body ? ': ' + body : '')
-      })
-      parts.push('### Repository state' + String.fromCharCode(10) + lines.join(String.fromCharCode(10)))
-    }
-  }
-  // The agent must know this file exists, that it is THEIRS, and what it is for. So the card
-  // names the file and its purpose, and an unrecorded file is called out rather than hidden:
-  // silence would read as 'no working memory' when it actually means 'nothing written yet'.
-  if (scope === 'workspace') {
-    const relative = 'workspaces/' + key + '/working.md'
-    const marker = workingMemory ? workingMarker(workingMemory.verdict, workingMemory.ageMs) : ''
-    const hasContent = workingMemory && (workingMemory.sections.length > 0 || workingMemory.activity.length > 0)
-    const lines = ['### Working memory — yours' + marker]
-    lines.push('Your own file at ' + relative + ': the task in hand, recent activity, next steps.')
-    lines.push('You own it — read and edit it freely; keep it current. Repository state lives separately in state.md.')
-    if (hasContent) {
-      for (const section of workingMemory.sections.slice(0, 4)) {
-        lines.push('- **' + section.name + '**: ' + section.content.split(String.fromCharCode(10)).join(' ').slice(0, 300))
-      }
-      const recent = workingMemory.activity.slice(-4)
-      if (recent.length) lines.push('- **Recently**: ' + recent.map((a) => a.text).join('; ').slice(0, 400))
-    } else {
-      lines.push('- (nothing recorded yet. Record your task with memory_working if it helps you — this is optional.)')
-    }
-    parts.push(lines.join(String.fromCharCode(10)))
-  }
-  // The heading says WHICH rule chose these. 'Recent' and 'relevant to this task' are different
-  // claims, and a reader deciding how much to trust a line needs to know which one was made.
-  if (learnings.length) {
-    const heading = learningsRelevant ? '### Relevant learnings' : '### Recent learnings'
-    parts.push(heading + '\n' + learnings.map((e) => '- ' + e.heading + ': ' + e.content).join('\n'))
-  }
-  // Settled decisions belong in front of the agent: they are the constraints it must respect.
-  if (decisions.length) parts.push('### Decisions in force\n' + decisions.map((e) => '- ' + e.heading).join('\n'))
-  // The codebase map is per workspace: show what has been mapped so far, so the agent
-  // knows what it can already rely on and what is still unexplored.
-  const mapped = scope === 'workspace' ? readLayerTopics(store.root, scope, key, 'codebase') : []
-  if (mapped.length) {
-    const shown = mapped.slice(0, 30).map((topic) => {
-      const entry = topic.entries[0]
-      return '- ' + (entry ? entry.heading : topic.slug)
-    })
-    if (mapped.length > 30) shown.push('- (+' + (mapped.length - 30) + ' more)')
-    parts.push('### Codebase map\n' + shown.join('\n'))
-  }
-  // The footer is the one line the agent sees on every turn, so it carries the standing rule
-  // about RESTRAINT, not just the tools. An agent that feels obliged to write every few
-  // minutes turns memory into a junk drawer; declining is the correct outcome when nothing
-  // durable was learned.
-  // A subagent READS but does not write: memory is the main agent's account of the work, and the
-  // parent already owns the delegation and its result. Telling a child to record would invite it
-  // to write a partial account competing with its parent's, so the footer states the actual rule.
-  const WRITE_FOOTER = [
-    'Use memory_search to recall more.',
-    'Write ONLY when something durable was actually learned: a decision, a constraint, a',
-    'preference, an environment fact, a lesson, or how a module works.',
-    'Writing NOTHING is a correct and expected outcome - most turns add nothing, and a fact that',
-    'only mattered for one turn is not memory. Never invent an entry to fill a gap.',
-  ].join(String.fromCharCode(10))
-  const READ_FOOTER = [
-    'Use memory_search to recall more.',
-    'Memory is written by the main agent that delegated this work.',
-    'Report what you find back to it, and do not record memory yourself.',
-  ].join(String.fromCharCode(10))
-  const footer = subagent ? READ_FOOTER : WRITE_FOOTER
-  const body = parts.join('\n\n')
-  return (body.length <= maxChars ? body : body.slice(0, maxChars)) + '\n\n' + footer
-}
+// Session-start injection text: goal + working head + recent learnings + footer,
+// char-capped and scope-aware.
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { layerDir } from './store.js'
+import { buildLedger } from './ledger.js'
+import { readLayerTopics } from './layers.js'
+import { freshnessMarker, readState } from './state.js'
+import { readWorking, workingMarker } from './working.js'
+import { relevanceQuery, selectEntries } from './select.js'
+
+export function buildInjectionText(store, { scope = 'global', key, goal, maxChars = 3600, subagent = false } = {}) {
+  const dir = layerDir(store.root, scope, key)
+  // Working memory is the AGENT's intent (task, recent activity, next steps); repository
+  const ledger = buildLedger(store.root)
+  const prefix = scope === 'global' ? 'global/' : 'workspaces/' + key + '/'
+  // The pools are LISTED here and CHOSEN later, because choosing needs the question, and the
+  // question comes from working memory - which is read below.
+  const learningPool = ledger.filter((e) => e.file.startsWith(prefix) && e.layer === 'learning')
+  const decisionPool = ledger.filter((e) => e.file.startsWith(prefix) && e.layer === 'decision')
+  // state (state.md) is the repository's. Different owners, different lifetimes: a repository
+  const workingMemory = scope === 'workspace' ? readWorking(store.root, scope, key) : undefined
+  // What this turn is about, from the agent's own live task - see relevanceQuery for why the
+  // task outranks the goal.
+  const query = relevanceQuery(workingMemory, goal)
+  const learned = selectEntries(store, learningPool, query, 5, { scope, key })
+  const learnings = learned.entries
+  const learningsRelevant = learned.relevant
+  const decisions = selectEntries(store, decisionPool, query, 5, { scope, key }).entries
+  const parts = ['## DSH memory context']
+  if (goal) parts.push('### Goal\n' + goal)
+  // Workspace state goes FIRST and is never buried: it is the overview, and its value
+  // depends on the reader knowing how current it is. A stale section is shown WITH its age
+  // rather than hidden, so it reads as something to check instead of something to trust.
+  if (scope === 'workspace') {
+    const state = readState(store.root, key)
+    if (state && state.sections.length > 0) {
+      const lines = state.sections.slice(0, 8).map((section) => {
+        const marker = freshnessMarker(section.verdict, section.ageMs)
+        const body = section.content.split(String.fromCharCode(10)).slice(0, 3).join(' ')
+        return '- **' + section.name + '**' + marker + (body ? ': ' + body : '')
+      })
+      parts.push('### Repository state' + String.fromCharCode(10) + lines.join(String.fromCharCode(10)))
+    }
+  }
+  // The agent must know this file exists, that it is THEIRS, and what it is for. So the card
+  // names the file and its purpose, and an unrecorded file is called out rather than hidden:
+  // silence would read as 'no working memory' when it actually means 'nothing written yet'.
+  if (scope === 'workspace') {
+    const relative = 'workspaces/' + key + '/working.md'
+    const marker = workingMemory ? workingMarker(workingMemory.verdict, workingMemory.ageMs) : ''
+    const hasContent = workingMemory && (workingMemory.sections.length > 0 || workingMemory.activity.length > 0)
+    const lines = ['### Working memory — yours' + marker]
+    lines.push('Your own file at ' + relative + ': the task in hand, recent activity, next steps.')
+    lines.push('You own it — read and edit it freely; keep it current. Repository state lives separately in state.md.')
+    if (hasContent) {
+      for (const section of workingMemory.sections.slice(0, 4)) {
+        lines.push('- **' + section.name + '**: ' + section.content.split(String.fromCharCode(10)).join(' ').slice(0, 300))
+      }
+      const recent = workingMemory.activity.slice(-4)
+      if (recent.length) lines.push('- **Recently**: ' + recent.map((a) => a.text).join('; ').slice(0, 400))
+    } else {
+      lines.push('- (nothing recorded yet. Record your task with memory_working if it helps you — this is optional.)')
+    }
+    parts.push(lines.join(String.fromCharCode(10)))
+  }
+  // The heading says WHICH rule chose these. 'Recent' and 'relevant to this task' are different
+  // claims, and a reader deciding how much to trust a line needs to know which one was made.
+  if (learnings.length) {
+    const heading = learningsRelevant ? '### Relevant learnings' : '### Recent learnings'
+    parts.push(heading + '\n' + learnings.map((e) => '- ' + e.heading + ': ' + e.content).join('\n'))
+  }
+  // Settled decisions belong in front of the agent: they are the constraints it must respect.
+  if (decisions.length) parts.push('### Decisions in force\n' + decisions.map((e) => '- ' + e.heading).join('\n'))
+  // The codebase map is per workspace: show what has been mapped so far, so the agent
+  // knows what it can already rely on and what is still unexplored.
+  const mapped = scope === 'workspace' ? readLayerTopics(store.root, scope, key, 'codebase') : []
+  if (mapped.length) {
+    const shown = mapped.slice(0, 30).map((topic) => {
+      const entry = topic.entries[0]
+      return '- ' + (entry ? entry.heading : topic.slug)
+    })
+    if (mapped.length > 30) shown.push('- (+' + (mapped.length - 30) + ' more)')
+    parts.push('### Codebase map\n' + shown.join('\n'))
+  }
+  // The footer is the one line the agent sees on every turn, so it carries the standing rule
+  // about RESTRAINT, not just the tools. An agent that feels obliged to write every few
+  // minutes turns memory into a junk drawer; declining is the correct outcome when nothing
+  // durable was learned.
+  // A subagent READS but does not write: memory is the main agent's account of the work, and the
+  // parent already owns the delegation and its result. Telling a child to record would invite it
+  // to write a partial account competing with its parent's, so the footer states the actual rule.
+  const WRITE_FOOTER = [
+    'Use memory_search to recall more.',
+    'Write ONLY when something durable was actually learned: a decision, a constraint, a',
+    'preference, an environment fact, a lesson, or how a module works.',
+    'Writing NOTHING is a correct and expected outcome - most turns add nothing, and a fact that',
+    'only mattered for one turn is not memory. Never invent an entry to fill a gap.',
+  ].join(String.fromCharCode(10))
+  const READ_FOOTER = [
+    'Use memory_search to recall more.',
+    'Memory is written by the main agent that delegated this work.',
+    'Report what you find back to it, and do not record memory yourself.',
+  ].join(String.fromCharCode(10))
+  const footer = subagent ? READ_FOOTER : WRITE_FOOTER
+  const body = parts.join('\n\n')
+  return (body.length <= maxChars ? body : body.slice(0, maxChars)) + '\n\n' + footer
+}