Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

10.6 KB
Raw Blame
import fs from "node:fs/promises";
import path from "node:path";
import { markMemoryChanged, writeTextFile } from "./fs-utils.js";
import { normalizeValidMemoryMarkdown } from "./okf-validation.js";
import { resolveMemoryOutputPath } from "./paths.js";
import type { MemoryUpdateOutput } from "./types.js";
import { validateAll } from "./validation.js";

export interface ApplyOptions {
  allowedSubjectKeys?: string[];
  allowedPathPrefixes?: string[];
  allowedDeletePathPrefixes?: string[];
}

export async function validateMemoryUpdate(
  memoryRoot: string,
  output: MemoryUpdateOutput,
  options: ApplyOptions = {},
): Promise<MemoryUpdateOutput> {
  if (output.schema_version !== 1) {
    throw new Error(
      `Unsupported daily update schema: ${JSON.stringify(output.schema_version)}`,
    );
  }
  const allowedSubjectKeys = new Set(options.allowedSubjectKeys ?? []);
  const normalizedFiles: MemoryUpdateOutput["files"] = [];
  const fileTargets = new Set<string>();
  const checks = output.files.map((file) => () => {
    assertMemoryOutputPath(file.path, allowedSubjectKeys);
    assertAllowedPathPrefix(file.path, options.allowedPathPrefixes);
    const targetPath = safeMemoryPath(memoryRoot, file.path);
    if (fileTargets.has(targetPath)) {
      throw new Error(
        `Memory output writes the same path more than once: ${file.path}`,
      );
    }
    fileTargets.add(targetPath);
    if (shouldSkipMemoryPath(file.path)) {
      normalizedFiles.push(file);
      return;
    }
    const normalizedPath = normalizeMemoryPath(file.path);
    const subjectRelativePath = normalizedPath.split("/").slice(1).join("/");
    normalizedFiles.push({
      ...file,
      content: normalizeValidMemoryMarkdown(subjectRelativePath, file.content),
    });
  });
  const deletedPaths = output.deleted_paths ?? [];
  const deletedTargets = new Set<string>();
  for (const relativePath of deletedPaths)
    checks.push(() => {
      assertMemoryOutputPath(relativePath, allowedSubjectKeys);
      assertAllowedDeletePathPrefix(
        relativePath,
        options.allowedDeletePathPrefixes,
      );
      const targetPath = safeMemoryPath(memoryRoot, relativePath);
      if (deletedTargets.has(targetPath)) {
        throw new Error(
          `Memory output deletes the same path more than once: ${relativePath}`,
        );
      }
      if (fileTargets.has(targetPath)) {
        throw new Error(
          `Memory output cannot write and delete the same path: ${relativePath}`,
        );
      }
      deletedTargets.add(targetPath);
    });
  checks.push(() => {
    for (const entry of output.memory_log_entries) {
      if (typeof entry.memory_path === "string") {
        assertAllowedPathPrefix(entry.memory_path, options.allowedPathPrefixes);
      }
    }
    groupLogEntriesBySubject(output, allowedSubjectKeys);
  });
  await validateAll(checks);
  return { ...output, files: normalizedFiles };
}

export async function applyMemoryUpdate(
  memoryRoot: string,
  output: MemoryUpdateOutput,
  options: ApplyOptions = {},
): Promise<void> {
  output = await validateMemoryUpdate(memoryRoot, output, options);
  const allowedSubjectKeys = new Set(options.allowedSubjectKeys ?? []);
  const snapshots = await captureApplySnapshots(memoryRoot, output);
  const changedSubjects = new Set<string>();
  try {
    for (const file of output.files) {
      const subjectKey = assertMemoryOutputPath(file.path, allowedSubjectKeys);
      changedSubjects.add(subjectKey);
      assertAllowedPathPrefix(file.path, options.allowedPathPrefixes);
      if (shouldSkipMemoryPath(file.path)) continue;
      await writeTextFile(safeMemoryPath(memoryRoot, file.path), file.content);
    }

    for (const relativePath of output.deleted_paths ?? []) {
      const subjectKey = assertMemoryOutputPath(
        relativePath,
        allowedSubjectKeys,
      );
      changedSubjects.add(subjectKey);
      assertAllowedDeletePathPrefix(
        relativePath,
        options.allowedDeletePathPrefixes,
      );
      await fs.rm(safeMemoryPath(memoryRoot, relativePath), { force: true });
    }
  } catch (error) {
    try {
      await restoreApplySnapshots(snapshots);
    } catch {
      // Preserve the original apply failure; the snapshot remains diagnostic.
    }
    throw error;
  } finally {
    // Runs after any restore, so the bump follows every content change.
    for (const subjectKey of changedSubjects)
      await markMemoryChanged(memoryRoot, subjectKey);
  }
}

export const applyDailyUpdate = applyMemoryUpdate;

export function safeMemoryPath(
  memoryRoot: string,
  relativePath: string,
): string {
  return resolveMemoryOutputPath(memoryRoot, relativePath);
}

function assertSubjectPath(
  relativePath: string,
  allowedSubjectKeys: Set<string>,
): string {
  const subjectKey = relativePath.split(/[\\/]/)[0];
  if (!subjectKey) {
    throw new Error(`Memory output path is empty: ${relativePath}`);
  }
  if (!allowedSubjectKeys.has(subjectKey)) {
    throw new Error(
      `Memory output path must start with a memory subject key: ${relativePath}. Expected subject: ${[...allowedSubjectKeys].join(", ")}`,
    );
  }
  return subjectKey;
}

function assertMemoryOutputPath(
  relativePath: string,
  allowedSubjectKeys: Set<string>,
): string {
  if (allowedSubjectKeys.size > 0) {
    return assertSubjectPath(relativePath, allowedSubjectKeys);
  }
  const subjectKey = relativePath.split(/[\\/]/)[0];
  if (!subjectKey) {
    throw new Error(`Memory output path is empty: ${relativePath}`);
  }
  return subjectKey;
}

function assertAllowedPathPrefix(
  relativePath: string,
  allowedPathPrefixes: readonly string[] | undefined,
): void {
  if (!allowedPathPrefixes || allowedPathPrefixes.length === 0) {
    return;
  }
  const [, ...segments] = normalizeMemoryPath(relativePath).split("/");
  const subjectRelativePath = segments.join("/");
  if (
    !allowedPathPrefixes.some((prefix) =>
      subjectRelativePath.startsWith(prefix),
    )
  ) {
    throw new Error(
      `Memory output path is outside the allowed scope: ${relativePath}`,
    );
  }
}

function assertAllowedDeletePathPrefix(
  relativePath: string,
  allowedDeletePathPrefixes: readonly string[] | undefined,
): void {
  if (allowedDeletePathPrefixes === undefined) return;
  const [, ...segments] = normalizeMemoryPath(relativePath).split("/");
  const subjectRelativePath = segments.join("/");
  if (
    !allowedDeletePathPrefixes.some((prefix) =>
      subjectRelativePath.startsWith(prefix),
    )
  ) {
    throw new Error(
      `Memory deletion is outside the allowed scope: ${relativePath}`,
    );
  }
}

function groupLogEntriesBySubject(
  output: MemoryUpdateOutput,
  allowedSubjectKeys: Set<string>,
): Map<string, Array<Record<string, unknown>>> {
  const result = new Map<string, Array<Record<string, unknown>>>();
  for (const entry of output.memory_log_entries) {
    if (
      typeof entry.memory_path === "string" &&
      shouldSkipMemoryPath(entry.memory_path)
    ) {
      continue;
    }
    const subjectKey =
      typeof entry.memory_subject_key === "string"
        ? entry.memory_subject_key
        : typeof entry.memory_path === "string"
          ? (entry.memory_path.split(/[\\/]/)[0] ?? undefined)
          : undefined;
    if (!subjectKey) {
      throw new Error("Memory log entry is missing memory_subject_key");
    }
    if (allowedSubjectKeys.size > 0 && !allowedSubjectKeys.has(subjectKey)) {
      throw new Error(
        `Memory log entry uses an unknown subject key: ${subjectKey}`,
      );
    }
    const entries = result.get(subjectKey) ?? [];
    entries.push(entry);
    result.set(subjectKey, entries);
  }
  return result;
}

export function parseMemoryUpdateOutput(
  raw: string,
  allowedSubjectKeys: readonly string[] = [],
): MemoryUpdateOutput {
  const parsed = JSON.parse(raw) as Partial<MemoryUpdateOutput>;
  if (
    parsed.schema_version !== 1 ||
    typeof parsed.date !== "string" ||
    !Array.isArray(parsed.files) ||
    !Array.isArray(parsed.memory_log_entries)
  ) {
    throw new Error("LLM output does not match the daily update shape");
  }
  for (const file of parsed.files) {
    if (
      typeof file !== "object" ||
      file === null ||
      typeof file.path !== "string" ||
      typeof file.content !== "string" ||
      (file.source_refs !== undefined &&
        (!Array.isArray(file.source_refs) ||
          file.source_refs.some((entry) => typeof entry !== "string")))
    ) {
      throw new Error("LLM output contains an invalid file entry");
    }
  }
  if (
    parsed.deleted_paths !== undefined &&
    (!Array.isArray(parsed.deleted_paths) ||
      parsed.deleted_paths.some((entry) => typeof entry !== "string"))
  ) {
    throw new Error("LLM output contains invalid deleted paths");
  }
  const output = parsed as MemoryUpdateOutput;
  if (allowedSubjectKeys.length > 0) {
    const subjects = new Set(allowedSubjectKeys);
    for (const file of output.files) assertSubjectPath(file.path, subjects);
    for (const filePath of output.deleted_paths ?? []) {
      assertSubjectPath(filePath, subjects);
    }
    for (const entry of output.memory_log_entries) {
      if (typeof entry.memory_path === "string") {
        assertSubjectPath(entry.memory_path, subjects);
      }
    }
    groupLogEntriesBySubject(output, subjects);
  }
  return output;
}

async function captureApplySnapshots(
  memoryRoot: string,
  output: MemoryUpdateOutput,
): Promise<Map<string, string | null>> {
  const paths = new Set<string>();
  for (const file of output.files) {
    paths.add(safeMemoryPath(memoryRoot, file.path));
  }
  for (const relativePath of output.deleted_paths ?? []) {
    paths.add(safeMemoryPath(memoryRoot, relativePath));
  }
  const snapshots = new Map<string, string | null>();
  for (const targetPath of paths) {
    snapshots.set(targetPath, await readOptionalTextFile(targetPath));
  }
  return snapshots;
}

async function restoreApplySnapshots(
  snapshots: Map<string, string | null>,
): Promise<void> {
  for (const [targetPath, content] of snapshots) {
    if (content === null) {
      await fs.rm(targetPath, { force: true });
    } else {
      await writeTextFile(targetPath, content);
    }
  }
}

async function readOptionalTextFile(filePath: string): Promise<string | null> {
  try {
    return await fs.readFile(filePath, "utf8");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
      return null;
    }
    throw error;
  }
}

function normalizeMemoryPath(relativePath: string): string {
  return path.normalize(relativePath).split(path.sep).join("/");
}

function shouldSkipMemoryPath(relativePath: string): boolean {
  const parts = path.normalize(relativePath).split(path.sep);
  if (parts.length < 4 || parts[1] !== "evidence") {
    return false;
  }
  return parts[3] === "events";
}