@kage-core/kage-graph-mcp 2.2.6 → 2.3.0

package/dist/cli.js

@@ -71,12 +71,14 @@ Usage:
   kage slots set --project <dir> --label <label> --content <text> [--description <text>] [--paths a,b] [--tags a,b] [--size-limit <n>] [--unpinned] [--json]
   kage slots delete --project <dir> --label <label> [--json]
   kage handoff --project <dir> [--json]
+  kage layers --project <dir> [--json]
   kage lifecycle --project <dir> [--json]
   kage reverify --project <dir> --packet <id> [--json]
   kage reconcile --project <dir> [--session <id>] [--json]
   kage timeline --project <dir> [--days <n>] [--json]
   kage lineage --project <dir> [--json]
   kage supersede --project <dir> --packet <old-id> --replacement <new-id> [--reason <text>] [--json]
+  kage conflicts --project <dir> [--json]
   kage contributors --project <dir> [--json]
   kage profile --project <dir> [--json]
   kage xray --project <dir> [--json]
@@ -108,7 +110,8 @@ Usage:
   kage graph "<query>" --project <dir> [--json]
   kage graph-registry --project <dir> [--json]
   kage embeddings build --project <dir> [--model Xenova/all-MiniLM-L6-v2] [--json]
-  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--max-context-tokens <n>] [--structural-hops <n>]
+  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--docs] [--max-context-tokens <n>] [--structural-hops <n>]
+  kage docs-search "<query>" --project <dir> [--limit <n>] [--json]   search this repo's own committed docs (README, docs/**, *.md)
   kage file-context --project <dir> --path <file> [--json]
   kage observe --project <dir> --event <json>
   kage sessions --project <dir> [--json]
@@ -166,6 +169,15 @@ function numberArg(args, name, fallback) {
     const value = takeArg(args, name);
     return value ? Number(value) : fallback;
 }
+function printContradictionWarning(contradictions) {
+    if (!contradictions?.length)
+        return;
+    console.log(`\n⚠ This contradicts ${contradictions.length} existing memor${contradictions.length === 1 ? "y" : "ies"}:`);
+    for (const item of contradictions) {
+        console.log(`  - ${item.packet_id} (${item.title}): ${item.reason}`);
+    }
+    console.log("  Resolve with kage supersede --packet <old> --replacement <new>, or keep both intentionally.");
+}
 function firstPositional(args) {
     return args.find((arg, index) => index > 0 && !arg.startsWith("--") && !args[index - 1]?.startsWith("--"));
 }
@@ -1363,6 +1375,21 @@ async function main() {
         }
         return;
     }
+    if (command === "layers" || command === "memory-layers") {
+        const result = (0, kernel_js_1.kageLayers)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log("Kage memory layers");
+        for (const layer of result.layers) {
+            console.log(`  ${layer.layer} ${layer.label} (${layer.count})`);
+            console.log(`     ${layer.description}`);
+            for (const ex of layer.examples)
+                console.log(`     · ${ex}`);
+        }
+        return;
+    }
     if (command === "lifecycle" || command === "memory-lifecycle") {
         const result = (0, kernel_js_1.kageMemoryLifecycle)(projectArg(args));
         if (args.includes("--json")) {
@@ -1604,6 +1631,27 @@ async function main() {
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;
     }
+    if (command === "conflicts") {
+        const result = (0, kernel_js_1.kageConflicts)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (!result.count) {
+            console.log("Memory conflicts: none — no contradicting packet pairs found.");
+            return;
+        }
+        console.log(`Memory conflicts: ${result.count} contradicting packet pair${result.count === 1 ? "" : "s"}`);
+        for (const pair of result.pairs) {
+            console.log(`\n  ⚠ ${pair.a.title}  <-->  ${pair.b.title}`);
+            console.log(`    ${pair.a.id}`);
+            console.log(`    ${pair.b.id}`);
+            console.log(`    shared paths: ${pair.shared_paths.join(", ")}`);
+            console.log(`    ${pair.reason}`);
+        }
+        console.log("\nResolve each with: kage supersede --packet <old> --replacement <new>");
+        return;
+    }
     if (command === "module-health") {
         const result = (0, kernel_js_1.kageModuleHealth)(projectArg(args));
         if (args.includes("--json")) {
@@ -1918,6 +1966,7 @@ async function main() {
             graphNodes: listArg(takeArg(args, "--graph-nodes")),
             allowMissingPaths: args.includes("--allow-missing-paths"),
             strictCitations: true,
+            strictContradictions: args.includes("--strict-contradictions"),
             discoveryTokens: args.includes("--discovery-tokens") ? numberArg(args, "--discovery-tokens", 0) : undefined,
         });
         if (!result.ok) {
@@ -1925,6 +1974,7 @@ async function main() {
             process.exit(2);
         }
         console.log(`Captured ${personal ? "personal" : "session"} learning: ${result.path}`);
+        printContradictionWarning(result.contradictions);
         if (result.warnings?.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log(personal
@@ -2003,6 +2053,11 @@ async function main() {
         const result = args.includes("--embeddings")
             ? await (0, kernel_js_1.recallWithEmbeddings)(projectArg(args), query, 5, args.includes("--explain"))
             : (0, kernel_js_1.recall)(projectArg(args), query, 5, args.includes("--explain"), { maxContextTokens, structuralHops });
+        if (args.includes("--docs")) {
+            const docsSection = (0, kernel_js_1.docsRecallSection)(projectArg(args), query, 3);
+            if (docsSection)
+                result.context_block = `${result.context_block}\n\n${docsSection}`;
+        }
         if (args.includes("--json"))
             console.log(JSON.stringify(result, null, 2));
         else {
@@ -2034,6 +2089,27 @@ async function main() {
         console.log(`Packets: ${result.packet_count}`);
         return;
     }
+    if (command === "docs-search") {
+        const query = firstPositional(args);
+        if (!query)
+            usage();
+        const limit = numberArg(args, "--limit", 5);
+        const hits = (0, kernel_js_1.searchDocs)(projectArg(args), query, limit);
+        if (args.includes("--json")) {
+            console.log(JSON.stringify({ query, source: "repo-docs", hits }, null, 2));
+            return;
+        }
+        if (!hits.length) {
+            console.log("No matching docs found in this repo's own committed documentation.");
+            return;
+        }
+        console.log(`Docs search (this repo's own committed documentation) — "${query}":`);
+        for (const hit of hits) {
+            console.log(`\n${hit.doc_path}:${hit.line}  [${hit.score}]  ${hit.heading}`);
+            console.log(`  ${hit.snippet}`);
+        }
+        return;
+    }
     if (command === "observe") {
         const event = takeArg(args, "--event");
         if (!event)
@@ -2173,6 +2249,7 @@ async function main() {
             graphNodes: listArg(takeArg(args, "--graph-nodes")),
             allowMissingPaths: args.includes("--allow-missing-paths"),
             strictCitations: true,
+            strictContradictions: args.includes("--strict-contradictions"),
         };
         const result = (0, kernel_js_1.capture)(input);
         if (!result.ok) {
@@ -2180,6 +2257,7 @@ async function main() {
             process.exit(2);
         }
         console.log(`Captured repo-local packet: ${result.path}`);
+        printContradictionWarning(result.contradictions);
         if (result.warnings?.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");

package/dist/index.js

@@ -160,6 +160,7 @@ function listTools() {
                     limit: { type: "number" },
                     explain: { type: "boolean" },
                     embeddings: { type: "boolean" },
+                    docs: { type: "boolean", description: "If true, append a Docs section (<=3 hits) drawn from this repo's own committed documentation." },
                     json: { type: "boolean" },
                     max_context_tokens: { type: "number" },
                     structural_hops: { type: "number", description: "If >0, append a bounded N-hop code-graph blast radius seeded from the recalled memory's files." },
@@ -374,6 +375,19 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_docs_search",
+            description: "Search this repo's OWN committed documentation (README, docs/**, *.md, common doc dirs — including any framework/API docs checked into the repo). BM25 over heading-anchored chunks from .agent_memory/indexes/docs-index.json. Returns ranked doc hits with doc_path, heading, line, and snippet. This indexes only files on disk in the project, never the internet.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    project_dir: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["query", "project_dir"],
+            },
+        },
         {
             name: "kage_metrics",
             description: "Return concise Kage adoption and quality metrics: code graph counts, language/parser coverage, memory graph evidence coverage, pending/approved packets, validation state, and readiness score.",
@@ -602,6 +616,17 @@ function listTools() {
                 required: ["project_dir", "packet_id", "replacement_packet_id"],
             },
         },
+        {
+            name: "kage_conflicts",
+            description: "List repo-local memory packet pairs that contradict each other (same cited path, same subject, opposing claim). Resolve each with kage_supersede, or keep both intentionally.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_benchmark",
             description: "Return Kage proof metrics, or set mode=memory_quality / memory_scale for synthetic memory retrieval benchmarks.",
@@ -1052,10 +1077,21 @@ async function callTool(name, args) {
         const result = args?.embeddings
             ? await (0, kernel_js_1.recallWithEmbeddings)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain))
             : (0, kernel_js_1.recall)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain), { maxContextTokens, structuralHops });
+        if (args?.docs) {
+            const docsSection = (0, kernel_js_1.docsRecallSection)(String(args?.project_dir ?? ""), String(args?.query ?? ""), 3);
+            if (docsSection)
+                result.context_block = `${result.context_block}\n\n${docsSection}`;
+        }
         return {
             content: [{ type: "text", text: args?.json || args?.explain ? JSON.stringify(result, null, 2) : result.context_block }],
         };
     }
+    if (name === "kage_docs_search") {
+        const hits = (0, kernel_js_1.searchDocs)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5));
+        return {
+            content: [{ type: "text", text: JSON.stringify({ query: String(args?.query ?? ""), source: "repo-docs", hits }, null, 2) }],
+        };
+    }
     if (name === "kage_graph") {
         const result = (0, kernel_js_1.queryGraph)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 10));
         return {
@@ -1224,6 +1260,12 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_conflicts") {
+        const result = (0, kernel_js_1.kageConflicts)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_module_health") {
         const result = (0, kernel_js_1.kageModuleHealth)(String(args?.project_dir ?? ""));
         return {

package/dist/kernel.js

@@ -67,6 +67,8 @@ exports.valueSummary = valueSummary;
 exports.formatTokenCount = formatTokenCount;
 exports.kageFileContext = kageFileContext;
 exports.kageActivity = kageActivity;
+exports.detectContradictions = detectContradictions;
+exports.kageConflicts = kageConflicts;
 exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
 exports.validatePacket = validatePacket;
@@ -87,6 +89,9 @@ exports.writeLspSymbolIndex = writeLspSymbolIndex;
 exports.writeCodeIndex = writeCodeIndex;
 exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
+exports.buildDocsIndex = buildDocsIndex;
+exports.searchDocs = searchDocs;
+exports.docsRecallSection = docsRecallSection;
 exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
@@ -189,6 +194,7 @@ exports.capturePersonal = capturePersonal;
 exports.syncSetup = syncSetup;
 exports.syncStatus = syncStatus;
 exports.syncPersonal = syncPersonal;
+exports.kageLayers = kageLayers;
 const node_crypto_1 = require("node:crypto");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -249,6 +255,9 @@ exports.SETUP_AGENTS = [
     "kilo-code",
     "claude-desktop",
     "aider",
+    "openclaw",
+    "copilot",
+    "hermes",
     "generic-mcp",
 ];
 const DEFAULT_CONFIDENCE = 0.7;
@@ -1345,6 +1354,184 @@ function duplicateCandidatesWithContext(packet, context, threshold = 0.58) {
         status: entry.packet.status,
     }));
 }
+// Negation cues: a body that flips a claim. "do not use", "is not", "never",
+// "should not", "no longer", "stop using", "avoid", "instead of".
+const CONTRADICTION_NEGATION_CUES = [
+    "do not",
+    "don't",
+    "does not",
+    "doesn't",
+    "is not",
+    "isn't",
+    "are not",
+    "aren't",
+    "was not",
+    "should not",
+    "shouldn't",
+    "must not",
+    "cannot",
+    "can't",
+    "never",
+    "no longer",
+    "not idempotent",
+    "not safe",
+    "not thread-safe",
+    "not supported",
+    "not required",
+    "not needed",
+    "stop using",
+    "avoid",
+    "deprecated",
+    "removed",
+    "disable",
+    "disabled",
+];
+// Replacement cues: a body that points the claim at a different answer.
+// "use Y instead", "replaced by", "switched to", "now use", "migrate to".
+const CONTRADICTION_REPLACEMENT_CUES = [
+    "instead",
+    "instead of",
+    "replaced by",
+    "replaced with",
+    "replace with",
+    "switched to",
+    "switch to",
+    "migrated to",
+    "migrate to",
+    "now use",
+    "now uses",
+    "moved to",
+    "superseded by",
+    "in favor of",
+    "rather than",
+];
+function normalizedClaimText(packet) {
+    return `${packet.title}\n${packet.summary}\n${packet.body}`.toLowerCase();
+}
+function negationCueCount(text) {
+    let count = 0;
+    for (const cue of CONTRADICTION_NEGATION_CUES)
+        if (text.includes(cue))
+            count += 1;
+    return count;
+}
+function replacementCueCount(text) {
+    let count = 0;
+    for (const cue of CONTRADICTION_REPLACEMENT_CUES)
+        if (text.includes(cue))
+            count += 1;
+    return count;
+}
+// The subject is the shared vocabulary that BOTH packets are talking about. We
+// require the two packets to agree on a subject (token overlap in title+summary)
+// but DISAGREE on polarity around it.
+function sharedSubjectTokens(a, b) {
+    const aSubject = tokenSet(`${a.title}\n${a.summary}`);
+    const bSubject = tokenSet(`${b.title}\n${b.summary}`);
+    const shared = new Set();
+    for (const token of aSubject)
+        if (bSubject.has(token))
+            shared.add(token);
+    return shared;
+}
+// Opposing-polarity signal between two same-subject bodies. Conservative: a
+// contradiction needs one side to assert a claim and the other to negate or
+// replace it — NOT both sides carrying identical framing (that's a duplicate).
+function opposingPolarity(aText, bText) {
+    const aNeg = negationCueCount(aText);
+    const bNeg = negationCueCount(bText);
+    const aRepl = replacementCueCount(aText);
+    const bRepl = replacementCueCount(bText);
+    // (1) Negation asymmetry: one side negates the claim, the other does not.
+    // Two equally-hedged notes (both negate, or neither negates) are not flagged.
+    if (aNeg === 0 && bNeg >= 1)
+        return "one memory negates a claim the other asserts";
+    if (bNeg === 0 && aNeg >= 1)
+        return "one memory negates a claim the other asserts";
+    // (2) Replacement asymmetry: one side says "use Y instead", the other still
+    // asserts the original (no replacement framing). Same-subject + redirect.
+    if (aRepl === 0 && bRepl >= 1)
+        return "one memory replaces the approach the other still recommends";
+    if (bRepl === 0 && aRepl >= 1)
+        return "one memory replaces the approach the other still recommends";
+    return null;
+}
+// Detect existing approved packets that contradict `candidate`. Pure: takes the
+// candidate and (optionally) the existing pool, performs no writes. Returns the
+// conflicting approved packets with the shared paths and a human reason.
+function detectContradictions(projectDir, candidate, opts = {}) {
+    const subjectThreshold = opts.subjectThreshold ?? 0.34;
+    const candidatePaths = new Set(candidate.paths.filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path)));
+    if (!candidatePaths.size)
+        return [];
+    const existing = (opts.existing ?? loadApprovedPackets(projectDir)).filter((packet) => packet.id !== candidate.id && packet.status === "approved");
+    const candidateText = normalizedClaimText(candidate);
+    const candidateSubject = tokenSet(`${candidate.title}\n${candidate.summary}`);
+    const findings = [];
+    for (const packet of existing) {
+        // (a) shared cited path — the structural anchor that makes a contradiction
+        //     about the SAME thing rather than two unrelated facts.
+        const sharedPaths = packet.paths.filter((path) => candidatePaths.has(path));
+        if (!sharedPaths.length)
+            continue;
+        // (b) same subject — high title/summary similarity. Reuses the duplicate
+        //     similarity machinery (jaccard over token sets) so detection rides on
+        //     the same proven scorer rather than a new bespoke metric.
+        const subjectSimilarity = jaccard(candidateSubject, tokenSet(`${packet.title}\n${packet.summary}`));
+        const subjectOverlap = sharedSubjectTokens(candidate, packet).size;
+        if (subjectSimilarity < subjectThreshold && subjectOverlap < 2)
+            continue;
+        // (c) opposing polarity — the claim itself is flipped/redirected.
+        const reason = opposingPolarity(candidateText, normalizedClaimText(packet));
+        if (!reason)
+            continue;
+        findings.push({
+            packet_id: packet.id,
+            title: packet.title,
+            shared_paths: sharedPaths,
+            reason: `${reason} (shared path: ${sharedPaths.join(", ")})`,
+        });
+    }
+    return findings
+        .sort((a, b) => a.title.localeCompare(b.title))
+        .slice(0, 5);
+}
+// Repo-wide pairwise contradiction scan across approved packets. Reuses
+// detectContradictions per packet against the already-loaded pool so the same
+// conservative heuristic governs both write-time surfacing and the audit view.
+function kageConflicts(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const byId = new Map(approved.map((packet) => [packet.id, packet]));
+    const pairs = [];
+    const seen = new Set();
+    for (const packet of approved) {
+        const findings = detectContradictions(projectDir, packet, { existing: approved });
+        for (const finding of findings) {
+            const ordered = [packet.id, finding.packet_id].sort();
+            const key = ordered.join("\0");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const firstPacket = byId.get(ordered[0]);
+            const secondPacket = byId.get(ordered[1]);
+            pairs.push({
+                a: { id: firstPacket.id, title: firstPacket.title },
+                b: { id: secondPacket.id, title: secondPacket.title },
+                shared_paths: finding.shared_paths,
+                reason: finding.reason,
+            });
+        }
+    }
+    pairs.sort((x, y) => x.a.title.localeCompare(y.a.title) || x.b.title.localeCompare(y.b.title));
+    return {
+        ok: true,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        count: pairs.length,
+        pairs,
+    };
+}
 function packetFeedbackScore(packet) {
     const quality = (packet.quality ?? {});
     return Number(quality.votes_up ?? 0) * 2 - Number(quality.votes_down ?? 0) * 3 - Number(quality.reports_stale ?? 0) * 4;
@@ -5984,6 +6171,213 @@ function hydrateKnowledgeGraphArtifact(projectDir, artifact) {
         edges: readJson(edgesPath),
     };
 }
+// --- Docs search index ---------------------------------------------------
+// Searchable index over the REPO's OWN committed documentation (project README,
+// docs/**, *.md, and common doc dirs — plus any framework/API docs that are
+// checked into this repo). It indexes nothing from the internet; only files
+// that exist on disk in this project. Recall can therefore answer from docs,
+// not just learned memory packets and code.
+const DOCS_INDEX_SCHEMA_VERSION = 1;
+// Heading-anchored chunks are capped so a single long section can't dominate the
+// BM25 length normalization or bloat the artifact.
+const DOCS_CHUNK_MAX_CHARS = 1600;
+// Directory names that commonly hold prose documentation, beyond the root README
+// and a top-level docs/ dir. These are matched as path segments.
+const DOCS_DIR_NAMES = new Set(["docs", "doc", "documentation", "guides", "guide", "wiki", "manual", "handbook"]);
+const DOCS_EXTENSIONS = new Set([".md", ".mdx", ".markdown", ".rst", ".txt"]);
+function isDocFile(relativePath) {
+    if (shouldSkipCodePath(relativePath))
+        return false;
+    if (isNoisePath(relativePath))
+        return false;
+    const segments = relativePath.split("/");
+    const name = segments[segments.length - 1];
+    if (!DOCS_EXTENSIONS.has(extensionOf(name)))
+        return false;
+    // A markdown/rst/txt file qualifies if it is the root README, sits under a
+    // recognised doc directory, or is any committed *.md anywhere in the tree.
+    if (/^readme\b/i.test(name))
+        return true;
+    if (segments.slice(0, -1).some((part) => DOCS_DIR_NAMES.has(part.toLowerCase())))
+        return true;
+    const extension = extensionOf(name);
+    return extension === ".md" || extension === ".mdx" || extension === ".markdown";
+}
+function discoverDocFiles(projectDir) {
+    const all = walkFiles(projectDir, (absolute) => {
+        const relativePath = (0, node_path_1.relative)(projectDir, absolute).replace(/\\/g, "/");
+        return isDocFile(relativePath);
+    });
+    return all.map((absolute) => (0, node_path_1.relative)(projectDir, absolute).replace(/\\/g, "/")).sort();
+}
+function headingAnchor(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+// Split a doc into heading-anchored chunks. Each chunk carries the heading path
+// (e.g. "Setup > Install") plus the body beneath it, capped at DOCS_CHUNK_MAX_CHARS.
+function chunkDoc(docPath, text) {
+    const lines = text.split(/\r?\n/);
+    const chunks = [];
+    const headingStack = [];
+    let bodyLines = [];
+    let chunkStartLine = 1;
+    let inFence = false;
+    const headingPath = () => headingStack.map((entry) => entry.title).join(" > ");
+    const flush = (startLine) => {
+        const body = bodyLines.join("\n").trim();
+        bodyLines = [];
+        if (!body)
+            return;
+        const heading = headingPath() || (0, node_path_1.basename)(docPath);
+        for (let offset = 0; offset < body.length; offset += DOCS_CHUNK_MAX_CHARS) {
+            const slice = body.slice(offset, offset + DOCS_CHUNK_MAX_CHARS);
+            chunks.push({
+                doc_path: docPath,
+                heading,
+                anchor: headingAnchor(headingStack[headingStack.length - 1]?.title ?? heading),
+                text: slice,
+                line: startLine,
+            });
+        }
+    };
+    lines.forEach((line, index) => {
+        const fenceMatch = line.match(/^\s*(?:```|~~~)/);
+        if (fenceMatch)
+            inFence = !inFence;
+        const headingMatch = inFence ? null : line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+        if (headingMatch) {
+            flush(chunkStartLine);
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].trim();
+            while (headingStack.length && headingStack[headingStack.length - 1].level >= level)
+                headingStack.pop();
+            headingStack.push({ level, title });
+            chunkStartLine = index + 1;
+            return;
+        }
+        bodyLines.push(line);
+    });
+    flush(chunkStartLine);
+    return chunks;
+}
+function buildDocsIndex(projectDir) {
+    const docFiles = discoverDocFiles(projectDir);
+    const chunks = [];
+    for (const docPath of docFiles) {
+        const text = safeReadText((0, node_path_1.join)(projectDir, docPath));
+        if (!text)
+            continue;
+        chunks.push(...chunkDoc(docPath, text));
+    }
+    const artifact = {
+        schema_version: DOCS_INDEX_SCHEMA_VERSION,
+        generated_at: nowIso(),
+        source: "repo-docs",
+        doc_count: docFiles.length,
+        chunk_count: chunks.length,
+        chunks,
+    };
+    writeJson((0, node_path_1.join)(indexesDir(projectDir), "docs-index.json"), artifact);
+    return artifact;
+}
+function readDocsIndex(projectDir) {
+    const path = (0, node_path_1.join)(indexesDir(projectDir), "docs-index.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const artifact = readJson(path);
+        if (!Array.isArray(artifact?.chunks))
+            return null;
+        return artifact;
+    }
+    catch {
+        return null;
+    }
+}
+// BM25 over doc chunks, reusing the same lexical scorer (tokenize + stemming +
+// IDF) as packet recall. Heading text is weighted above body, mirroring how the
+// packet scorer weights titles.
+function scoreDocsBm25(queryTerms, chunks) {
+    const terms = expandQueryTerms(queryTerms);
+    const result = new Map();
+    if (!terms.length || !chunks.length)
+        return result;
+    const HEADING_WEIGHT = 3;
+    const documents = chunks.map((chunk) => {
+        const termFrequency = new Map();
+        let length = 0;
+        const add = (textValue, weight) => {
+            for (const token of tokenize(textValue)) {
+                termFrequency.set(token, (termFrequency.get(token) ?? 0) + weight);
+                length += weight;
+            }
+        };
+        add(chunk.heading, HEADING_WEIGHT);
+        add(chunk.text, 1);
+        return { termFrequency, length: Math.max(1, length) };
+    });
+    const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+    const documentFrequency = new Map();
+    for (const term of terms) {
+        documentFrequency.set(term, documents.filter((document) => document.termFrequency.has(term)).length);
+    }
+    documents.forEach((document, index) => {
+        let score = 0;
+        for (const term of terms) {
+            const termFrequency = document.termFrequency.get(term) ?? 0;
+            if (termFrequency <= 0)
+                continue;
+            const df = documentFrequency.get(term) ?? 0;
+            const idf = Math.log(1 + (documents.length - df + 0.5) / (df + 0.5));
+            const denominator = termFrequency + BM25_K1 * (1 - BM25_B + BM25_B * (document.length / averageLength));
+            score += idf * ((termFrequency * (BM25_K1 + 1)) / denominator);
+        }
+        if (score > 0)
+            result.set(index, Number(score.toFixed(2)));
+    });
+    return result;
+}
+function docsSnippet(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 200 ? `${collapsed.slice(0, 197)}...` : collapsed;
+}
+function searchDocs(projectDir, query, limit = 5) {
+    // Use the persisted index when present; rebuild on the fly otherwise so the
+    // search works even before the first refresh.
+    const artifact = readDocsIndex(projectDir) ?? buildDocsIndex(projectDir);
+    const chunks = artifact.chunks;
+    const scores = scoreDocsBm25(tokenize(query), chunks);
+    return [...scores.entries()]
+        .sort((a, b) => b[1] - a[1] || chunks[a[0]].doc_path.localeCompare(chunks[b[0]].doc_path) || chunks[a[0]].line - chunks[b[0]].line)
+        .slice(0, Math.max(0, limit))
+        .map(([index, score]) => {
+        const chunk = chunks[index];
+        return {
+            doc_path: chunk.doc_path,
+            heading: chunk.heading,
+            line: chunk.line,
+            snippet: docsSnippet(chunk.text),
+            score,
+        };
+    });
+}
+// Renders a "Docs" section appended to recall output. Honest framing: these are
+// the repo's own committed docs, not the internet.
+function docsRecallSection(projectDir, query, limit = 3) {
+    const hits = searchDocs(projectDir, query, limit);
+    if (!hits.length)
+        return null;
+    const lines = ["Docs (from this repo's own committed documentation):"];
+    for (const hit of hits) {
+        lines.push(`- ${hit.doc_path}:${hit.line} — ${hit.heading}`);
+        lines.push(`  ${hit.snippet}`);
+    }
+    return lines.join("\n");
+}
 function buildPacketIndexes(projectDir) {
     ensureMemoryDirs(projectDir);
     const packets = loadPacketsFromDir(packetsDir(projectDir)).sort((a, b) => a.id.localeCompare(b.id));
@@ -6029,6 +6423,10 @@ function buildPacketIndexes(projectDir) {
     writeJson(written[2], byTag);
     writeJson(written[3], byType);
     written.push(writeSparseVectorIndex(projectDir, packets));
+    // Docs search index over the repo's own committed documentation. Built here so
+    // it stays current through both indexProject and refreshProject.
+    buildDocsIndex(projectDir);
+    written.push((0, node_path_1.join)(indexesDir(projectDir), "docs-index.json"));
     return written;
 }
 function readCurrentCodeGraph(projectDir, expectedInputHash) {
@@ -6130,6 +6528,7 @@ function currentOrBuildGraphs(projectDir) {
                 (0, node_path_1.join)(indexesDir(projectDir), "by-tag.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "by-type.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "vector-local.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "docs-index.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "structural.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "graph.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "code-graph.json"),
@@ -7404,13 +7803,20 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
             ? [`## Structural Blast Radius (${structuralHops}-hop)`, ...blastRadius.map((path, index) => `${index + 1}. ${path}`), ""]
             : []),
         scored.length ? "## Relevant Memory" : "No relevant repo memory found.",
-        ...scored.flatMap((entry, index) => [
-            "",
-            `${index + 1}. [${entry.packet.type} | ${entry.packet.scope} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
-            `   Summary: ${entry.packet.summary}`,
-            `   Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
-            `   Source: ${sourceLabel(entry.packet)}`,
-        ]),
+        ...scored.flatMap((entry, index) => {
+            const contradicts = (entry.packet.quality ?? {}).contradicts;
+            const contested = Array.isArray(contradicts) && contradicts.length > 0;
+            return [
+                "",
+                `${index + 1}. [${entry.packet.type} | ${entry.packet.scope} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
+                `   Summary: ${entry.packet.summary}`,
+                `   Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
+                `   Source: ${sourceLabel(entry.packet)}`,
+                ...(contested
+                    ? [`   ⚠ Contested: this memory contradicts ${contradicts.length} other packet(s) (${contradicts.join(", ")}). Resolve with kage conflicts / kage supersede before relying on it.`]
+                    : []),
+            ];
+        }),
         "",
         pendingScored.length ? "## Working Memory (Pending Review)" : "",
         ...pendingScored.flatMap((entry, index) => [
@@ -8089,9 +8495,15 @@ function kageRisk(projectDir, targets = [], changedFiles = []) {
     const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const graphPaths = new Set(graph.files.map((file) => file.path));
     const dependents = codeDependents(graph);
-    const resolvedTargets = unique((targets.length ? targets : changedFiles.length ? changedFiles : gitChangedFiles(projectDir))
+    const explicitTargets = targets.length > 0;
+    const resolvedTargets = unique((explicitTargets ? targets : changedFiles.length ? changedFiles : gitChangedFiles(projectDir))
         .map((path) => gitPathToProjectRelative(projectDir, path) ?? path)
-        .filter((path) => path && !isNoisePath(path)));
+        .filter((path) => path && !isNoisePath(path))
+        // Risk is a CODE assessment. When inferring targets from the working tree,
+        // keep only files the code graph actually knows about — memory packets,
+        // dotfiles, and docs have no dependents/hotspot signal and are pure noise
+        // here. Explicitly-named targets are always honored.
+        .filter((path) => explicitTargets || graphPaths.has(path)));
     const warnings = [];
     if (!gitHead(projectDir))
         warnings.push("Git history is unavailable, so churn, ownership, and co-change signals may be empty.");
@@ -9204,9 +9616,15 @@ function renderClaudeMemAuditReceipt(report) {
 function kageReviewerSuggestions(projectDir, targets = [], changedFiles = []) {
     const graph = readCurrentCodeGraph(projectDir) ?? buildCodeGraph(projectDir);
     const graphPaths = new Set(graph.files.map((file) => file.path));
-    const resolvedTargets = unique((targets.length ? targets : changedFiles.length ? changedFiles : gitChangedFiles(projectDir))
+    const explicitTargets = targets.length > 0;
+    const resolvedTargets = unique((explicitTargets ? targets : changedFiles.length ? changedFiles : gitChangedFiles(projectDir))
         .map((path) => gitPathToProjectRelative(projectDir, path) ?? path)
-        .filter((path) => path && !isNoisePath(path)));
+        .filter((path) => path && !isNoisePath(path))
+        // Risk is a CODE assessment. When inferring targets from the working tree,
+        // keep only files the code graph actually knows about — memory packets,
+        // dotfiles, and docs have no dependents/hotspot signal and are pure noise
+        // here. Explicitly-named targets are always honored.
+        .filter((path) => explicitTargets || graphPaths.has(path)));
     const warnings = [];
     if (!gitHead(projectDir))
         warnings.push("Git history is unavailable, so reviewer suggestions cannot be computed.");
@@ -12509,6 +12927,7 @@ function learn(input) {
         strictCitations: input.strictCitations,
         graphNodes: input.graphNodes,
         pendingReview: input.pendingReview,
+        strictContradictions: input.strictContradictions,
         discoveryTokens: input.discoveryTokens,
     });
 }
@@ -12618,9 +13037,26 @@ function capture(input) {
     const validation = validatePacket(packet);
     if (!validation.ok)
         return { ok: false, errors: validation.errors, warnings };
+    // Memory-vs-memory contradiction detection: surface (and optionally refuse)
+    // a capture that directly opposes an existing approved packet on a shared
+    // path, instead of silently storing two conflicting facts.
+    const contradictions = detectContradictions(input.projectDir, packet);
+    if (contradictions.length && input.strictContradictions) {
+        return {
+            ok: false,
+            errors: [
+                `Contradiction blocked: this memory contradicts ${contradictions.length} existing approved ` +
+                    `packet(s): ${contradictions.map((c) => `${c.packet_id} (${c.title})`).join("; ")}. ` +
+                    `Resolve with kage supersede --packet <old> --replacement <new>, or drop --strict-contradictions to keep both.`,
+            ],
+            warnings,
+            contradictions,
+        };
+    }
     packet.quality = {
         ...packet.quality,
         ...evaluateMemoryQuality(input.projectDir, packet),
+        ...(contradictions.length ? { contradicts: contradictions.map((c) => c.packet_id) } : {}),
     };
     const path = writePacket(input.projectDir, packet, input.pendingReview ? "pending" : "packets");
     recordMemoryAudit(input.projectDir, "capture", [packet], {
@@ -12629,7 +13065,7 @@ function capture(input) {
         path: (0, node_path_1.relative)(input.projectDir, path),
         source_kind: packet.source_refs[0]?.kind ?? "explicit_capture",
     });
-    return { ok: true, packet, path, errors: [], warnings };
+    return { ok: true, packet, path, errors: [], warnings, ...(contradictions.length ? { contradictions } : {}) };
 }
 function createPublicCandidate(projectDir, id) {
     ensureMemoryDirs(projectDir);
@@ -13163,6 +13599,9 @@ exit 0
         "roo-code": (0, node_path_1.join)(home, ".roo", "mcp_settings.json"),
         "kilo-code": (0, node_path_1.join)(home, ".kilo", "mcp_settings.json"),
         "claude-desktop": (0, node_path_1.join)(home, ".config", "claude", "claude_desktop_config.json"),
+        openclaw: (0, node_path_1.join)(home, ".openclaw", "mcp.json"),
+        copilot: (0, node_path_1.join)(home, ".config", "github-copilot", "mcp.json"),
+        hermes: (0, node_path_1.join)(home, ".hermes", "mcp.json"),
         "generic-mcp": "",
     };
     setSnippet(paths[agent] || null, universal, [`Merge this MCP stdio config into ${agent}'s MCP settings.`, "Restart the agent after updating config."]);
@@ -14693,6 +15132,12 @@ function prCheck(projectDir) {
     if (reconciliation.unresolved_count > 0) {
         warnings.push(`${reconciliation.unresolved_count} memory reconciliation item(s) may need update after recent code changes (review on handoff; not blocking).`);
     }
+    // Surface unresolved memory-vs-memory contradictions (not a hard fail —
+    // resolving them is an agent/human decision via supersede or keep-both).
+    const conflicts = kageConflicts(projectDir);
+    if (conflicts.count > 0) {
+        warnings.push(`${conflicts.count} memory contradiction pair(s) unresolved — run kage conflicts, then kage supersede the wrong one (not blocking).`);
+    }
     if (!codeGraphCurrent || !memoryGraphCurrent) {
         errors.push("Generated graph artifacts are missing or not current for this working tree content.");
         requiredActions.push("Run kage refresh --project <dir> before merge.");
@@ -15828,8 +16273,35 @@ function supersedeMemory(projectDir, oldPacketId, replacementPacketId, reason =
     upsertPacketEdge(oldPacket, "superseded_by", replacementPacket.id, trimmedReason, at);
     replacementPacket.updated_at = at;
     upsertPacketEdge(replacementPacket, "supersedes", oldPacket.id, trimmedReason, at);
+    // Superseding resolves any recorded contradiction involving the retired
+    // packet: drop the old id from every other packet's quality.contradicts, and
+    // clear the old packet's own contradicts list (it is no longer live memory).
+    const clearContradiction = (packet) => {
+        const quality = (packet.quality ?? {});
+        const existing = Array.isArray(quality.contradicts) ? quality.contradicts : [];
+        if (!existing.length)
+            return false;
+        const next = existing.filter((id) => id !== oldPacket.id && id !== replacementPacket.id);
+        if (next.length === existing.length)
+            return false;
+        if (next.length)
+            quality.contradicts = next;
+        else
+            delete quality.contradicts;
+        packet.quality = quality;
+        packet.updated_at = at;
+        return true;
+    };
+    clearContradiction(oldPacket);
+    clearContradiction(replacementPacket);
     writeJson(oldEntry.path, oldPacket);
     writeJson(replacementEntry.path, replacementPacket);
+    for (const entry of entries) {
+        if (entry.packet.id === oldPacket.id || entry.packet.id === replacementPacket.id)
+            continue;
+        if (clearContradiction(entry.packet))
+            writeJson(entry.path, entry.packet);
+    }
     recordMemoryAudit(projectDir, "supersede", [oldPacket, replacementPacket], {
         old_packet_id: oldPacket.id,
         replacement_packet_id: replacementPacket.id,
@@ -16495,3 +16967,36 @@ function syncPersonal() {
     result.ok = true;
     return result;
 }
+// Kage's memory is hierarchical by construction:
+//   L0 raw       — session observations captured by hooks (unreviewed signal)
+//   L1 reviewed  — verified memory packets (the trusted store)
+//   L2 synthesis — generated overviews: repo maps, project profile, branch/change summaries
+// This surfaces that existing structure rather than inventing a field.
+function kageLayers(projectDir) {
+    const L2_TYPES = new Set(["repo_map"]);
+    const isSynthesis = (p) => {
+        const q = (p.quality ?? {});
+        return L2_TYPES.has(p.type) || q.candidate_kind === "change_memory";
+    };
+    const entries = (0, node_fs_1.existsSync)(packetsDir(projectDir)) ? loadPacketEntriesFromDir(packetsDir(projectDir)) : [];
+    const l2 = entries.filter((e) => isSynthesis(e.packet));
+    const l1 = entries.filter((e) => !isSynthesis(e.packet));
+    let observationCount = 0;
+    const obsDir = observationsDir(projectDir);
+    if ((0, node_fs_1.existsSync)(obsDir)) {
+        try {
+            observationCount = (0, node_fs_1.readdirSync)(obsDir).filter((f) => f.endsWith(".jsonl") || f.endsWith(".json")).length;
+        }
+        catch {
+            observationCount = 0;
+        }
+    }
+    return {
+        project_dir: projectDir,
+        layers: [
+            { layer: "L0", label: "Raw observations", description: "Session signal captured by hooks; unreviewed, feeds auto-distill.", count: observationCount, examples: [] },
+            { layer: "L1", label: "Reviewed memory", description: "Verified packets — cited, fingerprinted, the trusted recall store.", count: l1.length, examples: l1.slice(0, 3).map((e) => e.packet.title) },
+            { layer: "L2", label: "Synthesis", description: "Generated overviews: repo maps and branch/change summaries.", count: l2.length, examples: l2.slice(0, 3).map((e) => e.packet.title) },
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kage-core/kage-graph-mcp",
-  "version": "2.2.6",
+  "version": "2.3.0",
   "description": "Local-first repo memory, code graph, and recall MCP server for coding agents",
   "main": "dist/index.js",
   "files": [