pi-memoria 0.2.0 → 0.3.0

package/src/database.ts

@@ -0,0 +1,301 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { DatabaseSync, type StatementSync } from "node:sqlite";
+import { expandQuery, loadAliases, type AliasConfiguration } from "./aliases.ts";
+import { ExpectedError, isSqliteError, storeUnavailable } from "./errors.ts";
+import { chunk, excerpt, integer, MEMORY_LIMIT, nonempty, tags as validateTags } from "./text.ts";
+
+export interface Memory {
+  id: string;
+  content: string;
+  tags: string[];
+  source: string;
+  created_at: string;
+  updated_at: string;
+  revision: number;
+}
+
+export interface MemoryInput { content: string; tags?: string[]; source?: string }
+export type SearchMode = "any" | "all" | "phrase" | "literal";
+export interface MemorySearchOptions {
+  /** Expand configured terminology alternatives for any/all keyword modes. Defaults to true. */
+  expandAliases?: boolean;
+  /** Require exact, case-sensitive membership for every supplied tag. */
+  tags?: string[];
+}
+interface Row { [key: string]: unknown }
+
+function validatedInput(input: MemoryInput, preserveWhitespace = false): Required<MemoryInput> {
+  const content = preserveWhitespace ? input.content : nonempty(input.content, "content");
+  if (!content.length || content.length > MEMORY_LIMIT || content.includes("\0")) {
+    throw new ExpectedError("invalid_input", `content must contain 1–${MEMORY_LIMIT} characters and no NUL bytes.`, { field: "content" });
+  }
+  return {
+    content, tags: validateTags(input.tags),
+    source: input.source ? nonempty(input.source, "source", 2_000) : "",
+  };
+}
+
+function memory(row: Row): Memory {
+  return {
+    id: String(row.id), content: String(row.content), tags: JSON.parse(String(row.tags)) as string[],
+    source: String(row.source), created_at: String(row.created_at), updated_at: String(row.updated_at),
+    revision: Number(row.revision),
+  };
+}
+
+export class MemoryDatabase {
+  private db: DatabaseSync;
+  private statements = new Map<string, StatementSync>();
+  private aliases?: AliasConfiguration;
+  private closed = false;
+
+  constructor(readonly path: string, private readonly aliasesPath?: string) {
+    try { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); }
+    catch (error) { throw storeUnavailable("open", path, error); }
+    try { this.db = new DatabaseSync(path); }
+    catch (error) { throw storeUnavailable("open", path, error); }
+    try {
+      chmodSync(path, 0o600);
+      this.db.exec("PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;");
+      this.db.function("memoria_fold", { deterministic: true }, (value) => String(value).toLowerCase());
+      this.transaction(() => {
+        const version = Number(this.db.prepare("PRAGMA user_version").get()?.user_version);
+        if (version > 2) throw new Error(`Database schema ${version} is newer than this pi-memoria version.`);
+        if (version === 0) {
+          this.db.exec(`
+            CREATE TABLE memories (
+              rowid INTEGER PRIMARY KEY,
+              id TEXT NOT NULL UNIQUE,
+              content TEXT NOT NULL,
+              tags TEXT NOT NULL DEFAULT '[]',
+              tag_text TEXT NOT NULL DEFAULT '',
+              source TEXT NOT NULL DEFAULT '',
+              created_at TEXT NOT NULL,
+              updated_at TEXT NOT NULL,
+              revision INTEGER NOT NULL DEFAULT 1
+            ) STRICT;
+            CREATE VIRTUAL TABLE memories_fts USING fts5(
+              content, tag_text, source, content='memories', content_rowid='rowid',
+              tokenize='porter unicode61 remove_diacritics 2', prefix='2 3'
+            );
+            CREATE TRIGGER memories_insert AFTER INSERT ON memories BEGIN
+              INSERT INTO memories_fts(rowid, content, tag_text, source) VALUES(new.rowid, new.content, new.tag_text, new.source);
+            END;
+            CREATE TRIGGER memories_delete AFTER DELETE ON memories BEGIN
+              INSERT INTO memories_fts(memories_fts, rowid, content, tag_text, source)
+                VALUES('delete', old.rowid, old.content, old.tag_text, old.source);
+            END;
+            CREATE TRIGGER memories_update AFTER UPDATE ON memories BEGIN
+              INSERT INTO memories_fts(memories_fts, rowid, content, tag_text, source)
+                VALUES('delete', old.rowid, old.content, old.tag_text, old.source);
+              INSERT INTO memories_fts(rowid, content, tag_text, source) VALUES(new.rowid, new.content, new.tag_text, new.source);
+            END;
+            CREATE TABLE session_roots (path TEXT PRIMARY KEY) STRICT;
+            PRAGMA user_version=1;
+          `);
+        }
+        if (version < 2) {
+          // Keep existing duplicates and archive evidence intact; serialize new adds below.
+          this.db.exec("CREATE INDEX memories_content ON memories(content); PRAGMA user_version=2;");
+        }
+      });
+    } catch (error) {
+      this.closed = true;
+      try { this.db.close(); } catch { /* keep the original failure */ }
+      throw storeUnavailable("open", path, error);
+    }
+  }
+
+  private attempt<T>(operation: string, work: () => T): T {
+    try { return work(); }
+    catch (error) {
+      if (error instanceof ExpectedError) throw error;
+      if (isSqliteError(error)) throw storeUnavailable(operation, this.path, error);
+      throw error;
+    }
+  }
+
+  private statement(sql: string): StatementSync {
+    if (this.closed) throw storeUnavailable("access", this.path, new Error("database is closed"));
+    let result = this.statements.get(sql);
+    if (!result) { result = this.db.prepare(sql); this.statements.set(sql, result); }
+    return result;
+  }
+
+  private transaction<T>(operation: () => T): T {
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      const result = operation();
+      this.db.exec("COMMIT");
+      return result;
+    } catch (error) { this.db.exec("ROLLBACK"); throw error; }
+  }
+
+  add(input: MemoryInput): { memory: Memory; created: boolean } {
+    const value = validatedInput(input);
+    // BEGIN IMMEDIATE covers both lookup and insertion, including competing Pi processes.
+    return this.attempt("add", () => this.transaction(() => {
+      const existing = this.statement("SELECT * FROM memories WHERE content=? ORDER BY rowid LIMIT 1").get(value.content);
+      if (existing) return { memory: memory(existing), created: false };
+      const id = `m_${randomUUID()}`;
+      this.insert(id, value);
+      return { memory: this.get(id), created: true };
+    }));
+  }
+
+  private insert(id: string, { content, tags, source }: Required<MemoryInput>, ignore = false): void {
+    const timestamp = new Date().toISOString();
+    this.statement(`INSERT ${ignore ? "OR IGNORE" : ""} INTO memories(id,content,tags,tag_text,source,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`)
+      .run(id, content, JSON.stringify(tags), tags.join("\n"), source, timestamp, timestamp);
+  }
+
+  /** Save first, then let the caller replace MEMORY.md. Retrying is idempotent. */
+  archive(entries: { id: string; content: string }[], sourcePath: string): string[] {
+    return this.attempt("archive", () => this.transaction(() => entries.map((entry) => {
+      const id = `m_archive_${createHash("sha256").update(entry.id + "\0" + entry.content).digest("hex").slice(0, 24)}`;
+      // Oversized hand-written bullets are preserved in complete, bounded pieces.
+      const parts: string[] = [];
+      for (let offset = 0; offset < entry.content.length;) {
+        const part = chunk(entry.content, offset, 19_000);
+        parts.push(part.text);
+        offset = part.next_text_offset ?? entry.content.length;
+      }
+      parts.forEach((content, index) => this.insert(parts.length === 1 ? id : `${id}_${index + 1}`, validatedInput({
+        content, tags: ["hot-archive"], source: `${sourcePath}#${entry.id}${parts.length === 1 ? "" : ` (part ${index + 1}/${parts.length})`}`,
+      }, true), true));
+      return id;
+    })));
+  }
+
+  get(id: string): Memory {
+    return this.attempt("read", () => {
+      const row = this.statement("SELECT * FROM memories WHERE id=?").get(id);
+      if (!row) throw new ExpectedError("not_found", `Memory ${id} does not exist. Search before editing or deleting.`, { id });
+      return memory(row);
+    });
+  }
+
+  edit(id: string, changes: Partial<MemoryInput>, expectedRevision?: number): Memory {
+    return this.attempt("edit", () => this.transaction(() => {
+      const previous = this.get(id);
+      this.checkRevision(previous, expectedRevision);
+      const content = changes.content === undefined ? previous.content : nonempty(changes.content, "content");
+      const tags = changes.tags === undefined ? previous.tags : validateTags(changes.tags);
+      const source = changes.source === undefined ? previous.source : changes.source ? nonempty(changes.source, "source", 2_000) : "";
+      this.statement("UPDATE memories SET content=?,tags=?,tag_text=?,source=?,updated_at=?,revision=revision+1 WHERE id=?")
+        .run(content, JSON.stringify(tags), tags.join("\n"), source, new Date().toISOString(), id);
+      return this.get(id);
+    }));
+  }
+
+  delete(id: string, expectedRevision?: number): Memory {
+    return this.attempt("delete", () => this.transaction(() => {
+      const previous = this.get(id);
+      this.checkRevision(previous, expectedRevision);
+      this.statement("DELETE FROM memories WHERE id=?").run(id);
+      return previous;
+    }));
+  }
+
+  private checkRevision(value: Memory, expected?: number): void {
+    if (expected !== undefined && value.revision !== expected) {
+      throw new ExpectedError("conflict", `Memory ${value.id} changed (revision ${value.revision}, expected ${expected}). Search again before changing it.`, {
+        id: value.id, current_revision: value.revision, expected_revision: expected,
+      });
+    }
+  }
+
+  search(query = "", mode: SearchMode = "any", limit = 20, offset = 0, options: MemorySearchOptions = {}) {
+    integer(limit, "limit", 1, 50);
+    integer(offset, "offset", 0, Number.MAX_SAFE_INTEGER);
+    if (query.length > 2_000 || query.includes("\0")) {
+      throw new ExpectedError("invalid_input", "Query must be at most 2,000 characters without NUL bytes.", { field: "query" });
+    }
+    if (!["any", "all", "phrase", "literal"].includes(mode)) {
+      throw new ExpectedError("invalid_input", "Unknown memory search mode.", { field: "mode" });
+    }
+    const requestedTags = validateTags(options.tags);
+    const start = performance.now();
+    const trimmed = query.trim();
+    const terms = [...new Set(trimmed.match(/[\p{L}\p{N}\p{M}_]+/gu) ?? [])];
+    const keyword = mode === "any" || mode === "all";
+    const aliasExpansionEnabled = keyword && terms.length > 0 && (options.expandAliases ?? true);
+    const alias = aliasExpansionEnabled ? this.aliasConfiguration() : undefined;
+    const expansion = alias ? expandQuery(terms, alias.aliases) : { expansions: [] as Array<{ term: string; aliases: string[] }> };
+    const warnings = alias ? [alias.warning, expansion.warning].filter((value): value is string => value !== undefined) : [];
+    const tagClauses = requestedTags.map(() => "EXISTS (SELECT 1 FROM json_each(m.tags) AS requested_tag WHERE requested_tag.value = ? COLLATE BINARY)");
+    const tagWhere = tagClauses.join(" AND ");
+
+    let usedMode: SearchMode | "browse" = mode;
+    let rows: Row[];
+    const literal = () => this.statement(`SELECT m.* FROM memories m
+      WHERE instr(memoria_fold(m.content || char(10) || m.tag_text || char(10) || m.source), memoria_fold(?)) > 0${tagWhere ? ` AND ${tagWhere}` : ""}
+      ORDER BY m.created_at, m.id LIMIT ? OFFSET ?`).all(trimmed, ...requestedTags, limit + 1, offset);
+    if (!trimmed) {
+      usedMode = "browse";
+      rows = this.statement(`SELECT m.* FROM memories m${tagWhere ? ` WHERE ${tagWhere}` : ""} ORDER BY m.created_at,m.id LIMIT ? OFFSET ?`)
+        .all(...requestedTags, limit + 1, offset);
+    } else if (mode === "literal" || !terms.length) {
+      usedMode = "literal";
+      rows = literal();
+    } else {
+      const fts = mode === "phrase"
+        ? `"${terms.join(" ")}"`
+        : terms.map((term) => {
+          const alternatives = expansion.expansions.find((value) => value.term === term)?.aliases ?? [];
+          const tokens = [term, ...alternatives].map((token) => `"${token}"*`);
+          return tokens.length > 1 ? `(${tokens.join(" OR ")})` : tokens[0]!;
+        }).join(mode === "all" ? " AND " : " OR ");
+      rows = this.statement(`SELECT m.* FROM memories_fts JOIN memories m ON m.rowid=memories_fts.rowid
+        WHERE memories_fts MATCH ?${tagWhere ? ` AND ${tagWhere}` : ""} ORDER BY bm25(memories_fts),m.id LIMIT ? OFFSET ?`)
+        .all(fts, ...requestedTags, limit + 1, offset);
+      // Decide fallback independently of page offset so subsequent pages retain the same semantics.
+      // The existence probe uses the same tag predicate so an all-filtered corpus can still fall back.
+      if (!this.statement(`SELECT m.rowid FROM memories_fts JOIN memories m ON m.rowid=memories_fts.rowid
+        WHERE memories_fts MATCH ?${tagWhere ? ` AND ${tagWhere}` : ""} LIMIT 1`).get(fts, ...requestedTags)) {
+        usedMode = "literal";
+        rows = literal();
+      }
+    }
+    const hasMore = rows.length > limit;
+    return {
+      mode: usedMode,
+      query: trimmed,
+      tags: requestedTags,
+      alias_expansion_enabled: aliasExpansionEnabled,
+      expansions: expansion.expansions,
+      warnings,
+      results: rows.slice(0, limit).map((row) => {
+        const item = memory(row);
+        return { ...item, content: excerpt(item.content, terms[0] ?? trimmed), content_characters: item.content.length, content_clipped: item.content.length > 600 };
+      }),
+      next_offset: hasMore ? offset + limit : null,
+      elapsed_ms: Number((performance.now() - start).toFixed(3)),
+      hint: "Use id to read a complete memory. Try mode=literal for exact substrings, shorter/alternate terms, or query='' to browse everything. For historical claims or uncertain/empty recall, use memoria_sessions; an empty keyword result does not prove absence.",
+    };
+  }
+
+  private aliasConfiguration(): AliasConfiguration {
+    this.aliases ??= loadAliases(this.aliasesPath);
+    return this.aliases;
+  }
+
+  rememberRoots(paths: string[]): void {
+    this.attempt("remember_roots", () => this.transaction(() => {
+      for (const path of paths) this.statement("INSERT OR IGNORE INTO session_roots(path) VALUES(?)").run(resolve(path));
+    }));
+  }
+
+  roots(): string[] {
+    return this.attempt("list_roots", () => this.statement("SELECT path FROM session_roots ORDER BY path").all().map((row) => String(row.path)));
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.statements.clear();
+    this.db.close();
+  }
+}

package/src/errors.ts

@@ -0,0 +1,55 @@
+/** Stable codes for expected, recoverable failures. Unexpected errors pass through untouched. */
+export type ErrorCode =
+  | "invalid_input"
+  | "not_found"
+  | "conflict"
+  | "duplicate_hot_content"
+  | "hot_capacity"
+  | "store_unavailable"
+  | "hot_locked";
+
+export type ErrorDetails = Record<string, unknown>;
+
+export class ExpectedError extends Error {
+  readonly code: ErrorCode;
+  readonly details: ErrorDetails;
+
+  constructor(code: ErrorCode, message: string, details: ErrorDetails = {}) {
+    super(message);
+    this.name = "ExpectedError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function record(error: unknown): { code?: unknown; errcode?: unknown; errstr?: unknown; message?: unknown } {
+  return error !== null && typeof error === "object" ? error as Record<string, unknown> : {};
+}
+
+/** Extract the SQLite error code/string without losing the original message. */
+export function sqliteInfo(error: unknown): { code?: string; errcode?: number; errstr?: string; message: string } {
+  const value = record(error);
+  return {
+    ...(typeof value.code === "string" ? { code: value.code } : {}),
+    ...(typeof value.errcode === "number" ? { errcode: value.errcode } : {}),
+    ...(typeof value.errstr === "string" ? { errstr: value.errstr } : {}),
+    message: error instanceof Error ? error.message : String(error),
+  };
+}
+
+/** True when an error came from the SQLite driver, including a closed connection. */
+export function isSqliteError(error: unknown): boolean {
+  const code = record(error).code;
+  return typeof code === "string" && (code.startsWith("ERR_SQLITE") || code === "ERR_INVALID_STATE");
+}
+
+/** Classify a known database access failure. Passes through already classified errors. */
+export function storeUnavailable(operation: string, path: string, error: unknown): ExpectedError {
+  if (error instanceof ExpectedError) return error;
+  const info = sqliteInfo(error);
+  return new ExpectedError("store_unavailable", `SQLite is unavailable for ${operation} (${path}): ${info.message}`, {
+    operation,
+    path,
+    sqlite: info,
+  });
+}

package/src/files.ts

@@ -0,0 +1,29 @@
+import { randomUUID } from "node:crypto";
+import { open, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/** Same-directory replacement: readers see the previous or the complete new file. */
+export async function atomicWrite(path: string, text: string): Promise<void> {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    const file = await open(temporary, "wx", 0o600);
+    try {
+      await file.writeFile(text, "utf8");
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    await rename(temporary, path);
+    // Directory fsync is not supported on Windows.
+    if (process.platform !== "win32") {
+      const directory = await open(dirname(path), "r");
+      try { await directory.sync(); } finally { await directory.close(); }
+    }
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export function isMissing(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException)?.code === "ENOENT";
+}

package/src/hot-memory.ts

@@ -0,0 +1,231 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import lockfile from "proper-lockfile";
+import { atomicWrite, isMissing } from "./files.ts";
+import { ExpectedError } from "./errors.ts";
+import { HOT_LIMIT, integer, singleLine } from "./text.ts";
+
+export interface HotMemory { id: string; priority: number; content: string }
+export interface HotSnapshot { text: string; entries: HotMemory[]; characters: number; remaining: number; archived: HotMemory[]; backup?: string }
+export interface HotAddResult extends HotSnapshot { memory: HotMemory; created: boolean; note?: string }
+export interface HotEditResult extends HotSnapshot { memory: HotMemory }
+export interface HotDeleteResult extends HotSnapshot { deleted: HotMemory }
+type Queue = <T>(path: string, operation: () => Promise<T>) => Promise<T>;
+
+function serialize(entries: HotMemory[]): string {
+  return entries.map((entry) => `- [${entry.id}] [p=${entry.priority}] ${entry.content}\n`).join("");
+}
+
+function parse(text: string): HotMemory[] {
+  const entries: HotMemory[] = [];
+  for (const line of text.split(/\r?\n/u)) {
+    if (!line.trim() || /^#\s+MEMORY(?:\.md)?\s*$/iu.test(line)) continue;
+    if (/^\s+\S/u.test(line) && entries.length) {
+      entries[entries.length - 1]!.content += ` ${line.trim()}`;
+      continue;
+    }
+    const body = line.replace(/^\s*[-*+]\s+/u, "").trim();
+    const match = /^\[(h_[a-zA-Z0-9_-]+)\]\s+\[p=(\d+)\]\s+(.+)$/u.exec(body);
+    const content = match ? match[3]! : body;
+    const id = match ? match[1]! : `h_${createHash("sha256").update(body).digest("hex").slice(0, 16)}`;
+    if (entries.some((entry) => entry.id === id)) throw new Error(`Duplicate hot memory ID ${id}; repair MEMORY.md before editing.`);
+    entries.push({ id, priority: match ? integer(Number(match[2]), "priority", 0, 100) : 50, content });
+  }
+  return entries;
+}
+
+interface CapacityEntry { id: string; priority: number; characters: number; content: string }
+
+function described(entry: HotMemory): CapacityEntry {
+  return { id: entry.id, priority: entry.priority, characters: serialize([entry]).length, content: entry.content };
+}
+
+/**
+ * Exact serialized diagnostics for a refused hot operation. `current` is the
+ * pre-change list, `proposed` includes the requested add/edit, and `entry` is
+ * the proposed or duplicated bullet.
+ */
+function capacityDetails(reason: string, operation: string, current: HotMemory[], proposed: HotMemory[], entry: HotMemory) {
+  const currentCharacters = serialize(current).length;
+  const proposedCharacters = serialize(proposed).length;
+  const eligible = current
+    .filter((item) => item.id !== entry.id && item.priority < entry.priority)
+    .sort((a, b) => a.priority - b.priority)
+    .map(described);
+  const eligibleCharacters = eligible.reduce((sum, item) => sum + item.characters, 0);
+  return {
+    reason,
+    operation,
+    limit: HOT_LIMIT,
+    current_characters: currentCharacters,
+    proposed_characters: proposedCharacters,
+    over_by: Math.max(0, proposedCharacters - HOT_LIMIT),
+    remaining: Math.max(0, HOT_LIMIT - currentCharacters),
+    proposed_entry: described(entry),
+    entries: current.map(described),
+    eligible,
+    eligible_characters: eligibleCharacters,
+    shortfall_after_eligible_eviction: Math.max(0, proposedCharacters - eligibleCharacters - HOT_LIMIT),
+    live_file_unchanged: true,
+    next_actions: [
+      "Shorten the bullet or explicitly delete lower-value bullets with memoria_delete.",
+      "Save the fact in SQLite long-term memory instead.",
+      "Use memoria_edit to raise the priority of an important entry only when justified.",
+    ],
+  };
+}
+
+export class HotMemoryStore {
+  constructor(
+    readonly path: string,
+    private archive: (entries: HotMemory[]) => void,
+    private queue: Queue = async (_path, operation) => operation(),
+  ) {}
+
+  private async locked<T>(operation: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    return this.queue(this.path, async () => {
+      signal?.throwIfAborted();
+      await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+      let release: () => Promise<void>;
+      try {
+        release = await lockfile.lock(this.path, {
+          realpath: false, stale: 10_000, update: 2_000,
+          retries: { retries: 80, minTimeout: 10, maxTimeout: 100, randomize: true },
+        });
+      } catch (error) {
+        const code = (error as NodeJS.ErrnoException | undefined)?.code;
+        if (code === "ELOCKED") {
+          throw new ExpectedError("hot_locked", `Could not lock MEMORY.md within the retry window (ELOCKED). Another process is mutating it; retry shortly.`, { path: this.path, lock_code: code });
+        }
+        throw error;
+      }
+      try { signal?.throwIfAborted(); return await operation(); } finally { await release(); }
+    });
+  }
+
+  private async read(): Promise<string | undefined> {
+    try { return await readFile(this.path, "utf8"); }
+    catch (error) { if (isMissing(error)) return undefined; throw error; }
+  }
+
+  private snapshot(entries: HotMemory[], archived: HotMemory[], backup?: string): HotSnapshot {
+    const text = serialize(entries);
+    return { text, entries, characters: text.length, remaining: HOT_LIMIT - text.length, archived, ...(backup ? { backup } : {}) };
+  }
+
+  private capacityError(reason: string, operation: string, current: HotMemory[], proposed: HotMemory[], entry: HotMemory): ExpectedError {
+    const details = capacityDetails(reason, operation, current, proposed, entry);
+    const prefix = reason === "bullet_too_large"
+      ? `A single hot bullet serializes to ${details.proposed_entry.characters} characters including metadata, over the ${HOT_LIMIT}-character total limit.`
+      : reason === "existing_over_limit"
+        ? `MEMORY.md is already over the ${HOT_LIMIT}-character limit and must be repaired before duplicate content can be returned safely.`
+        : `MEMORY.md is ${details.over_by} characters over budget even after evicting every eligible lower-priority entry (shortfall ${details.shortfall_after_eligible_eviction}).`;
+    return new ExpectedError("hot_capacity", `${prefix} The live file was not changed. Shorten the content, delete a bullet, use SQLite, or adjust priority.`, details);
+  }
+
+  /** Normalize manual edits; preserve a backup before any automatic capacity repair. */
+  async load(): Promise<HotSnapshot> {
+    return this.locked(async () => {
+      const original = await this.read();
+      const previous = original ?? "";
+      const entries = parse(previous);
+      const archived: HotMemory[] = [];
+      while (serialize(entries).length > HOT_LIMIT) {
+        const victim = entries.reduce((a, b) => b.priority < a.priority ? b : a);
+        archived.push(victim);
+        entries.splice(entries.indexOf(victim), 1);
+      }
+      let backup: string | undefined;
+      if (archived.length) {
+        const backups = join(dirname(this.path), "backups");
+        await mkdir(backups, { recursive: true, mode: 0o700 });
+        backup = join(backups, `MEMORY-${Date.now()}-${randomUUID()}.md`);
+        await writeFile(backup, previous, { flag: "wx", mode: 0o600, flush: true });
+        this.archive(archived);
+      }
+      const result = this.snapshot(entries, archived, backup);
+      // Ensure a real file exists even when the store is empty.
+      if (result.text !== previous || original === undefined) await atomicWrite(this.path, result.text);
+      return result;
+    });
+  }
+
+  async add(content: string, priority = 50, signal?: AbortSignal): Promise<HotAddResult> {
+    const normalized = singleLine(content);
+    const requested = integer(priority, "priority", 0, 100);
+    return this.locked(async () => {
+      const entries = parse((await this.read()) ?? "");
+      const existing = entries.find((entry) => entry.content === normalized);
+      if (existing) {
+        // An oversized live state must not be reported as a successful snapshot.
+        if (serialize(entries).length > HOT_LIMIT) throw this.capacityError("existing_over_limit", "add", entries, entries, existing);
+        return {
+          ...this.snapshot(entries, []), memory: existing, created: false,
+          note: `Reused existing hot memory ${existing.id}; its content, priority ${existing.priority}, and file position were preserved. Use memoria_edit to change its content or priority.`,
+        };
+      }
+      const entry: HotMemory = { id: `h_${randomUUID().replaceAll("-", "").slice(0, 16)}`, priority: requested, content: normalized };
+      return { ...await this.commit(entries, entry, undefined, "add", signal), created: true };
+    }, signal);
+  }
+
+  async edit(id: string, content?: string, priority?: number, expectedContent?: string, signal?: AbortSignal): Promise<HotEditResult> {
+    const normalized = content === undefined ? undefined : singleLine(content);
+    const requested = priority === undefined ? undefined : integer(priority, "priority", 0, 100);
+    return this.locked(async () => {
+      const entries = parse((await this.read()) ?? "");
+      const index = entries.findIndex((entry) => entry.id === id);
+      if (index === -1) throw new ExpectedError("not_found", `Hot memory ${id} does not exist. Read MEMORY.md again.`, { id });
+      const previous = entries[index]!;
+      if (expectedContent !== undefined && previous.content !== expectedContent) {
+        throw new ExpectedError("conflict", `Hot memory ${id} changed (stored content differs from expected_content). Read MEMORY.md again before editing.`, { id, expected_content: expectedContent, current_content: previous.content });
+      }
+      const entry: HotMemory = { id, content: normalized ?? previous.content, priority: requested ?? previous.priority };
+      if (normalized !== undefined && normalized !== previous.content) {
+        const duplicate = entries.find((item) => item.id !== id && item.content === normalized);
+        if (duplicate) {
+          throw new ExpectedError("duplicate_hot_content", `Edit rejected: setting ${id} to that content would duplicate hot memory ${duplicate.id}. Neither entry was changed; keep one entry or choose distinct content.`, { id, existing_id: duplicate.id });
+        }
+      }
+      return this.commit(entries, entry, index, "edit", signal);
+    }, signal);
+  }
+
+  private async commit(entriesBefore: HotMemory[], entry: HotMemory, index: number | undefined, operation: string, signal?: AbortSignal): Promise<HotEditResult> {
+    signal?.throwIfAborted();
+    const proposed = index === undefined ? [...entriesBefore, entry] : entriesBefore.map((item, current) => current === index ? entry : item);
+    if (serialize([entry]).length > HOT_LIMIT) throw this.capacityError("bullet_too_large", operation, entriesBefore, proposed, entry);
+    const entries = proposed.slice();
+    const archived: HotMemory[] = [];
+    if (serialize(entries).length > HOT_LIMIT) {
+      const candidates = entriesBefore.filter((item) => item.id !== entry.id && item.priority < entry.priority).sort((a, b) => a.priority - b.priority);
+      while (serialize(entries).length > HOT_LIMIT) {
+        const victim = candidates.shift();
+        if (!victim) throw this.capacityError("cannot_free_space", operation, entriesBefore, proposed, entry);
+        archived.push(victim);
+        entries.splice(entries.indexOf(victim), 1);
+      }
+    }
+    if (archived.length) this.archive(archived);
+    const result = this.snapshot(entries, archived);
+    await atomicWrite(this.path, result.text);
+    return { ...result, memory: entry };
+  }
+
+  async delete(id: string, expectedContent?: string, signal?: AbortSignal): Promise<HotDeleteResult> {
+    return this.locked(async () => {
+      const entries = parse((await this.read()) ?? "");
+      const index = entries.findIndex((entry) => entry.id === id);
+      if (index === -1) throw new ExpectedError("not_found", `Hot memory ${id} does not exist.`, { id });
+      const deleted = entries[index]!;
+      if (expectedContent !== undefined && deleted.content !== expectedContent) {
+        throw new ExpectedError("conflict", `Hot memory ${id} changed (stored content differs from expected_content). Read MEMORY.md again before deleting.`, { id, expected_content: expectedContent, current_content: deleted.content });
+      }
+      entries.splice(index, 1);
+      const result = this.snapshot(entries, []);
+      await atomicWrite(this.path, result.text);
+      return { ...result, deleted };
+    }, signal);
+  }
+}