akm-cli 0.8.0-rc2 → 0.8.0

package/dist/core/memory-contradiction-detect.js

@@ -0,0 +1,274 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * LLM-based contradiction-detection pass for derived memories (M-1 / #367).
+ *
+ * Runs BEFORE `analyzeMemoryCleanup` to populate `contradictedBy` frontmatter
+ * edges so the existing `resolveFamilyContradictions` SCC resolver has real
+ * input to work on. Without this pass the SCC resolver operates on a nearly
+ * empty edge graph because no automated subsystem was previously generating
+ * contradiction edges — the elegant Tarjan implementation in memory-improve.ts
+ * had no input.
+ *
+ * # Algorithm
+ *
+ *   1. Collect all derived memories grouped by `parentRef` family.
+ *   2. For each family, enumerate candidate pairs (limited to MAX_FAMILY_SIZE).
+ *   3. For each pair, call the LLM to judge whether the two memories are in
+ *      direct factual conflict.
+ *   4. For confirmed contradictions, write `contradictedBy` edges directly to
+ *      the losing memory's frontmatter (same mechanism as `persistBeliefStateTransition`).
+ *
+ * # LLM Feature Gate
+ *
+ * The pass is gated behind `profiles.improve.default.processes.consolidate.contradictionDetection.enabled`.
+ * When the gate is disabled or no LLM is configured,
+ * the pass is a no-op and `analyzeMemoryCleanup` proceeds with only manually
+ * annotated edges.
+ *
+ * # References
+ *
+ * - Zep / Graphiti (arXiv:2501.13956): writes contradiction edges at detection time.
+ * - ATMS (de Kleer 1986): assumption-based truth maintenance via edge propagation.
+ * - mem0 contradiction probe (arXiv:2504.19413): pairwise LLM-judge pattern.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
+import { tryLlmFeature } from "../llm/feature-gate";
+import { assembleAsset } from "./asset-serialize";
+import { getDefaultLlmConfig } from "./config";
+import { parseFrontmatter } from "./frontmatter";
+// ── Constants ────────────────────────────────────────────────────────────────
+/**
+ * Maximum family size for pairwise contradiction checking. Families larger
+ * than this are skipped to bound the LLM call count (O(n²) pairs).
+ */
+const MAX_FAMILY_SIZE = 8;
+/**
+ * Maximum number of contradiction pairs to check per improve run, across all
+ * families. Prevents runaway LLM usage on stashes with many memories.
+ */
+const MAX_PAIRS_PER_RUN = 20;
+/**
+ * Truncation limit for memory body content sent to the LLM judge.
+ * Keeps prompts compact while preserving the key factual claims.
+ */
+const BODY_TRUNCATION = 800;
+// ── Prompt builder ────────────────────────────────────────────────────────────
+function buildContradictionJudgePrompt(a, b) {
+    return [
+        "You are evaluating two derived memory entries to determine if they contain",
+        "directly contradictory factual claims about the same subject.",
+        "",
+        "Memory A:",
+        `Ref: ${a.ref}`,
+        `Description: ${a.description || "(none)"}`,
+        "Content:",
+        "```",
+        a.body.slice(0, BODY_TRUNCATION),
+        "```",
+        "",
+        "Memory B:",
+        `Ref: ${b.ref}`,
+        `Description: ${b.description || "(none)"}`,
+        "Content:",
+        "```",
+        b.body.slice(0, BODY_TRUNCATION),
+        "```",
+        "",
+        "Answer ONLY with valid JSON — no prose, no code fences:",
+        '{"contradicts": true|false, "reason": "<one sentence explaining why or why not>"}',
+        "",
+        "A contradiction means the memories make mutually exclusive factual claims about the",
+        "same topic (e.g. Memory A says 'always use VPN' while Memory B says 'VPN is optional').",
+        "If the memories are complementary, about different topics, or one supersedes the other",
+        "without direct conflict, return false.",
+    ].join("\n");
+}
+// ── Filesystem helpers ────────────────────────────────────────────────────────
+function* walkMarkdownFilesLocal(root) {
+    if (!fs.existsSync(root))
+        return;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        const full = path.join(root, entry.name);
+        if (entry.isDirectory())
+            yield* walkMarkdownFilesLocal(full);
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            yield full;
+    }
+}
+function toMemoryRef(memoriesDir, filePath) {
+    const rel = path.relative(memoriesDir, filePath);
+    if (!rel || rel.startsWith(".."))
+        return undefined;
+    const name = rel.replace(/\\/g, "/").replace(/\.md$/i, "");
+    return `memory:${name}`;
+}
+function isDerivedMemory(filePath, frontmatter) {
+    // Name-based guard (M-2): the .derived suffix is structural and immutable.
+    const base = path.basename(filePath, ".md");
+    if (base.endsWith(".derived"))
+        return true;
+    // Frontmatter-based guard: inferred: true marks explicit child memories.
+    return frontmatter.inferred === true;
+}
+function resolveParentRef(filePath, frontmatter, memoriesRootDir) {
+    // Prefer the explicit source: frontmatter.
+    const source = frontmatter.source;
+    if (typeof source === "string" && source.startsWith("memory:"))
+        return source;
+    // Fall back to deriving parent from the file name (strip .derived suffix).
+    const base = path.basename(filePath, ".md");
+    if (base.endsWith(".derived")) {
+        const parentName = base.slice(0, -".derived".length);
+        // Use the stash memories root so nested paths (e.g. memories/nested/foo.derived.md)
+        // resolve to the correct relative ref (memory:nested/foo, not memory:foo).
+        const rootDir = memoriesRootDir ?? path.dirname(filePath);
+        const rel = path.relative(rootDir, path.join(path.dirname(filePath), parentName));
+        return `memory:${rel.replace(/\\/g, "/")}`;
+    }
+    return undefined;
+}
+// ── Edge writing ─────────────────────────────────────────────────────────────
+/**
+ * Write a `contradictedBy` edge to the losing memory's frontmatter file.
+ * Preserves all existing frontmatter keys; only adds/updates `contradictedBy`
+ * and `beliefState: contradicted`.
+ */
+/** Returns true if the edge was newly written, false if it already existed. */
+function writeContradictedByEdge(filePath, contradictedByRef) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const existing = Array.isArray(parsed.data.contradictedBy) ? parsed.data.contradictedBy : [];
+    if (existing.includes(contradictedByRef))
+        return false; // Edge already written.
+    const updatedContradictedBy = [...new Set([...existing, contradictedByRef])].sort();
+    const nextFrontmatter = {
+        ...parsed.data,
+        contradictedBy: updatedContradictedBy,
+        beliefState: "contradicted",
+    };
+    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+    return true;
+}
+// ── Main entry point ──────────────────────────────────────────────────────────
+/**
+ * Run the LLM-based contradiction-detection pass on derived memories in
+ * `<stashDir>/memories/`. Writes `contradictedBy` frontmatter edges for
+ * confirmed contradiction pairs so the subsequent `resolveFamilyContradictions`
+ * SCC pass has edges to work on.
+ *
+ * @param stashDir - Root stash directory.
+ * @param config   - Loaded AKM config (used to access LLM settings).
+ * @param chat     - Optional chat seam for testing (defaults to chatCompletion).
+ */
+export async function detectAndWriteContradictions(stashDir, config, chat = chatCompletion) {
+    const result = {
+        familiesExamined: 0,
+        pairsChecked: 0,
+        edgesWritten: 0,
+        warnings: [],
+    };
+    const contradictionLlm = getDefaultLlmConfig(config);
+    if (!contradictionLlm)
+        return result;
+    // Collect derived memories grouped by parent.
+    const memoriesDir = path.join(stashDir, "memories");
+    const byParent = new Map();
+    for (const filePath of walkMarkdownFilesLocal(memoriesDir)) {
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseFrontmatter(raw);
+        if (!isDerivedMemory(filePath, parsed.data))
+            continue;
+        const parentRef = resolveParentRef(filePath, parsed.data, memoriesDir);
+        if (!parentRef)
+            continue;
+        const ref = toMemoryRef(memoriesDir, filePath);
+        if (!ref)
+            continue;
+        const entry = {
+            filePath,
+            ref,
+            parentRef,
+            body: parsed.content.trim(),
+            description: typeof parsed.data.description === "string" ? parsed.data.description : "",
+        };
+        const family = byParent.get(parentRef) ?? [];
+        family.push(entry);
+        byParent.set(parentRef, family);
+    }
+    let totalPairsChecked = 0;
+    for (const [, family] of byParent) {
+        if (family.length < 2)
+            continue;
+        if (family.length > MAX_FAMILY_SIZE) {
+            result.warnings.push(`Skipping contradiction check for family of ${family.length} members (exceeds MAX_FAMILY_SIZE=${MAX_FAMILY_SIZE})`);
+            continue;
+        }
+        result.familiesExamined++;
+        for (let i = 0; i < family.length - 1; i++) {
+            for (let j = i + 1; j < family.length; j++) {
+                if (totalPairsChecked >= MAX_PAIRS_PER_RUN)
+                    break;
+                const a = family[i];
+                const b = family[j];
+                if (!a || !b)
+                    continue;
+                // Skip pairs where edges already exist in BOTH directions (no new information).
+                const aRaw = fs.readFileSync(a.filePath, "utf8");
+                const aParsed = parseFrontmatter(aRaw);
+                const aCB = Array.isArray(aParsed.data.contradictedBy)
+                    ? aParsed.data.contradictedBy
+                    : [];
+                const bRaw = fs.readFileSync(b.filePath, "utf8");
+                const bParsed = parseFrontmatter(bRaw);
+                const bCB = Array.isArray(bParsed.data.contradictedBy)
+                    ? bParsed.data.contradictedBy
+                    : [];
+                if (aCB.includes(b.ref) && bCB.includes(a.ref))
+                    continue;
+                const prompt = buildContradictionJudgePrompt(a, b);
+                const judgeResult = await tryLlmFeature("memory_contradiction_detection", config, async () => {
+                    return chat(contradictionLlm, [
+                        { role: "system", content: "Return only valid JSON. No prose." },
+                        { role: "user", content: prompt },
+                    ]);
+                }, null);
+                totalPairsChecked++;
+                result.pairsChecked++;
+                if (!judgeResult)
+                    continue; // Feature gate disabled or LLM call failed.
+                let parsed = null;
+                try {
+                    parsed = parseEmbeddedJsonResponse(judgeResult);
+                }
+                catch {
+                    result.warnings.push(`Could not parse contradiction judge response for pair ${a.ref} / ${b.ref}`);
+                    continue;
+                }
+                if (!parsed?.contradicts)
+                    continue;
+                // Write contradiction edges: both members get contradictedBy pointing to each other.
+                try {
+                    const wroteA = writeContradictedByEdge(a.filePath, b.ref);
+                    const wroteB = writeContradictedByEdge(b.filePath, a.ref);
+                    result.edgesWritten += (wroteA ? 1 : 0) + (wroteB ? 1 : 0);
+                }
+                catch (err) {
+                    result.warnings.push(`Failed to write contradiction edge ${a.ref} <-> ${b.ref}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            if (totalPairsChecked >= MAX_PAIRS_PER_RUN)
+                break;
+        }
+    }
+    return result;
+}

package/dist/core/memory-improve.js

@@ -1,7 +1,10 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { stringify as yamlStringify } from "yaml";
 import { makeAssetRef, parseAssetRef } from "./asset-ref";
+import { assembleAsset } from "./asset-serialize";
 import { firstString, groupBy, stringArray } from "./common";
 import { parseFrontmatter } from "./frontmatter";
 const DERIVED_SUFFIX = ".derived";
@@ -172,6 +175,34 @@ export function applyMemoryCleanup(stashDir, plan) {
             warnings.push(formatApplyWarning("archive", candidate.ref, error));
         }
     }
+    // M-5 / #396: Resolve relative dates for flagged candidates.
+    // Anchor: use the file's `createdAt` frontmatter field, or fall back to the
+    // file's mtime. Graphiti arXiv:2501.13956, HeidelTime (Strötgen & Gertz 2010).
+    let relativeDatesResolved = 0;
+    for (const candidate of plan.relativeDateCandidates) {
+        try {
+            const raw = fs.readFileSync(candidate.filePath, "utf8");
+            const fm = parseFrontmatter(raw);
+            const createdAtStr = fm.data.createdAt;
+            let referenceDate;
+            if (createdAtStr) {
+                const parsed = new Date(createdAtStr);
+                referenceDate = Number.isNaN(parsed.getTime()) ? new Date(fs.statSync(candidate.filePath).mtimeMs) : parsed;
+            }
+            else {
+                referenceDate = new Date(fs.statSync(candidate.filePath).mtimeMs);
+            }
+            const resolvedBody = resolveRelativeDates(fm.content ?? "", referenceDate);
+            if (resolvedBody === (fm.content ?? ""))
+                continue; // no change
+            const newContent = assembleAsset(fm.data, resolvedBody);
+            fs.writeFileSync(candidate.filePath, newContent, "utf8");
+            relativeDatesResolved++;
+        }
+        catch (error) {
+            warnings.push(formatApplyWarning("relative-date-resolve", candidate.ref, error));
+        }
+    }
     archived.sort((a, b) => a.ref.localeCompare(b.ref));
     appliedBeliefTransitions.sort(compareBeliefTransitions);
     return {
@@ -179,6 +210,7 @@ export function applyMemoryCleanup(stashDir, plan) {
         beliefStateTransitions: appliedBeliefTransitions,
         ...(transitionLogPath ? { transitionLogPath: path.relative(stashDir, transitionLogPath).replace(/\\/g, "/") } : {}),
         ...(transitionLogPath ? { transitionLogEntries: appliedBeliefTransitions.length } : {}),
+        ...(relativeDatesResolved > 0 ? { relativeDatesResolved } : {}),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -186,6 +218,52 @@ function formatApplyWarning(stage, ref, error) {
     const detail = error instanceof Error ? error.message : String(error);
     return `${stage} failed for ${ref}: ${detail}`;
 }
+/**
+ * M-5 / #396: Resolve relative date expressions to absolute ISO dates.
+ *
+ * Uses `referenceDate` as the anchor point (Graphiti arXiv:2501.13956,
+ * HeidelTime Strötgen & Gertz 2010 — document creation time as reference).
+ * Replaces patterns like "yesterday", "3 days ago", "last week" with their
+ * ISO 8601 date string (YYYY-MM-DD).
+ *
+ * Returns the rewritten string; returns the original if no matches.
+ */
+function resolveRelativeDates(text, referenceDate) {
+    const RELATIVE_DATE_RE = /\b(yesterday|last week|last month|last year|\d+ days? ago|\d+ weeks? ago|\d+ months? ago)\b/gi;
+    return text.replace(RELATIVE_DATE_RE, (match) => {
+        const lower = match.toLowerCase().trim();
+        const d = new Date(referenceDate);
+        if (lower === "yesterday") {
+            d.setDate(d.getDate() - 1);
+        }
+        else if (lower === "last week") {
+            d.setDate(d.getDate() - 7);
+        }
+        else if (lower === "last month") {
+            d.setMonth(d.getMonth() - 1);
+        }
+        else if (lower === "last year") {
+            d.setFullYear(d.getFullYear() - 1);
+        }
+        else {
+            const numMatch = lower.match(/^(\d+)\s+(day|week|month)s?\s+ago$/);
+            if (numMatch) {
+                const n = Number.parseInt(numMatch[1] ?? "0", 10);
+                const unit = numMatch[2] ?? "day";
+                if (unit === "day")
+                    d.setDate(d.getDate() - n);
+                else if (unit === "week")
+                    d.setDate(d.getDate() - n * 7);
+                else if (unit === "month")
+                    d.setMonth(d.getMonth() - n);
+            }
+            else {
+                return match; // unrecognized pattern — leave as-is
+            }
+        }
+        return d.toISOString().slice(0, 10); // YYYY-MM-DD
+    });
+}
 function resolveFamilyContradictions(family) {
     if (family.length === 0)
         return { contradictionCandidates: [], transitions: [] };
@@ -203,12 +281,25 @@ function resolveFamilyContradictions(family) {
         return {
             contradictionCandidates: [],
             transitions: family
-                .filter((record) => record.beliefState !== "active" || record.contradictedBy.length > 0 || record.currentBeliefRefs.length > 0)
+                .filter((record) => {
+                // `deprecated` is a frozen historical state — never refresh it to active.
+                // (`superseded` is intentionally still refreshable to preserve pre-Phase-1A behavior.)
+                if (isFrozenHistoricalBeliefState(record.beliefState))
+                    return false;
+                // `active` and `asserted` are both "current/believed" states. Only emit a
+                // refresh if there is something to clear (contradictions / currentBeliefRefs)
+                // or the state is something else entirely (e.g. lingering `contradicted`).
+                if (isActiveLikeBeliefState(record.beliefState)) {
+                    return record.contradictedBy.length > 0 || record.currentBeliefRefs.length > 0;
+                }
+                return true;
+            })
                 .map((record) => ({
                 ref: record.ref,
                 parentRef: record.parentRef,
                 fromState: record.beliefState,
-                toState: "active",
+                // Preserve `asserted` authority; otherwise refresh to plain `active`.
+                toState: record.beliefState === "asserted" ? "asserted" : "active",
                 reason: "belief-refresh",
             })),
         };
@@ -289,14 +380,22 @@ function resolveFamilyContradictions(family) {
         }
         const componentRefs = [...components[componentIndex]].sort();
         const peerCurrentRefs = componentRefs.filter((ref) => ref !== record.ref);
-        if (record.beliefState !== "active" ||
-            record.contradictedBy.length > 0 ||
-            !sameStringArray(record.currentBeliefRefs, peerCurrentRefs)) {
+        // `deprecated` is a frozen historical state — never refresh to active.
+        // (`superseded` is intentionally still refreshable to preserve pre-Phase-1A behavior.)
+        if (isFrozenHistoricalBeliefState(record.beliefState)) {
+            continue;
+        }
+        // For `active` / `asserted` records, only refresh when something changes.
+        // For everything else (e.g. lingering `contradicted`) always refresh.
+        const isActiveLike = isActiveLikeBeliefState(record.beliefState);
+        const needsRefresh = !isActiveLike || record.contradictedBy.length > 0 || !sameStringArray(record.currentBeliefRefs, peerCurrentRefs);
+        if (needsRefresh) {
             transitions.push({
                 ref: record.ref,
                 parentRef: record.parentRef,
                 fromState: record.beliefState,
-                toState: "active",
+                // Preserve `asserted` authority; otherwise refresh to plain `active`.
+                toState: record.beliefState === "asserted" ? "asserted" : "active",
                 reason: "belief-refresh",
                 ...(peerCurrentRefs[0] ? { relatedRef: peerCurrentRefs[0], relatedRefs: peerCurrentRefs } : {}),
                 ...(peerCurrentRefs.length > 0 ? { currentBeliefRefs: peerCurrentRefs } : {}),
@@ -364,7 +463,7 @@ function archiveCleanupCandidate(stashDir, candidate, filePath) {
     const archiveRef = path.relative(stashDir, archivedPath).replace(/\\/g, "/");
     const auditPath = path.join(archiveDir, "cleanup.md");
     const auditRef = path.relative(stashDir, auditPath).replace(/\\/g, "/");
-    const auditFrontmatter = yamlStringify({
+    const auditAsset = assembleAsset({
         schemaVersion: 1,
         kind: "memory-cleanup-archive",
         archivedAt,
@@ -376,8 +475,8 @@ function archiveCleanupCandidate(stashDir, candidate, filePath) {
         ...(candidate.survivorRef ? { survivorRef: candidate.survivorRef } : {}),
         originalPath,
         archivedPath: archiveRef,
-    }).trimEnd();
-    fs.writeFileSync(auditPath, `---\n${auditFrontmatter}\n---\n\nArchived derived memory for recoverable cleanup.\n`, "utf8");
+    }, "Archived derived memory for recoverable cleanup.\n");
+    fs.writeFileSync(auditPath, auditAsset, "utf8");
     return {
         ref: candidate.ref,
         parentRef: candidate.parentRef,
@@ -412,9 +511,7 @@ function persistBeliefStateTransition(filePath, transition) {
         nextFrontmatter.currentBeliefRefs = [...currentBeliefRefs];
     else
         delete nextFrontmatter.currentBeliefRefs;
-    const frontmatter = yamlStringify(nextFrontmatter).trimEnd();
-    const body = parsed.content.replace(/^\n+/, "");
-    fs.writeFileSync(filePath, `---\n${frontmatter}\n---\n\n${body}`, "utf8");
+    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
 }
 function appendBeliefStateTransitionLog(stashDir, transitions) {
     const logDir = path.join(stashDir, ".akm", "memory-cleanup");
@@ -512,9 +609,40 @@ function collectDerivedMemories(stashDir, parentRefFilter) {
     }
     return records.sort(compareRecords);
 }
+/**
+ * `active` and `asserted` are both "currently believed" states. `asserted` carries
+ * stronger user-explicit authority (set by the hot-path `akm remember`) but for
+ * state-machine purposes (contradiction resolution, refresh logic) they are
+ * equivalent.
+ */
+function isActiveLikeBeliefState(state) {
+    return state === "active" || state === "asserted";
+}
+/**
+ * `deprecated` is a frozen historical state introduced in Phase 1A. Once
+ * recorded, the contradiction-resolution pass must not refresh it back to
+ * active. (`contradicted` is also historical but it *is* updated by the
+ * contradiction resolver, so it is treated separately.)
+ *
+ * Note: `superseded` is deliberately NOT included here. Pre-Phase-1A,
+ * `superseded` records were refreshed to `active` by the belief-refresh
+ * pass (the old guard was `record.beliefState !== "active"`). In practice
+ * most `superseded` records are pruned earlier via `supersededBy` metadata
+ * in `analyzeMemoryCleanup`, so they never reach belief refresh — but a
+ * record marked `beliefState: superseded` without `supersededBy` metadata
+ * was previously refreshable. Preserving that behavior here avoids a
+ * surprise regression; only `deprecated` is the new frozen state.
+ */
+function isFrozenHistoricalBeliefState(state) {
+    return state === "deprecated";
+}
 function resolveBeliefState(frontmatter) {
     const explicit = firstString(frontmatter.beliefState);
-    if (explicit === "active" || explicit === "superseded" || explicit === "contradicted") {
+    if (explicit === "active" ||
+        explicit === "asserted" ||
+        explicit === "deprecated" ||
+        explicit === "superseded" ||
+        explicit === "contradicted") {
         return explicit;
     }
     return "active";

package/dist/core/parse.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Shared JSON parsing utilities for LLM and agent output.
  *