Function parseMemoryPath

src/node/services/memoryService.ts:132–207

(virtualPath: string)

 * model-recoverable message on invalid input.
 */
export function parseMemoryPath(virtualPath: string): ParsedMemoryPath {
  const trimmed = virtualPath.trim();
  if (!trimmed.startsWith(MEMORY_VIRTUAL_ROOT)) {
    throw new MemoryCommandError(
      `Invalid memory path '${virtualPath}': paths must start with ${MEMORY_VIRTUAL_ROOT}/ (e.g. ${MEMORY_VIRTUAL_ROOT}/global/notes.md)`
    );
  }
  const rest = trimmed.slice(MEMORY_VIRTUAL_ROOT.length).replace(/\/+$/, "");
  if (rest === "") {
    return { scope: null, relPath: "" };
  }
  if (!rest.startsWith("/")) {
    throw new MemoryCommandError(
      `Invalid memory path '${virtualPath}': expected ${MEMORY_VIRTUAL_ROOT}/<scope>/...`
    );
  }
  const segments = rest.slice(1).split("/");
  const scope = segments[0] as MemoryScope;
  if (!MEMORY_SCOPES.includes(scope)) {
    throw new MemoryCommandError(
      `Invalid memory scope '${segments[0]}': expected one of ${MEMORY_SCOPES.join(", ")}`
    );
  }
  const relSegments = segments.slice(1);
  for (const segment of relSegments) {
    if (segment === "" || segment === ".") {
      throw new MemoryCommandError(
        `Invalid memory path '${virtualPath}': empty or '.' path segments are not allowed`
      );
    }
    if (segment === ".." || segment.includes("..")) {
      throw new MemoryCommandError(
        `Invalid memory path '${virtualPath}': path traversal ('..') is not allowed`
      );
    }
    if (segment.includes("~")) {
      throw new MemoryCommandError(
        `Invalid memory path '${virtualPath}': '~' is not allowed in memory paths`
      );
    }
    if (segment.includes("\\")) {
      throw new MemoryCommandError(
        `Invalid memory path '${virtualPath}': backslashes are not allowed (use '/')`
      );
    }
    if (ENCODED_TRAVERSAL_PATTERN.test(segment)) {
      throw new MemoryCommandError(
        `Invalid memory path '${virtualPath}': URL-encoded traversal sequences are not allowed`
      );
    }
    if (CONTROL_CHARS_PATTERN.test(segment)) {
      throw new MemoryCommandError(
        `Invalid memory path '${virtualPath}': control characters are not allowed`
      );
    }
    // Paths are rendered into prompt context (the memory tool's index and
    // the <hot_memories> block): names containing XML metacharacters could
    // reassemble structure-breaking markup across segments (e.g. 'a<' +