@y0shua1ee/dsh-auto-memory 0.0.0-stage → 0.3.0

package/lib/inject.js

@@ -0,0 +1,114 @@
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { renderMemoryContext } from "./render.js";
+
+/** Message source kind used to recognize injected memory snapshots. */
+export const AUTO_MEMORY_SOURCE_KIND = "auto-memory";
+
+function isAutoMemoryMessage(message) {
+  return message?.source?.kind === AUTO_MEMORY_SOURCE_KIND;
+}
+
+/**
+ * Whether the index holds anything beyond its heading and HTML comments.
+ * A header-only index (for example after deleting the last memory) carries no
+ * context and is not worth injecting.
+ *
+ * @param {string} content - raw MEMORY.md text.
+ * @returns {boolean} true when at least one non-heading line exists.
+ */
+export function hasIndexEntries(content) {
+  return content
+    .replace(/<!--[\s\S]*?-->/gu, "")
+    .split("\n")
+    .some((line) => {
+      const trimmed = line.trim();
+      return trimmed.length > 0 && !trimmed.startsWith("#");
+    });
+}
+
+export function isSubagent(agent) {
+  const header = agent?.session?.header;
+  if (header === undefined || header === null) return false;
+  return header.origin === "subagent" || (header.delegationDepth ?? 0) > 0;
+}
+
+function hasDigest(agent, decision, digest) {
+  const matches = (message) => isAutoMemoryMessage(message) && message.source.digest === digest;
+  if (decision.messages.some(matches)) return true;
+  for (const seq of agent.session.surface.nodes) {
+    const event = agent.session.eventAt(seq);
+    if (event?.type === "user/message" && matches(event.data)) return true;
+  }
+  return agent.inbox.nextStep.some(matches);
+}
+
+export function enterWithMessage(agent, messages, decision, message, isManaged) {
+  const pending = agent.inbox.nextStep.filter(isManaged);
+  if (decision.messages.length === 0) {
+    if (pending.length > 0) {
+      agent.inbox.replace(pending[0].id, message);
+      for (const extra of pending.slice(1)) agent.inbox.remove(extra.id);
+    } else {
+      agent.inbox.prepend("next-step", message);
+    }
+    return decision;
+  }
+  for (const extra of pending) agent.inbox.remove(extra.id);
+  const lastClaimedIndex = decision.messages.findLastIndex((candidate) => messages.includes(candidate));
+  return {
+    ...decision,
+    messages: decision.messages.toSpliced(lastClaimedIndex + 1, 0, message)
+  };
+}
+
+/**
+ * Create the `agent/pre-step` listener that injects the project index.
+ *
+ * The index is re-read on every step. The rendered snapshot's digest is
+ * recorded in the message source, so the same snapshot is never injected
+ * twice; after compaction the old message leaves the surface and the next step
+ * injects the current index again.
+ *
+ * @param {object} input - listener dependencies.
+ * @param {(agent: object, signal: AbortSignal) => Promise<object>} input.projectFor - resolve the session's project.
+ * @param {object} input.config - normalized plugin configuration.
+ * @param {object} [input.logger] - host logger.
+ * @returns {(payload: object, next: Function) => Promise<object>} pre-step listener.
+ */
+export function createPreStepHandler({ projectFor, config, logger }) {
+  return async ({ agent, messages, step, signal }, next) => {
+    const decision = await next();
+    if (decision.kind === "reject") return decision;
+    if (!config.inject) return decision;
+    if (!config.injectInSubagents && isSubagent(agent)) return decision;
+    try {
+      const project = await projectFor(agent, signal);
+      const index = await project.store.index();
+      if (!index.exists || !hasIndexEntries(index.content)) return decision;
+      const rendered = renderMemoryContext({
+        content: index.content,
+        memoryDir: project.dirLabel,
+        projectKey: project.key,
+        maxBytes: config.maxIndexBytes,
+        maxLines: config.maxIndexLines,
+        replacePrevious: true
+      });
+      if (hasDigest(agent, decision, rendered.digest)) return decision;
+      const message = createUserMessage({
+        content: [{ type: "text", text: rendered.text }],
+        source: {
+          kind: AUTO_MEMORY_SOURCE_KIND,
+          form: "memory",
+          projectKey: project.key,
+          digest: rendered.digest,
+          baseline: true
+        }
+      });
+      return enterWithMessage(agent, messages, decision, message, isAutoMemoryMessage);
+    } catch (error) {
+      if (signal?.aborted) return decision;
+      logger?.warn?.("auto-memory: could not load project memory for this step: %o", error);
+      return decision;
+    }
+  };
+}

package/lib/memory-frontmatter.js

@@ -0,0 +1,95 @@
+/**
+ * Parse the frontmatter of one memory file, in the shape Claude Code uses:
+ *
+ * ```markdown
+ * ---
+ * name: prefer-pnpm
+ * description: The user wants pnpm, never npm, in this repo
+ * metadata:
+ *   type: feedback
+ * ---
+ * ```
+ *
+ * Only flat `key: value` scalars and the one-level `metadata:` block are read;
+ * a top-level `type` is accepted as a fallback. Anything unparsable yields no
+ * fields, so a malformed file still loads as plain text.
+ */
+
+const DELIMITER = "---";
+
+/** Memory types, mirroring Claude Code's memory taxonomy. */
+export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
+
+/** Memory names share DSH's skill-name shape so `[[name]]` maps to `name.md`. */
+export const MEMORY_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+function scalar(value) {
+  const trimmed = value.trim();
+  if (
+    trimmed.length >= 2 &&
+    ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'")))
+  ) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+/**
+ * Read a memory file's frontmatter fields and body.
+ *
+ * @param {string} content - complete memory file text.
+ * @returns {{frontmatter: boolean, name?: string, description?: string, type?: string, body: string}}
+ */
+export function parseMemory(content) {
+  const source = content.startsWith("\uFEFF") ? content.slice(1) : content;
+  const lines = source.split(/\r?\n/u);
+  if (lines[0]?.trim() !== DELIMITER) return { frontmatter: false, body: source };
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === DELIMITER);
+  if (end === -1) return { frontmatter: false, body: source };
+
+  const top = {};
+  const metadata = {};
+  let inMetadata = false;
+  for (const line of lines.slice(1, end)) {
+    if (line.trim().length === 0 || line.trim().startsWith("#")) continue;
+    const match = /^(\s*)([A-Za-z_][\w-]*)\s*:(.*)$/u.exec(line);
+    if (match === null) continue;
+    const [, indent, key, rest] = match;
+    if (indent.length === 0) {
+      inMetadata = key === "metadata" && rest.trim().length === 0;
+      if (!inMetadata) top[key] = scalar(rest);
+    } else if (inMetadata) {
+      metadata[key] = scalar(rest);
+    }
+  }
+
+  const result = { frontmatter: true, body: lines.slice(end + 1).join("\n").replace(/^\n+/u, "") };
+  for (const [field, value] of [
+    ["name", top.name],
+    ["description", top.description],
+    ["type", metadata.type ?? top.type]
+  ]) {
+    if (value !== undefined && value.length > 0) result[field] = value;
+  }
+  return result;
+}
+
+/**
+ * List what a topic file's frontmatter is missing, for a non-blocking hint.
+ *
+ * @param {ReturnType<typeof parseMemory>} parsed - parsed memory file.
+ * @returns {string[]} human-readable problems; empty when the file is well-formed.
+ */
+export function memoryFrontmatterProblems(parsed) {
+  if (!parsed.frontmatter) return ["no frontmatter (name, description, metadata.type)"];
+  const problems = [];
+  if (parsed.name === undefined) problems.push("missing name");
+  else if (!MEMORY_NAME.test(parsed.name)) problems.push(`name ${JSON.stringify(parsed.name)} is not kebab-case`);
+  if (parsed.description === undefined) problems.push("missing description");
+  if (parsed.type === undefined) problems.push("missing metadata.type");
+  else if (!MEMORY_TYPES.includes(parsed.type)) {
+    problems.push(`metadata.type ${JSON.stringify(parsed.type)} is not one of ${MEMORY_TYPES.join(", ")}`);
+  }
+  return problems;
+}

package/lib/paths.js

@@ -0,0 +1,97 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+
+/**
+ * Encode one project directory the same way DSH names its session project
+ * directories: separator and drive runs collapse to a single `-`, unsafe code
+ * units use `~XXXX`, and the result is wrapped in `--…--`.
+ *
+ * Keeping this identical to `@deepseek-ai/dsh-session-persistence-jsonl` means
+ * memory folders sit next to the session folders they belong to when the user
+ * browses `~/.dsh`.
+ *
+ * @param {string} cwd - absolute project directory.
+ * @returns {string} one filesystem-safe directory component.
+ */
+export function projectKey(cwd) {
+  if (typeof cwd !== "string" || cwd.length === 0) {
+    throw new TypeError("auto-memory: cannot encode an empty project path");
+  }
+  let readable = "";
+  let separatorRun = false;
+  for (let index = 0; index < cwd.length; index += 1) {
+    const code = cwd.charCodeAt(index);
+    const character = String.fromCharCode(code);
+    if (character === "/" || character === "\\" || character === ":") {
+      if (!separatorRun) readable += "-";
+      separatorRun = true;
+    } else if (character !== "~" && /^[A-Za-z0-9._-]$/.test(character)) {
+      readable += character;
+      separatorRun = false;
+    } else {
+      readable += `~${code.toString(16).toUpperCase().padStart(4, "0")}`;
+      separatorRun = false;
+    }
+  }
+  return `--${(readable.replace(/^-+/, "") || "root").slice(0, 251)}--`;
+}
+
+/**
+ * Walk up from `cwd` until a directory containing one of `markers` is found.
+ *
+ * This is the project boundary used to share memory between subdirectories of
+ * one checkout. When no marker exists the working directory itself is the
+ * project, which keeps unrelated folders separate.
+ *
+ * @param {string} cwd - absolute working directory.
+ * @param {string[]} markers - file or directory names such as `.git`.
+ * @param {AbortSignal} [signal] - cancellation for the walk.
+ * @returns {Promise<string>} absolute project root.
+ */
+export async function findProjectRoot(cwd, markers, signal) {
+  const start = resolve(cwd);
+  if (!Array.isArray(markers) || markers.length === 0) return start;
+  let current = start;
+  for (;;) {
+    signal?.throwIfAborted();
+    for (const marker of markers) {
+      try {
+        const info = await stat(join(current, marker));
+        signal?.throwIfAborted();
+        if (info !== undefined) return current;
+      } catch {
+        // A permission error on one marker must not hide another marker or a
+        // parent project; keep walking.
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return start;
+    current = parent;
+  }
+}
+
+/**
+ * Abbreviate a path below the OS home for model-facing prompts.
+ *
+ * @param {string} path - absolute path.
+ * @returns {string} `~`, `~/…`, or the unchanged path.
+ */
+export function displayPath(path) {
+  const home = homedir().replace(/\/+$/, "");
+  if (home.length === 0) return path;
+  if (path === home) return "~";
+  if (path.startsWith(`${home}${sep}`)) return `~${path.slice(home.length)}`;
+  return path;
+}
+
+/**
+ * Compute the memory directory for one project.
+ *
+ * @param {string} memoryRoot - absolute root holding every project folder.
+ * @param {string} key - encoded project key.
+ * @returns {string} absolute project memory directory.
+ */
+export function memoryDirectory(memoryRoot, key) {
+  return join(memoryRoot, key);
+}

package/lib/render.js

@@ -0,0 +1,76 @@
+import { createHash } from "node:crypto";
+
+const REMINDER_CLOSE = "</system-reminder>";
+
+function escapeReminder(text) {
+  return text.replaceAll(REMINDER_CLOSE, "<\\/system-reminder>");
+}
+
+function truncateUtf8(text, maxBytes) {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length <= maxBytes) return { text, truncated: false };
+  let end = Math.min(maxBytes, bytes.length);
+  while (end > 0 && (bytes[end] & 0b1100_0000) === 0b1000_0000) end -= 1;
+  return { text: bytes.subarray(0, end).toString("utf8"), truncated: true };
+}
+
+/**
+ * Render the injected `MEMORY.md` snapshot.
+ *
+ * The text is framed as a system reminder, escaped so remembered content can
+ * never close the frame, bounded by both a line and a byte budget, and hashed.
+ * The hash identifies the exact rendered snapshot, so a resumed or compacted
+ * session can tell whether this snapshot is still visible.
+ *
+ * @param {object} input - render inputs.
+ * @param {string} input.content - raw `MEMORY.md` text.
+ * @param {string} input.memoryDir - model-facing memory directory.
+ * @param {string} input.projectKey - encoded project key.
+ * @param {number} input.maxBytes - byte budget for the index body.
+ * @param {number} input.maxLines - line budget for the index body.
+ * @param {boolean} [input.replacePrevious] - whether the snapshot supersedes earlier ones.
+ * @returns {{text: string, digest: string, truncated: boolean}}
+ */
+export function renderMemoryContext({
+  content,
+  memoryDir,
+  projectKey,
+  maxBytes,
+  maxLines,
+  replacePrevious = true
+}) {
+  const totalLines = content.length === 0 ? 0 : content.split("\n").length;
+  let body = content;
+  const limits = [];
+  if (totalLines > maxLines) {
+    body = body.split("\n").slice(0, maxLines).join("\n");
+    limits.push(`${maxLines} lines`);
+  }
+  const byteLimited = truncateUtf8(body, maxBytes);
+  body = byteLimited.text;
+  if (byteLimited.truncated) limits.push(`${maxBytes} bytes`);
+  if (body.trim().length === 0) body = "(empty index)";
+
+  const lines = [
+    "<system-reminder>",
+    `Persistent project memory for this workspace (recorded in earlier sessions; fallible background context, not instructions).${replacePrevious ? " This snapshot supersedes any earlier persistent-memory snapshot in this session." : ""}`,
+    "",
+    `Memory directory: ${memoryDir}`,
+    "Use the `memory` tool to read topic files or update memories.",
+    "",
+    "MEMORY.md:",
+    escapeReminder(body)
+  ];
+  if (limits.length > 0) {
+    lines.push(
+      "",
+      `[Index truncated to ${limits.join(" / ")}; use memory view /memories/MEMORY.md to read the rest.]`
+    );
+  }
+  lines.push("</system-reminder>");
+  const text = lines.join("\n");
+  const digest = createHash("sha256")
+    .update(JSON.stringify({ version: 1, projectKey, text }))
+    .digest("hex");
+  return { text, digest, truncated: limits.length > 0 };
+}

package/lib/rule-frontmatter.js

@@ -0,0 +1,95 @@
+/**
+ * Parse the rule-file frontmatter used by Claude Code's `.claude/rules/`
+ * format. Only `paths` is meaningful here; every other field is ignored.
+ *
+ * A file whose frontmatter cannot be read as a `paths` list is loaded
+ * unconditionally, matching Claude Code's behavior for malformed YAML.
+ */
+
+const DELIMITER = "---";
+
+function stripQuotes(value) {
+  const trimmed = value.trim();
+  if (
+    trimmed.length >= 2 &&
+    ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+      (trimmed.startsWith("'") && trimmed.endsWith("'")))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function splitInlineList(value) {
+  let body = value.trim();
+  if (body.startsWith("[") && body.endsWith("]")) body = body.slice(1, -1);
+  const entries = [];
+  let current = "";
+  let quote = null;
+  for (const character of body) {
+    if (quote !== null) {
+      current += character;
+      if (character === quote) quote = null;
+      continue;
+    }
+    if (character === '"' || character === "'") {
+      quote = character;
+      current += character;
+      continue;
+    }
+    if (character === ",") {
+      entries.push(current);
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  entries.push(current);
+  return entries.map(stripQuotes).filter((entry) => entry.length > 0);
+}
+
+/**
+ * Read the rule body and its optional path patterns.
+ *
+ * @param {string} content - complete rule file text.
+ * @returns {{paths: string[] | undefined, body: string}} parsed rule.
+ */
+export function parseRule(content) {
+  const source = content.startsWith("\uFEFF") ? content.slice(1) : content;
+  const lines = source.split(/\r?\n/);
+  if (lines[0]?.trim() !== DELIMITER) return { paths: undefined, body: source };
+
+  let end = -1;
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index].trim() === DELIMITER) {
+      end = index;
+      break;
+    }
+  }
+  if (end === -1) return { paths: undefined, body: source };
+
+  const frontmatter = lines.slice(1, end);
+  const body = lines.slice(end + 1).join("\n").replace(/^\n+/u, "");
+  return { paths: parsePaths(frontmatter), body };
+}
+
+function parsePaths(frontmatter) {
+  const index = frontmatter.findIndex((line) => /^paths\s*:/u.test(line));
+  if (index === -1) return undefined;
+  const value = frontmatter[index].replace(/^paths\s*:/u, "").trim();
+  if (value.length > 0) {
+    const inline = splitInlineList(value);
+    return inline.length > 0 ? inline : undefined;
+  }
+
+  const paths = [];
+  for (let cursor = index + 1; cursor < frontmatter.length; cursor += 1) {
+    const line = frontmatter[cursor];
+    if (line.trim().length === 0 || line.trim().startsWith("#")) continue;
+    const match = /^\s*-\s+(.*)$/u.exec(line);
+    if (match === null) break;
+    const path = stripQuotes(match[1]);
+    if (path.length > 0) paths.push(path);
+  }
+  return paths.length > 0 ? paths : undefined;
+}

package/lib/rule-glob.js

@@ -0,0 +1,163 @@
+/**
+ * Small glob matcher for rule `paths` patterns.
+ *
+ * Supports `*`, `**`, `?`, brace expansion (`{a,b}`), and character classes
+ * (`[abc]`). Patterns are relative to the rule's base directory and use `/`
+ * separators on every platform.
+ */
+
+const EXPANSION_BUDGET = 1000;
+const COMPILED_CACHE = new Map();
+const COMPILED_CACHE_LIMIT = 2000;
+
+function findBrace(pattern, from) {
+  let depth = 0;
+  let start = -1;
+  for (let index = from; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === "\\") {
+      index += 1;
+      continue;
+    }
+    if (character === "{") {
+      if (depth === 0) start = index;
+      depth += 1;
+    } else if (character === "}") {
+      if (depth > 0) {
+        depth -= 1;
+        if (depth === 0 && start !== -1) return { start, end: index };
+      }
+    }
+  }
+  return undefined;
+}
+
+function splitAlternatives(inner) {
+  const parts = [];
+  let current = "";
+  let depth = 0;
+  for (const character of inner) {
+    if (character === "{") depth += 1;
+    if (character === "}") depth -= 1;
+    if (character === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += character;
+    }
+  }
+  parts.push(current);
+  return parts;
+}
+
+function expandInto(pattern, from, output) {
+  if (output.length >= EXPANSION_BUDGET) return;
+  const brace = findBrace(pattern, from);
+  if (brace === undefined) {
+    output.push(pattern);
+    return;
+  }
+  const alternatives = splitAlternatives(pattern.slice(brace.start + 1, brace.end));
+  if (alternatives.length < 2) {
+    expandInto(pattern, brace.end + 1, output);
+    return;
+  }
+  const prefix = pattern.slice(0, brace.start);
+  const suffix = pattern.slice(brace.end + 1);
+  for (const alternative of alternatives) {
+    if (output.length >= EXPANSION_BUDGET) break;
+    expandInto(`${prefix}${alternative}${suffix}`, brace.start, output);
+  }
+}
+
+/**
+ * Expand brace alternatives with a hard budget. A pattern over budget is
+ * returned unexpanded, so its literal braces match nothing rather than
+ * consuming unbounded memory.
+ *
+ * @param {string} pattern - glob pattern.
+ * @returns {string[]} expanded patterns.
+ */
+export function expandBraces(pattern) {
+  const output = [];
+  expandInto(pattern, 0, output);
+  return output.length > 0 ? output : [pattern];
+}
+
+function normalizePattern(pattern) {
+  return pattern.replaceAll("\\", "/").replace(/^\.\//u, "").replace(/^\/+/u, "");
+}
+
+/**
+ * Compile one glob pattern into an anchored regular expression.
+ *
+ * @param {string} pattern - glob pattern.
+ * @returns {RegExp} matcher for `/`-separated relative paths.
+ */
+export function compileGlob(pattern) {
+  const cached = COMPILED_CACHE.get(pattern);
+  if (cached !== undefined) return cached;
+  const source = normalizePattern(pattern);
+  let expression = "^";
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    if (character === "*") {
+      let end = index;
+      while (source[end + 1] === "*") end += 1;
+      if (end > index) {
+        if (source[end + 1] === "/") {
+          expression += "(?:.*/)?";
+          index = end + 1;
+        } else {
+          expression += ".*";
+          index = end;
+        }
+      } else {
+        expression += "[^/]*";
+      }
+      continue;
+    }
+    if (character === "?") {
+      expression += "[^/]";
+      continue;
+    }
+    if (character === "[") {
+      const close = source.indexOf("]", index + 1);
+      if (close === -1) {
+        expression += "\\[";
+        continue;
+      }
+      let characterClass = source.slice(index + 1, close);
+      if (characterClass.startsWith("!")) characterClass = `^${characterClass.slice(1)}`;
+      expression += `[${characterClass}]`;
+      index = close;
+      continue;
+    }
+    if (character === "{" || character === "}") {
+      expression += `\\${character}`;
+      continue;
+    }
+    if ("\\.+^$()|".includes(character)) {
+      expression += `\\${character}`;
+      continue;
+    }
+    expression += character;
+  }
+  expression += "$";
+  const compiled = new RegExp(expression);
+  if (COMPILED_CACHE.size >= COMPILED_CACHE_LIMIT) COMPILED_CACHE.clear();
+  COMPILED_CACHE.set(pattern, compiled);
+  return compiled;
+}
+
+/**
+ * Test one `/`-separated relative path against a glob.
+ *
+ * @param {string} path - relative path.
+ * @param {string} pattern - glob pattern.
+ * @returns {boolean} whether the path matches.
+ */
+export function matchGlob(path, pattern) {
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//u, "");
+  return expandBraces(pattern).some((expanded) => compileGlob(expanded).test(normalized));
+}