Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

14.9 KB
Raw Blame
/**
 * Memory: the Agent's long-term notes across Sessions.
 *
 * Memory keeps what cannot be re-derived from the current Workspace or its code history —
 * user feedback, project decisions, working conventions, entry points into external systems.
 * It is **not** context compaction: compaction preserves one Session's short-term working
 * state, Memory preserves what later Sessions need.
 *
 * There are two scopes, both belonging to one Agent and never shared with another:
 *
 *   - **User scope** (`memory/user/`) — what stays true wherever the Agent works: who the user
 *     is, their standing preferences, reference material not tied to one codebase. Every
 *     Session reads it, including one running in a temporary Workspace, which has no other
 *     place to write.
 *   - **Workspace scope** (`memory/<workspace_key>/`) — facts about one Workspace. Sessions of
 *     the same Agent in the same Workspace share it; different Workspaces keep their topic files
 *     apart. A Session in a temporary Workspace gets no Workspace scope at all.
 *
 * Each scope directory carries its own `MEMORY.md` index; only the indexes enter the model
 * context, topic bodies are read on demand. Memory lives in Agent State, so it travels with
 * export / import / snapshots and is visible to every Project member who can reach the Agent.
 *
 * On-disk layout (`agent_state/memory/`):
 *
 *     memory/
 *     ├── user/                        # User scope (no marker: it stands for no path)
 *     │   ├── MEMORY.md                # this scope's index
 *     │   └── <topic>.md
 *     └── <workspace_memory_key>/
 *         ├── .workspace               # the Workspace path this key stands for
 *         ├── MEMORY.md
 *         └── <topic>.md               # frontmatter + body, semantic topics (not per Task/date)
 *
 * The Harness only decides *where* Memory lives, keeps writes inside that directory, and
 * injects the indexes into the prompt; the model owns the semantics — what is worth keeping,
 * how topics are split, and how the indexes are maintained — using the ordinary file tools.
 * Docs: /docs/configuration § "Memory".
 */
import { createHash } from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import { agentsDir, memoryScopeDir } from "./paths.js";

/** Per-scope index file name, also excluded from a scope's topic listing. */
export const MEMORY_INDEX_FILENAME = "MEMORY.md";

/**
 * Directory name of the User scope under `memory/`, and its scope key throughout the API — it
 * sits alongside the Workspace directories and is read through the same code paths.
 *
 * The name is safe to reserve because a generated workspace key is always
 * `<safe-basename>-<8 hex>` and therefore always contains a hyphen: a name without one can
 * never be produced by `workspaceMemoryKeyForRealPath`, so no Workspace can ever collide with
 * it. (A Workspace directory literally named `user` yields `user-<hash>`, not `user`.)
 */
export const USER_SCOPE_KEY = "user";

/**
 * Marker file inside a Workspace Memory directory recording the Workspace path the key was
 * derived from. The key alone is a hash and cannot be read back into a path, so this is what
 * lets the Web App label a Workspace; it is a dotfile so it never shows up as a topic.
 */
export const WORKSPACE_MARKER_FILENAME = ".workspace";

/** Length of the path hash suffix in a workspace key: 32 bits of a sha256, enough that two Workspaces on one machine practically never collide. */
const KEY_HASH_LENGTH = 8;

/** Cap on the readable part of a workspace key, so a deeply named directory can't produce an unwieldy path. */
const KEY_BASE_MAX_LENGTH = 40;

/** Frontmatter of one Memory topic file. */
export interface MemoryTopicMetadata {
  /** Display name; falls back to the file name when the frontmatter omits it. */
  name: string;
  /** One line telling a reader whether the body is worth opening. */
  description: string;
  /** Last-updated date as written in the file (`YYYY-MM-DD` by convention, not parsed). */
  updatedAt?: string;
}

/** The Workspace scope of one Session: absent when the Session runs in a temporary Workspace. */
export interface SessionWorkspaceMemory {
  /** Workspace memory key — the `memory/` subdirectory name and the API's scope key. */
  key: string;
  /** Absolute path of the Workspace's topic directory — used by the server and Web App, and the `{{WORKSPACE_MEMORY_DIR}}` value in the workspace Memory prompt. */
  dir: string;
  /** Content of this scope's `MEMORY.md` (the `{{WORKSPACE_MEMORY_INDEX}}` value; empty string when blank). */
  index: string;
}

/**
 * The Memory binding of one Session, as resolved at Session creation: the User scope (always)
 * and the Workspace scope (only in a persistent Workspace), each with its own index.
 */
export interface SessionMemory {
  /** Absolute path of `memory/user/` — used by the server and Web App; the prompt names this directory as a literal `<app_data_dir>/…` pattern instead. */
  userDir: string;
  /** Content of `memory/user/MEMORY.md` (the `{{USER_MEMORY_INDEX}}` value; empty string when blank). */
  userIndex: string;
  /** The Workspace scope; `undefined` in a temporary Workspace, where the User scope is the only place to write. */
  workspace?: SessionWorkspaceMemory;
}

/**
 * Turns a Workspace directory name into the readable half of its key: everything outside
 * `[A-Za-z0-9_-]` collapses to a hyphen, and the result is lowercased and truncated. A
 * directory whose name survives as empty (a filesystem root, a name made only of separators
 * or CJK characters) falls back to `workspace` — the hash half still keeps the key unique.
 */
function safeKeyBase(dirName: string): string {
  const cleaned = dirName
    .replace(/[^A-Za-z0-9_-]+/g, "-")
    .replace(/^-+|-+$/g, "")
    .slice(0, KEY_BASE_MAX_LENGTH)
    .toLowerCase();
  return cleaned.length > 0 ? cleaned : "workspace";
}

/**
 * The workspace key for an already-canonical absolute path: `<safe-basename>-<8 hex of the
 * path's sha256>`. The hyphen before the hash is what makes `USER_SCOPE_KEY` safe to reserve —
 * every generated key carries one, so a hyphen-free name is unreachable from here.
 *
 * Identity is the directory itself and has nothing to do with Git: two symlinks pointing at
 * one directory resolve to the same real path and therefore the same key, while moving or
 * renaming a directory makes it a new Workspace (its old Memory stays on disk under the old
 * key). Prefer `workspaceMemoryKey`, which canonicalizes first.
 */
export function workspaceMemoryKeyForRealPath(realPath: string): string {
  const hash = createHash("sha256").update(realPath).digest("hex").slice(0, KEY_HASH_LENGTH);
  return `${safeKeyBase(path.basename(realPath))}-${hash}`;
}

/**
 * The workspace key for a Workspace directory: resolves symlinks and `..` first so every
 * route to one directory produces one key. A path that cannot be canonicalized (already
 * deleted, or not readable) falls back to `path.resolve`, which still yields a stable key
 * rather than failing Session creation.
 */
export async function workspaceMemoryKey(workspaceDir: string): Promise<string> {
  return workspaceMemoryKeyForRealPath(await realPathOrResolve(workspaceDir));
}

async function realPathOrResolve(dir: string): Promise<string> {
  try {
    return await fs.realpath(dir);
  } catch {
    return path.resolve(dir);
  }
}

/**
 * Whether a Workspace is one Adelie created for a Session itself, i.e. it sits under
 * some Agent's `workspaces/` directory (`<project>/agents/<agent>/workspaces/tmp-xxxxxxxx`).
 *
 * Temporary Workspaces get no Memory, because one is allocated per Session (see
 * `createTempWorkspace`, called once per `createSession`): no later Session ever runs in that
 * directory, so anything written to a Memory directory keyed off it could never be read back —
 * it would be write-only storage. Note this is *not* because the directory gets cleaned up:
 * deleting a Session removes its Traces and scratchpad but leaves `workspaces/tmp-xxxxxxxx`
 * behind, and nothing prunes it.
 *
 * The check is by location rather than by "did the caller pass a workspaceDir", because a
 * subagent inherits its parent's Workspace as an explicit argument — including when that
 * Workspace is the parent's temporary one.
 */
export async function isTemporaryWorkspace(
  root: string,
  projectId: string,
  workspaceDir: string,
): Promise<boolean> {
  const real = await realPathOrResolve(workspaceDir);
  const base = await realPathOrResolve(agentsDir(root, projectId));
  const rel = path.relative(base, real);
  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return false;
  const segments = rel.split(path.sep);
  // <agentId>/workspaces/<workspace_id>: anything shallower is the Agent directory itself.
  return segments.length >= 3 && segments[1] === "workspaces";
}

/**
 * Creates a scope's empty `MEMORY.md` when it does not exist yet. Existing content — including
 * a deliberately emptied file — is never touched: the index is the model's document, the
 * Harness only guarantees there is one to open.
 */
async function ensureScopeIndex(dir: string): Promise<void> {
  try {
    await fs.writeFile(path.join(dir, MEMORY_INDEX_FILENAME), "", { flag: "wx" });
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
  }
}

/** Reads a scope's `MEMORY.md`; an empty string when it does not exist yet. */
export async function readScopeIndex(dir: string): Promise<string> {
  try {
    return await fs.readFile(path.join(dir, MEMORY_INDEX_FILENAME), "utf8");
  } catch {
    return "";
  }
}

/**
 * Creates a Workspace's Memory directory (with an empty `MEMORY.md`) if needed and records the
 * Workspace path in its `.workspace` marker.
 *
 * The marker is (re)written whenever it is missing or does not match, which repairs one that
 * was hand-edited, truncated or written by an older version. It is deliberately *not* a rename
 * path and cannot be one: the key is a hash of the very path the marker records, so a directory
 * reached another way — through a symlink — canonicalizes to the same real path and lands on
 * this same directory with an identical marker, while a directory that genuinely moved hashes
 * to a different key and therefore a different Memory directory.
 *
 * Never touches topic files or an existing index — those are the model's to maintain.
 */
export async function ensureWorkspaceMemoryDir(args: {
  root: string;
  projectId: string;
  agentId: string;
  workspaceKey: string;
  workspacePath: string;
}): Promise<string> {
  const dir = memoryScopeDir(args.root, args.projectId, args.agentId, args.workspaceKey);
  await fs.mkdir(dir, { recursive: true });
  await ensureScopeIndex(dir);
  const marker = path.join(dir, WORKSPACE_MARKER_FILENAME);
  const line = `${args.workspacePath}\n`;
  try {
    if ((await fs.readFile(marker, "utf8")) === line) return dir;
  } catch {
    // No marker yet (or unreadable): fall through and write it.
  }
  await fs.writeFile(marker, line, "utf8");
  return dir;
}

/** Absolute path of the User scope's topic directory (`memory/user/`). */
export function userMemoryDir(root: string, projectId: string, agentId: string): string {
  return memoryScopeDir(root, projectId, agentId, USER_SCOPE_KEY);
}

/**
 * Creates the User scope's directory (with an empty `MEMORY.md`) if needed. Unlike a Workspace
 * directory it gets no `.workspace` marker: the marker records the path a key was hashed from,
 * and this scope stands for no path at all — it belongs to the Agent itself. Called at Agent
 * State init and again at every Session creation, so Agents created before Memory shipped
 * self-heal.
 */
export async function ensureUserMemoryDir(
  root: string,
  projectId: string,
  agentId: string,
): Promise<string> {
  const dir = userMemoryDir(root, projectId, agentId);
  await fs.mkdir(dir, { recursive: true });
  await ensureScopeIndex(dir);
  return dir;
}

/** Reads the Workspace path recorded in a Memory directory's marker; `undefined` when the marker is missing or empty. */
export async function readWorkspaceMarker(dir: string): Promise<string | undefined> {
  try {
    const raw = (await fs.readFile(path.join(dir, WORKSPACE_MARKER_FILENAME), "utf8")).trim();
    return raw.length > 0 ? raw : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Resolves the Memory a Session should run with, creating the scope directories (and their
 * empty `MEMORY.md` indexes) as a side effect. The User scope is always prepared; the Workspace
 * scope only when the Session runs in a persistent Workspace, so a temporary one never gets a
 * directory that no later Session could read back.
 *
 * Returns `null` — nothing injected, nothing created — when Memory is disabled for the Agent.
 * Failures to prepare a directory are also `null`: Memory is an enhancement, and an unwritable
 * Agent State should not take down Session creation.
 */
export async function resolveSessionMemory(args: {
  root: string;
  projectId: string;
  agentId: string;
  workspaceDir: string;
  enabled: boolean;
}): Promise<SessionMemory | null> {
  if (!args.enabled) return null;
  try {
    const userDir = await ensureUserMemoryDir(args.root, args.projectId, args.agentId);
    const userIndex = await readScopeIndex(userDir);
    if (await isTemporaryWorkspace(args.root, args.projectId, args.workspaceDir)) {
      return { userDir, userIndex };
    }
    const workspacePath = await realPathOrResolve(args.workspaceDir);
    const key = workspaceMemoryKeyForRealPath(workspacePath);
    const dir = await ensureWorkspaceMemoryDir({
      root: args.root,
      projectId: args.projectId,
      agentId: args.agentId,
      workspaceKey: key,
      workspacePath,
    });
    return { userDir, userIndex, workspace: { key, dir, index: await readScopeIndex(dir) } };
  } catch {
    return null;
  }
}

/**
 * Parses a Memory topic file's frontmatter, in the same line-oriented way as Skill
 * frontmatter (values are plain scalars, not full YAML). Returns `null` when the file has no
 * frontmatter block at all; individual missing fields are simply left out, and unknown fields
 * (including the retired `type:` earlier files may carry) are ignored, so a hand-edited file
 * never fails to list. `fallbackName` (normally the file name) stands in for a missing `name`.
 */
export function parseMemoryFrontmatter(
  content: string,
  fallbackName: string,
): MemoryTopicMetadata | null {
  // Strip a possible UTF-8 BOM (editors add one when a file is edited by hand); CRLF is handled by \r?\n.
  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content.replace(/^/, ""));
  if (!match) return null;
  const fields: Record<string, string> = {};
  for (const line of match[1]!.split(/\r?\n/)) {
    const idx = line.indexOf(":");
    if (idx <= 0) continue;
    const key = line.slice(0, idx).trim();
    if (key) fields[key] = line.slice(idx + 1).trim();
  }
  const updatedAt = fields["updated_at"];
  return {
    name: fields["name"] || fallbackName,
    description: fields["description"] ?? "",
    ...(updatedAt ? { updatedAt } : {}),
  };
}