A local-first multi-agent app development platform, built on PenguinHarness
/**
* Memory management (`agent_state/memory/`): the Web App's read/delete access to what the Agent
* remembers between Sessions.
*
* The layout is core's (see core's state/memory.ts): one directory per scope holding Markdown
* topic files and that scope's own `MEMORY.md` index — `memory/user/` for the User scope and
* `memory/<workspace_key>/` for each Workspace. The User scope is addressed through the same
* `scopeKey` parameter as any Workspace (`USER_SCOPE_KEY`), so it needs no routes of its own;
* the one difference is that it may be created on demand, since it belongs to the Agent rather
* than to a Session that has run.
*
* Per-file content changes go through a chat Session where the model edits the same files,
* keeping frontmatter and index in step; this service's own writes are the mechanical ones a
* model cannot be asked for. Deleting a topic file drops its `](<file>)` index lines, so the
* index never lists a file that is gone. Whole-scope import writes the files a transfer
* document carries and adds their index lines, the same invariant read the other way: the
* index never omits a file that arrived. Only the indexes enter the model's context (core's
* state/memory.ts), so an unindexed topic file would be a file the Agent never reads.
*
* This service never invents paths from client input — a request names an `agentId`, a
* `scopeKey` and a file name inside that scope, each validated against a character rule and
* then re-checked for containment after resolution, so neither `..` nor a symlink can reach
* outside the Agent's Memory directory.
*
* Files are the source of truth and are read fresh on every request (they are small, requests
* are rare, and the model edits the same files from its side).
*/
import fs from "node:fs/promises";
import path from "node:path";
import {
MEMORY_INDEX_FILENAME,
USER_SCOPE_KEY,
atomicWriteFile,
hasMemoryPlaceholder,
insertMemoryPlaceholder,
memoryDir,
memoryScopeDir,
parseMemoryFrontmatter,
readWorkspaceMarker,
} from "@adelie/core";
import type {
MemoryFileInfo,
MemoryFilesResponse,
MemoryFileResponse,
MemoryImportMode,
MemoryImportResponse,
MemoryOverviewResponse,
MemoryScopeExport,
MemoryScopeInfo,
MemoryTransferFile,
} from "../api/types.js";
import { HttpError } from "../http/errors.js";
import { badRequest } from "../http/validate.js";
import { Component, Use } from "@adelie/core/kernel";
import type { Config, Paths } from "../hmr/capabilities.js";
import type { AgentConfig, Memory } from "../mechanisms/agents.js";
/** Scope directory names: what core's key generator produces (a safe base may start with `_`), plus the leeway of a hand-made directory. Excludes `.`/`..` and any separator, so the name can never climb out of `memory/`. */
const SCOPE_KEY_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
/** The transfer document's format marker, checked before anything in it is believed. Typed against the DTO so the two literals cannot drift apart. */
const SCOPE_FORMAT: MemoryScopeExport["format"] = "penguin-memory-scope";
/** The document version this reader accepts. A later format bumps it and states its own compatibility. */
const SCOPE_FORMAT_VERSION: MemoryScopeExport["version"] = 1;
/**
* What one import may carry.
*
* These are Memory's own numbers, not the attachment budget's: an attachment is an opaque blob
* handed to the model's file tools, while a memory is Markdown the model wrote for itself to
* re-read, and 100MB of it would be a scope no index could describe. The request as a whole is
* already bounded by the API body cap before any of this runs — what follows bounds what one
* scope directory can be made to hold.
*/
/** Topic files one document may carry. A scope the model keeps by hand runs to tens of files, so this is far past ordinary use and still a directory that lists. */
const MAX_IMPORT_FILES = 500;
/** Bytes of one file's text (UTF-8), the index included. A memory that does not fit in 512KB of Markdown is not a memory. */
const MAX_IMPORT_FILE_BYTES = 512 * 1024;
/** Bytes across the whole document: one scope directory's total. */
const MAX_IMPORT_TOTAL_BYTES = 8 * 1024 * 1024;
/**
* Bytes of one file name. The name rule says nothing about length, and a name longer than the
* filesystem's own limit for a path component fails at the write with ENAMETOOLONG — a 500 for
* what is plainly a bad request. 255 is that limit on ext4, APFS and NTFS alike.
*/
const MAX_IMPORT_NAME_BYTES = 255;
/**
* Matches an index line's Markdown link to one file — `](file)`, `](./file)`, `](<file>)`,
* `](file "title")`. A prose mention of the name is not a link and never matches, which is what
* keeps both index edits (prune on delete, extend on import) mechanical rather than clever.
*/
function indexLinkPattern(fileName: string): RegExp {
const escaped = fileName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
return new RegExp(`\\]\\(\\s*<?(?:\\./)?${escaped}>?\\s*(?:"[^"]*"\\s*)?\\)`);
}
/**
* Whether a name is a topic file: any Markdown file that is not a dotfile (`.workspace` is the
* Harness's), carries no path separator, and is not the index under any casing — macOS and
* Windows resolve `memory.md` to `MEMORY.md`. The model writes these files with the ordinary
* file tools, so non-ASCII names are as legitimate as kebab-case ones; the same rule guards
* client-supplied names, with containment re-checked after resolution. Exported so the Agent
* list's memory count (agent-service) shares this one definition of "a memory".
*/
export function isTopicFileName(name: string): boolean {
return (
name.length > 0 &&
!name.startsWith(".") &&
!/[/\\]/.test(name) &&
name.toLowerCase().endsWith(".md") &&
name.toLowerCase() !== MEMORY_INDEX_FILENAME.toLowerCase()
);
}
/**
* Orders topic file names identically on every host. `localeCompare` is deliberately not used
* here: with no locale argument it follows the server's own locale, so the same scope listed its
* files one way under `en_US.UTF-8` and another under `zh_CN.UTF-8` — and that order is what an
* export document carries. Case-folded first, so `Alpha.md` still sorts between `a.md` and
* `beta.md` rather than jumping ahead of both as raw code units would; ties then fall back to
* code units so the order is total. `toLowerCase`, never `toLocaleLowerCase` — the locale-aware
* one would put the dependency straight back.
*/
function compareTopicFileNames(a: string, b: string): number {
const foldedA = a.toLowerCase();
const foldedB = b.toLowerCase();
if (foldedA !== foldedB) return foldedA < foldedB ? -1 : 1;
return a < b ? -1 : a > b ? 1 : 0;
}
/**
* Validates a transfer document on its way to the server's disk.
*
* Everything here is untrusted: the document may have been hand-written, produced by another
* tool, or crafted. So the shape is checked field by field before any of it is believed, and the
* result carries only what was verified — the entry names are handed to the same `resolveFile`
* check that guards every other write, which is what keeps one definition of "a legal memory
* file name" in the service.
*
* Refuses, with the reason: a foreign or future format, entries that are not text, a name that
* carries a NUL or is longer than a path component may be (both of which the filesystem layer
* would throw on rather than reject), the same name twice, and any of the size bounds.
*/
function parseTransferDocument(payload: unknown): {
index: string | null;
files: MemoryTransferFile[];
} {
if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
throw badRequest("payload must be a Memory scope export object.");
}
const doc = payload as Record<string, unknown>;
if (doc.format !== SCOPE_FORMAT) {
throw badRequest(`payload.format must be "${SCOPE_FORMAT}".`);
}
if (doc.version !== SCOPE_FORMAT_VERSION) {
throw badRequest(`payload.version must be ${SCOPE_FORMAT_VERSION}.`);
}
if (!Array.isArray(doc.files)) throw badRequest("payload.files must be an array.");
if (doc.files.length > MAX_IMPORT_FILES) {
throw badRequest(`payload.files must hold at most ${MAX_IMPORT_FILES} entries.`);
}
let total = 0;
const measure = (text: string, label: string): void => {
if (text.includes("\u0000")) throw badRequest(`${label} must be text.`);
const bytes = Buffer.byteLength(text, "utf8");
if (bytes > MAX_IMPORT_FILE_BYTES) {
throw badRequest(`${label} exceeds the ${MAX_IMPORT_FILE_BYTES / 1024}KB limit.`);
}
total += bytes;
if (total > MAX_IMPORT_TOTAL_BYTES) {
throw badRequest(
`payload exceeds the ${MAX_IMPORT_TOTAL_BYTES / (1024 * 1024)}MB total limit.`,
);
}
};
let index: string | null = null;
if (doc.index !== null && doc.index !== undefined) {
if (typeof doc.index !== "string") throw badRequest("payload.index must be a string or null.");
measure(doc.index, "payload.index");
index = doc.index;
}
const files: MemoryTransferFile[] = [];
const seen = new Set<string>();
for (const entry of doc.files) {
if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
throw badRequest("Each payload.files entry must be an object.");
}
const { name, content } = entry as Record<string, unknown>;
if (typeof name !== "string") throw badRequest("Each payload.files entry needs a name.");
if (typeof content !== "string") {
throw badRequest(`Content of ${name} must be a string.`);
}
if (name.includes("\u0000")) throw badRequest("A file name must be text.");
if (Buffer.byteLength(name, "utf8") > MAX_IMPORT_NAME_BYTES) {
throw badRequest(`A file name must be at most ${MAX_IMPORT_NAME_BYTES} bytes.`);
}
if (seen.has(name)) throw badRequest(`payload.files names ${name} twice.`);
seen.add(name);
measure(content, `Content of ${name}`);
files.push({ name, content });
}
return { index, files };
}
@Component()
export class MemoryService implements Memory {
@Use() private readonly paths!: Paths;
private get root(): string {
return this.paths.root;
}
@Use() private readonly agentConfigService!: AgentConfig;
/** The tab's landing payload: the Agent-level switch and one entry per scope directory. */
async overview(projectId: string, agentId: string): Promise<MemoryOverviewResponse> {
const view = await this.agentConfigService.getConfig(projectId, agentId);
return {
enabled: view.config.memory.enabled,
templateHasMemory: hasMemoryPlaceholder(view.config.systemPrompt),
memoryDir: memoryDir(this.root, projectId, agentId),
scopes: await this.listScopes(projectId, agentId),
};
}
/**
* Inserts the `{{MEMORY}}` placeholder into the Agent's prompt template — the explicit
* adoption path for an Agent created before Memory shipped; nothing inserts automatically.
* Idempotent: a template that already carries it is left as it is (the refreshed overview
* reports `templateHasMemory` either way).
*/
async insertTemplatePlaceholder(
projectId: string,
agentId: string,
): Promise<MemoryOverviewResponse> {
const view = await this.agentConfigService.getConfig(projectId, agentId);
const next = insertMemoryPlaceholder(view.config.systemPrompt);
if (next !== view.config.systemPrompt) {
await this.agentConfigService.updateConfig(projectId, agentId, {
config: { systemPrompt: next },
});
}
return this.overview(projectId, agentId);
}
/**
* The scope directories under `memory/`: the User scope first — always listed, even before it
* exists on disk, so a memory can be filed there without waiting for a Session to create it —
* then the Workspaces, newest activity first (one with no topic file yet sorts last, by key).
*/
async listScopes(projectId: string, agentId: string): Promise<MemoryScopeInfo[]> {
const base = memoryDir(this.root, projectId, agentId);
let entries: string[] = [];
try {
entries = (await fs.readdir(base, { withFileTypes: true }))
.filter((e) => e.isDirectory() && e.name !== USER_SCOPE_KEY)
.map((e) => e.name);
} catch {
// No memory/ directory yet (never initialized): the User scope entry below still stands.
}
const workspaces = await Promise.all(
entries.map((key) => this.scopeInfo(path.join(base, key), key, "workspace")),
);
workspaces.sort((a, b) => {
if (a.updatedAt && b.updatedAt) return b.updatedAt.localeCompare(a.updatedAt);
if (a.updatedAt) return -1;
if (b.updatedAt) return 1;
return a.scopeKey.localeCompare(b.scopeKey);
});
const userScope = await this.scopeInfo(path.join(base, USER_SCOPE_KEY), USER_SCOPE_KEY, "user");
return [userScope, ...workspaces];
}
private async scopeInfo(
dir: string,
key: string,
kind: MemoryScopeInfo["kind"],
): Promise<MemoryScopeInfo> {
const files = await this.topicFileNames(dir);
let latest = 0;
for (const name of files) {
try {
const stat = await fs.stat(path.join(dir, name));
latest = Math.max(latest, stat.mtimeMs);
} catch {
// Raced with a delete: leave it out of the timestamp.
}
}
const workspacePath = kind === "workspace" ? await readWorkspaceMarker(dir) : undefined;
return {
scopeKey: key,
kind,
...(workspacePath !== undefined ? { workspacePath } : {}),
fileCount: files.length,
hasIndex: await this.hasIndexFile(dir),
...(latest > 0 ? { updatedAt: new Date(latest).toISOString() } : {}),
};
}
/**
* Whether the scope holds its own `MEMORY.md`. lstat, not stat: a symlink planted at that name
* is not an index — treating it as one would carry a read or a write outside the Memory
* directory, and the atomic write below replaces such a link instead of following it.
*/
private async hasIndexFile(dir: string): Promise<boolean> {
try {
return (await fs.lstat(path.join(dir, MEMORY_INDEX_FILENAME))).isFile();
} catch {
return false;
}
}
/** Topic files of one scope: regular Markdown files only — the index, the `.workspace` marker, stray directories and symlinks (dirents that are not regular files) all stay out. */
private async topicFileNames(dir: string): Promise<string[]> {
try {
return (await fs.readdir(dir, { withFileTypes: true }))
.filter((e) => e.isFile() && isTopicFileName(e.name))
.map((e) => e.name)
.sort(compareTopicFileNames);
} catch {
return [];
}
}
async listFiles(
projectId: string,
agentId: string,
scopeKey: string,
): Promise<MemoryFilesResponse> {
const dir = await this.requireScopeDir(projectId, agentId, scopeKey);
const names = await this.topicFileNames(dir);
const files: MemoryFileInfo[] = [];
for (const name of names) {
const info = await this.fileInfo(dir, name);
if (info) files.push(info);
}
return { scopeKey, files };
}
async readFile(
projectId: string,
agentId: string,
scopeKey: string,
fileName: string,
): Promise<MemoryFileResponse> {
const dir = await this.requireScopeDir(projectId, agentId, scopeKey);
const target = this.resolveFile(dir, fileName);
try {
// lstat, not stat: a symlink planted among the topic files (the model can create one with
// its file tools) must not lead the read outside the Memory directory. A non-regular file
// — or one deleted between the calls — is a 404, never a 500.
const stat = await fs.lstat(target);
if (!stat.isFile()) throw new Error("not a regular file");
const content = await fs.readFile(target, "utf8");
return {
scopeKey,
file: this.describe(fileName, content, stat.size, stat.mtime),
content,
};
} catch {
throw new HttpError(404, "memory_file_not_found", `Memory file not found: ${fileName}`);
}
}
/**
* The whole scope as one transfer document: every topic file plus the scope's own `MEMORY.md`.
*
* JSON rather than an archive, because the payload is entirely UTF-8 Markdown and the import
* side of it is an untrusted write into the Agent's Memory directory: a JSON document carries
* no paths, no permissions and no compression, so its entries can go through the same per-file
* name check every other write here uses, with nothing to unpack first.
*
* Unreadable entries are left out rather than failing the export, as elsewhere in this service.
* The size bounds below apply to import only — an export reports what the directory actually
* holds, and a scope grown past them is exactly the thing its owner needs to see.
*/
async exportScope(
projectId: string,
agentId: string,
scopeKey: string,
): Promise<MemoryScopeExport> {
const dir = await this.requireScopeDir(projectId, agentId, scopeKey);
const files: MemoryTransferFile[] = [];
for (const name of await this.topicFileNames(dir)) {
const content = await this.readTextFile(path.join(dir, name));
if (content !== null) files.push({ name, content });
}
const kind = scopeKey === USER_SCOPE_KEY ? "user" : "workspace";
const workspacePath = kind === "workspace" ? await readWorkspaceMarker(dir) : undefined;
return {
format: SCOPE_FORMAT,
version: SCOPE_FORMAT_VERSION,
scopeKey,
kind,
...(workspacePath !== undefined ? { workspacePath } : {}),
exportedAt: new Date().toISOString(),
index: (await this.hasIndexFile(dir))
? await this.readTextFile(path.join(dir, MEMORY_INDEX_FILENAME))
: null,
files,
};
}
/**
* Writes a transfer document into one scope.
*
* The default mode keeps every file already on disk and writes only names the scope does not
* have, so an import can never cost the user a memory they did not agree to lose. `overwrite`
* replaces a same-named file's content and `replace` additionally deletes what the document
* does not carry; both are refused with 409 unless `confirm` is set — but only when they would
* actually destroy something, since a confirmation that names nothing is just a click.
*
* The index follows the files. A scope with no index takes the document's; `replace` takes it
* too (the whole scope is being replaced); a merge keeps the index that is there and appends
* the document's lines for the files this import added, because only the indexes enter the
* model's context and an unindexed memory is one the Agent never reads.
*/
async importScope(
projectId: string,
agentId: string,
scopeKey: string,
request: { mode: MemoryImportMode; confirm: boolean; payload: unknown },
): Promise<MemoryImportResponse> {
const dir = await this.requireScopeDir(projectId, agentId, scopeKey);
const { index, files } = parseTransferDocument(request.payload);
// Names are resolved before anything is written, so a document with one bad entry writes
// nothing at all rather than half of itself.
const planned = files.map((f) => ({ ...f, target: this.resolveFile(dir, f.name) }));
const present = new Set(await this.topicFileNames(dir));
const carried = new Set(files.map((f) => f.name));
const collides = files.filter((f) => present.has(f.name)).map((f) => f.name);
const removed =
request.mode === "replace" ? [...present].filter((name) => !carried.has(name)) : [];
const overwritten = request.mode === "skip" ? [] : collides;
const skipped = request.mode === "skip" ? collides : [];
// `replace` takes the document's index over the scope's own, which is the user's text too.
const replacesIndex =
request.mode === "replace" && index !== null && (await this.hasIndexFile(dir));
if (!request.confirm && (overwritten.length > 0 || removed.length > 0 || replacesIndex)) {
throw new HttpError(
409,
"memory_import_confirm_required",
`This import would overwrite ${overwritten.length} and delete ${removed.length} memories in ${scopeKey}` +
`${replacesIndex ? `, and replace its ${MEMORY_INDEX_FILENAME}` : ""}. Repeat it with confirm set.`,
);
}
const added: string[] = [];
for (const file of planned) {
if (request.mode === "skip" && present.has(file.name)) continue;
await this.writeScopeFile(file.target, file.content);
if (!present.has(file.name)) added.push(file.name);
}
for (const name of removed) {
await fs.unlink(path.join(dir, name)).catch(() => {
// Raced with a delete from a Session: the file is gone either way.
});
}
const written = [...added, ...overwritten];
let indexWritten = false;
if (index !== null) {
if (replacesIndex || !(await this.hasIndexFile(dir))) {
await this.writeScopeFile(path.join(dir, MEMORY_INDEX_FILENAME), index);
indexWritten = true;
} else {
indexWritten = await this.extendIndex(dir, index, written);
}
}
// Whatever the index now says, it must not list a file this import deleted.
for (const name of removed) await this.pruneIndexLines(dir, name);
return { scopeKey, mode: request.mode, added, overwritten, skipped, removed, indexWritten };
}
/**
* Appends the document's index lines for the files this import wrote: a line linking a written
* file that the scope's index does not already link is added at the end, in the document's own
* order. Nothing else is touched — the mirror image of pruneIndexLines, so between them the
* index lists neither a file that is gone nor omits one that arrived.
*/
private async extendIndex(dir: string, docIndex: string, written: string[]): Promise<boolean> {
const indexPath = path.join(dir, MEMORY_INDEX_FILENAME);
const current = await this.readTextFile(indexPath);
if (current === null) return false;
const docLines = docIndex.split("\n");
const additions: string[] = [];
for (const name of written) {
const link = indexLinkPattern(name);
if (link.test(current)) continue;
const line = docLines.find((l) => link.test(l));
if (line !== undefined && !additions.includes(line)) additions.push(line);
}
if (additions.length === 0) return false;
const head = current === "" || current.endsWith("\n") ? current : `${current}\n`;
await this.writeScopeFile(indexPath, `${head}${additions.join("\n")}\n`);
return true;
}
/**
* The write path for every change this service makes to Memory content, shared by the imported
* topic files and the index.
*
* The target has already been through `resolveFile` (or is the reserved index name, which is
* never client-supplied), so it names a file directly inside this scope. The write goes to a
* temporary dotfile — invisible to every topic listing — and is renamed over the target, so a
* reader never sees a half-written memory. Symlinks are deliberately not followed: the Memory
* directory is model-writable, and a link planted at a topic's name would otherwise carry the
* write out of it. Replacing the link keeps the write inside the scope.
*/
private async writeScopeFile(target: string, content: string): Promise<void> {
await atomicWriteFile(target, content);
}
/** Reads a regular file as text, null when it is absent, unreadable, or not a regular file (lstat, so a symlink is never followed). */
private async readTextFile(target: string): Promise<string | null> {
try {
if (!(await fs.lstat(target)).isFile()) return null;
return await fs.readFile(target, "utf8");
} catch {
return null;
}
}
/**
* Deletes a topic file and mechanically drops its lines from the scope's `MEMORY.md`: any
* line whose Markdown link target is exactly this file (`](<file>)`) goes; a mention of the
* name in ordinary prose, or a link to a different file, survives. This is the only write the
* API performs on Memory content — everything else is the model's, through a chat Session.
*/
async deleteFile(
projectId: string,
agentId: string,
scopeKey: string,
fileName: string,
): Promise<void> {
const dir = await this.requireScopeDir(projectId, agentId, scopeKey);
const target = this.resolveFile(dir, fileName);
try {
await fs.unlink(target);
} catch {
throw new HttpError(404, "memory_file_not_found", `Memory file not found: ${fileName}`);
}
await this.pruneIndexLines(dir, fileName);
}
/** Removes index lines linking to a deleted file. Best-effort: a missing or unreadable index is left alone. */
private async pruneIndexLines(dir: string, fileName: string): Promise<void> {
const indexPath = path.join(dir, MEMORY_INDEX_FILENAME);
let content: string;
try {
content = await fs.readFile(indexPath, "utf8");
} catch {
return;
}
const link = indexLinkPattern(fileName);
const lines = content.split("\n");
const kept = lines.filter((line) => !link.test(line));
if (kept.length === lines.length) return;
await this.writeScopeFile(indexPath, kept.join("\n"));
}
private async fileInfo(dir: string, name: string): Promise<MemoryFileInfo | null> {
try {
const [content, stat] = await Promise.all([
fs.readFile(path.join(dir, name), "utf8"),
fs.stat(path.join(dir, name)),
]);
return this.describe(name, content, stat.size, stat.mtime);
} catch {
// Raced with a delete, or not readable: leave it out of the listing rather than failing the request.
return null;
}
}
/** One listing entry: frontmatter (falling back to the file name for an unparsed file) plus file stats. */
private describe(name: string, content: string, size: number, mtime: Date): MemoryFileInfo {
const meta = parseMemoryFrontmatter(content, name);
return {
name,
title: meta?.name ?? name,
description: meta?.description ?? "",
...(meta?.updatedAt !== undefined ? { updatedAt: meta.updatedAt } : {}),
size,
modifiedAt: mtime.toISOString(),
};
}
/**
* Validates a scope key and returns its directory, 404 if it does not exist. The key is only
* ever a single directory name.
*
* A Workspace directory is created by a Session, so this API never creates one — a key with no
* directory means no Session has run there and there is nothing to list. The User scope is the
* exception: it belongs to the Agent rather than to any Session, so it is created on demand
* (Agents that predate Memory have no `memory/user/` until their next Session).
*/
private async requireScopeDir(
projectId: string,
agentId: string,
scopeKey: string,
): Promise<string> {
await this.agentConfigService.requireExists(projectId, agentId);
if (!SCOPE_KEY_PATTERN.test(scopeKey)) {
throw badRequest("scopeKey is invalid.");
}
const dir = memoryScopeDir(this.root, projectId, agentId, scopeKey);
if (scopeKey === USER_SCOPE_KEY) {
await fs.mkdir(dir, { recursive: true });
return this.requireRealScopeDir(projectId, agentId, scopeKey, dir);
}
try {
if ((await fs.stat(dir)).isDirectory()) {
return this.requireRealScopeDir(projectId, agentId, scopeKey, dir);
}
} catch {
// Fall through to the 404 below.
}
throw new HttpError(
404,
"memory_scope_not_found",
`No Memory directory for scope: ${scopeKey}`,
);
}
/**
* Symlink hardening for the scope directory itself: a scope smuggled in as a symlink (the
* model can create one with its file tools) would carry every read and delete outside
* `memory/`, so the resolved real path must be exactly `<real memory/>/<scopeKey>` — not a
* link's target, wherever it points.
*/
private async requireRealScopeDir(
projectId: string,
agentId: string,
scopeKey: string,
dir: string,
): Promise<string> {
try {
const realBase = await fs.realpath(memoryDir(this.root, projectId, agentId));
if ((await fs.realpath(dir)) === path.join(realBase, scopeKey)) return dir;
} catch {
// Unresolvable path: treat as absent.
}
throw new HttpError(
404,
"memory_scope_not_found",
`No Memory directory for scope: ${scopeKey}`,
);
}
/**
* The absolute path of a topic file inside a scope directory. The name must pass the
* character rule, must not be the reserved index name, and the joined path is checked
* for containment — belt and braces, since the rule already excludes separators.
*/
private resolveFile(dir: string, fileName: string): string {
if (!isTopicFileName(fileName)) {
throw badRequest(
`File name must be a Markdown topic file — no path, no leading dot, and not the ${MEMORY_INDEX_FILENAME} index.`,
);
}
const target = path.join(dir, fileName);
const rel = path.relative(dir, target);
if (rel !== fileName || rel.includes(path.sep)) {
throw badRequest("File name must not contain a path.");
}
return target;
}
}