@kage-core/kage-graph-mcp 1.1.36 → 1.1.37

package/README.md

@@ -34,6 +34,9 @@ Roo Code, Kilo Code, Claude Desktop, Aider, generic MCP (`kage setup list`).
 
 - Repo-local memory for decisions, runbooks, bug fixes, gotchas, conventions,
   and code explanations.
+- Claude Code ambient hooks for prompt-time recall, tool-result observation,
+  failure capture, pre-compact/session-end distillation, and stop-time review
+  refresh.
 - A code graph for files, symbols, imports, confidence-scored calls, routes
   (FastAPI / Flask / Django / Rails / Laravel / Spring / Go / Rust / ASP.NET),
   tests, and packages.
@@ -42,7 +45,37 @@ Roo Code, Kilo Code, Claude Desktop, Aider, generic MCP (`kage setup list`).
   ownership silos, module health.
 - Conservative cleanup review input (unreferenced files, unused exports,
   internal-looking unused symbols). Never deletes code.
-- A local viewer for memory, code graph, risks, review, and metrics.
+- A local viewer for memory, code graph, risks, review, and metrics, served
+  with conservative browser security headers.
+- Local memory-access tracking in `.agent_memory/reports/memory-access.json`
+  so agents can learn which memories are reused and recommend what to verify,
+  ground, or clean up without changing shareable packet files on every recall.
+- Memory lifecycle reporting in `.agent_memory/reports/lifecycle.json` so
+  teammates can review healthy, hot, stale, disputed, ungrounded, pending, and
+  generated packets with concrete actions.
+- Memory timeline reporting in `.agent_memory/reports/timeline.json` so
+  handoffs show recently added, updated, pending, and retired repo knowledge.
+- Memory lineage reporting in `.agent_memory/reports/lineage.json` so
+  superseded packets point at the current replacement memory agents should use.
+- Memory audit reporting in `.agent_memory/audit/events.jsonl` and
+  `.agent_memory/reports/memory-audit.json` so memory mutations are reviewable.
+- Memory handoff reporting in `.agent_memory/reports/handoff.json` so the next
+  teammate or agent gets one queue across inbox, lifecycle, audit, timeline,
+  lineage, and distillable session learnings.
+- Project profile reporting in `.agent_memory/reports/profile.json` so agents
+  get a compact orientation across repo shape, top concepts, key files,
+  commands, memory focus, and next actions.
+- Capability audit reporting in `.agent_memory/reports/capabilities.json` so
+  teams can see evidence-backed readiness across memory, collaboration,
+  benchmark proof, and dashboard/viewer proof.
+- Pinned context slots in `.agent_memory/slots/slots.json` so teams can review
+  tiny always-relevant repo guidance that Kage includes before task-specific
+  recall.
+- Session replay digest in `.agent_memory/reports/replay.json` so teams can
+  review observed agent timelines, paths, commands, durable candidates, and
+  distill actions without exposing raw transcript text.
+- A viewer benchmark proof ledger that shows measured results, thresholds,
+  exact commands, and next actions for retrieval, scale, and repo trust gates.
 
 No hosted service, external database, or API key is required.
 
@@ -52,8 +85,24 @@ No hosted service, external database, or API key is required.
 kage recall "how do I run tests" --project .
 kage code-graph "auth routes tests" --project .
 kage risk --project . --targets src/auth.ts --json
+kage profile --project . --json
+kage capabilities --project . --json
+kage slots set --project . --label project_context --content "Always run retry tests after changing retry modules." --paths src/retry.ts --tags retry,tests
+kage slots --project . --json
 kage learn --project . --learning "Use npm test after parser changes."
+kage sessions --project . # observed sessions and distillation actions
+kage replay --project . # privacy-preserving observed-session timeline
+kage memory-access --project . # hot/cold memories and review actions
+kage memory-audit --project . # auditable memory mutations
+kage handoff --project . # combined teammate/agent handoff queue
+kage lifecycle --project . # memory health, freshness, grounding, and feedback
+kage timeline --project . # recent memory changes for handoff
+kage lineage --project . # current replacements for retired memories
+kage supersede --project . --packet <old-id> --replacement <new-id> --reason "why"
+kage benchmark --memory-quality # coding-memory retrieval proof
+kage benchmark --scale --sizes 240,1000,5000 # large-memory recall proof
 kage refresh --project .
+kage embeddings build --project . # optional dense local recall
 kage hook install --project .
 kage pr check --project .
 kage viewer --project .
@@ -62,6 +111,14 @@ kage viewer --project .
 MCP agents should start with `kage_context`. When the query or target list
 mentions file paths, it also includes risk and dependency-path context.
 
+Normal recall is local and dependency-free. For repos that need denser semantic
+matching, install `@xenova/transformers` in the same Node environment as Kage,
+then run `kage embeddings build --project .`. The default lexical layer is
+Unicode-aware and adds CJK bigrams for memory written without spaces. Dense
+embeddings write an optional rebuildable
+`.agent_memory/indexes/embeddings-local.json` artifact, and
+`kage recall "query" --project . --embeddings --explain` uses it.
+
 For stale or wrong memory:
 
 ```bash
@@ -79,6 +136,46 @@ kage setup claude-code --project . --write
 kage setup generic-mcp --project .
 ```
 
+`kage setup claude-code --write` installs the MCP server plus SessionStart,
+UserPromptSubmit, PostToolUse, PostToolUseFailure, PreCompact, Stop, and
+SessionEnd hooks. The hooks observe reusable work signals, inject relevant
+repo memory on new prompts, and distill durable learnings before compaction or
+handoff.
+
+`kage setup verify-agent --agent claude-code --project .` checks those hooks,
+not only the MCP config. If a teammate has the server configured but missing
+ambient hooks, verification reports the missing events and tells them to rerun
+setup.
+
+`kage setup doctor --project . --json` also includes the Claude hook summary,
+so teams can audit partial installs before relying on automatic capture.
+MCP agents can call `kage_setup_doctor` for the same audit without shelling out.
+
+## REST daemon
+
+HTTP-only agents can use the same memory system through the local daemon:
+
+```bash
+kage daemon start --project .
+curl -X POST http://127.0.0.1:3111/kage/context \
+  -H 'content-type: application/json' \
+  -d '{"query":"how does auth work?","limit":5}'
+```
+
+Useful endpoints:
+
+- `POST /kage/context` - combined recall, graph facts, validation, risk, and dependency context.
+- `POST /kage/recall` - repo memory recall.
+- `POST /kage/capture` and `POST /kage/learn` - write durable repo memory.
+- `POST /kage/feedback` - mark recalled memory helpful, wrong, or stale.
+- `POST /kage/observe` and `POST /kage/distill` - session observation and durable learning distillation.
+- `GET /kage/replay` - privacy-preserving session replay digest without raw transcript text.
+- `GET /kage/setup-doctor` - supported-agent setup and Claude hook readiness.
+- `GET /kage/profile` - compact project profile for agent orientation.
+- `GET /kage/capabilities` - evidence-backed memory system readiness across memory, collaboration, benchmarks, and viewer proof.
+- `GET /kage/context-slots`, `POST /kage/context-slots`, `DELETE /kage/context-slots/:label` - pinned repo context slots.
+- `GET /kage/metrics`, `/kage/quality`, `/kage/inbox`, `/kage/benchmark`, `/kage/handoff`, `/kage/lifecycle`, `/kage/timeline`, `/kage/lineage`, `/kage/memory-audit` - human and agent review reports.
+
 ## Storage
 
 Kage writes to `.agent_memory/`. Packets are durable repo memory; everything
@@ -90,7 +187,9 @@ else is rebuildable with `kage refresh`.
 | `.agent_memory/graph/` | memory graph (rebuildable) |
 | `.agent_memory/code_graph/` | source-derived code facts (rebuildable) |
 | `.agent_memory/structural/` | files, symbols, imports |
-| `.agent_memory/reports/` | risk, contributors, decisions, module health, workspace, quality, benchmark |
+| `.agent_memory/slots/` | pinned repo context slots |
+| `.agent_memory/indexes/` | recall indexes, including optional embeddings |
+| `.agent_memory/reports/` | profile, capabilities, context-slots, replay, risk, contributors, decisions, module health, workspace, quality, benchmark, handoff, lifecycle, timeline, lineage |
 
 Repo-local packets are git-visible and reviewable. Generated indexes and
 graphs are rebuildable.

package/dist/cli.js

@@ -34,7 +34,20 @@ Usage:
   kage upgrade [--dry-run]
   kage branch --project <dir> [--json]
   kage metrics --project <dir> [--json]
+  kage memory-access --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]
+  kage slots delete --project <dir> --label <label> [--json]
+  kage handoff --project <dir> [--json]
+  kage lifecycle --project <dir> [--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 contributors --project <dir> [--json]
+  kage profile --project <dir> [--json]
+  kage capabilities --project <dir> [--json]
   kage decisions --project <dir> [--json]
   kage module-health --project <dir> [--json]
   kage graph-insights --project <dir> [--json]
@@ -44,6 +57,8 @@ Usage:
   kage inbox --project <dir> [--json]
   kage quality --project <dir> [--json]
   kage benchmark --project <dir> [--json]
+  kage benchmark --memory-quality [--json]
+  kage benchmark --scale [--sizes 240,1000,5000] [--json]
   kage benchmark --project <dir> --compare --task <task> [--json]
   kage code-graph --project <dir> [--json]
   kage code-graph "<query>" --project <dir> [--json]
@@ -57,8 +72,11 @@ Usage:
   kage graph --project <dir> --mermaid
   kage graph "<query>" --project <dir> [--json]
   kage graph-registry --project <dir> [--json]
-  kage recall "<query>" --project <dir> [--json] [--explain]
+  kage embeddings build --project <dir> [--model Xenova/all-MiniLM-L6-v2] [--json]
+  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings]
   kage observe --project <dir> --event <json>
+  kage sessions --project <dir> [--json]
+  kage replay --project <dir> [--session <id>] [--limit <n>] [--json]
   kage distill --project <dir> --session <id>
   kage learn --project <dir> --learning <text> [--title <title>] [--type <type>] [--evidence <text>] [--verified-by <text>] [--tags a,b] [--paths a,b]
   kage feedback --project <dir> --packet <packet-id> --kind helpful|wrong|stale
@@ -220,7 +238,10 @@ async function main() {
             }
             console.log("Kage setup doctor");
             for (const item of result) {
-                console.log(`- ${item.agent}: ${item.configured ? "configured" : "not detected"}${item.config_path ? ` (${item.config_path})` : ""}`);
+                const hookStatus = item.hook_summary
+                    ? item.hook_summary.ready ? " hooks: installed" : ` hooks: missing ${item.hook_summary.missing.join(", ")}`
+                    : "";
+                console.log(`- ${item.agent}: ${item.configured ? "configured" : "not detected"}${hookStatus}${item.config_path ? ` (${item.config_path})` : ""}`);
             }
             return;
         }
@@ -240,6 +261,9 @@ async function main() {
             console.log(`Indexes: ${result.checks.indexes_present ? "present" : "missing"}`);
             console.log(`Recall: ${result.checks.recall_works ? "ok" : "failed"} (${result.recall_preview})`);
             console.log(`Code graph: ${result.checks.code_graph_works ? "ok" : "failed"} (${result.code_graph_summary})`);
+            if (result.hook_summary) {
+                console.log(`Ambient hooks: ${result.checks.ambient_hooks_present ? "installed" : `missing ${result.hook_summary.missing.join(", ")}`}`);
+            }
             console.log(`Active MCP tool: ${result.checks.mcp_tool_reachable ? "reachable" : "not verified from CLI"}`);
             if (result.warnings.length)
                 console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
@@ -641,6 +665,33 @@ async function main() {
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;
     }
+    if (command === "profile") {
+        const result = (0, kernel_js_1.kageProjectProfile)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage project profile: ${result.summary}`);
+        console.log(`Files: ${result.totals.files} (${result.totals.source_files} source, ${result.totals.test_files} test), symbols: ${result.totals.symbols}`);
+        console.log(`Memory: ${result.totals.approved_memory} packets, ${result.totals.memory_code_coverage_percent}% memory-code coverage`);
+        if (result.top_concepts.length)
+            console.log(`Top concepts: ${result.top_concepts.slice(0, 6).map((item) => `${item.concept} (${item.count})`).join(", ")}`);
+        if (result.key_files.length) {
+            console.log("Key files:");
+            for (const file of result.key_files.slice(0, 8))
+                console.log(`- ${file.path}: ${file.why.slice(0, 3).join("; ")}`);
+        }
+        if (result.run_commands.length) {
+            console.log("Commands:");
+            for (const commandItem of result.run_commands.slice(0, 6))
+                console.log(`- ${commandItem.name}: ${commandItem.command}`);
+        }
+        if (result.next_actions.length)
+            console.log(`Next: ${result.next_actions[0]}`);
+        if (result.warnings.length)
+            console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+        return;
+    }
     if (command === "decisions") {
         const result = (0, kernel_js_1.kageDecisionIntelligence)(projectArg(args));
         if (args.includes("--json")) {
@@ -775,6 +826,256 @@ async function main() {
             console.log(`  Estimated tokens saved: ${result.pain.estimated_tokens_saved}`);
             console.log(`  Time to first use: ${result.pain.time_to_first_use_seconds}s`);
         }
+        if (result.memory_access) {
+            console.log("\nMemory access:");
+            console.log(`  Tracked packets: ${result.memory_access.tracked_packets}`);
+            console.log(`  Uses in 30d: ${result.memory_access.uses_30d}`);
+            console.log(`  Hot / cold packets: ${result.memory_access.hot_packets} / ${result.memory_access.cold_packets}`);
+        }
+        return;
+    }
+    if (command === "memory-access") {
+        const result = (0, kernel_js_1.kageMemoryAccess)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage memory access: ${result.totals.tracked_packets} tracked packet${result.totals.tracked_packets === 1 ? "" : "s"}`);
+        console.log(`Recent uses: ${result.totals.uses_30d} in ${result.window_days} days`);
+        console.log(`Hot / cold: ${result.totals.hot_packets} / ${result.totals.cold_packets}`);
+        if (result.recommendations.length) {
+            console.log("\nRecommended review:");
+            for (const item of result.recommendations.slice(0, 5)) {
+                console.log(`- ${item.summary}`);
+                console.log(`  ${item.action}`);
+            }
+        }
+        console.log("\nTop recalled packets:");
+        for (const entry of result.entries.filter((item) => !(item.tags.includes("change-memory") && item.tags.includes("diff-proposal"))).slice(0, 10)) {
+            if (!entry.total_uses)
+                continue;
+            console.log(`- ${entry.title}: ${entry.uses_30d} recent, ${entry.total_uses} total${entry.best_rank ? `, best rank ${entry.best_rank}` : ""}`);
+        }
+        return;
+    }
+    if (command === "lifecycle" || command === "memory-lifecycle") {
+        const result = (0, kernel_js_1.kageMemoryLifecycle)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage memory lifecycle: ${result.totals.approved} approved, ${result.totals.pending} pending`);
+        console.log(`Healthy / hot / stale: ${result.totals.healthy} / ${result.totals.hot} / ${result.totals.stale}`);
+        console.log(`Ungrounded / disputed / generated: ${result.totals.ungrounded} / ${result.totals.disputed} / ${result.totals.generated}`);
+        if (result.recommendations.length) {
+            console.log("\nRecommended actions:");
+            for (const item of result.recommendations.slice(0, 6)) {
+                console.log(`- ${item.title ? `${item.title}: ` : ""}${item.summary}`);
+                console.log(`  ${item.action}`);
+            }
+        }
+        return;
+    }
+    if (command === "reconcile" || command === "memory-reconcile" || command === "memory-reconciliation") {
+        const result = (0, kernel_js_1.kageMemoryReconciliation)(projectArg(args), {
+            sessionId: takeArg(args, "--session"),
+            limit: numberArg(args, "--limit", 25),
+        });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(result.agent_instruction);
+            if (result.items.length) {
+                console.log("\nItems:");
+                for (const item of result.items) {
+                    console.log(`- ${item.packet_id}: ${item.title}`);
+                    console.log(`  Paths: ${item.changed_paths.join(", ") || item.paths.join(", ")}`);
+                    console.log(`  Action: ${item.next_action}`);
+                }
+            }
+        }
+        if (!result.ok)
+            process.exitCode = 2;
+        return;
+    }
+    if (command === "memory-audit" || command === "audit-log") {
+        const result = (0, kernel_js_1.kageMemoryAudit)(projectArg(args), numberArg(args, "--limit", 100));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage memory audit: ${result.totals.total} mutation${result.totals.total === 1 ? "" : "s"}`);
+        console.log(`Capture / feedback / supersede: ${result.totals.capture} / ${result.totals.feedback} / ${result.totals.supersede}`);
+        for (const entry of result.entries.slice(0, 12)) {
+            console.log(`- ${entry.operation}: ${entry.packet_titles.join(", ") || entry.packet_ids.join(", ")} (${entry.timestamp.slice(0, 19)})`);
+        }
+        if (!result.entries.length)
+            console.log("No memory mutations have been audited yet.");
+        return;
+    }
+    if (command === "capabilities" || command === "capability-audit" || command === "readiness") {
+        const result = (0, kernel_js_1.kageCapabilityAudit)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage capability audit: ${result.overall_score}/100 (${result.status})`);
+        console.log(result.summary);
+        for (const pillar of result.pillars) {
+            console.log(`\n${pillar.label}: ${pillar.score}/100 (${pillar.status})`);
+            for (const item of pillar.evidence.slice(0, 4))
+                console.log(`  - ${item.label}: ${item.value}`);
+            if (pillar.gaps.length)
+                console.log(`  Gap: ${pillar.gaps[0]}`);
+            if (pillar.actions.length)
+                console.log(`  Action: ${pillar.actions[0]}`);
+        }
+        return;
+    }
+    if (command === "slots" || command === "context-slots") {
+        const action = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
+        if (!action || action === "list") {
+            const result = (0, kernel_js_1.kageContextSlots)(projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Kage pinned context slots: ${result.summary}`);
+            for (const slot of result.slots) {
+                console.log(`- ${slot.label}${slot.pinned ? " [pinned]" : ""}: ${slot.description || "(no description)"}`);
+                console.log(`  ${slot.content.slice(0, 160)}${slot.content.length > 160 ? "..." : ""}`);
+            }
+            if (!result.slots.length)
+                console.log("No slots yet. Add one with `kage slots set --label project_context --content \"...\" --project .`.");
+            if (result.warnings.length)
+                console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
+            return;
+        }
+        if (action === "set") {
+            const label = takeArg(args, "--label");
+            const content = takeArg(args, "--content");
+            if (!label || !content)
+                usage();
+            const result = (0, kernel_js_1.setContextSlot)(projectArg(args), {
+                label,
+                content,
+                description: takeArg(args, "--description"),
+                pinned: !args.includes("--unpinned"),
+                size_limit: numberArg(args, "--size-limit", 2000),
+                paths: listArg(takeArg(args, "--paths")),
+                tags: listArg(takeArg(args, "--tags")),
+            });
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exit(2);
+                return;
+            }
+            if (!result.ok) {
+                console.error(`Context slot not saved:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+                process.exit(2);
+            }
+            console.log(`Saved context slot: ${result.slot?.label}`);
+            return;
+        }
+        if (action === "delete") {
+            const label = takeArg(args, "--label");
+            if (!label)
+                usage();
+            const result = (0, kernel_js_1.deleteContextSlot)(projectArg(args), label);
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    process.exit(2);
+                return;
+            }
+            if (!result.ok) {
+                console.error(`Context slot not deleted:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+                process.exit(2);
+            }
+            console.log(`Deleted context slot: ${result.deleted?.label}`);
+            return;
+        }
+        usage();
+    }
+    if (command === "handoff" || command === "memory-handoff") {
+        const result = (0, kernel_js_1.kageMemoryHandoff)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage memory handoff: ${result.totals.open_items} open item${result.totals.open_items === 1 ? "" : "s"}, ${result.totals.distillable_sessions} distillable session${result.totals.distillable_sessions === 1 ? "" : "s"}, ${result.totals.recent_mutations} recent mutation${result.totals.recent_mutations === 1 ? "" : "s"}`);
+        console.log(result.summary);
+        console.log(`Primary action: ${result.primary_action.label} — ${result.primary_action.action}`);
+        if (result.items.length) {
+            console.log("\nNext actions:");
+            for (const item of result.items.slice(0, 10)) {
+                console.log(`- [${item.severity}] ${item.title}: ${item.summary}`);
+                console.log(`  ${item.action}`);
+            }
+        }
+        if (result.recommendations.length) {
+            console.log("\nRecommendations:");
+            for (const item of result.recommendations.slice(0, 5))
+                console.log(`- ${item}`);
+        }
+        return;
+    }
+    if (command === "timeline" || command === "memory-timeline") {
+        const result = (0, kernel_js_1.kageMemoryTimeline)(projectArg(args), numberArg(args, "--days", 14));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage memory timeline: last ${result.days} day${result.days === 1 ? "" : "s"} — ${result.totals.total} event${result.totals.total === 1 ? "" : "s"}`);
+        console.log(`Added / updated / pending / deprecated: ${result.totals.added} / ${result.totals.updated} / ${result.totals.pending} / ${result.totals.deprecated}`);
+        for (const entry of result.entries.slice(0, 12)) {
+            const prefix = entry.kind === "added" ? "+" : entry.kind === "updated" ? "~" : entry.kind === "pending" ? "?" : "-";
+            console.log(`  ${prefix} [${entry.type}] ${entry.title} (${entry.date.slice(0, 10)})`);
+        }
+        if (!result.entries.length)
+            console.log("No memory activity in this period.");
+        return;
+    }
+    if (command === "lineage" || command === "memory-lineage") {
+        const result = (0, kernel_js_1.kageMemoryLineage)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Kage memory lineage: ${result.totals.chains} replacement chain${result.totals.chains === 1 ? "" : "s"}, ${result.totals.orphans} orphan${result.totals.orphans === 1 ? "" : "s"}`);
+        for (const chain of result.chains.slice(0, 10)) {
+            console.log(`- ${chain.current_title}: replaces ${chain.superseded_packet_ids.length} packet${chain.superseded_packet_ids.length === 1 ? "" : "s"}`);
+            console.log(`  ${chain.action}`);
+        }
+        if (result.orphans.length) {
+            console.log("\nNeeds repair:");
+            for (const orphan of result.orphans.slice(0, 10))
+                console.log(`- ${orphan.title}: ${orphan.action}`);
+        }
+        if (!result.chains.length && !result.orphans.length)
+            console.log("No superseded memory chains yet.");
+        return;
+    }
+    if (command === "supersede") {
+        const oldId = takeArg(args, "--packet");
+        const replacementId = takeArg(args, "--replacement");
+        if (!oldId || !replacementId)
+            usage();
+        const result = (0, kernel_js_1.supersedeMemory)(projectArg(args), oldId, replacementId, takeArg(args, "--reason") ?? "");
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (!result.ok) {
+            console.error(`Failed to supersede memory: ${result.errors.join("; ")}`);
+            process.exit(1);
+        }
+        console.log(`Superseded memory: ${result.old_packet_id}`);
+        console.log(`Replacement: ${result.replacement_packet_id}`);
+        if (result.warnings.length)
+            console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;
     }
     if (command === "module-health") {
@@ -935,6 +1236,55 @@ async function main() {
         return;
     }
     if (command === "benchmark") {
+        if (args.includes("--memory-quality")) {
+            const result = (0, kernel_js_1.benchmarkCodingMemoryQuality)({
+                topK: Number(takeArg(args, "--top-k") ?? 10),
+                packetsPerTopic: Number(takeArg(args, "--packets-per-topic") ?? 5),
+                distractorsPerTopic: Number(takeArg(args, "--distractors-per-topic") ?? 7),
+                keep: args.includes("--keep"),
+            });
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log("Kage Coding Memory Quality Benchmark");
+            console.log(`Packets: ${result.summary.packets}`);
+            console.log(`Queries: ${result.summary.queries}`);
+            console.log(`Refresh/index: ${result.summary.refresh_ms}ms`);
+            console.log(`R@5: ${result.summary.recall_at_5_percent ?? "n/a"}%`);
+            console.log(`R@10: ${result.summary.recall_at_10_percent ?? "n/a"}%`);
+            console.log(`NDCG@10: ${result.summary.ndcg_at_10}`);
+            console.log(`MRR: ${result.summary.mrr}`);
+            console.log(`Median recall: ${result.summary.median_latency_ms}ms`);
+            console.log(`Context reduction: ${result.summary.context_reduction_percent}%`);
+            return;
+        }
+        if (args.includes("--scale")) {
+            const sizes = String(takeArg(args, "--sizes") ?? "240,1000,5000")
+                .split(",")
+                .map((value) => Number(value.trim()))
+                .filter((value) => Number.isFinite(value) && value > 0);
+            const result = (0, kernel_js_1.benchmarkMemoryScale)({
+                sizes,
+                topK: Number(takeArg(args, "--top-k") ?? 10),
+                keep: args.includes("--keep"),
+            });
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log("Kage Memory Scale Benchmark");
+            console.log(`Sizes: ${result.sizes.join(", ")}`);
+            console.log(`Top K: ${result.top_k}`);
+            console.log(`Largest corpus: ${result.summary.largest_packets} packets`);
+            console.log(`Hit rate: ${result.summary.largest_hit_rate_percent}%`);
+            console.log(`Median recall: ${result.summary.largest_median_recall_latency_ms}ms`);
+            console.log(`Context reduction: ${result.summary.largest_context_reduction_percent}%`);
+            for (const row of result.results) {
+                console.log(`- ${row.packets} packets: ${row.recall_hit_rate_percent}% hit, ${row.median_recall_latency_ms}ms median, ${row.context_reduction_percent}% context reduction`);
+            }
+            return;
+        }
         if (args.includes("--compare")) {
             const result = (0, kernel_js_1.benchmarkTaskComparison)(projectArg(args), takeArg(args, "--task") ?? firstPositional(args) ?? "how do I run tests");
             if (args.includes("--json")) {
@@ -1193,13 +1543,36 @@ async function main() {
         const query = firstPositional(args);
         if (!query)
             usage();
-        const result = (0, kernel_js_1.recall)(projectArg(args), query, 5, args.includes("--explain"));
+        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"));
         if (args.includes("--json"))
             console.log(JSON.stringify(result, null, 2));
         else
             console.log(result.context_block);
         return;
     }
+    if (command === "embeddings") {
+        const action = firstPositional(args);
+        if (action !== "build")
+            usage();
+        const result = await (0, kernel_js_1.buildEmbeddingIndex)(projectArg(args), { model: takeArg(args, "--model") });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            if (!result.ok)
+                process.exitCode = 2;
+            return;
+        }
+        if (!result.ok) {
+            console.error(`Embedding index failed:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
+            process.exit(2);
+        }
+        console.log(`Embedding index: ${result.path}`);
+        console.log(`Provider: ${result.provider}`);
+        console.log(`Model: ${result.model}`);
+        console.log(`Packets: ${result.packet_count}`);
+        return;
+    }
     if (command === "observe") {
         const event = takeArg(args, "--event");
         if (!event)
@@ -1217,6 +1590,59 @@ async function main() {
         }
         return;
     }
+    if (command === "sessions") {
+        const result = (0, kernel_js_1.kageSessionCaptureReport)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Sessions: ${result.totals.sessions}`);
+        console.log(`Observations: ${result.totals.observations}`);
+        console.log(`Distillable observations: ${result.totals.durable_observations}`);
+        for (const session of result.sessions.slice(0, 10)) {
+            console.log(`\n${session.session_id} — ${session.observations} observation${session.observations === 1 ? "" : "s"}, ${session.durable_observations} distillable`);
+            console.log(`  ${session.first_at || "unknown"} → ${session.last_at || "unknown"}`);
+            if (session.candidate_types.length)
+                console.log(`  Candidates: ${session.candidate_types.join(", ")}`);
+            console.log(`  Next: ${session.next_action}`);
+        }
+        if (!result.sessions.length)
+            console.log("No local observation sessions recorded yet.");
+        return;
+    }
+    if (command === "replay" || command === "session-replay") {
+        const result = (0, kernel_js_1.kageSessionReplay)(projectArg(args), {
+            sessionId: takeArg(args, "--session"),
+            limit: Number(takeArg(args, "--limit") ?? 200),
+        });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Session replay digest: ${result.totals.sessions} session${result.totals.sessions === 1 ? "" : "s"}, ${result.totals.events} event${result.totals.events === 1 ? "" : "s"}`);
+        console.log(`Durable candidates: ${result.totals.durable_candidates}`);
+        for (const session of result.sessions.slice(0, 8)) {
+            console.log(`\n${session.session_id} — ${session.events} event${session.events === 1 ? "" : "s"}, ${session.durable_candidates} durable candidate${session.durable_candidates === 1 ? "" : "s"}`);
+            console.log(`  ${session.first_at || "unknown"} → ${session.last_at || "unknown"}`);
+            if (session.paths.length)
+                console.log(`  Paths: ${session.paths.slice(0, 4).join(", ")}`);
+            if (session.commands.length)
+                console.log(`  Commands: ${session.commands.slice(0, 3).join(", ")}`);
+            if (session.durable_candidates)
+                console.log(`  Next: ${session.distill_command}`);
+        }
+        if (result.events.length) {
+            console.log("\nTimeline:");
+            for (const event of result.events.slice(0, 20)) {
+                const durable = event.durable_candidate ? ` [${event.candidate_type ?? "durable"}]` : "";
+                console.log(`  ${event.timestamp} ${event.label}${durable}: ${event.summary}`);
+            }
+        }
+        else {
+            console.log("No local observation events recorded yet.");
+        }
+        return;
+    }
     if (command === "distill") {
         const sessionId = takeArg(args, "--session");
         if (!sessionId)