shariq-pi-extensions 0.1.0

package/extensions/pi-memory/src/extraction.ts

@@ -0,0 +1,178 @@
+import { uuidv7, type Api, type Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MemoryModelConfig } from "./config.ts";
+import type { MemoryDatabase } from "./database.ts";
+import type { CaptureJob, MemoryCandidate, MemoryKind, MemoryRecord } from "./types.ts";
+import { MEMORY_KINDS } from "./types.ts";
+
+const KIND_SET = new Set<string>(MEMORY_KINDS);
+const FORMER_AGENT_REFERENCE = /\b(?:codex|grok)\b|\.(?:codex|grok)(?:\/|\\)/i;
+
+function responseText(content: Array<{ type: string; text?: string }>): string {
+  return content.filter((part) => part.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n");
+}
+
+function parseJsonArray(text: string): unknown[] {
+  const stripped = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  const start = stripped.indexOf("[");
+  const end = stripped.lastIndexOf("]");
+  if (start < 0 || end < start) throw new Error("memory extractor returned no JSON array");
+  const parsed: unknown = JSON.parse(stripped.slice(start, end + 1));
+  if (!Array.isArray(parsed)) throw new Error("memory extractor output was not an array");
+  return parsed;
+}
+
+function finiteNumber(value: unknown, fallback: number, min: number, max: number): number {
+  return typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+
+export function validateCandidates(raw: unknown[], options: {
+  evidenceIds: ReadonlySet<string>;
+  targetIds: ReadonlySet<string>;
+}): MemoryCandidate[] {
+  const candidates: MemoryCandidate[] = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) continue;
+    const value = item as Record<string, unknown>;
+    const operation = ["add", "update", "supersede", "ignore"].includes(String(value.operation))
+      ? String(value.operation) as MemoryCandidate["operation"] : "add";
+    const scope = value.scope === "global" ? "global" : value.scope === "project" ? "project" : undefined;
+    const kind = KIND_SET.has(String(value.kind)) ? String(value.kind) as MemoryKind : undefined;
+    const title = typeof value.title === "string" ? value.title.trim().slice(0, 160) : "";
+    const content = typeof value.content === "string" ? value.content.trim().slice(0, 4_000) : "";
+    if (!scope || !kind || !title || !content || FORMER_AGENT_REFERENCE.test(`${title}\n${content}`)) continue;
+    const targetId = typeof value.targetId === "string" && options.targetIds.has(value.targetId) ? value.targetId : undefined;
+    if ((operation === "update" || operation === "supersede") && !targetId) continue;
+    const tags = Array.isArray(value.tags)
+      ? [...new Set(value.tags.filter((tag): tag is string => typeof tag === "string").map((tag) => tag.trim().toLowerCase()).filter(Boolean))].slice(0, 16)
+      : [];
+    const evidenceEntryIds = Array.isArray(value.evidenceEntryIds)
+      ? value.evidenceEntryIds.filter((id): id is string => typeof id === "string" && options.evidenceIds.has(id)).slice(0, 20)
+      : [];
+    candidates.push({
+      operation,
+      ...(targetId ? { targetId } : {}),
+      scope,
+      kind,
+      title,
+      content,
+      tags,
+      importance: Math.round(finiteNumber(value.importance, 3, 1, 5)),
+      confidence: finiteNumber(value.confidence, 0.75, 0, 1),
+      evidenceEntryIds,
+    });
+  }
+  return candidates.slice(0, 24);
+}
+
+function relatedMemoryText(memories: MemoryRecord[]): string {
+  if (memories.length === 0) return "(none)";
+  return memories.map((memory) => [
+    `ID: ${memory.memoryId}`,
+    `Scope: ${memory.scope}${memory.projectId ? ` (${memory.projectId})` : ""}`,
+    `Kind: ${memory.kind}`,
+    `Title: ${memory.title}`,
+    `Content: ${memory.content}`,
+  ].join("\n")).join("\n\n---\n\n");
+}
+
+function resolveModel(ctx: Pick<ExtensionContext, "modelRegistry">, configured: MemoryModelConfig): Model<Api> | undefined {
+  return ctx.modelRegistry.find(configured.provider, configured.model);
+}
+
+export async function extractJob(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  database: MemoryDatabase,
+  job: CaptureJob,
+  options: { model: MemoryModelConfig; maxOutputTokens: number; signal?: AbortSignal; authorizeApply: () => boolean },
+): Promise<number> {
+  const model = resolveModel(ctx, options.model);
+  if (!model) throw new Error(`${options.model.provider}/${options.model.model} is unavailable for memory extraction`);
+
+  const related = database.search(job.payload.queryText || job.payload.transcript.slice(-8_000), job.projectId, 16);
+  const allowedTargets = new Set(related.map((memory) => memory.memoryId));
+  const evidenceIds = new Set(job.payload.entryIds);
+  const prompt = `You extract durable memory from work performed inside Pi.
+
+Return ONLY a JSON array. Never include markdown fences or commentary.
+
+A durable memory must help in a future session. Keep:
+- explicit user preferences and standing constraints;
+- project conventions and architecture decisions;
+- verified facts that remain useful beyond this turn;
+- reusable solutions, warnings, and failure lessons.
+
+Do NOT keep:
+- secrets, credentials, tokens, cookies, private keys, or sensitive raw values;
+- transient task status, todos, progress narration, or one-off command output;
+- guesses, assistant proposals the user did not accept, duplicated facts, or information contradicted later;
+- raw transcript, hidden reasoning, or generic advice;
+- former-agent names, paths, commands, thread mechanics, runtime behavior, or migration details that do not apply to Pi.
+
+When a harness-independent lesson remains useful, express it in Pi-native or general terms without naming the former agent. If that would make the statement inaccurate, omit it.
+
+Scope rules:
+- global: stable cross-project user preferences only;
+- project: facts, conventions, decisions, and solutions specific to this project.
+
+Compare against RELATED MEMORIES. Use:
+- add: genuinely new durable memory;
+- update: same durable memory should be clarified in place;
+- supersede: a newer decision or correction replaces the target;
+- ignore: omit it from the returned array instead.
+Only target an exact ID listed below. Prefer one atomic fact per item.
+
+Each array item must be:
+{"operation":"add|update|supersede","targetId":"required for update/supersede","scope":"global|project","kind":"preference|decision|convention|fact|solution|warning|reference","title":"short label","content":"self-contained durable statement","tags":["search","terms"],"importance":1,"confidence":0.0,"evidenceEntryIds":["entry id"]}
+Importance is 1-5. Confidence is 0-1. Evidence IDs must come from the transcript labels.
+
+PROJECT
+ID: ${job.payload.project.id}
+Name: ${job.payload.project.displayName}
+Root: ${job.payload.project.rootPath}
+Identity: ${job.payload.project.identity}
+
+RELATED MEMORIES
+${relatedMemoryText(related)}
+
+PI SESSION DELTA
+${job.payload.transcript}`;
+
+  const response = await ctx.modelRegistry.complete(
+    model,
+    { messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }] },
+    {
+      maxTokens: options.maxOutputTokens,
+      reasoning: options.model.reasoning,
+      signal: options.signal,
+      cacheRetention: "none",
+      sessionId: uuidv7(),
+    },
+  );
+  const candidates = validateCandidates(parseJsonArray(responseText(response.content)), {
+    evidenceIds,
+    targetIds: allowedTargets,
+  });
+
+  if (!options.authorizeApply()) throw new Error("memory job lease was lost before apply");
+
+  let applied = 0;
+  for (const candidate of candidates) {
+    if (candidate.operation === "ignore") continue;
+    const { operation: _operation, targetId: _targetId, ...data } = candidate;
+    const target = candidate.targetId ? database.getMemory(candidate.targetId) : undefined;
+    if (target) {
+      data.scope = target.scope;
+      data.kind = target.kind;
+    }
+    if (candidate.operation === "update" && candidate.targetId && target) {
+      if (database.updateMemory(candidate.targetId, data, target.projectId, "pi-session", job.payload.sessionFile)) applied += 1;
+    } else if (candidate.operation === "supersede" && candidate.targetId && target) {
+      if (database.supersedeMemory(candidate.targetId, data, target.projectId, "pi-session", job.payload.sessionFile)) applied += 1;
+    } else {
+      database.addMemory({ candidate: data, projectId: job.projectId, sourceKind: "pi-session", sourceRef: job.payload.sessionFile });
+      applied += 1;
+    }
+  }
+  return applied;
+}

package/extensions/pi-memory/src/project.ts

@@ -0,0 +1,80 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import type { ProjectIdentity } from "./types.ts";
+
+function runGit(cwd: string, args: string[], preserveWhitespace = false): string | undefined {
+  try {
+    const output = execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 2_000,
+    }).replace(/\r?\n$/, "");
+    const normalized = preserveWhitespace ? output : output.trim();
+    return normalized || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeRemoteUrl(value: string): string | undefined {
+  const trimmed = value.trim().replace(/\.git$/i, "").replace(/\/$/, "");
+  if (!trimmed) return undefined;
+
+  const scp = trimmed.match(/^[^@\s]+@([^:\s]+):(.+)$/);
+  if (scp) return `${scp[1]!.toLowerCase()}/${scp[2]!.replace(/^\/+/, "")}`;
+
+  try {
+    const url = new URL(trimmed);
+    const pathname = url.pathname.replace(/^\/+/, "");
+    if (!url.hostname || !pathname) return undefined;
+    return `${url.hostname.toLowerCase()}/${pathname}`;
+  } catch {
+    return undefined;
+  }
+}
+
+function slugify(value: string): string {
+  const slug = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return slug || "workspace";
+}
+
+export function resolveProject(cwd: string): ProjectIdentity {
+  const canonicalCwd = fs.realpathSync.native(cwd);
+  const gitRoot = runGit(canonicalCwd, ["rev-parse", "--show-toplevel"], true);
+  const canonicalRoot = gitRoot && fs.existsSync(gitRoot) ? fs.realpathSync.native(gitRoot) : canonicalCwd;
+  const remote = gitRoot ? runGit(canonicalRoot, ["config", "--get", "remote.origin.url"]) : undefined;
+  const normalizedRemote = remote ? normalizeRemoteUrl(remote) : undefined;
+  const identity = normalizedRemote ? `git:${normalizedRemote}` : `path:${canonicalRoot}`;
+  const hash = crypto.createHash("sha256").update(identity).digest("hex").slice(0, 12);
+  const displayName = path.basename(canonicalRoot) || "workspace";
+  return {
+    id: hash,
+    identity,
+    rootPath: canonicalRoot,
+    displayName,
+    directoryName: `${slugify(displayName)}-${hash.slice(0, 8)}`,
+  };
+}
+
+export function isEphemeralProject(project: ProjectIdentity): boolean {
+  const roots = [os.tmpdir()];
+  if (process.platform !== "win32") roots.push("/tmp", "/private/tmp", "/var/tmp");
+  return roots.some((temporaryRoot) => {
+    let canonicalTemporaryRoot: string;
+    try {
+      canonicalTemporaryRoot = fs.realpathSync.native(temporaryRoot);
+    } catch {
+      canonicalTemporaryRoot = path.resolve(temporaryRoot);
+    }
+    const relative = path.relative(canonicalTemporaryRoot, path.resolve(project.rootPath));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+  });
+}

package/extensions/pi-memory/src/projection.ts

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { MemoryDatabase } from "./database.ts";
+import type { MemoryRecord, ProjectIdentity } from "./types.ts";
+
+function render(title: string, memories: MemoryRecord[]): string {
+  const lines = [
+    `# ${title}`,
+    "",
+    "<!-- Generated from pi-memory's SQLite database. Use Pi memory tools to edit durable memory. -->",
+    "",
+  ];
+  if (memories.length === 0) {
+    lines.push("_No durable memories yet._", "");
+    return lines.join("\n");
+  }
+  const groups = new Map<string, MemoryRecord[]>();
+  for (const memory of memories) {
+    const group = groups.get(memory.kind) ?? [];
+    group.push(memory);
+    groups.set(memory.kind, group);
+  }
+  for (const [kind, records] of groups) {
+    lines.push(`## ${kind[0]!.toUpperCase()}${kind.slice(1)}`, "");
+    for (const memory of records) {
+      lines.push(`### ${memory.title}`, "", memory.content, "", `<!-- id:${memory.memoryId} confidence:${memory.confidence.toFixed(2)} importance:${memory.importance} -->`, "");
+    }
+  }
+  return lines.join("\n");
+}
+
+function atomicWrite(file: string, content: string): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, content, { encoding: "utf8", mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+export function writeProjections(database: MemoryDatabase, root: string): void {
+  atomicWrite(path.join(root, "global", "MEMORY.md"), render("Global Memory", database.listActive("global", null)));
+  const projects = database.listProjects();
+  for (const project of projects) writeProjectProjection(database, root, project);
+
+  const projectsRoot = path.join(root, "projects");
+  const expected = new Set(projects.map((project) => project.directoryName));
+  if (!fs.existsSync(projectsRoot)) return;
+  for (const entry of fs.readdirSync(projectsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || expected.has(entry.name)) continue;
+    const projection = path.join(projectsRoot, entry.name, "MEMORY.md");
+    if (!fs.existsSync(projection)) continue;
+    fs.rmSync(projection);
+    try { fs.rmdirSync(path.dirname(projection)); } catch {}
+  }
+}
+
+export function writeProjectProjection(database: MemoryDatabase, root: string, project: ProjectIdentity): void {
+  const memories = database.listActive("project", project.id);
+  atomicWrite(path.join(root, "projects", project.directoryName, "MEMORY.md"), render(`Project Memory — ${project.displayName}`, memories));
+}

package/extensions/pi-memory/src/redaction.ts

@@ -0,0 +1,60 @@
+import path from "node:path";
+
+const SENSITIVE_PATH_PARTS = new Set([
+  ".env",
+  "auth.json",
+  "credentials",
+  "credential",
+  "secrets",
+  "secret",
+  "keychain",
+  ".ssh",
+  ".aws",
+  ".gnupg",
+]);
+
+const CREDENTIAL_NAME = "(?:api[_-]?key|apiKey|access[_-]?token|accessToken|refresh[_-]?token|refreshToken|auth(?:orization)?|password|passwd|secret|cookie|session[_-]?token|sessionToken|aws[_-]?secret[_-]?access[_-]?key|aws[_-]?access[_-]?key[_-]?id|client[_-]?secret|clientSecret|private[_-]?key|privateKey|database[_-]?url|databaseUrl|connection[_-]?string|connectionString|dsn)";
+
+const REDACTIONS: Array<[RegExp, string]> = [
+  [/\b([a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:)[^\s/@]+@/gi, "$1<redacted>@"],
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi, "Bearer <redacted>"],
+  [new RegExp(`(\\b${CREDENTIAL_NAME}\\b\\s*[:=]\\s*)(["'])(.*?)\\2`, "gi"), "$1$2<redacted>$2"],
+  [new RegExp(`(\\b${CREDENTIAL_NAME}\\b\\s*[:=]\\s*)[^\\r\\n,;]+`, "gi"), "$1<redacted>"],
+  [/\b(?:sk|pk|rk|ghp|github_pat|xox[baprs]|AIza)[-_A-Za-z0-9]{12,}\b/g, "<redacted-token>"],
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "<redacted-private-key>"],
+  [/\b[A-Za-z0-9+/]{40,}={0,2}\b/g, "<redacted-opaque-value>"],
+];
+
+export function redactSecrets(value: string): string {
+  let result = value;
+  for (const [pattern, replacement] of REDACTIONS) result = result.replace(pattern, replacement);
+  return result;
+}
+
+export function isSensitivePath(value: string): boolean {
+  const normalized = value.toLowerCase().replaceAll("\\", "/");
+  return normalized.split("/").some((part) => SENSITIVE_PATH_PARTS.has(part))
+    || /(?:^|\/)\.env(?:\.|$)/.test(normalized)
+    || /(?:^|\/)(?:id_rsa|id_ed25519|known_hosts)(?:$|\/)/.test(normalized);
+}
+
+export function hasSensitiveToolArguments(toolName: string, input: unknown): boolean {
+  if (!["read", "write", "edit"].includes(toolName)) return false;
+  const possiblePath = typeof input === "object" && input !== null && "path" in input
+    ? String((input as { path?: unknown }).path ?? "")
+    : "";
+  return Boolean(possiblePath && isSensitivePath(path.normalize(possiblePath)));
+}
+
+export function sanitizeToolArguments(toolName: string, input: unknown): string {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(input);
+  } catch {
+    return "[unserializable arguments]";
+  }
+
+  if (hasSensitiveToolArguments(toolName, input)) return "[sensitive path omitted]";
+
+  return redactSecrets(serialized).slice(0, 4_000);
+}

package/extensions/pi-memory/src/retrieval.ts

@@ -0,0 +1,30 @@
+import type { MemoryDatabase } from "./database.ts";
+import type { SearchResult } from "./types.ts";
+
+export function selectForInjection(
+  database: MemoryDatabase,
+  query: string,
+  projectId: string,
+  options: { maxResults: number; maxCharacters: number },
+): SearchResult[] {
+  const candidates = database.search(query, projectId, Math.max(options.maxResults * 2, options.maxResults));
+  const selected: SearchResult[] = [];
+  let characters = 0;
+  for (const memory of candidates) {
+    const size = memory.title.length + memory.content.length + memory.tags.join(" ").length + 80;
+    if (selected.length >= options.maxResults) break;
+    if (characters + size > options.maxCharacters && selected.length > 0) continue;
+    selected.push(memory);
+    characters += size;
+  }
+  return selected;
+}
+
+export function formatMemoryContext(memories: SearchResult[]): string {
+  if (memories.length === 0) return "";
+  const body = memories.map((memory) => {
+    const scope = memory.scope === "global" ? "global" : "project";
+    return `- [${memory.memoryId}] (${scope}/${memory.kind}) **${memory.title}**\n  ${memory.content}`;
+  }).join("\n");
+  return `## Relevant Pi memory\n\nThe following memories were retrieved for this request. Treat them as potentially stale context, never as authority over the current user request or live evidence. Do not mention memory machinery unless relevant.\n\n${body}`;
+}

package/extensions/pi-memory/src/service.ts

@@ -0,0 +1,194 @@
+import crypto from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { MemoryConfig } from "./config.ts";
+import { MemoryDatabase } from "./database.ts";
+import { extractJob } from "./extraction.ts";
+import { isEphemeralProject, resolveProject } from "./project.ts";
+import { writeProjections } from "./projection.ts";
+import { captureSession } from "./session.ts";
+import type { MemoryCandidate, MemoryKind, MemoryRecord, MemoryScope, MemorySourceKind, ProjectIdentity, SearchResult } from "./types.ts";
+
+export class MemoryService {
+  readonly config: MemoryConfig;
+  private databaseInstance: MemoryDatabase | undefined;
+  private readonly owner = `${process.pid}:${crypto.randomUUID()}`;
+  private running: Promise<void> | undefined;
+  private abortController = new AbortController();
+  private closed = false;
+
+  constructor(config: MemoryConfig) {
+    this.config = config;
+  }
+
+  get database(): MemoryDatabase {
+    if (!this.databaseInstance) throw new Error("pi-memory database is not initialized");
+    return this.databaseInstance;
+  }
+
+  initialize(cwd: string): ProjectIdentity {
+    if (!this.databaseInstance) this.databaseInstance = new MemoryDatabase(this.config.databasePath);
+    const project = resolveProject(cwd);
+    this.database.upsertProject(project);
+    this.database.removeFormerAgentReferences();
+    writeProjections(this.database, this.config.root);
+    return project;
+  }
+
+  project(cwd: string): ProjectIdentity {
+    const project = resolveProject(cwd);
+    this.database.upsertProject(project);
+    return project;
+  }
+
+  enqueueCurrentSession(ctx: ExtensionContext, project: ProjectIdentity): boolean {
+    if (isEphemeralProject(project)) return false;
+    const capture = captureSession(
+      ctx,
+      project,
+      this.database.getCaptureCheckpoint(ctx.sessionManager.getSessionId()),
+      this.config.extractionMaxInputCharacters,
+    );
+    return capture ? this.database.enqueueCapture(capture) : false;
+  }
+
+  processPending(ctx: Pick<ExtensionContext, "model" | "modelRegistry">, maxJobs = 1): Promise<void> {
+    if (this.closed) return Promise.resolve();
+    if (this.running) return this.running;
+    this.running = this.runJobs(ctx, maxJobs)
+      .catch(() => {})
+      .finally(() => { this.running = undefined; });
+    return this.running;
+  }
+
+  private async runJobs(ctx: Pick<ExtensionContext, "model" | "modelRegistry">, maxJobs: number): Promise<void> {
+    for (let processed = 0; processed < maxJobs && !this.abortController.signal.aborted; processed += 1) {
+      const job = this.database.claimNextJob(this.owner, this.config.jobLeaseMs, this.config.maxJobAttempts);
+      if (!job) return;
+      const jobAbort = new AbortController();
+      const signal = AbortSignal.any([this.abortController.signal, jobAbort.signal]);
+      const heartbeat = setInterval(() => {
+        if (!this.database.renewJobLease(job.id, this.owner, this.config.jobLeaseMs)) jobAbort.abort();
+      }, Math.max(5_000, Math.floor(this.config.jobLeaseMs / 3)));
+      heartbeat.unref();
+      try {
+        await extractJob(ctx, this.database, job, {
+          model: { ...this.config.extractionModel },
+          maxOutputTokens: this.config.extractionMaxOutputTokens,
+          signal,
+          authorizeApply: () => this.database.renewJobLease(job.id, this.owner, this.config.jobLeaseMs),
+        });
+        if (this.database.completeJob(job, this.owner)) writeProjections(this.database, this.config.root);
+      } catch (error) {
+        if (this.abortController.signal.aborted) {
+          this.database.failJob(job, this.owner, "memory extraction cancelled during shutdown", this.config.maxJobAttempts);
+          return;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        this.database.failJob(job, this.owner, message, this.config.maxJobAttempts);
+      } finally {
+        clearInterval(heartbeat);
+      }
+    }
+  }
+
+  search(query: string, projectId: string, limit = this.config.maxSearchResults): SearchResult[] {
+    return this.database.search(query, projectId, limit);
+  }
+
+  save(input: {
+    scope: MemoryScope;
+    project: ProjectIdentity;
+    kind: MemoryKind;
+    title: string;
+    content: string;
+    tags?: string[];
+    importance?: number;
+    confidence?: number;
+    sourceKind?: MemorySourceKind;
+    sourceRef?: string;
+  }): MemoryRecord {
+    const candidate: Omit<MemoryCandidate, "operation" | "targetId"> = {
+      scope: input.scope,
+      kind: input.kind,
+      title: input.title.trim().slice(0, 160),
+      content: input.content.trim().slice(0, 4_000),
+      tags: [...new Set(input.tags ?? [])].slice(0, 16),
+      importance: Math.min(5, Math.max(1, Math.round(input.importance ?? 4))),
+      confidence: Math.min(1, Math.max(0, input.confidence ?? 1)),
+      evidenceEntryIds: [],
+    };
+    if (!candidate.title || !candidate.content) throw new Error("title and content are required");
+    const memory = this.database.addMemory({
+      candidate,
+      projectId: input.scope === "project" ? input.project.id : null,
+      sourceKind: input.sourceKind ?? "manual",
+      sourceRef: input.sourceRef ?? "manual",
+    });
+    writeProjections(this.database, this.config.root);
+    return memory;
+  }
+
+  correct(memoryId: string, input: {
+    project: ProjectIdentity;
+    title?: string;
+    content?: string;
+    tags?: string[];
+    importance?: number;
+    confidence?: number;
+  }): MemoryRecord | undefined {
+    const existing = this.database.getMemory(memoryId);
+    if (!existing || existing.status !== "active") return undefined;
+    const candidate: Omit<MemoryCandidate, "operation" | "targetId"> = {
+      scope: existing.scope,
+      kind: existing.kind,
+      title: input.title?.trim().slice(0, 160) || existing.title,
+      content: input.content?.trim().slice(0, 4_000) || existing.content,
+      tags: input.tags ? [...new Set(input.tags)].slice(0, 16) : existing.tags,
+      importance: Math.min(5, Math.max(1, Math.round(input.importance ?? existing.importance))),
+      confidence: Math.min(1, Math.max(0, input.confidence ?? existing.confidence)),
+      evidenceEntryIds: existing.sourceEntryIds,
+    };
+    const updated = this.database.updateMemory(memoryId, candidate, existing.projectId ?? input.project.id, "manual", "manual-correction");
+    writeProjections(this.database, this.config.root);
+    return updated;
+  }
+
+  forget(memoryId: string): boolean {
+    const changed = this.database.forgetMemory(memoryId);
+    if (changed) writeProjections(this.database, this.config.root);
+    return changed;
+  }
+
+  review(projectId: string, limit = 30): MemoryRecord[] {
+    const global = this.database.listActive("global", null, limit);
+    const project = this.database.listActive("project", projectId, limit);
+    return [...global, ...project]
+      .sort((a, b) => b.importance - a.importance || b.updatedAt - a.updatedAt)
+      .slice(0, limit);
+  }
+
+  rebuild(): void {
+    this.database.rebuildSearchIndex();
+    writeProjections(this.database, this.config.root);
+  }
+
+  status() {
+    return {
+      memories: this.database.countMemories(),
+      jobs: this.database.countJobs(),
+      projects: this.database.listProjects().length,
+      root: this.config.root,
+      database: this.config.databasePath,
+      extractionModel: { ...this.config.extractionModel },
+    };
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.abortController.abort();
+    await this.running?.catch(() => {});
+    this.databaseInstance?.close();
+    this.databaseInstance = undefined;
+  }
+}