@kage-core/kage-graph-mcp 1.3.0 → 1.4.0

package/dist/cli.js

@@ -39,6 +39,7 @@ Usage:
   kage branch --project <dir> [--json]
   kage metrics --project <dir> [--json]
   kage memory-access --project <dir> [--json]
+  kage activity --project <dir> [--json]
   kage memory-audit --project <dir> [--limit <n>] [--json]
   kage slots --project <dir> [--json]
   kage slots set --project <dir> --label <label> --content <text> [--description <text>] [--paths a,b] [--tags a,b] [--size-limit <n>] [--unpinned] [--json]
@@ -983,6 +984,19 @@ async function main() {
         }
         return;
     }
+    if (command === "activity") {
+        const result = (0, kernel_js_1.kageActivity)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage activity: ${result.totals.events} events (${result.totals.recalls} recalls, ${result.totals.captures} captures); ${result.totals.recalls_7d} recalls in 7 days`);
+        console.log("\nRecent:");
+        for (const event of result.events.slice(0, 15)) {
+            console.log(`- ${event.at.slice(0, 16).replace("T", " ")}  ${event.kind.padEnd(9)} ${event.title}`);
+        }
+        return;
+    }
     if (command === "lifecycle" || command === "memory-lifecycle") {
         const result = (0, kernel_js_1.kageMemoryLifecycle)(projectArg(args));
         if (args.includes("--json")) {

package/dist/daemon.js

@@ -570,6 +570,7 @@ async function startViewer(projectDir, options = {}) {
     const memoryAuditPath = (0, node_path_1.join)(reportsDir, "memory-audit.json");
     const handoffPath = (0, node_path_1.join)(reportsDir, "handoff.json");
     const lifecyclePath = (0, node_path_1.join)(reportsDir, "lifecycle.json");
+    const activityPath = (0, node_path_1.join)(reportsDir, "activity.json");
     const timelinePath = (0, node_path_1.join)(reportsDir, "timeline.json");
     const lineagePath = (0, node_path_1.join)(reportsDir, "lineage.json");
     const setupPath = (0, node_path_1.join)(reportsDir, "setup.json");
@@ -600,6 +601,7 @@ async function startViewer(projectDir, options = {}) {
         (0, node_fs_1.writeFileSync)(memoryAuditPath, JSON.stringify((0, kernel_js_1.kageMemoryAudit)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(handoffPath, JSON.stringify((0, kernel_js_1.kageMemoryHandoff)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(lifecyclePath, JSON.stringify((0, kernel_js_1.kageMemoryLifecycle)(projectDir), null, 2));
+        (0, node_fs_1.writeFileSync)(activityPath, JSON.stringify((0, kernel_js_1.kageActivity)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(timelinePath, JSON.stringify((0, kernel_js_1.kageMemoryTimeline)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(lineagePath, JSON.stringify((0, kernel_js_1.kageMemoryLineage)(projectDir), null, 2));
         (0, node_fs_1.writeFileSync)(setupPath, JSON.stringify((0, kernel_js_1.setupDoctor)(projectDir), null, 2));
@@ -609,7 +611,7 @@ async function startViewer(projectDir, options = {}) {
     catch {
         // non-fatal: viewer will show 404 for reports if generation fails
     }
-    const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&inbox=${encodeURIComponent(inboxPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}&quality=${encodeURIComponent(qualityPath)}&benchmark=${encodeURIComponent(benchmarkPath)}&contributors=${encodeURIComponent(contributorsPath)}&profile=${encodeURIComponent(profilePath)}&xray=${encodeURIComponent(xrayPath)}&capabilities=${encodeURIComponent(capabilitiesPath)}&slots=${encodeURIComponent(slotsPath)}&decisions=${encodeURIComponent(decisionsPath)}&risk=${encodeURIComponent(riskPath)}&moduleHealth=${encodeURIComponent(moduleHealthPath)}&graphInsights=${encodeURIComponent(graphInsightsPath)}&workspace=${encodeURIComponent(workspacePath)}&sessions=${encodeURIComponent(sessionsPath)}&replay=${encodeURIComponent(replayPath)}&memoryAccess=${encodeURIComponent(memoryAccessPath)}&memoryAudit=${encodeURIComponent(memoryAuditPath)}&handoff=${encodeURIComponent(handoffPath)}&lifecycle=${encodeURIComponent(lifecyclePath)}&timeline=${encodeURIComponent(timelinePath)}&lineage=${encodeURIComponent(lineagePath)}&setup=${encodeURIComponent(setupPath)}&trust=${encodeURIComponent(trustPath)}&suppressed=${encodeURIComponent(suppressedPath)}&view=code`;
+    const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&inbox=${encodeURIComponent(inboxPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}&quality=${encodeURIComponent(qualityPath)}&benchmark=${encodeURIComponent(benchmarkPath)}&contributors=${encodeURIComponent(contributorsPath)}&profile=${encodeURIComponent(profilePath)}&xray=${encodeURIComponent(xrayPath)}&capabilities=${encodeURIComponent(capabilitiesPath)}&slots=${encodeURIComponent(slotsPath)}&decisions=${encodeURIComponent(decisionsPath)}&risk=${encodeURIComponent(riskPath)}&moduleHealth=${encodeURIComponent(moduleHealthPath)}&graphInsights=${encodeURIComponent(graphInsightsPath)}&workspace=${encodeURIComponent(workspacePath)}&sessions=${encodeURIComponent(sessionsPath)}&replay=${encodeURIComponent(replayPath)}&memoryAccess=${encodeURIComponent(memoryAccessPath)}&memoryAudit=${encodeURIComponent(memoryAuditPath)}&handoff=${encodeURIComponent(handoffPath)}&lifecycle=${encodeURIComponent(lifecyclePath)}&activity=${encodeURIComponent(activityPath)}&timeline=${encodeURIComponent(timelinePath)}&lineage=${encodeURIComponent(lineagePath)}&setup=${encodeURIComponent(setupPath)}&trust=${encodeURIComponent(trustPath)}&suppressed=${encodeURIComponent(suppressedPath)}&view=code`;
     const server = (0, node_http_1.createServer)((req, res) => {
         const requestUrl = new URL(req.url ?? "/", `http://${host}:${port}`);
         let filePath = null;

package/dist/kernel.js

@@ -62,6 +62,7 @@ exports.makePacketId = makePacketId;
 exports.parseFrontmatter = parseFrontmatter;
 exports.kageMemoryAccess = kageMemoryAccess;
 exports.kageMemoryLifecycle = kageMemoryLifecycle;
+exports.kageActivity = kageActivity;
 exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
 exports.validatePacket = validatePacket;
@@ -873,6 +874,8 @@ function kageMemoryLifecycle(projectDir) {
         const item = {
             packet_id: packet.id,
             title: packet.title,
+            summary: packet.summary ?? "",
+            body: packet.body ?? "",
             type: packet.type,
             status: packet.status,
             health: action.health,
@@ -957,6 +960,54 @@ function recordRecallAccess(projectDir, results) {
         // Recall should never fail because local access telemetry could not be updated.
     }
 }
+const AUDIT_ACTIVITY_KIND = {
+    capture: "capture", approve: "capture", supersede: "supersede", deprecate: "deprecate",
+    update: "update", promote: "promote", feedback: "feedback",
+};
+function kageActivity(projectDir, options = {}) {
+    const limit = options.limit ?? 80;
+    const events = [];
+    let recalls = 0;
+    readMemoryAccessEntries(projectDir).forEach((entry) => {
+        (entry.recent ?? []).forEach((r) => {
+            if (!r || !r.at)
+                return;
+            recalls += 1;
+            events.push({ at: r.at, kind: "recall", title: entry.title, detail: `recalled · rank ${r.rank}` });
+        });
+    });
+    let captures = 0;
+    for (const audit of loadMemoryAuditEntries(projectDir)) {
+        const kind = AUDIT_ACTIVITY_KIND[audit.operation] ?? "other";
+        if (kind === "capture")
+            captures += 1;
+        const extra = audit.packet_titles.length > 1 ? ` (+${audit.packet_titles.length - 1} more)` : "";
+        events.push({ at: audit.timestamp, kind, title: (audit.packet_titles[0] ?? audit.operation) + extra, detail: audit.operation, actor: audit.actor });
+    }
+    events.sort((a, b) => (Date.parse(b.at) || 0) - (Date.parse(a.at) || 0));
+    const dayMap = new Map();
+    events.forEach((e) => { if (e.kind === "recall") {
+        const d = e.at.slice(0, 10);
+        dayMap.set(d, (dayMap.get(d) ?? 0) + 1);
+    } });
+    // Zero-fill the last 14 calendar days so the chart reads as a timeline, not a lone bar.
+    const daily = [];
+    for (let i = 13; i >= 0; i -= 1) {
+        const day = new Date(Date.now() - i * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
+        daily.push({ day, recalls: dayMap.get(day) ?? 0 });
+    }
+    const cutoff7 = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    const recalls7d = events.filter((e) => e.kind === "recall" && (Date.parse(e.at) || 0) >= cutoff7).length;
+    return {
+        schema_version: 1,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        window_days: ACCESS_WINDOW_DAYS,
+        totals: { events: events.length, recalls, captures, recalls_7d: recalls7d },
+        daily,
+        events: events.slice(0, limit),
+    };
+}
 function isGeneratedChangeMemory(packet) {
     return packet.type === "workflow"
         && packet.tags.includes("change-memory")
@@ -1122,7 +1173,7 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
         if (ageDays > ttlDays)
             reasons.push(`freshness ttl expired (${Math.floor(ageDays)}d old, ttl ${ttlDays}d)`);
     }
-    const paths = packet.paths.filter(meaningfulMemoryPath);
+    const paths = packet.paths.filter((path) => meaningfulMemoryPath(path) && !isGroundingIgnored(projectDir, path));
     const missingPaths = paths.filter((path) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, path)));
     if (paths.length > 0 && missingPaths.length === paths.length) {
         reasons.push(`all referenced paths are missing: ${missingPaths.slice(0, 4).join(", ")}`);
@@ -1133,6 +1184,7 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
     if (freshness.path_fingerprint_policy === "source_hash_staleness") {
         const storedFingerprints = packetStoredPathFingerprints(packet);
         const changedPaths = storedFingerprints
+            .filter((fingerprint) => !isGroundingIgnored(projectDir, fingerprint.path))
             .filter((fingerprint) => (0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, fingerprint.path)))
             .filter((fingerprint) => {
             const current = memoryPathFingerprint(projectDir, fingerprint.path, fingerprintCache);
@@ -2341,7 +2393,7 @@ function pathExistsInRepo(projectDir, packetPath) {
 }
 function packetGroundingWarnings(projectDir, packet, source) {
     const warnings = [];
-    const meaningfulPaths = packet.paths.filter((path) => path && path !== "root" && !shouldSkipRepoMemoryPath(path));
+    const meaningfulPaths = packet.paths.filter((path) => path && path !== "root" && !shouldSkipRepoMemoryPath(path) && !isGroundingIgnored(projectDir, path));
     const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(projectDir, path));
     if (meaningfulPaths.length && missingPaths.length === meaningfulPaths.length) {
         warnings.push(`${source}: none of the referenced paths exist in this repo: ${missingPaths.join(", ")}`);
@@ -2805,6 +2857,54 @@ function readKageIgnore(projectDir) {
         .map((line) => line.trim())
         .filter((line) => line.length > 0 && !line.startsWith("#"));
 }
+// A repo can declare non-knowledge paths (e.g. a presentation/visualization layer)
+// in .kageignore. Those paths must not count as memory grounding: memory should never
+// be anchored to, or marked stale by, files the repo says are not knowledge-bearing.
+function normalizeRelPath(path) {
+    return String(path).replace(/\\/g, "/").replace(/^\/+/, "");
+}
+function isGroundingIgnored(projectDir, path) {
+    const patterns = readKageIgnore(projectDir);
+    if (!patterns.length)
+        return false;
+    return isKageIgnored(normalizeRelPath(path), patterns);
+}
+// Strip .kageignore'd paths from a packet's grounding (paths, source refs, and
+// path fingerprints). Returns a new packet if anything changed, else null.
+function prunePacketGroundingPaths(packet, patterns) {
+    if (!patterns.length)
+        return null;
+    const ignored = (p) => typeof p === "string" && isKageIgnored(normalizeRelPath(p), patterns);
+    let changed = false;
+    const paths = packet.paths.filter((p) => (ignored(p) ? ((changed = true), false) : true));
+    const sourceRefs = packet.source_refs.map((ref) => {
+        const next = { ...ref };
+        if (ignored(next.path)) {
+            delete next.path;
+            changed = true;
+        }
+        if (Array.isArray(next.changed_files)) {
+            const kept = next.changed_files.filter((f) => !ignored(f));
+            if (kept.length !== next.changed_files.length) {
+                next.changed_files = kept;
+                changed = true;
+            }
+        }
+        return next;
+    });
+    const freshness = { ...(packet.freshness ?? {}) };
+    if (Array.isArray(freshness.path_fingerprints)) {
+        const fps = freshness.path_fingerprints;
+        const kept = fps.filter((f) => !ignored(f?.path));
+        if (kept.length !== fps.length) {
+            freshness.path_fingerprints = kept;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return null;
+    return { ...packet, paths, source_refs: sourceRefs, freshness };
+}
 function wildcardPattern(pattern) {
     const escaped = pattern
         .replace(/[.+^${}()|[\]\\]/g, "\\$&")
@@ -5447,13 +5547,18 @@ function refreshPacketStaleness(projectDir) {
     const findings = [];
     let updated = 0;
     const fingerprintCache = new Map();
+    const ignorePatterns = readKageIgnore(projectDir);
     for (const entry of loadPacketEntriesFromDir(packetsDir(projectDir))) {
-        const reasons = staleMemoryReasons(projectDir, entry.packet, fingerprintCache);
-        const oldQuality = (entry.packet.quality ?? {});
-        const oldFreshness = (entry.packet.freshness ?? {});
+        // Drop any .kageignore'd grounding (presentation layers etc.) from the stored packet
+        // so memory is never anchored to non-knowledge files.
+        const pruned = prunePacketGroundingPaths(entry.packet, ignorePatterns);
+        const packet = pruned ?? entry.packet;
+        const reasons = staleMemoryReasons(projectDir, packet, fingerprintCache);
+        const oldQuality = (packet.quality ?? {});
+        const oldFreshness = (packet.freshness ?? {});
         let nextQuality;
         if (reasons.length) {
-            const finding = staleFinding(entry.packet, reasons);
+            const finding = staleFinding(packet, reasons);
             findings.push(finding);
             nextQuality = {
                 ...oldQuality,
@@ -5467,11 +5572,12 @@ function refreshPacketStaleness(projectDir) {
             nextQuality = rest;
         }
         const nextFreshness = oldFreshness;
-        const changed = JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
+        const changed = pruned !== null
+            || JSON.stringify(oldQuality) !== JSON.stringify(nextQuality)
             || JSON.stringify(oldFreshness) !== JSON.stringify(nextFreshness);
         if (changed) {
             writeJson(entry.path, {
-                ...entry.packet,
+                ...packet,
                 freshness: nextFreshness,
                 quality: nextQuality,
                 updated_at: nowIso(),
@@ -10897,8 +11003,11 @@ function capture(input) {
         };
     }
     const warnings = [];
-    const meaningfulPaths = (input.paths ?? [])
-        .filter((path) => path && meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
+    // .kageignore'd paths (e.g. a presentation/visualization layer) are not knowledge-bearing,
+    // so they never become grounding for a packet — dropped before validation and storage.
+    const groundedPaths = (input.paths ?? []).filter((path) => path && !isGroundingIgnored(input.projectDir, path));
+    const meaningfulPaths = groundedPaths
+        .filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path));
     const missingPaths = meaningfulPaths.filter((path) => !pathExistsInRepo(input.projectDir, path));
     // Citation validation. Strict mode (agent-facing record_memory tools / CLI) rejects a
     // write whose every cited path is missing — the PRD's "reject if citations don't exist".
@@ -10937,7 +11046,7 @@ function capture(input) {
         status: "approved",
         confidence: DEFAULT_CONFIDENCE,
         tags: input.tags ?? [],
-        paths: input.paths ?? [],
+        paths: groundedPaths,
         stack: input.stack ?? [],
         source_refs: [
             {
@@ -10949,7 +11058,7 @@ function capture(input) {
         freshness: {
             ttl_days: 365,
             last_verified_at: createdAt,
-            path_fingerprints: memoryPathFingerprints(input.projectDir, input.paths ?? []),
+            path_fingerprints: memoryPathFingerprints(input.projectDir, groundedPaths),
             path_fingerprint_policy: "source_hash_staleness",
             verification: "repo_local_agent_capture",
         },
@@ -12509,11 +12618,14 @@ function prCheck(projectDir) {
     const tree = gitTree(projectDir);
     const codeInputHash = currentCodeGraphInputHash(projectDir);
     const memoryInputHash = knowledgeGraphInputHash(projectDir, codeInputHash);
-    const stalePackets = loadPacketsFromDir(packetsDir(projectDir))
+    const fpCache = new Map();
+    const staleEntries = loadPacketsFromDir(packetsDir(projectDir))
         .filter((packet) => packet.status === "approved" || packet.status === "pending")
-        .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet) }))
-        .filter((entry) => entry.reasons.length)
-        .map((entry) => staleFinding(entry.packet, entry.reasons));
+        .map((packet) => ({ packet, reasons: staleMemoryReasons(projectDir, packet, fpCache), hard: recallHardStaleReason(projectDir, packet, fpCache) !== null }))
+        .filter((entry) => entry.reasons.length);
+    const stalePackets = staleEntries.map((entry) => staleFinding(entry.packet, entry.reasons));
+    const hardStaleCount = staleEntries.filter((entry) => entry.hard).length;
+    const softStaleCount = staleEntries.length - hardStaleCount;
     const memoryPacketChanges = unique(rawStatus
         .split(/\r?\n/)
         .map(parsePorcelainPath)
@@ -12526,13 +12638,18 @@ function prCheck(projectDir) {
     const errors = [...validation.errors];
     const warnings = [...validation.warnings];
     const requiredActions = [];
-    if (stalePackets.length) {
-        errors.push(`${stalePackets.length} stale memory packet(s) require update, verification, or supersession.`);
-        requiredActions.push("Run kage refresh, then update or supersede stale packets.");
+    // Block only on hard-stale memory (cited files deleted, ttl expired, reported
+    // stale). Soft-stale ("linked code changed since capture") is normal during
+    // active development — surface it as a warning, don't fail the gate.
+    if (hardStaleCount) {
+        errors.push(`${hardStaleCount} memory packet(s) are hard-stale (deleted citations, expired ttl, or reported) and must be updated or superseded.`);
+        requiredActions.push("Run kage compact (or kage gc), then update or supersede the affected packets.");
+    }
+    if (softStaleCount) {
+        warnings.push(`${softStaleCount} memory packet(s) reference code that changed since capture — review with kage verify (not blocking).`);
     }
     if (reconciliation.unresolved_count > 0) {
-        errors.push(`${reconciliation.unresolved_count} memory reconciliation item(s) require agent update or supersession.`);
-        requiredActions.push(...reconciliation.items.slice(0, 5).map((item) => item.next_action));
+        warnings.push(`${reconciliation.unresolved_count} memory reconciliation item(s) may need update after recent code changes (review on handoff; not blocking).`);
     }
     if (!codeGraphCurrent || !memoryGraphCurrent) {
         errors.push("Generated graph artifacts are missing or not current for this working tree content.");
@@ -12540,8 +12657,7 @@ function prCheck(projectDir) {
     }
     const distillableSessions = sessions.sessions.filter((session) => session.durable_observations > 0);
     if (distillableSessions.length) {
-        errors.push(`${distillableSessions.length} distillable session learning${distillableSessions.length === 1 ? "" : "s"} require review before merge.`);
-        requiredActions.push(...distillableSessions.slice(0, 5).map((session) => session.next_action));
+        warnings.push(`${distillableSessions.length} distillable session learning${distillableSessions.length === 1 ? "" : "s"} pending review (run kage distill; not blocking).`);
     }
     if (!memoryPacketChanges.length && overlay.changed_files.some((path) => !path.startsWith(".agent_memory/"))) {
         warnings.push("No repo memory packet changed for this branch. If durable knowledge was learned, run kage propose --from-diff or kage learn.");

package/package.json

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