dsh-claude-memory 0.1.0

package/src/index.js

@@ -0,0 +1,277 @@
+/**
+ * dsh-claude-memory — surface Claude Code's existing memory inside DeepSeek Harness.
+ *
+ * Why this exists: when a Claude Code quota runs out mid-task, the next agent
+ * should be able to pick the work up. Claude Code already wrote down what it
+ * learned as markdown under `~/.claude/projects/<key>/memory/`. This plugin
+ * reads that store and puts a bounded, redacted view of it in front of the DSH
+ * model, plus a tool to open any memory on demand.
+ *
+ * Design constraints, in order:
+ *  1. **Read-only.** Nothing under `~/.claude` is ever written or moved.
+ *  2. **Confined.** Every read resolves through `realpath` and must land inside
+ *     the Claude Code home, so a symlinked memory file cannot escape.
+ *  3. **Redacted.** Memory notes on this machine contain live credentials, and
+ *     DSH sends context to a different provider than Claude Code does. Every
+ *     contributed byte passes the redactor.
+ *  4. **Small by default.** The system prompt carries only the index; full
+ *     bodies arrive through the tool, one file at a time.
+ *  5. **Zero dependencies.** No `@deepseek-ai/*` import, so the plugin resolves
+ *     in a profile whose `node_modules` is empty, and the audit surface stays
+ *     one small tree.
+ *
+ * Two harness contracts shape the implementation:
+ *
+ *  - Prompt providers are **synchronous**: `dsh-system-prompt` resolves `text`
+ *    without awaiting it (`lib/index.js:330,337`), so this plugin keeps a
+ *    synchronously refreshed cache and never returns a promise from `text`.
+ *  - The directory that matters is the **session's** working directory, not the
+ *    server process's. `process.cwd()` is wherever `dsh` was launched, so the
+ *    plugin registers global sections as a fallback and shadows them per agent
+ *    from `agent/created` using `agent.session.header.cwd` — the same source the
+ *    first-party `dsh-agent-instructions` loader reads (`lib/index.js:1111`).
+ *
+ * @module dsh-claude-memory
+ */
+
+import { resolve } from 'node:path'
+import { formatIndexDate, findGitRoot, listMemoryProjects, resolveClaudeHome, selectProjects } from './paths.js'
+import { readInstructionsWithImports, readProjectIndex } from './store.js'
+import { renderGlobalBlock, renderMemoryBlock } from './render.js'
+import { redactText } from './redact.js'
+import { createClaudeMemoryTool } from './tool.js'
+
+export const name = 'claude-memory'
+
+/** Services this plugin needs; absent, the plugin must not activate. */
+export const inject = ['systemPrompt', 'tools']
+
+/** Prompt placement: just after the deployment persona, before tool prose. */
+const SECTION_ORDER = { global: 10, memory: 11 }
+
+/** Maximum distinct working directories cached at once. */
+const MAX_CACHES = 32
+
+const DEFAULTS = {
+  includeDescendants: true,
+  descendantLimit: 12,
+  maxIndexBytes: 24000,
+  maxGlobalBytes: 6000,
+  enableGlobalInstructions: true,
+  enableMemory: true,
+  enableTool: true,
+  redactMode: 'on',
+  refreshMs: 20000,
+}
+
+/** Coerce a config value to a boolean with a default. */
+function bool(value, fallback) {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+/** Coerce a config value to a finite positive number with a default. */
+function num(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+/**
+ * Normalize raw plugin configuration.
+ *
+ * @param {object} raw - configuration from the profile patch.
+ * @returns {object} fully defaulted configuration.
+ */
+function normalizeConfig(raw = {}) {
+  const redactMode = ['on', 'report', 'off'].includes(raw.redactMode) ? raw.redactMode : DEFAULTS.redactMode
+  return {
+    claudeHome: resolveClaudeHome(raw),
+    // Fallback only: a live agent's session cwd wins over this.
+    cwd: resolve(String(raw.cwd ?? process.cwd())),
+    includeDescendants: bool(raw.includeDescendants, DEFAULTS.includeDescendants),
+    descendantLimit: num(raw.descendantLimit, DEFAULTS.descendantLimit),
+    maxIndexBytes: num(raw.maxIndexBytes, DEFAULTS.maxIndexBytes),
+    maxGlobalBytes: num(raw.maxGlobalBytes, DEFAULTS.maxGlobalBytes),
+    enableGlobalInstructions: bool(raw.enableGlobalInstructions, DEFAULTS.enableGlobalInstructions),
+    enableMemory: bool(raw.enableMemory, DEFAULTS.enableMemory),
+    enableTool: bool(raw.enableTool, DEFAULTS.enableTool),
+    redactMode,
+    refreshMs: num(raw.refreshMs, DEFAULTS.refreshMs),
+  }
+}
+
+/**
+ * Read the working directory recorded on an agent's session.
+ *
+ * @param {object} agent - a live DSH agent.
+ * @returns {string|null} absolute cwd, or null when unavailable.
+ */
+function agentCwd(agent) {
+  const cwd = agent?.session?.header?.cwd
+  return typeof cwd === 'string' && cwd.length > 0 ? resolve(cwd) : null
+}
+
+/**
+ * Register the plugin.
+ *
+ * @param {object} ctx - Cordis context carrying `systemPrompt` and `tools`.
+ * @param {object} [rawConfig] - profile configuration.
+ */
+export function apply(ctx, rawConfig = {}) {
+  const config = normalizeConfig(rawConfig)
+
+  /** Per-working-directory render cache: cwd → block state. */
+  const caches = new Map()
+
+  /** Create (or fetch) the cache entry for one working directory. */
+  function cacheFor(cwd) {
+    let entry = caches.get(cwd)
+    if (entry !== undefined) return entry
+    if (caches.size >= MAX_CACHES) {
+      const oldest = caches.keys().next()
+      if (oldest.done !== true) caches.delete(oldest.value)
+    }
+    entry = { memoryBlock: '', globalBlock: '', projects: [], currentKey: null, lastRefreshAt: 0, error: null }
+    caches.set(cwd, entry)
+    return entry
+  }
+
+  /** Refresh one working directory's cache when it is older than `refreshMs`. */
+  function refreshIfStale(cwd) {
+    const entry = cacheFor(cwd)
+    if (Date.now() - entry.lastRefreshAt >= config.refreshMs) refresh(cwd)
+    return entry
+  }
+
+  /** Re-read the store for one working directory and rebuild both blocks. */
+  function refresh(cwd) {
+    const entry = cacheFor(cwd)
+    entry.lastRefreshAt = Date.now()
+    try {
+      const projects = listMemoryProjects(config.claudeHome)
+      // Claude Code files memory under the enclosing git repository root, so a
+      // subdirectory of a repo must resolve to the same project Claude Code used.
+      const gitRoot = findGitRoot(cwd)
+      const { current, related, match } = selectProjects({
+        projects,
+        cwd,
+        gitRoot,
+        includeDescendants: config.includeDescendants,
+        descendantLimit: config.descendantLimit,
+      })
+
+      // Annotate entry counts and dates so the catalog and the "other projects"
+      // list are useful without reading every index body.
+      const annotated = projects.map((p) => {
+        const read = readProjectIndex(config.claudeHome, p)
+        return { ...p, entries: read !== null ? read.entries : 0, date: formatIndexDate(p.mtimeMs) }
+      })
+      const annotatedByKey = new Map(annotated.map((p) => [p.key, p]))
+      const currentProject = current === null ? null : annotatedByKey.get(current.key) ?? current
+      const relatedProjects = related.map((p) => annotatedByKey.get(p.key) ?? p)
+
+      if (config.enableMemory) {
+        const index = currentProject === null ? null : readProjectIndex(config.claudeHome, currentProject)
+        const rawIndex = index === null ? null : { text: redactText(index.text, { mode: config.redactMode }) }
+        const redactedIndex = rawIndex === null ? null : { ...index, text: rawIndex.text.text }
+        const hits = rawIndex === null ? {} : rawIndex.text.hits
+        entry.memoryBlock = renderMemoryBlock({
+          project: currentProject,
+          index: redactedIndex,
+          related: relatedProjects,
+          all: annotated,
+          match,
+          cwd,
+          gitRoot,
+          maxBytes: config.maxIndexBytes,
+          hits,
+        })
+      } else {
+        entry.memoryBlock = ''
+      }
+
+      if (config.enableGlobalInstructions) {
+        const instructions = readInstructionsWithImports(config.claudeHome, resolve(config.claudeHome, 'CLAUDE.md'))
+        const redacted = instructions === null ? null : redactText(instructions.text, { mode: config.redactMode })
+        entry.globalBlock = renderGlobalBlock(
+          instructions === null || redacted === null ? null : { ...instructions, text: redacted.text },
+          config.maxGlobalBytes,
+          redacted === null ? {} : redacted.hits,
+        )
+      } else {
+        entry.globalBlock = ''
+      }
+
+      entry.projects = annotated
+      entry.currentKey = currentProject === null ? null : currentProject.key
+      entry.error = null
+    } catch (error) {
+      entry.error = error instanceof Error ? error.message : String(error)
+      entry.memoryBlock = ''
+      entry.globalBlock = ''
+    }
+  }
+
+  /** Register the two sections into one prompt registry (global or agent-scoped). */
+  function registerSections(systemPrompt, cwd) {
+    systemPrompt.section({
+      name: 'claude-memory:global',
+      order: SECTION_ORDER.global,
+      text: () => refreshIfStale(cwd).globalBlock,
+    })
+    systemPrompt.section({
+      name: 'claude-memory:memory',
+      order: SECTION_ORDER.memory,
+      text: () => refreshIfStale(cwd).memoryBlock,
+    })
+  }
+
+  // Seed the fallback before the first request so the first prompt is complete.
+  refresh(config.cwd)
+  registerSections(ctx.systemPrompt, config.cwd)
+
+  // A session's working directory is authoritative and differs from the server's
+  // cwd. Agent-scoped sections shadow the global ones with the same name.
+  let shadowed = 0
+  ctx.on('agent/created', ({ agent }) => {
+    const cwd = agentCwd(agent)
+    if (cwd === null || cwd === config.cwd) return
+    try {
+      registerSections(agent.ctx.systemPrompt, cwd)
+      shadowed += 1
+    } catch (error) {
+      ctx.logger?.warn?.(
+        `[claude-memory] could not register agent-scoped sections for ${cwd}: ${error?.message ?? error}`,
+      )
+    }
+  })
+
+  if (config.enableTool) {
+    const tool = createClaudeMemoryTool({
+      claudeHome: config.claudeHome,
+      redactMode: config.redactMode,
+      // Resolve against the calling agent's session so a subagent or a session
+      // started elsewhere sees its own project's memory.
+      cwd: (exec) => agentCwd(exec?.agent) ?? config.cwd,
+      projects: (cwd) => refreshIfStale(cwd).projects,
+      current: (cwd) => {
+        const entry = refreshIfStale(cwd)
+        if (entry.currentKey === null) return null
+        return entry.projects.find((p) => p.key === entry.currentKey) ?? null
+      },
+    })
+    try {
+      ctx.tools.register(tool)
+    } catch (error) {
+      ctx.logger?.warn?.(`[claude-memory] could not register ${tool.name}: ${error?.message ?? error}`)
+    }
+  }
+
+  ctx.logger?.debug?.(
+    `[claude-memory] home=${config.claudeHome} fallbackCwd=${config.cwd} ` +
+      `projects=${cacheFor(config.cwd).projects.length}`,
+  )
+
+  /** Test hook: inspect caches and how many agents shadowed the global sections. */
+  apply.__debug = { caches, shadowedCount: () => shadowed }
+}
+
+export default { name, inject, apply }

package/src/paths.js

@@ -0,0 +1,315 @@
+/**
+ * Claude Code project-path encoding and memory-directory discovery.
+ *
+ * Claude Code stores per-project state under `~/.claude/projects/<key>/`, where
+ * `<key>` is the absolute project path with `:` removed and every `/` or `\`
+ * replaced by `-`. The encoding is lossy (a real `-` in a path is
+ * indistinguishable from a separator), so this module never decodes a key to
+ * make security decisions — it only decodes for human-readable display.
+ *
+ * @module dsh-claude-memory/paths
+ */
+
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve, sep } from 'node:path'
+import { existsSync, realpathSync } from 'node:fs'
+import { readdirSync, statSync } from 'node:fs'
+
+/** Directory that holds one Claude Code memory set. */
+export const MEMORY_DIRNAME = 'memory'
+
+/** Index file inside a memory directory. */
+export const MEMORY_INDEX_FILENAME = 'MEMORY.md'
+
+/**
+ * Encode an absolute filesystem path into a Claude Code project key.
+ *
+ * `C:\Users\me` → `C-Users-me`, `/Users/me/proj` → `-Users-me-proj`.
+ *
+ * @param {string} absolutePath - absolute path to encode.
+ * @returns {string} the encoded project key.
+ */
+export function encodeProjectKey(absolutePath) {
+  return absolutePath.replace(/:/g, '').replace(/[/\\]/g, '-')
+}
+
+/**
+ * Resolve the Claude Code home directory from configuration.
+ *
+ * @param {{claudeHome?: string}} config - plugin configuration.
+ * @returns {string} absolute Claude Code home.
+ */
+export function resolveClaudeHome(config = {}) {
+  const raw = config.claudeHome ?? join(homedir(), '.claude')
+  return resolve(expandHome(raw))
+}
+
+/**
+ * Expand a leading `~` to the current user's home directory.
+ *
+ * @param {string} p - possibly home-relative path.
+ * @returns {string} expanded path.
+ */
+export function expandHome(p) {
+  if (p === '~') return homedir()
+  if (p.startsWith('~/') || p.startsWith('~\\')) return join(homedir(), p.slice(2))
+  return p
+}
+
+/**
+ * Assert that a resolved path stays inside a root directory.
+ *
+ * Compares real (symlink-resolved) paths so a symlink cannot smuggle a target
+ * out of the tree. Returns the real path when it is confined.
+ *
+ * @param {string} root - directory that must contain the target.
+ * @param {string} target - path to check.
+ * @returns {string|null} the real path, or null when it escapes or is missing.
+ */
+export function confinedRealPath(root, target) {
+  let realRoot
+  try {
+    realRoot = realpathSync(root)
+  } catch {
+    return null
+  }
+  let realTarget
+  try {
+    realTarget = realpathSync(target)
+  } catch {
+    return null
+  }
+  if (realTarget === realRoot) return realTarget
+  return realTarget.startsWith(realRoot.endsWith(sep) ? realRoot : realRoot + sep) ? realTarget : null
+}
+
+/**
+ * Count index entries in a `MEMORY.md` body.
+ *
+ * Claude Code's index is a list of `- [title](file.md) — summary` lines; other
+ * lines (headings, blanks) are ignored.
+ *
+ * @param {string} text - index file contents.
+ * @returns {number} number of pointer lines.
+ */
+export function countIndexEntries(text) {
+  let n = 0
+  for (const line of text.split('\n')) {
+    if (/^\s*[-*]\s+\[[^\]]+\]\([^)]+\)/.test(line)) n += 1
+  }
+  return n
+}
+
+/**
+ * List every project that has a memory directory under a Claude Code home.
+ *
+ * A project is included only when `<home>/projects/<key>/memory/MEMORY.md`
+ * exists and is a regular file inside the home tree. The scan is one level deep
+ * and never follows a memory directory out of the tree.
+ *
+ * @param {string} claudeHome - resolved Claude Code home.
+ * @returns {Array<{key: string, memoryDir: string, indexFile: string, mtimeMs: number, size: number, entries: number}>}
+ */
+export function listMemoryProjects(claudeHome) {
+  const projectsRoot = join(claudeHome, 'projects')
+  let keys
+  try {
+    keys = readdirSync(projectsRoot, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  const found = []
+  for (const dirent of keys) {
+    if (!dirent.isDirectory()) continue
+    const key = dirent.name
+    const memoryDir = join(projectsRoot, key, MEMORY_DIRNAME)
+    const indexFile = join(memoryDir, MEMORY_INDEX_FILENAME)
+
+    // The index must resolve inside the Claude home; this rejects a symlinked
+    // memory directory pointing somewhere else on disk.
+    const real = confinedRealPath(claudeHome, indexFile)
+    if (real === null) continue
+
+    let stat
+    try {
+      stat = statSync(real)
+    } catch {
+      continue
+    }
+    if (!stat.isFile()) continue
+
+    found.push({
+      key,
+      memoryDir,
+      indexFile,
+      mtimeMs: stat.mtimeMs,
+      size: stat.size,
+      entries: 0, // filled lazily by the store when the index is read
+    })
+  }
+
+  found.sort((a, b) => a.key.localeCompare(b.key))
+  return found
+}
+
+/**
+ * Find the enclosing git repository root for a directory.
+ *
+ * Claude Code files memory under the **git repository root**, not the raw
+ * working directory: a session launched in a subdirectory that has no `.git` of
+ * its own (for example a docs hub inside a larger repo) writes to the enclosing
+ * repo's key, not the subdirectory's. Both a `.git` directory and a `.git` file
+ * (worktrees and submodules) mark a root.
+ *
+ * @param {string} startDir - directory to walk up from.
+ * @returns {string|null} the repository root, or null when there is none.
+ */
+export function findGitRoot(startDir) {
+  let current = resolve(expandHome(startDir))
+  for (;;) {
+    if (existsSync(join(current, '.git'))) return current
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+}
+
+/**
+ * Select the project whose memory is most relevant to a working directory.
+ *
+ * Resolution order mirrors how Claude Code itself files memory:
+ *  1. **exact** — the encoded key for `cwd` has memory;
+ *  2. **git-root** — the encoded key for the enclosing git repository root has
+ *     memory (the common case for a subdirectory of a repo);
+ *  3. **freshest** — otherwise, the most recently updated memory set among the
+ *     containing ancestors and the child projects.
+ *
+ * Rule 3 is deliberately recency-based rather than "nearest ancestor": a hub
+ * directory's own memory is often stale while the work that just ran is in one
+ * of its children. The chosen rule is reported back so the model knows whether
+ * the memory is certain or a best guess.
+ *
+ * @param {object} options - selection inputs.
+ * @param {Array<object>} options.projects - result of {@link listMemoryProjects}.
+ * @param {string} options.cwd - session working directory.
+ * @param {string|null} [options.gitRoot] - enclosing git root, from {@link findGitRoot}.
+ * @param {boolean} [options.includeDescendants] - also return sibling candidates.
+ * @param {number} [options.descendantLimit] - maximum other candidates to return.
+ * @returns {{current: object|null, related: Array<object>, match: 'exact'|'git-root'|'freshest'|'none'}} selection.
+ */
+export function selectProjects({
+  projects,
+  cwd,
+  gitRoot = null,
+  includeDescendants = true,
+  descendantLimit = 12,
+}) {
+  const cwdKey = encodeProjectKey(resolve(expandHome(cwd)))
+  const byKey = new Map(projects.map((p) => [p.key, p]))
+
+  const exact = byKey.get(cwdKey) ?? null
+  const descendants = projects.filter((p) => p.key.startsWith(cwdKey + '-'))
+  const ancestors = projects.filter((p) => cwdKey.startsWith(p.key + '-'))
+
+  const byRecency = (a, b) => b.mtimeMs - a.mtimeMs || a.key.localeCompare(b.key)
+
+  const relatedFor = () =>
+    includeDescendants ? descendants.sort(byRecency).slice(0, Math.max(0, descendantLimit)) : []
+
+  if (exact !== null) return { current: exact, related: relatedFor(), match: 'exact' }
+
+  if (gitRoot !== null) {
+    const gitKey = encodeProjectKey(resolve(expandHome(gitRoot)))
+    const fromRoot = byKey.get(gitKey) ?? null
+    if (fromRoot !== null) {
+      return {
+        current: fromRoot,
+        related: includeDescendants
+          ? [...ancestors, ...descendants]
+              .filter((p) => p.key !== fromRoot.key)
+              .sort(byRecency)
+              .slice(0, Math.max(0, descendantLimit))
+          : [],
+        match: 'git-root',
+      }
+    }
+  }
+
+  const candidates = [...ancestors, ...descendants].sort(byRecency)
+  if (candidates.length === 0) return { current: null, related: [], match: 'none' }
+
+  const [current, ...rest] = candidates
+  return {
+    current,
+    related: includeDescendants ? rest.slice(0, Math.max(0, descendantLimit)) : [],
+    match: 'freshest',
+  }
+}
+
+/**
+ * Format an index mtime as a short local date for prompt display.
+ *
+ * @param {number} mtimeMs - modification time in milliseconds.
+ * @returns {string} `YYYY-MM-DD`, or `?` when unknown.
+ */
+export function formatIndexDate(mtimeMs) {
+  if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs) || mtimeMs <= 0) return '?'
+  const d = new Date(mtimeMs)
+  const pad = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
+}
+
+/**
+ * Recover the original directory path from a project key by walking the filesystem.
+ *
+ * The encoding is lossy — `-` is both the separator and a legal character in a
+ * directory name — so a naive decode turns `...-agent-harness-quality-pilot`
+ * into `.../agent/harness/quality/pilot`. Walking the real tree and preferring
+ * the longest matching join recovers the true path when it still exists.
+ *
+ * @param {string} key - encoded project key.
+ * @returns {string|null} the real directory, or null when it cannot be recovered.
+ */
+export function resolveKeyToPath(key) {
+  if (!key.startsWith('-')) return null // Windows drive keys have no leading dash
+  const segments = key.slice(1).split('-')
+  let current = sep
+  let index = 0
+
+  while (index < segments.length) {
+    let matched = false
+    for (let take = segments.length - index; take >= 1; take -= 1) {
+      const candidate = join(current, segments.slice(index, index + take).join('-'))
+      try {
+        if (statSync(candidate).isDirectory()) {
+          current = candidate
+          index += take
+          matched = true
+          break
+        }
+      } catch {
+        // not a directory: try a shorter join
+      }
+    }
+    if (!matched) return null
+  }
+
+  return current
+}
+
+/**
+ * Short, stable label for a project key.
+ *
+ * Prefers the real directory name recovered from disk; falls back to the last
+ * two raw key segments, which is the best a lossy encoding allows.
+ *
+ * @param {string} key - encoded project key.
+ * @returns {string} display label.
+ */
+export function projectLabel(key) {
+  const real = resolveKeyToPath(key)
+  if (real !== null) return basename(real) || key
+  const segments = key.replace(/^-/, '').split('-')
+  return segments.slice(-2).join('-')
+}