@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/context.js

@@ -1,88 +1,88 @@
-// Context card: a lane-allocated budget over working/episodes/learnings/queryRecall.
-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 { search } from './search.js'
-
-export const CONTEXT_DEFAULT_TOKENS = 2000
-const SPEC = { working: { floor: 250, ceiling: 600 }, episodes: { floor: 0, ceiling: 300 }, learnings: { floor: 0, ceiling: 300 }, codebase: { floor: 0, ceiling: 300 }, decisions: { floor: 0, ceiling: 300 } }
-const QUERY_RESERVE = 200
-
-/**
- * Distribute a token budget across lanes: reserve query, fill floors, grow to
- * ceilings in priority order (working > episodes > learnings), then let query
- * borrow the remainder. Pure; returns the per-lane allocation.
- */
-export function allocateContextLanes({ budgetTokens = CONTEXT_DEFAULT_TOKENS, demand = {} } = {}) {
-  const budget = Number.isFinite(budgetTokens) && budgetTokens > 0 ? budgetTokens : CONTEXT_DEFAULT_TOKENS
-  const lanes = ['working', 'episodes', 'learnings', 'decisions', 'codebase']
-  const allocated = { working: 0, episodes: 0, learnings: 0, decisions: 0, codebase: 0, queryRecall: 0 }
-  let remaining = budget
-  for (const lane of lanes) {
-    const give = Math.min(SPEC[lane].floor, demand[lane] ?? 0, remaining)
-    allocated[lane] = give
-    remaining -= give
-  }
-  allocated.queryRecall = Math.min(QUERY_RESERVE, demand.queryRecall ?? 0, remaining)
-  remaining -= allocated.queryRecall
-  for (const lane of lanes) {
-    const want = Math.min(demand[lane] ?? 0, SPEC[lane].ceiling) - allocated[lane]
-    const give = Math.max(0, Math.min(want, remaining))
-    allocated[lane] += give
-    remaining -= give
-  }
-  const qWant = Math.max(0, (demand.queryRecall ?? 0) - allocated.queryRecall)
-  const qGive = Math.min(qWant, remaining)
-  allocated.queryRecall += qGive
-  remaining -= qGive
-  return { policyVersion: 1, allocated, unallocated: remaining }
-}
-
-export function estimateTokens(text) { return String(text ?? '').split(/\s+/).filter(Boolean).length }
-export function truncateToTokens(text, budgetTokens) {
-  const words = String(text ?? '').split(/\s+/).filter(Boolean)
-  if (words.length <= budgetTokens) return String(text ?? '')
-  return words.slice(0, budgetTokens).join(' ') + ' …'
-}
-
-/** Assemble a scope-aware context card under a token budget. Pure over the store. */
-export function buildContextCard(store, { scope = 'global', key, budgetTokens = CONTEXT_DEFAULT_TOKENS, query, goal } = {}) {
-  const dir = layerDir(store.root, scope, key)
-  // Working memory is per repo/workspace; the global layer has no working lane.
-  const working = scope === 'workspace' && existsSync(join(dir, 'working.md')) ? readFileSync(join(dir, 'working.md'), 'utf8') : ''
-  const ledger = buildLedger(store.root)
-  const prefix = scope === 'global' ? 'global/' : 'workspaces/' + key + '/'
-  const scoped = ledger.filter((e) => e.file.startsWith(prefix))
-  const episodes = scoped.filter((e) => e.layer === 'episodic')
-    .sort((a, b) => String(b.date ?? '').localeCompare(String(a.date ?? ''))).slice(0, 5)
-  const learnings = scoped.filter((e) => e.layer === 'learning').slice(-5)
-  const decisions = scoped.filter((e) => e.layer === 'decision').slice(-5)
-  const queryHits = query ? search(store, query, { scope, key, limit: 5 }) : []
-
-  // The codebase map is per workspace; its index topics are the useful summary.
-  const mapped = scope === 'workspace' ? readLayerTopics(store.root, scope, key, 'codebase') : []
-  const codebase = mapped.map((topic) => (topic.entries[0] ? topic.entries[0].heading : topic.slug)).join('\n')
-  const demand = {
-    working: estimateTokens(working),
-    codebase: estimateTokens(codebase),
-    episodes: estimateTokens(episodes.map((e) => e.content).join('\n')),
-    learnings: estimateTokens(learnings.map((e) => e.content).join('\n')),
-    decisions: estimateTokens(decisions.map((e) => e.heading).join('\n')),
-    queryRecall: estimateTokens(queryHits.map((h) => h.snippet).join('\n')),
-  }
-  const { allocated } = allocateContextLanes({ budgetTokens, demand })
-
-  const sections = []
-  if (goal) sections.push('## Goal\n' + goal)
-  const workingSec = truncateToTokens(working, allocated.working)
-  if (workingSec.trim()) sections.push('## Working memory\n' + workingSec)
-  if (episodes.length) sections.push('## Recent episodes\n' + truncateToTokens(episodes.map((e) => '- ' + e.heading + ': ' + e.content).join('\n'), allocated.episodes))
-  if (codebase.trim()) sections.push('## Codebase map\n' + truncateToTokens(codebase, allocated.codebase))
-  if (decisions.length) sections.push('## Decisions in force\n' + truncateToTokens(decisions.map((e) => '- ' + e.heading).join('\n'), allocated.decisions))
-  if (learnings.length) sections.push('## Learnings\n' + truncateToTokens(learnings.map((e) => '- ' + e.heading + ': ' + e.content).join('\n'), allocated.learnings))
-  if (queryHits.length) sections.push('## Query-relevant memories\n' + truncateToTokens(queryHits.map((h) => h.file + ':' + h.line + ' ' + h.snippet).join('\n'), allocated.queryRecall))
-  sections.push('## Use\nRun memory_search to go deeper; memory_remember to persist a fact.')
-  return sections.join('\n\n')
-}
+// Context card: a lane-allocated budget over working/episodes/learnings/queryRecall.
+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 { search } from './search.js'
+
+export const CONTEXT_DEFAULT_TOKENS = 2000
+const SPEC = { working: { floor: 250, ceiling: 600 }, episodes: { floor: 0, ceiling: 300 }, learnings: { floor: 0, ceiling: 300 }, codebase: { floor: 0, ceiling: 300 }, decisions: { floor: 0, ceiling: 300 } }
+const QUERY_RESERVE = 200
+
+/**
+ * Distribute a token budget across lanes: reserve query, fill floors, grow to
+ * ceilings in priority order (working > episodes > learnings), then let query
+ * borrow the remainder. Pure; returns the per-lane allocation.
+ */
+export function allocateContextLanes({ budgetTokens = CONTEXT_DEFAULT_TOKENS, demand = {} } = {}) {
+  const budget = Number.isFinite(budgetTokens) && budgetTokens > 0 ? budgetTokens : CONTEXT_DEFAULT_TOKENS
+  const lanes = ['working', 'episodes', 'learnings', 'decisions', 'codebase']
+  const allocated = { working: 0, episodes: 0, learnings: 0, decisions: 0, codebase: 0, queryRecall: 0 }
+  let remaining = budget
+  for (const lane of lanes) {
+    const give = Math.min(SPEC[lane].floor, demand[lane] ?? 0, remaining)
+    allocated[lane] = give
+    remaining -= give
+  }
+  allocated.queryRecall = Math.min(QUERY_RESERVE, demand.queryRecall ?? 0, remaining)
+  remaining -= allocated.queryRecall
+  for (const lane of lanes) {
+    const want = Math.min(demand[lane] ?? 0, SPEC[lane].ceiling) - allocated[lane]
+    const give = Math.max(0, Math.min(want, remaining))
+    allocated[lane] += give
+    remaining -= give
+  }
+  const qWant = Math.max(0, (demand.queryRecall ?? 0) - allocated.queryRecall)
+  const qGive = Math.min(qWant, remaining)
+  allocated.queryRecall += qGive
+  remaining -= qGive
+  return { policyVersion: 1, allocated, unallocated: remaining }
+}
+
+export function estimateTokens(text) { return String(text ?? '').split(/\s+/).filter(Boolean).length }
+export function truncateToTokens(text, budgetTokens) {
+  const words = String(text ?? '').split(/\s+/).filter(Boolean)
+  if (words.length <= budgetTokens) return String(text ?? '')
+  return words.slice(0, budgetTokens).join(' ') + ' …'
+}
+
+/** Assemble a scope-aware context card under a token budget. Pure over the store. */
+export function buildContextCard(store, { scope = 'global', key, budgetTokens = CONTEXT_DEFAULT_TOKENS, query, goal } = {}) {
+  const dir = layerDir(store.root, scope, key)
+  // Working memory is per repo/workspace; the global layer has no working lane.
+  const working = scope === 'workspace' && existsSync(join(dir, 'working.md')) ? readFileSync(join(dir, 'working.md'), 'utf8') : ''
+  const ledger = buildLedger(store.root)
+  const prefix = scope === 'global' ? 'global/' : 'workspaces/' + key + '/'
+  const scoped = ledger.filter((e) => e.file.startsWith(prefix))
+  const episodes = scoped.filter((e) => e.layer === 'episodic')
+    .sort((a, b) => String(b.date ?? '').localeCompare(String(a.date ?? ''))).slice(0, 5)
+  const learnings = scoped.filter((e) => e.layer === 'learning').slice(-5)
+  const decisions = scoped.filter((e) => e.layer === 'decision').slice(-5)
+  const queryHits = query ? search(store, query, { scope, key, limit: 5 }) : []
+
+  // The codebase map is per workspace; its index topics are the useful summary.
+  const mapped = scope === 'workspace' ? readLayerTopics(store.root, scope, key, 'codebase') : []
+  const codebase = mapped.map((topic) => (topic.entries[0] ? topic.entries[0].heading : topic.slug)).join('\n')
+  const demand = {
+    working: estimateTokens(working),
+    codebase: estimateTokens(codebase),
+    episodes: estimateTokens(episodes.map((e) => e.content).join('\n')),
+    learnings: estimateTokens(learnings.map((e) => e.content).join('\n')),
+    decisions: estimateTokens(decisions.map((e) => e.heading).join('\n')),
+    queryRecall: estimateTokens(queryHits.map((h) => h.snippet).join('\n')),
+  }
+  const { allocated } = allocateContextLanes({ budgetTokens, demand })
+
+  const sections = []
+  if (goal) sections.push('## Goal\n' + goal)
+  const workingSec = truncateToTokens(working, allocated.working)
+  if (workingSec.trim()) sections.push('## Working memory\n' + workingSec)
+  if (episodes.length) sections.push('## Recent episodes\n' + truncateToTokens(episodes.map((e) => '- ' + e.heading + ': ' + e.content).join('\n'), allocated.episodes))
+  if (codebase.trim()) sections.push('## Codebase map\n' + truncateToTokens(codebase, allocated.codebase))
+  if (decisions.length) sections.push('## Decisions in force\n' + truncateToTokens(decisions.map((e) => '- ' + e.heading).join('\n'), allocated.decisions))
+  if (learnings.length) sections.push('## Learnings\n' + truncateToTokens(learnings.map((e) => '- ' + e.heading + ': ' + e.content).join('\n'), allocated.learnings))
+  if (queryHits.length) sections.push('## Query-relevant memories\n' + truncateToTokens(queryHits.map((h) => h.file + ':' + h.line + ' ' + h.snippet).join('\n'), allocated.queryRecall))
+  sections.push('## Use\nRun memory_search to go deeper; memory_remember to persist a fact.')
+  return sections.join('\n\n')
+}

package/src/decisions.js

@@ -1,106 +1,106 @@
-// Decisions: why this project is the way it is.
-//
-// A decision is not a fact (semantic) or a lesson (learning). It is a choice that was made,
-// with the reason it won and what it rules out - the thing that stops a future session from
-// re-litigating a settled question or silently reversing it.
-//
-// The writer owns the shape: the decision statement is the entry heading (so the layer index
-// reads as a list of decisions) and the reasoning lives in fixed body sections, which is what
-// makes decisions greppable and comparable. Everything here is pure.
-
-/** Body sections, in the order they are rendered. */
-export const DECISION_SECTIONS = ['context', 'rationale', 'alternatives', 'consequences']
-
-/** Human labels for the sections, used for the body headings. */
-export const DECISION_LABELS = {
-  context: 'Context',
-  rationale: 'Rationale',
-  alternatives: 'Alternatives considered',
-  consequences: 'Consequences',
-}
-
-/** Clip a decision heading to something an index line can carry. */
-export function decisionHeading(decision, max = 80) {
-  const text = String(decision ?? '').trim().replace(/\s+/g, ' ')
-  if (text === '') return 'Untitled decision'
-  return text.length > max ? text.slice(0, max - 3) + '...' : text
-}
-
-/**
- * Normalize the free-form inputs into the section keys the renderer expects.
- * Alternatives may arrive as a list or as prose; both are accepted.
- */
-export function normalizeDecision(input = {}) {
-  const text = (value) => {
-    if (value === undefined || value === null) return ''
-    if (Array.isArray(value)) return value.map((item) => String(item).trim()).filter(Boolean).join('\n')
-    return String(value).trim()
-  }
-  return {
-    context: text(input.context),
-    rationale: text(input.rationale),
-    alternatives: text(input.alternatives),
-    consequences: text(input.consequences),
-  }
-}
-
-/**
- * Render the body of a decision entry.
- * @param input - { context, rationale, alternatives, consequences }.
- * @returns markdown body; sections without content are omitted rather than left empty.
- */
-export function renderDecisionBody(input = {}) {
-  const sections = normalizeDecision(input)
-  const out = []
-  for (const key of DECISION_SECTIONS) {
-    const value = sections[key]
-    if (value === '') continue
-    if (out.length > 0) out.push('')
-    out.push('**' + DECISION_LABELS[key] + ':**')
-    if (key === 'alternatives' && value.includes('\n')) {
-      // A list of rejected options reads better as bullets.
-      for (const line of value.split('\n')) {
-        const item = line.trim().replace(/^[-*]\s*/, '')
-        if (item !== '') out.push('- ' + item)
-      }
-    } else {
-      out.push(value)
-    }
-  }
-  return out.join('\n')
-}
-
-/**
- * Read the sections back out of a decision body, so a stored decision can be inspected or
- * compared without re-deriving it from prose.
- * @returns {{context: string, rationale: string, alternatives: string[], consequences: string}}
- */
-export function parseDecisionBody(text) {
-  const result = { context: '', rationale: '', alternatives: [], consequences: '' }
-  const source = String(text ?? '')
-  let current = null
-  const buffers = { context: [], rationale: [], alternatives: [], consequences: [] }
-  for (const raw of source.split('\n')) {
-    const heading = /^\*\*(Context|Rationale|Alternatives considered|Consequences):\*\*\s*$/.exec(raw.trim())
-    if (heading) {
-      current = heading[1] === 'Alternatives considered' ? 'alternatives' : heading[1].toLowerCase()
-      continue
-    }
-    // A decision body ends at the next entry heading.
-    if (/^##\s+/.test(raw)) { current = null; continue }
-    if (current !== null) buffers[current].push(raw)
-  }
-  result.context = buffers.context.join('\n').trim()
-  result.rationale = buffers.rationale.join('\n').trim()
-  result.alternatives = buffers.alternatives
-    .map((line) => line.trim().replace(/^[-*]\s*/, ''))
-    .filter(Boolean)
-  result.consequences = buffers.consequences.join('\n').trim()
-  return result
-}
-
-/** True when a text looks like it records a decision rather than a plain fact. */
-export function looksLikeDecision(text) {
-  const source = String(text ?? '')
-  return /\*\*(Rationale|Alternatives considered|Consequences):\*\*/.test(source)
-}
+// Decisions: why this project is the way it is.
+//
+// A decision is not a fact (semantic) or a lesson (learning). It is a choice that was made,
+// with the reason it won and what it rules out - the thing that stops a future session from
+// re-litigating a settled question or silently reversing it.
+//
+// The writer owns the shape: the decision statement is the entry heading (so the layer index
+// reads as a list of decisions) and the reasoning lives in fixed body sections, which is what
+// makes decisions greppable and comparable. Everything here is pure.
+
+/** Body sections, in the order they are rendered. */
+export const DECISION_SECTIONS = ['context', 'rationale', 'alternatives', 'consequences']
+
+/** Human labels for the sections, used for the body headings. */
+export const DECISION_LABELS = {
+  context: 'Context',
+  rationale: 'Rationale',
+  alternatives: 'Alternatives considered',
+  consequences: 'Consequences',
+}
+
+/** Clip a decision heading to something an index line can carry. */
+export function decisionHeading(decision, max = 80) {
+  const text = String(decision ?? '').trim().replace(/\s+/g, ' ')
+  if (text === '') return 'Untitled decision'
+  return text.length > max ? text.slice(0, max - 3) + '...' : text
+}
+
+/**
+ * Normalize the free-form inputs into the section keys the renderer expects.
+ * Alternatives may arrive as a list or as prose; both are accepted.
+ */
+export function normalizeDecision(input = {}) {
+  const text = (value) => {
+    if (value === undefined || value === null) return ''
+    if (Array.isArray(value)) return value.map((item) => String(item).trim()).filter(Boolean).join('\n')
+    return String(value).trim()
+  }
+  return {
+    context: text(input.context),
+    rationale: text(input.rationale),
+    alternatives: text(input.alternatives),
+    consequences: text(input.consequences),
+  }
+}
+
+/**
+ * Render the body of a decision entry.
+ * @param input - { context, rationale, alternatives, consequences }.
+ * @returns markdown body; sections without content are omitted rather than left empty.
+ */
+export function renderDecisionBody(input = {}) {
+  const sections = normalizeDecision(input)
+  const out = []
+  for (const key of DECISION_SECTIONS) {
+    const value = sections[key]
+    if (value === '') continue
+    if (out.length > 0) out.push('')
+    out.push('**' + DECISION_LABELS[key] + ':**')
+    if (key === 'alternatives' && value.includes('\n')) {
+      // A list of rejected options reads better as bullets.
+      for (const line of value.split('\n')) {
+        const item = line.trim().replace(/^[-*]\s*/, '')
+        if (item !== '') out.push('- ' + item)
+      }
+    } else {
+      out.push(value)
+    }
+  }
+  return out.join('\n')
+}
+
+/**
+ * Read the sections back out of a decision body, so a stored decision can be inspected or
+ * compared without re-deriving it from prose.
+ * @returns {{context: string, rationale: string, alternatives: string[], consequences: string}}
+ */
+export function parseDecisionBody(text) {
+  const result = { context: '', rationale: '', alternatives: [], consequences: '' }
+  const source = String(text ?? '')
+  let current = null
+  const buffers = { context: [], rationale: [], alternatives: [], consequences: [] }
+  for (const raw of source.split('\n')) {
+    const heading = /^\*\*(Context|Rationale|Alternatives considered|Consequences):\*\*\s*$/.exec(raw.trim())
+    if (heading) {
+      current = heading[1] === 'Alternatives considered' ? 'alternatives' : heading[1].toLowerCase()
+      continue
+    }
+    // A decision body ends at the next entry heading.
+    if (/^##\s+/.test(raw)) { current = null; continue }
+    if (current !== null) buffers[current].push(raw)
+  }
+  result.context = buffers.context.join('\n').trim()
+  result.rationale = buffers.rationale.join('\n').trim()
+  result.alternatives = buffers.alternatives
+    .map((line) => line.trim().replace(/^[-*]\s*/, ''))
+    .filter(Boolean)
+  result.consequences = buffers.consequences.join('\n').trim()
+  return result
+}
+
+/** True when a text looks like it records a decision rather than a plain fact. */
+export function looksLikeDecision(text) {
+  const source = String(text ?? '')
+  return /\*\*(Rationale|Alternatives considered|Consequences):\*\*/.test(source)
+}

package/src/defaults.js

@@ -1,93 +1,93 @@
-// Pure config defaults + resolution. No DSH imports, so this is unit-testable standalone.
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-/** Default memory root: a per-user folder (cross-platform via os.homedir()). */
-export function defaultMemoryRoot(home = homedir()) {
-  return join(home, '.dsh-memory')
-}
-
-/** Tunable defaults; every field is also UI-editable (volatile) in the settings form. */
-export const DEFAULT_CONFIG = Object.freeze({
-  memoryRoot: '',                    // '' -> resolved to defaultMemoryRoot()
-  summaryModel: '',                  // 'provider/model' for memory writes; '' -> the session's own model
-  memoryReasoningEffort: 'low',      // reasoning budget for memory LLM calls ('' -> leave the model default)
-  gitRemote: '',                     // GitHub origin URL; empty = no remote sync yet
-  gitBranch: 'main',
-  gitToken: '',                      // optional PAT; empty = use OS git credential helper
-  gitName: '',                       // optional commit identity
-  gitEmail: '',
-  autoCaptureIntervalMs: 300_000,    // per-session capture throttle (5 min)
-  // Capture budgets. Capture summarizes only NEW events, and the relevance filter
-  // bounds what reaches the summarizer, so a long session cannot blow the prompt.
-  digestMaxUserTurns: 60,            // most recent user turns kept per pass
-  digestMaxAssistantGists: 40,       // most recent assistant gists kept per pass
-  digestMaxMessageChars: 600,        // per-message clip handed to the summarizer
-  digestMaxBytes: 40_000,            // hard ceiling on summarizer input per pass
-  summaryMaxBullets: 16,             // durable bullets kept from one summary
-  consolidateMaxPromptBytes: 65_536, // hard ceiling on the consolidation prompt
-  consolidateMaxDigestBytes: 20_000, // per-digest clip inside that prompt
-  commitDebounceMs: 10_000,          // local commit debounce after writes settle
-  autoSyncIntervalMs: 3_600_000,     // GitHub push+pull cadence (1 hour)
-  autoConsolidateIntervalMs: 1_800_000, // small consolidation pass cadence
-  autoConsolidateMinPending: 1,
-  autoConsolidateBatchSize: 3,
-  autoRefreshIntervalMs: 86_400_000, // freshness lifecycle cadence
-  autoHistoryIntervalMs: 3_600_000,  // commit-history ingest cadence (1 hour)
-  autoHistoryLimit: 40,              // commits recorded per ingest pass
-  // Below this much NEW material a summary would cost more than it captures. Trivial sessions
-  // already skip the model; this skips a content session whose delta is only a line or two.
-  summaryMinSignalChars: 400,
-  summaryMaxAttempts: 2,             // failed summaries retry, then settle as failed
-  // Above this, rebuilding a digest needs a human to agree to the cost. The orphaned sessions
-  // measured 8-88MB compressed, so recovering every one unasked would be hundreds of megabytes.
-  recoverApprovalThresholdBytes: 8 * 1024 * 1024,
-  digestKeepCount: 50,               // consolidated digests kept on disk before pruning
-  // Search reranking is OFF by default: it costs a model call per search, and the lexical
-  // ranking is already deterministic and useful. Turn it on, or pass rerank to memory_search.
-  rerankSearch: false,
-  injectionMaxChars: 3_600,
-  injectionRefreshMs: 900_000,
-})
-
-/**
- * Read a Config field, unwrapping a schemastery live reference.
- *
- * Fields marked `.volatile()` parse to `{ get() }` rather than plain values. A
- * truthy reference object would otherwise survive `if (!config.memoryRoot)` and
- * reach `path.join` as an Object — the turn-breaking TypeError.
- * @param value - a plain value, a live reference, or absent.
- * @returns the current plain value, or undefined when absent or null.
- */
-function readField(value) {
-  if (value === undefined || value === null) return undefined
-  if (typeof value === 'object' && typeof value.get === 'function') {
-    const resolved = value.get()
-    return resolved === null ? undefined : resolved
-  }
-  return value
-}
-
-/**
- * Parse a configured "provider/model" reference. A model id may itself contain
- * slashes (e.g. "meta-llama/llama-3"), so only the FIRST separator splits it.
- * @returns {{provider: string, model: string}|undefined}
- */
-export function parseModelRef(value) {
-  const text = String(value == null ? '' : value).trim()
-  if (text === '') return undefined
-  const at = text.indexOf('/')
-  if (at <= 0 || at === text.length - 1) return undefined
-  return { provider: text.slice(0, at), model: text.slice(at + 1) }
-}
-
-/** Merge overrides over DEFAULT_CONFIG, dropping undefined/null, and fill the platform root. */
-export function resolveConfig(overrides = {}) {
-  const config = { ...DEFAULT_CONFIG }
-  for (const [key, value] of Object.entries(overrides ?? {})) {
-    const plain = readField(value)
-    if (plain !== undefined && plain !== null) config[key] = plain
-  }
-  if (!config.memoryRoot) config.memoryRoot = defaultMemoryRoot()
-  return config
-}
+// Pure config defaults + resolution. No DSH imports, so this is unit-testable standalone.
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Default memory root: a per-user folder (cross-platform via os.homedir()). */
+export function defaultMemoryRoot(home = homedir()) {
+  return join(home, '.dsh-memory')
+}
+
+/** Tunable defaults; every field is also UI-editable (volatile) in the settings form. */
+export const DEFAULT_CONFIG = Object.freeze({
+  memoryRoot: '',                    // '' -> resolved to defaultMemoryRoot()
+  summaryModel: '',                  // 'provider/model' for memory writes; '' -> the session's own model
+  memoryReasoningEffort: 'low',      // reasoning budget for memory LLM calls ('' -> leave the model default)
+  gitRemote: '',                     // GitHub origin URL; empty = no remote sync yet
+  gitBranch: 'main',
+  gitToken: '',                      // optional PAT; empty = use OS git credential helper
+  gitName: '',                       // optional commit identity
+  gitEmail: '',
+  autoCaptureIntervalMs: 300_000,    // per-session capture throttle (5 min)
+  // Capture budgets. Capture summarizes only NEW events, and the relevance filter
+  // bounds what reaches the summarizer, so a long session cannot blow the prompt.
+  digestMaxUserTurns: 60,            // most recent user turns kept per pass
+  digestMaxAssistantGists: 40,       // most recent assistant gists kept per pass
+  digestMaxMessageChars: 600,        // per-message clip handed to the summarizer
+  digestMaxBytes: 40_000,            // hard ceiling on summarizer input per pass
+  summaryMaxBullets: 16,             // durable bullets kept from one summary
+  consolidateMaxPromptBytes: 65_536, // hard ceiling on the consolidation prompt
+  consolidateMaxDigestBytes: 20_000, // per-digest clip inside that prompt
+  commitDebounceMs: 10_000,          // local commit debounce after writes settle
+  autoSyncIntervalMs: 3_600_000,     // GitHub push+pull cadence (1 hour)
+  autoConsolidateIntervalMs: 1_800_000, // small consolidation pass cadence
+  autoConsolidateMinPending: 1,
+  autoConsolidateBatchSize: 3,
+  autoRefreshIntervalMs: 86_400_000, // freshness lifecycle cadence
+  autoHistoryIntervalMs: 3_600_000,  // commit-history ingest cadence (1 hour)
+  autoHistoryLimit: 40,              // commits recorded per ingest pass
+  // Below this much NEW material a summary would cost more than it captures. Trivial sessions
+  // already skip the model; this skips a content session whose delta is only a line or two.
+  summaryMinSignalChars: 400,
+  summaryMaxAttempts: 2,             // failed summaries retry, then settle as failed
+  // Above this, rebuilding a digest needs a human to agree to the cost. The orphaned sessions
+  // measured 8-88MB compressed, so recovering every one unasked would be hundreds of megabytes.
+  recoverApprovalThresholdBytes: 8 * 1024 * 1024,
+  digestKeepCount: 50,               // consolidated digests kept on disk before pruning
+  // Search reranking is OFF by default: it costs a model call per search, and the lexical
+  // ranking is already deterministic and useful. Turn it on, or pass rerank to memory_search.
+  rerankSearch: false,
+  injectionMaxChars: 3_600,
+  injectionRefreshMs: 900_000,
+})
+
+/**
+ * Read a Config field, unwrapping a schemastery live reference.
+ *
+ * Fields marked `.volatile()` parse to `{ get() }` rather than plain values. A
+ * truthy reference object would otherwise survive `if (!config.memoryRoot)` and
+ * reach `path.join` as an Object — the turn-breaking TypeError.
+ * @param value - a plain value, a live reference, or absent.
+ * @returns the current plain value, or undefined when absent or null.
+ */
+function readField(value) {
+  if (value === undefined || value === null) return undefined
+  if (typeof value === 'object' && typeof value.get === 'function') {
+    const resolved = value.get()
+    return resolved === null ? undefined : resolved
+  }
+  return value
+}
+
+/**
+ * Parse a configured "provider/model" reference. A model id may itself contain
+ * slashes (e.g. "meta-llama/llama-3"), so only the FIRST separator splits it.
+ * @returns {{provider: string, model: string}|undefined}
+ */
+export function parseModelRef(value) {
+  const text = String(value == null ? '' : value).trim()
+  if (text === '') return undefined
+  const at = text.indexOf('/')
+  if (at <= 0 || at === text.length - 1) return undefined
+  return { provider: text.slice(0, at), model: text.slice(at + 1) }
+}
+
+/** Merge overrides over DEFAULT_CONFIG, dropping undefined/null, and fill the platform root. */
+export function resolveConfig(overrides = {}) {
+  const config = { ...DEFAULT_CONFIG }
+  for (const [key, value] of Object.entries(overrides ?? {})) {
+    const plain = readField(value)
+    if (plain !== undefined && plain !== null) config[key] = plain
+  }
+  if (!config.memoryRoot) config.memoryRoot = defaultMemoryRoot()
+  return config
+}