@iamem/amem 0.1.0

package/dist/context.d.ts

@@ -0,0 +1,46 @@
+import { type ClaimRow, type ComponentRow, type ConversationNoteRow, type FlowRow, type UsageEventRow } from "./db.js";
+import { type ClaimFreshness } from "./freshness.js";
+export type RankedClaim = ClaimRow & {
+    score: number;
+    freshness: ClaimFreshness;
+    /** Human-readable ranking factors for "why was this injected?" */
+    reasons: string[];
+};
+export type ContextPacket = {
+    query: string;
+    claims: RankedClaim[];
+    flows: FlowRow[];
+    components: ComponentRow[];
+    notes: Array<ConversationNoteRow & {
+        score: number;
+    }>;
+};
+export type BuildContextOptions = {
+    limit?: number;
+    rootPath?: string;
+    /** Include cross-repo personal prefs (default true). */
+    includePersonal?: boolean;
+};
+export declare function buildContext(repoId: string, query: string, limitOrOpts?: number | BuildContextOptions): ContextPacket;
+export type ShowdownClaim = {
+    id: string;
+    kind: string;
+    text: string;
+    score: number;
+    reasons: string[];
+};
+export type RetrievalShowdown = {
+    query: string;
+    free: ShowdownClaim[];
+    pro: ShowdownClaim[];
+    proLocked: boolean;
+    proOnlyIds: string[];
+    freeOnlyIds: string[];
+};
+/** Side-by-side free hash vs Pro n-gram retrieval for the same query. */
+export declare function buildRetrievalShowdown(repoId: string, query: string, limitOrOpts?: number | BuildContextOptions): RetrievalShowdown;
+/** Keyword match only. Fallback packets (score 0) are misses — the model call still happens. */
+export declare function classifyLookup(query: string, claims: ClaimRow[]): "local_hit" | "server_trip";
+export declare function decorateUsageEvent(e: UsageEventRow, claims: ClaimRow[]): UsageEventRow;
+export declare function decorateUsageEvents(events: UsageEventRow[]): UsageEventRow[];
+export declare function renderContextMarkdown(packet: ContextPacket): string;

package/dist/context.js

@@ -0,0 +1,334 @@
+import { getRepoByName, listClaims, listComponents, listConversationNotes, listEdges, listFlows, openDb, } from "./db.js";
+import { assessClaimFreshness, freshnessScoreMultiplier, } from "./freshness.js";
+import { kindRankBoost } from "./kinds.js";
+import { ftsBoostFromBm25, keywordScoreClaim, searchClaimsFts, tokenize, } from "./search.js";
+import { embedBoostFromScore, searchClaimsEmbed, searchClaimsEmbedLive } from "./embed.js";
+import { FEATURE_LOCAL_EMBED, hasFeature } from "./license.js";
+import { PERSONAL_SLUG } from "./personal.js";
+function scoreNote(note, queryTokens) {
+    if (queryTokens.length === 0)
+        return 0;
+    const hay = note.text.toLowerCase();
+    let score = 0;
+    for (const token of queryTokens) {
+        if (hay.includes(token))
+            score += token.length > 4 ? 3 : 2;
+    }
+    return score;
+}
+function rankClaims(claims, query, queryTokens, opts) {
+    return claims.map((c) => {
+        const freshness = assessClaimFreshness(opts.rootPath, c);
+        const keyword = keywordScoreClaim(c, queryTokens);
+        const boost = opts.ftsBoost.get(c.id) ?? 0;
+        const embed = opts.embedBoost.get(c.id) ?? 0;
+        const pinBoost = (c.pinned ?? 0) > 0 ? 40 : 0;
+        const kindBoost = kindRankBoost(c.kind);
+        const matchSignal = keyword + boost + embed + pinBoost;
+        const reasons = [];
+        if (opts.extraReason)
+            reasons.push(opts.extraReason);
+        if (keyword > 0)
+            reasons.push(`keyword+${keyword}`);
+        if (boost > 0)
+            reasons.push(`fts+${boost.toFixed(1)}`);
+        if (embed > 0)
+            reasons.push(`embed+${embed.toFixed(1)}`);
+        if (pinBoost > 0)
+            reasons.push("pinned");
+        if (matchSignal > 0 && kindBoost >= 8)
+            reasons.push(`kind:${c.kind}`);
+        if (freshness.status === "stale")
+            reasons.push("stale↓");
+        else if (freshness.status === "fresh" && matchSignal > 0)
+            reasons.push("fresh");
+        const raw = matchSignal > 0 ? matchSignal + kindBoost * 0.35 : 0;
+        const withFloor = raw > 0
+            ? Math.max(raw, boost > 0 || embed > 0 ? boost + embed + pinBoost + kindBoost * 0.35 : raw)
+            : 0;
+        const score = withFloor * freshnessScoreMultiplier(freshness.status);
+        if (score > 0 && reasons.length === 0)
+            reasons.push("rank");
+        return { ...c, score, freshness, reasons };
+    });
+}
+export function buildContext(repoId, query, limitOrOpts = 12) {
+    const opts = typeof limitOrOpts === "number" ? { limit: limitOrOpts } : limitOrOpts;
+    const limit = opts.limit ?? 12;
+    const rootPath = opts.rootPath;
+    const includePersonal = opts.includePersonal !== false;
+    const queryTokens = tokenize(query);
+    const db = openDb();
+    const allActive = listClaims(repoId);
+    const ftsHits = searchClaimsFts(db, repoId, query, Math.max(limit * 2, 24));
+    const ftsBoost = new Map();
+    for (const hit of ftsHits) {
+        ftsBoost.set(hit.id, ftsBoostFromBm25(hit.bm25));
+    }
+    const embedHits = searchClaimsEmbed(db, repoId, query, Math.max(limit * 2, 24));
+    const embedBoost = new Map();
+    for (const hit of embedHits) {
+        embedBoost.set(hit.id, embedBoostFromScore(hit.score));
+    }
+    const scored = rankClaims(allActive, query, queryTokens, {
+        rootPath,
+        ftsBoost,
+        embedBoost,
+    })
+        .filter((c) => (queryTokens.length === 0 ? true : c.score > 0))
+        .sort((a, b) => b.score - a.score || b.updated_at.localeCompare(a.updated_at));
+    // If no keyword/FTS/embed hits, return newest fresh-leaning claims as weak fallback
+    let selected = scored.length > 0
+        ? scored.slice(0, limit)
+        : allActive.slice(0, Math.min(5, limit)).map((c) => {
+            const freshness = assessClaimFreshness(rootPath, c);
+            const reasons = ["fallback:recent"];
+            if ((c.pinned ?? 0) > 0)
+                reasons.unshift("pinned");
+            return { ...c, score: 0, freshness, reasons };
+        });
+    // Blend a few personal-prefs claims into project context (not org wiki).
+    if (includePersonal) {
+        const personal = getRepoByName(PERSONAL_SLUG);
+        if (personal && personal.id !== repoId) {
+            const personalClaims = listClaims(personal.id).filter((c) => c.id !== "claim.personal_scope");
+            if (personalClaims.length > 0) {
+                const pFts = new Map();
+                for (const hit of searchClaimsFts(db, personal.id, query, 12)) {
+                    pFts.set(hit.id, ftsBoostFromBm25(hit.bm25));
+                }
+                const pEmbed = new Map();
+                for (const hit of searchClaimsEmbed(db, personal.id, query, 12)) {
+                    pEmbed.set(hit.id, embedBoostFromScore(hit.score));
+                }
+                const personalRanked = rankClaims(personalClaims, query, queryTokens, {
+                    rootPath: personal.root_path,
+                    ftsBoost: pFts,
+                    embedBoost: pEmbed,
+                    extraReason: "personal",
+                })
+                    .filter((c) => c.score > 0)
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, 3);
+                if (personalRanked.length > 0) {
+                    const room = Math.max(1, Math.min(3, Math.floor(limit / 4) || 1));
+                    const take = personalRanked.slice(0, room);
+                    const keep = selected.slice(0, Math.max(0, limit - take.length));
+                    selected = [...keep, ...take].sort((a, b) => b.score - a.score || b.updated_at.localeCompare(a.updated_at));
+                }
+            }
+        }
+    }
+    const edges = listEdges(repoId);
+    const flowIds = new Set();
+    const componentIds = new Set();
+    for (const claim of selected) {
+        for (const e of edges) {
+            if (e.from_type === "claim" && e.from_id === claim.id && e.to_type === "flow") {
+                flowIds.add(e.to_id);
+            }
+            if (e.to_type === "claim" && e.to_id === claim.id && e.from_type === "flow") {
+                flowIds.add(e.from_id);
+            }
+        }
+    }
+    for (const flowId of flowIds) {
+        for (const e of edges) {
+            if (e.from_type === "flow" && e.from_id === flowId && e.to_type === "component") {
+                componentIds.add(e.to_id);
+            }
+            if (e.to_type === "flow" && e.to_id === flowId && e.from_type === "component") {
+                componentIds.add(e.from_id);
+            }
+        }
+    }
+    const flows = listFlows(repoId).filter((f) => flowIds.has(f.id));
+    const components = listComponents(repoId).filter((c) => componentIds.has(c.id));
+    const notesRaw = listConversationNotes(repoId, 40)
+        .map((n) => ({ ...n, score: scoreNote(n, queryTokens) }))
+        .filter((n) => (queryTokens.length === 0 ? true : n.score > 0))
+        .sort((a, b) => b.score - a.score || b.created_at.localeCompare(a.created_at))
+        .slice(0, 5);
+    const notes = notesRaw.length > 0
+        ? notesRaw
+        : listConversationNotes(repoId, 5).map((n) => ({ ...n, score: 0 }));
+    return { query, claims: selected, flows, components, notes };
+}
+function toShowdownClaims(ranked) {
+    return ranked.map((c) => ({
+        id: c.id,
+        kind: c.kind,
+        text: c.text,
+        score: Math.round(c.score * 10) / 10,
+        reasons: c.reasons,
+    }));
+}
+function rankWithLiveEmbed(claims, query, queryTokens, ftsBoost, backend, rootPath, limit) {
+    const embedBoost = new Map();
+    for (const hit of searchClaimsEmbedLive(claims, query, backend, Math.max(limit * 2, 24))) {
+        embedBoost.set(hit.id, embedBoostFromScore(hit.score));
+    }
+    return rankClaims(claims, query, queryTokens, {
+        rootPath,
+        ftsBoost,
+        embedBoost,
+        extraReason: backend === "ngram" ? "embed:ngram" : "embed:hash",
+    })
+        .filter((c) => (queryTokens.length === 0 ? true : c.score > 0))
+        .sort((a, b) => b.score - a.score || b.updated_at.localeCompare(a.updated_at))
+        .slice(0, limit);
+}
+/** Side-by-side free hash vs Pro n-gram retrieval for the same query. */
+export function buildRetrievalShowdown(repoId, query, limitOrOpts = 8) {
+    const opts = typeof limitOrOpts === "number" ? { limit: limitOrOpts } : limitOrOpts;
+    const limit = opts.limit ?? 8;
+    const rootPath = opts.rootPath;
+    const queryTokens = tokenize(query);
+    const db = openDb();
+    const allActive = listClaims(repoId);
+    const ftsBoost = new Map();
+    for (const hit of searchClaimsFts(db, repoId, query, Math.max(limit * 2, 24))) {
+        ftsBoost.set(hit.id, ftsBoostFromBm25(hit.bm25));
+    }
+    const freeRanked = rankWithLiveEmbed(allActive, query, queryTokens, ftsBoost, "hash", rootPath, limit);
+    const free = toShowdownClaims(freeRanked);
+    const proLocked = !hasFeature(FEATURE_LOCAL_EMBED);
+    let pro = [];
+    if (!proLocked) {
+        const proRanked = rankWithLiveEmbed(allActive, query, queryTokens, ftsBoost, "ngram", rootPath, limit);
+        pro = toShowdownClaims(proRanked);
+    }
+    const freeIds = new Set(free.map((c) => c.id));
+    const proIds = new Set(pro.map((c) => c.id));
+    return {
+        query,
+        free,
+        pro,
+        proLocked,
+        proOnlyIds: pro.filter((c) => !freeIds.has(c.id)).map((c) => c.id),
+        freeOnlyIds: free.filter((c) => !proIds.has(c.id)).map((c) => c.id),
+    };
+}
+function freshnessLabel(status) {
+    switch (status) {
+        case "stale":
+            return "stale";
+        case "missing_anchor":
+            return "missing_anchor";
+        default:
+            return null;
+    }
+}
+/** Keyword match only. Fallback packets (score 0) are misses — the model call still happens. */
+export function classifyLookup(query, claims) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return "server_trip";
+    return claims.some((c) => keywordScoreClaim(c, tokens) > 0) ? "local_hit" : "server_trip";
+}
+export function decorateUsageEvent(e, claims) {
+    let ids = [];
+    try {
+        ids = JSON.parse(e.claim_ids || "[]");
+    }
+    catch {
+        ids = [];
+    }
+    const subset = ids.length ? claims.filter((c) => ids.includes(c.id)) : [];
+    const kind = classifyLookup(e.query || "", subset);
+    if (kind === "local_hit")
+        return { ...e, kind };
+    return {
+        ...e,
+        kind,
+        estimated_tokens_saved: 0,
+        estimated_ms_saved: 0,
+    };
+}
+export function decorateUsageEvents(events) {
+    const cache = new Map();
+    return events.map((e) => {
+        let claims = cache.get(e.repo_id);
+        if (!claims) {
+            claims = listClaims(e.repo_id);
+            cache.set(e.repo_id, claims);
+        }
+        return decorateUsageEvent(e, claims);
+    });
+}
+export function renderContextMarkdown(packet) {
+    const lines = ["# Agent Memory Context", "", `Query: ${packet.query}`, ""];
+    if (packet.claims.length === 0 && packet.notes.length === 0) {
+        lines.push("No claims stored for this repository yet.", "");
+        lines.push("Seed memory with the `amem-bootstrap` skill or `amem propose apply <file>`.");
+        return lines.join("\n");
+    }
+    if (packet.claims.length === 0) {
+        lines.push("No durable claims yet — using recent conversation memory.", "");
+    }
+    const staleCount = packet.claims.filter((c) => c.freshness.status === "stale").length;
+    if (staleCount > 0) {
+        lines.push(`_${staleCount} claim(s) marked stale — anchored files changed after the claim was written. Verify before trusting._`, "");
+    }
+    if (packet.claims.length > 0) {
+        lines.push("## Best Claims", "");
+        for (const claim of packet.claims) {
+            lines.push(`### ${claim.id}`);
+            lines.push(`Kind: \`${claim.kind}\``);
+            if ((claim.pinned ?? 0) > 0) {
+                lines.push(`Pinned: \`yes\``);
+            }
+            const fl = freshnessLabel(claim.freshness.status);
+            if (fl) {
+                const detail = claim.freshness.staleAnchors.length > 0
+                    ? ` — ${claim.freshness.staleAnchors.map((a) => `\`${a}\``).join(", ")} changed after claim`
+                    : claim.freshness.missingAnchors.length > 0
+                        ? ` — missing ${claim.freshness.missingAnchors.map((a) => `\`${a}\``).join(", ")}`
+                        : "";
+                lines.push(`Freshness: \`${fl}\`${detail}`);
+            }
+            if (claim.reasons?.length) {
+                lines.push(`Why: ${claim.reasons.map((r) => `\`${r}\``).join(", ")}`);
+            }
+            lines.push("");
+            lines.push(claim.text);
+            lines.push("");
+            let anchors = [];
+            try {
+                anchors = JSON.parse(claim.code_anchors);
+            }
+            catch {
+                anchors = [];
+            }
+            if (anchors.length > 0) {
+                lines.push(`Anchors: ${anchors.map((a) => `\`${a}\``).join(", ")}`);
+                lines.push("");
+            }
+        }
+    }
+    if (packet.flows.length > 0) {
+        lines.push("## Related Flows", "");
+        for (const flow of packet.flows) {
+            lines.push(`- \`${flow.id}\`: ${flow.name}`);
+        }
+        lines.push("");
+    }
+    if (packet.components.length > 0) {
+        lines.push("## Related Components", "");
+        for (const component of packet.components) {
+            const anchor = component.code_anchor ? ` — \`${component.code_anchor}\`` : "";
+            lines.push(`- \`${component.id}\`: ${component.name}${anchor}`);
+        }
+        lines.push("");
+    }
+    if (packet.notes.length > 0) {
+        lines.push("## Recent conversation memory", "");
+        for (const note of packet.notes) {
+            const label = note.role === "user" ? "You asked" : note.role === "assistant" ? "Prior answer" : note.role;
+            lines.push(`- (${label}) ${note.text.replace(/\s+/g, " ").slice(0, 280)}`);
+        }
+        lines.push("");
+    }
+    lines.push("_Memory is personal and local (`~/.amem`). Prefer these anchors over broad exploration. Verify current code before changing anything._");
+    return lines.join("\n");
+}

package/dist/crypto.d.ts

@@ -0,0 +1,39 @@
+export declare function encryptedDbPath(): string;
+export declare function saltPath(): string;
+export declare function isDbEncryptedAtRest(): boolean;
+export declare function encryptionConfigured(): boolean;
+/** AES-256-GCM encrypt bytes → salt||iv||tag||ciphertext layout for files. */
+export declare function encryptBytes(plain: Buffer, passphrase: string, salt?: Buffer): Buffer;
+export declare function decryptBytes(blob: Buffer, passphrase: string): Buffer;
+export declare function resolvePassphrase(explicit?: string): string;
+/** Encrypt plaintext DB to graph.db.enc and remove plaintext. */
+export declare function lockDatabase(passphrase: string): {
+    encPath: string;
+};
+/** Decrypt graph.db.enc to plaintext graph.db for this machine session. */
+export declare function unlockDatabase(passphrase: string): {
+    dbPath: string;
+};
+/** Re-encrypt after unlock (keeps enc in sync) without deleting plaintext — for backups. */
+export declare function encryptFileTo(path: string, outPath: string, passphrase: string): void;
+export declare function decryptFileTo(path: string, outPath: string, passphrase: string): void;
+export declare function fingerprintPassphrase(passphrase: string): string;
+export declare function defaultBackupDir(): string;
+export declare function createBackup(opts: {
+    outDir?: string;
+    passphrase?: string;
+    label?: string;
+}): {
+    path: string;
+    encrypted: boolean;
+};
+/** Replace graph.db from a local backup (plaintext .db or AMEM1 .enc). Caller must closeDb(). */
+export declare function restoreBackup(opts: {
+    file: string;
+    passphrase?: string;
+}): {
+    dbPath: string;
+    from: string;
+    safetyCopy: string | null;
+    encrypted: boolean;
+};

package/dist/crypto.js

@@ -0,0 +1,166 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from "node:crypto";
+import { existsSync, readFileSync, unlinkSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { amemHome, dbPath } from "./paths.js";
+const ENC_SUFFIX = ".enc";
+const SALT_FILE = "crypto.salt";
+export function encryptedDbPath() {
+    return `${dbPath()}${ENC_SUFFIX}`;
+}
+export function saltPath() {
+    return join(amemHome(), SALT_FILE);
+}
+export function isDbEncryptedAtRest() {
+    return existsSync(encryptedDbPath()) && !existsSync(dbPath());
+}
+export function encryptionConfigured() {
+    return existsSync(encryptedDbPath()) || existsSync(saltPath());
+}
+function deriveKey(passphrase, salt) {
+    return scryptSync(passphrase, salt, 32);
+}
+function loadOrCreateSalt() {
+    const path = saltPath();
+    if (existsSync(path))
+        return readFileSync(path);
+    mkdirSync(amemHome(), { recursive: true, mode: 0o700 });
+    const salt = randomBytes(16);
+    writeFileSync(path, salt, { mode: 0o600 });
+    return salt;
+}
+/** AES-256-GCM encrypt bytes → salt||iv||tag||ciphertext layout for files. */
+export function encryptBytes(plain, passphrase, salt) {
+    const useSalt = salt ?? loadOrCreateSalt();
+    const key = deriveKey(passphrase, useSalt);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return Buffer.concat([Buffer.from("AMEM1"), useSalt, iv, tag, ciphertext]);
+}
+export function decryptBytes(blob, passphrase) {
+    if (blob.length < 5 + 16 + 12 + 16 || blob.subarray(0, 5).toString() !== "AMEM1") {
+        throw new Error("Not an amem encrypted blob");
+    }
+    const salt = blob.subarray(5, 21);
+    const iv = blob.subarray(21, 33);
+    const tag = blob.subarray(33, 49);
+    const ciphertext = blob.subarray(49);
+    const key = deriveKey(passphrase, salt);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+export function resolvePassphrase(explicit) {
+    const p = explicit || process.env.AMEM_PASSPHRASE || "";
+    if (!p.trim()) {
+        throw new Error("Passphrase required. Pass --passphrase or set AMEM_PASSPHRASE (never commit it).");
+    }
+    return p;
+}
+/** Encrypt plaintext DB to graph.db.enc and remove plaintext. */
+export function lockDatabase(passphrase) {
+    const plain = dbPath();
+    if (!existsSync(plain))
+        throw new Error(`No database at ${plain}`);
+    const enc = encryptedDbPath();
+    const blob = encryptBytes(readFileSync(plain), passphrase);
+    writeFileSync(enc, blob, { mode: 0o600 });
+    unlinkSync(plain);
+    // also clear WAL/SHM if present
+    for (const side of [`${plain}-wal`, `${plain}-shm`]) {
+        if (existsSync(side))
+            unlinkSync(side);
+    }
+    return { encPath: enc };
+}
+/** Decrypt graph.db.enc to plaintext graph.db for this machine session. */
+export function unlockDatabase(passphrase) {
+    const enc = encryptedDbPath();
+    if (!existsSync(enc))
+        throw new Error(`No encrypted database at ${enc}`);
+    const plain = dbPath();
+    const data = decryptBytes(readFileSync(enc), passphrase);
+    writeFileSync(plain, data, { mode: 0o600 });
+    return { dbPath: plain };
+}
+/** Re-encrypt after unlock (keeps enc in sync) without deleting plaintext — for backups. */
+export function encryptFileTo(path, outPath, passphrase) {
+    const blob = encryptBytes(readFileSync(path), passphrase);
+    mkdirSync(dirname(outPath), { recursive: true, mode: 0o700 });
+    writeFileSync(outPath, blob, { mode: 0o600 });
+}
+export function decryptFileTo(path, outPath, passphrase) {
+    const data = decryptBytes(readFileSync(path), passphrase);
+    mkdirSync(dirname(outPath), { recursive: true, mode: 0o700 });
+    writeFileSync(outPath, data, { mode: 0o600 });
+}
+export function fingerprintPassphrase(passphrase) {
+    return createHash("sha256").update(passphrase).digest("hex").slice(0, 12);
+}
+export function defaultBackupDir() {
+    return join(amemHome(), "backups");
+}
+export function createBackup(opts) {
+    const plain = dbPath();
+    const enc = encryptedDbPath();
+    const source = existsSync(plain) ? plain : existsSync(enc) ? enc : null;
+    if (!source)
+        throw new Error("Nothing to back up — no local amem database found");
+    const dir = opts.outDir || defaultBackupDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const label = (opts.label || "amem").replace(/[^a-zA-Z0-9_-]+/g, "-").slice(0, 40);
+    const encrypted = Boolean(opts.passphrase) || source.endsWith(ENC_SUFFIX);
+    if (opts.passphrase) {
+        const out = join(dir, `${label}-${stamp}.db.enc`);
+        if (source.endsWith(ENC_SUFFIX)) {
+            // already encrypted — copy as-is (cannot re-wrap without unlock)
+            copyFileSync(source, out);
+        }
+        else {
+            encryptFileTo(source, out, opts.passphrase);
+        }
+        return { path: out, encrypted: true };
+    }
+    if (source.endsWith(ENC_SUFFIX)) {
+        const out = join(dir, `${label}-${stamp}.db.enc`);
+        copyFileSync(source, out);
+        return { path: out, encrypted: true };
+    }
+    const out = join(dir, `${label}-${stamp}.db`);
+    copyFileSync(source, out);
+    return { path: out, encrypted: false };
+}
+/** Replace graph.db from a local backup (plaintext .db or AMEM1 .enc). Caller must closeDb(). */
+export function restoreBackup(opts) {
+    const from = opts.file;
+    if (!existsSync(from))
+        throw new Error(`Backup not found: ${from}`);
+    const blob = readFileSync(from);
+    const looksEnc = blob.subarray(0, 5).toString() === "AMEM1" || from.endsWith(ENC_SUFFIX);
+    let plain;
+    if (looksEnc) {
+        const passphrase = opts.passphrase || process.env.AMEM_PASSPHRASE || "";
+        if (!passphrase.trim()) {
+            throw new Error("Encrypted backup — pass --passphrase or set AMEM_PASSPHRASE");
+        }
+        plain = decryptBytes(blob, passphrase);
+    }
+    else {
+        plain = blob;
+    }
+    if (plain.length < 16)
+        throw new Error("Backup file is empty or not a database");
+    const target = dbPath();
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    let safetyCopy = null;
+    if (existsSync(target)) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        safetyCopy = join(defaultBackupDir(), `pre-restore-${stamp}.db`);
+        mkdirSync(defaultBackupDir(), { recursive: true, mode: 0o700 });
+        copyFileSync(target, safetyCopy);
+    }
+    writeFileSync(target, plain, { mode: 0o600 });
+    return { dbPath: target, from, safetyCopy, encrypted: looksEnc };
+}