@y0shua1ee/dsh-auto-memory 0.3.3 → 0.4.0

package/lib/inject.d.ts

@@ -0,0 +1,36 @@
+import type { ResolvedConfig } from "./config.js";
+import type { MemoryStore } from "./store.js";
+import type { Agent, EnterDecision, Logger, Message, PreStepDecision, PreStepHandler } from "./types.js";
+/** Message source kind used to recognize injected memory snapshots. */
+export declare const AUTO_MEMORY_SOURCE_KIND = "auto-memory";
+/** The project fields the injection path needs. */
+export interface InjectionProject {
+    key: string;
+    dirLabel: string;
+    store: MemoryStore;
+    cwd: string;
+    projectRoot: string;
+    ruleRoot: string;
+}
+export type ProjectFor = (agent: Agent, signal?: AbortSignal) => Promise<InjectionProject>;
+/**
+ * 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.
+ */
+export declare function hasIndexEntries(content: string): boolean;
+export declare function isSubagent(agent: Agent): boolean;
+export declare function enterWithMessage(agent: Agent, messages: Message[], decision: EnterDecision, message: Message, isManaged: (candidate: Message) => boolean): PreStepDecision;
+/**
+ * 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.
+ */
+export declare function createPreStepHandler({ projectFor, config, logger }: {
+    projectFor: ProjectFor;
+    config: ResolvedConfig;
+    logger?: Logger;
+}): PreStepHandler;

package/lib/inject.js

@@ -1,66 +1,62 @@
 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;
+    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("#");
+    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;
+    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);
+    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);
+    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;
     }
-    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)
-  };
+    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.
  *
@@ -68,47 +64,49 @@ export function enterWithMessage(agent, messages, decision, message, isManaged)
  * 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 async ({ agent, messages, 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,
+                sourceTruncated: index.truncated
+            });
+            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);
         }
-      });
-      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;
-    }
-  };
+        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.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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` (and `modified`) is accepted as a fallback. Anything
+ * unparsable yields no fields, so a malformed file still loads as plain text.
+ */
+/** Memory types, mirroring Claude Code's memory taxonomy. */
+export declare const MEMORY_TYPES: readonly ["user", "feedback", "project", "reference"];
+export type MemoryType = (typeof MEMORY_TYPES)[number];
+/** Memory names share DSH's skill-name shape so `[[name]]` maps to `name.md`. */
+export declare const MEMORY_NAME: RegExp;
+/** One parsed memory file. */
+export interface ParsedMemory {
+    frontmatter: boolean;
+    name?: string;
+    description?: string;
+    type?: string;
+    modified?: string;
+    body: string;
+}
+/** One stable frontmatter problem code plus a readable message. */
+export interface MemoryIssue {
+    code: string;
+    message: string;
+}
+/**
+ * Read a memory file's frontmatter fields and body.
+ */
+export declare function parseMemory(content: string): ParsedMemory;
+/**
+ * Describe each frontmatter problem as a stable code plus a readable message.
+ *
+ * Codes stay stable when only the offending value changes, so callers can tell
+ * "the same problem still exists" from "this edit introduced a new problem".
+ */
+export declare function memoryFrontmatterIssues(parsed: ParsedMemory, fileStem?: string, filePath?: string): MemoryIssue[];
+/**
+ * List what a topic file's frontmatter is missing, for a non-blocking hint.
+ */
+export declare function memoryFrontmatterProblems(parsed: ParsedMemory, fileStem?: string, filePath?: string): string[];
+/**
+ * Record the write time in a `modified` frontmatter field.
+ *
+ * Claude Code records an ISO 8601 timestamp when it writes a memory file that
+ * begins with YAML frontmatter. A file without frontmatter is left untouched;
+ * an existing top-level or `metadata.modified` value is replaced in place, and
+ * a `metadata.modified` value is added only when a `metadata:` block exists.
+ * Line endings and every other line are preserved.
+ */
+export declare function touchModified(content: string, now?: Date): string;

package/lib/memory-frontmatter.js

@@ -11,131 +11,198 @@
  * ```
  *
  * 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.
+ * a top-level `type` (and `modified`) 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;
+    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;
+    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, "")
+    };
+    const name = top.name;
+    const description = top.description;
+    const type = metadata.type ?? top.type;
+    const modified = metadata.modified ?? top.modified;
+    if (name !== undefined && name.length > 0)
+        result.name = name;
+    if (description !== undefined && description.length > 0)
+        result.description = description;
+    if (type !== undefined && type.length > 0)
+        result.type = type;
+    if (modified !== undefined && modified.length > 0)
+        result.modified = modified;
+    return result;
 }
-
 /**
  * Describe each frontmatter problem as a stable code plus a readable message.
  *
  * Codes stay stable when only the offending value changes, so callers can tell
  * "the same problem still exists" from "this edit introduced a new problem".
- *
- * @param {ReturnType<typeof parseMemory>} parsed - parsed memory file.
- * @param {string} [fileStem] - file name without `.md`; `[[name]]` resolves to it.
- * @param {string} [filePath] - project-relative path, used to detect subdirectories.
- * @returns {Array<{code: string, message: string}>} problems; empty when well-formed.
  */
 export function memoryFrontmatterIssues(parsed, fileStem, filePath) {
-  if (!parsed.frontmatter) {
-    return [{ code: "frontmatter-missing", message: "no frontmatter (name, description, metadata.type)" }];
-  }
-
-  const issues = [];
-  if (parsed.name === undefined) {
-    issues.push({ code: "name-missing", message: "missing name" });
-  } else if (!MEMORY_NAME.test(parsed.name)) {
-    issues.push({
-      code: "name-invalid",
-      message: `name ${JSON.stringify(parsed.name)} is not kebab-case`
-    });
-  } else if (fileStem !== undefined && parsed.name !== fileStem) {
-    const file = filePath ?? `${fileStem}.md`;
-    issues.push({
-      code: "name-unmatched",
-      message: `name ${JSON.stringify(parsed.name)} does not match the file name ${file}, so [[${parsed.name}]] will not resolve`
-    });
-  } else if (filePath !== undefined && filePath.includes("/")) {
-    issues.push({
-      code: "name-nested",
-      message:
-        `name ${JSON.stringify(parsed.name)} matches the file name, but the file is in a subdirectory; ` +
-        `[[${parsed.name}]] resolves to /memories/${parsed.name}.md, not this file`
-    });
-  }
-
-  if (parsed.description === undefined) {
-    issues.push({ code: "description-missing", message: "missing description" });
-  }
-  if (parsed.type === undefined) {
-    issues.push({ code: "type-missing", message: "missing metadata.type" });
-  } else if (!MEMORY_TYPES.includes(parsed.type)) {
-    issues.push({
-      code: "type-invalid",
-      message: `metadata.type ${JSON.stringify(parsed.type)} is not one of ${MEMORY_TYPES.join(", ")}`
-    });
-  }
-  return issues;
+    if (!parsed.frontmatter) {
+        return [{ code: "frontmatter-missing", message: "no frontmatter (name, description, metadata.type)" }];
+    }
+    const issues = [];
+    if (parsed.name === undefined) {
+        issues.push({ code: "name-missing", message: "missing name" });
+    }
+    else if (!MEMORY_NAME.test(parsed.name)) {
+        issues.push({
+            code: "name-invalid",
+            message: `name ${JSON.stringify(parsed.name)} is not kebab-case`
+        });
+    }
+    else if (fileStem !== undefined && parsed.name !== fileStem) {
+        const file = filePath ?? `${fileStem}.md`;
+        issues.push({
+            code: "name-unmatched",
+            message: `name ${JSON.stringify(parsed.name)} does not match the file name ${file}, so [[${parsed.name}]] will not resolve`
+        });
+    }
+    else if (filePath !== undefined && filePath.includes("/")) {
+        issues.push({
+            code: "name-nested",
+            message: `name ${JSON.stringify(parsed.name)} matches the file name, but the file is in a subdirectory; ` +
+                `[[${parsed.name}]] resolves to /memories/${parsed.name}.md, not this file`
+        });
+    }
+    if (parsed.description === undefined) {
+        issues.push({ code: "description-missing", message: "missing description" });
+    }
+    if (parsed.type === undefined) {
+        issues.push({ code: "type-missing", message: "missing metadata.type" });
+    }
+    else if (!MEMORY_TYPES.includes(parsed.type)) {
+        issues.push({
+            code: "type-invalid",
+            message: `metadata.type ${JSON.stringify(parsed.type)} is not one of ${MEMORY_TYPES.join(", ")}`
+        });
+    }
+    return issues;
 }
-
 /**
  * List what a topic file's frontmatter is missing, for a non-blocking hint.
- *
- * @param {ReturnType<typeof parseMemory>} parsed - parsed memory file.
- * @param {string} [fileStem] - file name without `.md`; `[[name]]` resolves to it.
- * @param {string} [filePath] - project-relative path, used to detect subdirectories.
- * @returns {string[]} human-readable problems; empty when the file is well-formed.
  */
 export function memoryFrontmatterProblems(parsed, fileStem, filePath) {
-  return memoryFrontmatterIssues(parsed, fileStem, filePath).map((issue) => issue.message);
+    return memoryFrontmatterIssues(parsed, fileStem, filePath).map((issue) => issue.message);
+}
+/**
+ * Record the write time in a `modified` frontmatter field.
+ *
+ * Claude Code records an ISO 8601 timestamp when it writes a memory file that
+ * begins with YAML frontmatter. A file without frontmatter is left untouched;
+ * an existing top-level or `metadata.modified` value is replaced in place, and
+ * a `metadata.modified` value is added only when a `metadata:` block exists.
+ * Line endings and every other line are preserved.
+ */
+export function touchModified(content, now = new Date()) {
+    const bom = content.startsWith("\uFEFF") ? "\uFEFF" : "";
+    const source = bom.length > 0 ? content.slice(1) : content;
+    const eol = source.includes("\r\n") ? "\r\n" : "\n";
+    const lines = source.split(/\r?\n/u);
+    if (lines[0]?.trim() !== DELIMITER)
+        return content;
+    let end = -1;
+    for (let index = 1; index < lines.length; index += 1) {
+        if (lines[index].trim() === DELIMITER) {
+            end = index;
+            break;
+        }
+    }
+    if (end === -1)
+        return content;
+    const timestamp = now.toISOString();
+    const frontmatter = lines.slice(1, end);
+    let topModified = -1;
+    let metadataStart = -1;
+    let metadataEnd = -1;
+    for (let index = 0; index < frontmatter.length; index += 1) {
+        const line = frontmatter[index];
+        if (topModified === -1 && /^modified\s*:/u.test(line))
+            topModified = index;
+        if (metadataStart === -1 && /^metadata\s*:\s*$/u.test(line))
+            metadataStart = index;
+    }
+    if (metadataStart !== -1) {
+        metadataEnd = metadataStart + 1;
+        while (metadataEnd < frontmatter.length) {
+            const line = frontmatter[metadataEnd];
+            if (line.trim().length === 0)
+                break;
+            if (!/^\s+/u.test(line))
+                break;
+            metadataEnd += 1;
+        }
+    }
+    let nestedModified = -1;
+    if (metadataStart !== -1) {
+        for (let index = metadataStart + 1; index < metadataEnd; index += 1) {
+            if (/^\s+modified\s*:/u.test(frontmatter[index])) {
+                nestedModified = index;
+                break;
+            }
+        }
+    }
+    const replaceValue = (line) => {
+        const prefix = /^(\s*modified\s*:).*$/u.exec(line);
+        return prefix === null ? line : `${prefix[1]} ${timestamp}`;
+    };
+    if (topModified !== -1) {
+        frontmatter[topModified] = replaceValue(frontmatter[topModified]);
+    }
+    if (nestedModified !== -1) {
+        frontmatter[nestedModified] = replaceValue(frontmatter[nestedModified]);
+    }
+    if (nestedModified === -1 && metadataStart !== -1) {
+        frontmatter.splice(metadataStart + 1, 0, `  modified: ${timestamp}`);
+    }
+    if (topModified === -1 && metadataStart === -1) {
+        frontmatter.push(`modified: ${timestamp}`);
+    }
+    const next = [lines[0], ...frontmatter, ...lines.slice(end)].join(eol);
+    return `${bom}${next}`;
 }

package/lib/paths.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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`.
+ */
+export declare function projectKey(cwd: string): string;
+/** The memory key root and the directory project rules are anchored to. */
+export interface ProjectLocation {
+    /** Shared memory key: the main checkout for linked worktrees. */
+    projectRoot: string;
+    /** Directory that owns `.claude/rules` / `.dsh/rules` for this session. */
+    ruleRoot: string;
+}
+/**
+ * Walk up from `cwd` until a directory containing one of `markers` is found.
+ *
+ * Memory is keyed by `projectRoot` (a linked worktree resolves to its main
+ * checkout), while project rules and their `paths` base stay anchored to the
+ * checkout the session actually works in (`ruleRoot`). When no marker exists
+ * the working directory is both.
+ */
+export declare function findProjectLocation(cwd: string, markers: string[], signal?: AbortSignal): Promise<ProjectLocation>;
+/**
+ * Return only the memory project root (the main checkout for linked worktrees).
+ */
+export declare function findProjectRoot(cwd: string, markers: string[], signal?: AbortSignal): Promise<string>;
+/**
+ * Abbreviate a path below the OS home for model-facing prompts.
+ */
+export declare function displayPath(path: string): string;
+/**
+ * Compute the memory directory for one project.
+ */
+export declare function memoryDirectory(memoryRoot: string, key: string): string;