@kage-core/kage-graph-mcp 1.1.0 → 1.1.1

package/README.md

@@ -22,6 +22,7 @@ kage setup codex --project /path/to/repo --write
 kage setup claude-code --project /path/to/repo
 kage setup generic-mcp --project /path/to/repo
 kage setup doctor --project /path/to/repo
+kage setup verify-agent --agent codex --project /path/to/repo
 kage init --project /path/to/repo
 kage policy --project /path/to/repo
 kage doctor --project /path/to/repo
@@ -121,14 +122,14 @@ memory, validation status, estimated tokens saved per recall, duplicate
 candidates, average memory quality, and a readiness score.
 
 Review artifacts include memory quality reasons, risks, duplicate candidates,
-and estimated token savings so reviewers can approve, reject, or merge pending
-memory with less manual inspection.
+and estimated token savings for legacy pending/quarantine packets and promotion
+review.
 
 `kage observe` is the automatic-capture primitive for agent hooks and daemon
 clients. It accepts session, prompt, tool, file-change, command, test, and
 session-end events; deduplicates them; scans for secrets and PII; and stores raw
-observations locally only. `kage distill` turns those observations into pending
-packets with observation session source refs. It never approves or publishes
+observations locally only. `kage distill` turns useful observations into
+repo-local packets with observation session source refs. It never publishes
 memory.
 
 `kage recall --explain --json` exposes the hybrid scoring explanation used for
@@ -149,19 +150,22 @@ is deterministic text plus graph retrieval.
 - `POST /kage/distill`
 
 The daemon is not required for stdio MCP or CLI use; it exists for agents and
-workflows that need REST, live observation ingestion, or Aider-style scripting.
+workflows that need REST, live observation ingestion, Aider-style scripting, or
+automatic index refresh. On start it indexes once, then watches repo file changes
+and refreshes generated graph/index artifacts after a short debounce.
 
 ## Local Graph Viewer
 
 Run `kage viewer --project <repo>` to start the local terminal console. It
 serves the viewer and the selected repo's `.agent_memory/` files from the same
 localhost server, then prints a URL that auto-loads memory graph, code graph,
-metrics, review artifact, and pending packets. Manual JSON selection remains as
+metrics, review artifact, and pending packets when present. Manual JSON selection remains as
 a fallback, not the main workflow.
 
 The viewer renders nodes and relations in SVG, supports memory/code/combined
-modes, filters by type and relation, displays metrics, shows the pending review
-queue, and marks review risks such as low-confidence or missing-evidence edges.
+modes, filters by type and relation, displays metrics, shows packets and pending
+quarantine items when present, and marks risks such as low-confidence or
+missing-evidence edges.
 
 For demos or local docs, the viewer also accepts URL params:
 
@@ -264,9 +268,14 @@ Before code changes or repo-specific answers:
 3. Call `kage_graph` with the user task as the query.
 4. Capture reusable learnings with `kage_learn` or `kage_capture`.
 5. Before finishing changed-file tasks, call `kage_propose_from_diff`.
-6. Never approve or publish memory automatically.
+6. Never publish or promote org/global memory automatically.
 ```
 
+Run `kage setup verify-agent --agent codex --project <repo>` after setup. The
+CLI verifies config, policy, indexes, recall, and code graph. It intentionally
+reports `restart_required` until the active agent can call the MCP
+`kage_verify_agent` tool, which proves Kage is live inside that agent session.
+
 The official Codex MCP docs also support adding HTTP MCP servers with:
 
 ```bash
@@ -275,20 +284,21 @@ codex mcp list
 ```
 
 Kage currently runs as a local stdio MCP server, so the TOML form is the direct
-fit for this MVP.
+fit for the current package.
 
 ## Safety Model
 
 - `kage_learn` is the preferred surface for actual session learning. It creates
-  pending packets with explicit learning/evidence/verification text.
-- `kage_capture` only creates pending packets.
+  repo-local packets with explicit learning/evidence/verification text.
+- `kage_capture` creates repo-local packets.
 - `kage_propose_from_diff` writes a branch review summary under
-  `.agent_memory/review/` and a pending change-memory packet under
-  `.agent_memory/pending/`. It becomes shared recall only after human approval.
+  `.agent_memory/review/` and a repo-local change-memory packet under
+  `.agent_memory/packets/`. Promotion beyond the repo still requires explicit
+  review.
 - `kage_promote_public_candidate` writes a local sanitized review candidate
   under `.agent_memory/public-candidates/`; it does not publish.
 - Registry recommendations never auto-install skills, docs, or MCP servers.
-- Shared approved memory still requires `kage review`.
+- Org/global shared memory still requires explicit review.
 - Capture blocks obvious secrets, tokens, private URL credentials, bearer
   tokens, private keys, and email addresses before writing a packet.
 - Generated indexes are disposable and can be rebuilt from packets.

package/dist/cli.js

@@ -6,7 +6,7 @@ const node_process_1 = require("node:process");
 const daemon_js_1 = require("./daemon.js");
 const kernel_js_1 = require("./kernel.js");
 function usage() {
-    console.log(`Kage Repo-Recall MVP
+    console.log(`Kage repo memory and code graph
 
 Usage:
   kage index --project <dir>
@@ -16,6 +16,7 @@ Usage:
   kage setup list
   kage setup <agent> --project <dir> [--write] [--json]
   kage setup doctor --project <dir> [--json]
+  kage setup verify-agent --agent <agent> --project <dir> [--json]
   kage daemon start --project <dir> [--port 3111]
   kage daemon stop --project <dir>
   kage daemon status --project <dir> [--json]
@@ -49,6 +50,7 @@ Usage:
   kage org export --project <dir> --org <org> [--json]
   kage layered-recall "<query>" --project <dir> [--org <org>] [--global] [--json]
   kage global build --project <dir> [--org <org>] [--json]
+  kage changelog --project <dir> [--days <n>] [--json]
   kage review --project <dir>
   kage validate --project <dir>
 
@@ -196,6 +198,31 @@ async function main() {
             }
             return;
         }
+        if (action === "verify-agent") {
+            const agent = takeArg(args, "--agent") ?? "codex";
+            if (!kernel_js_1.SETUP_AGENTS.includes(agent))
+                usage();
+            const result = (0, kernel_js_1.verifyAgentActivation)(agent, projectArg(args));
+            if (args.includes("--json")) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log(`Kage agent activation: ${result.agent}`);
+            console.log(`Status: ${result.status}`);
+            console.log(`Config: ${result.checks.config_mentions_kage ? "kage configured" : result.checks.config_present ? "config present, kage missing" : "missing"}${result.config_path ? ` (${result.config_path})` : ""}`);
+            console.log(`Policy: ${result.checks.policy_installed ? "installed" : "missing"}`);
+            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})`);
+            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")}`);
+            if (result.next_steps.length)
+                console.log(`Next steps:\n${result.next_steps.map((step) => `  - ${step}`).join("\n")}`);
+            if (result.status !== "ready")
+                process.exitCode = 2;
+            return;
+        }
         if (!action || !kernel_js_1.SETUP_AGENTS.includes(action))
             usage();
         const result = (0, kernel_js_1.setupAgent)(action, projectArg(args), { write: args.includes("--write") });
@@ -440,7 +467,7 @@ async function main() {
             process.exit(2);
         }
         console.log(`Captured session learning: ${result.path}`);
-        console.log(`Review with: kage review --project ${projectArg(args)}`);
+        console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");
         return;
     }
     if (command === "propose") {
@@ -453,10 +480,9 @@ async function main() {
         }
         console.log(`Wrote branch review summary: ${result.path}`);
         if (result.packetPath)
-            console.log(`Captured pending change memory: ${result.packetPath}`);
+            console.log(`Captured repo-local change memory: ${result.packetPath}`);
         console.log(`Changed files: ${result.changedFiles.join(", ")}`);
-        console.log(`Review memory: kage review --project ${projectArg(args)}`);
-        console.log(`Review artifact: kage review-artifact --project ${projectArg(args)}`);
+        console.log("Use org/global promotion commands when this memory should leave the repo.");
         return;
     }
     if (command === "review-artifact") {
@@ -699,8 +725,39 @@ async function main() {
             console.error(`Capture blocked:\n${result.errors.map((error) => `  - ${error}`).join("\n")}`);
             process.exit(2);
         }
-        console.log(`Captured pending packet: ${result.path}`);
-        console.log(`Review with: kage review --project ${input.projectDir}`);
+        console.log(`Captured repo-local packet: ${result.path}`);
+        console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");
+        return;
+    }
+    if (command === "changelog") {
+        const days = numberArg(args, "--days", 7);
+        const result = (0, kernel_js_1.changelog)(projectArg(args), days);
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`Memory changelog: last ${result.days} day${result.days === 1 ? "" : "s"} — ${result.added.length} added, ${result.updated.length} updated, ${result.deprecated.length} deprecated (${result.total} total)`);
+        if (result.added.length > 0) {
+            console.log("\nNew packets:");
+            for (const entry of result.added) {
+                console.log(`  + [${entry.type}] ${entry.title}  (${entry.date.slice(0, 10)})`);
+            }
+        }
+        if (result.updated.length > 0) {
+            console.log("\nUpdated packets:");
+            for (const entry of result.updated) {
+                console.log(`  ~ [${entry.type}] ${entry.title}  (${entry.date.slice(0, 10)})`);
+            }
+        }
+        if (result.deprecated.length > 0) {
+            console.log("\nDeprecated packets:");
+            for (const entry of result.deprecated) {
+                console.log(`  - [${entry.type}] ${entry.title}  (${entry.date.slice(0, 10)})`);
+            }
+        }
+        if (result.total === 0) {
+            console.log("No memory activity in this period.");
+        }
         return;
     }
     if (command === "review") {

package/dist/daemon.js

@@ -83,6 +83,10 @@ function daemonDoctor(projectDir) {
         }
     }
     const restPort = status?.rest_port ?? DEFAULT_REST_PORT;
+    const warnings = [
+        ...(running ? [] : ["Daemon is not running. Start it with `kage daemon start --project <repo>`."]),
+        ...(running && status && !status.index_watch ? ["Index file watcher is not active; run `kage index --project <repo>` after source changes."] : []),
+    ];
     return {
         configured: Boolean(status),
         running,
@@ -96,7 +100,7 @@ function daemonDoctor(projectDir) {
             `GET http://${DEFAULT_HOST}:${restPort}/kage/quality`,
             `GET http://${DEFAULT_HOST}:${restPort}/kage/benchmark`,
         ],
-        warnings: running ? [] : ["Daemon is not running. Start it with `kage daemon start --project <repo>`."],
+        warnings,
     };
 }
 function stopDaemon(projectDir) {
@@ -116,6 +120,8 @@ async function startDaemon(projectDir, options = {}) {
     const restPort = options.restPort ?? DEFAULT_REST_PORT;
     const viewerPort = options.viewerPort ?? DEFAULT_VIEWER_PORT;
     (0, node_fs_1.mkdirSync)(daemonDir(projectDir), { recursive: true });
+    (0, kernel_js_1.indexProject)(projectDir);
+    let lastIndexedAt = new Date().toISOString();
     const status = {
         ok: true,
         project_dir: projectDir,
@@ -125,8 +131,41 @@ async function startDaemon(projectDir, options = {}) {
         viewer_port: viewerPort,
         started_at: new Date().toISOString(),
         status_path: statusPath(projectDir),
+        index_watch: false,
+        last_indexed_at: lastIndexedAt,
     };
     (0, node_fs_1.writeFileSync)(status.status_path, JSON.stringify(status, null, 2), "utf8");
+    let watcher = null;
+    let refreshTimer = null;
+    const refreshIndex = () => {
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
+        refreshTimer = setTimeout(() => {
+            try {
+                (0, kernel_js_1.indexProject)(projectDir);
+                lastIndexedAt = new Date().toISOString();
+                status.last_indexed_at = lastIndexedAt;
+                (0, node_fs_1.writeFileSync)(status.status_path, JSON.stringify(status, null, 2), "utf8");
+            }
+            catch {
+                // Keep the daemon alive; doctor/status surfaces stale indexes separately.
+            }
+        }, 350);
+    };
+    try {
+        watcher = (0, node_fs_1.watch)(projectDir, { recursive: true }, (_event, filename) => {
+            const file = String(filename ?? "");
+            if (!file || file.includes("node_modules") || file.includes(".git") || file.includes(".agent_memory/indexes") || file.includes(".agent_memory/code_graph") || file.includes(".agent_memory/graph"))
+                return;
+            refreshIndex();
+        });
+        status.index_watch = true;
+        (0, node_fs_1.writeFileSync)(status.status_path, JSON.stringify(status, null, 2), "utf8");
+    }
+    catch {
+        status.index_watch = false;
+        (0, node_fs_1.writeFileSync)(status.status_path, JSON.stringify(status, null, 2), "utf8");
+    }
     const server = (0, node_http_1.createServer)(async (req, res) => {
         const url = new URL(req.url ?? "/", `http://${host}:${restPort}`);
         try {
@@ -135,6 +174,7 @@ async function startDaemon(projectDir, options = {}) {
                 return;
             }
             if (req.method === "GET" && url.pathname === "/kage/status") {
+                status.last_indexed_at = lastIndexedAt;
                 json(res, 200, status);
                 return;
             }
@@ -176,6 +216,10 @@ async function startDaemon(projectDir, options = {}) {
     console.log(`Project: ${projectDir}`);
     console.log(`Status: ${status.status_path}`);
     process.on("SIGTERM", () => {
+        if (watcher)
+            watcher.close();
+        if (refreshTimer)
+            clearTimeout(refreshTimer);
         server.close(() => process.exit(0));
     });
 }
@@ -189,6 +233,14 @@ async function startViewer(projectDir, options = {}) {
     const metricsPath = (0, node_path_1.join)(projectRoot, ".agent_memory", "metrics.json");
     const reviewPath = (0, node_path_1.join)(projectRoot, ".agent_memory", "review", "memory-review.md");
     const pendingDir = (0, node_path_1.join)(projectRoot, ".agent_memory", "pending");
+    // Pre-generate metrics.json so the viewer can load it
+    try {
+        const metrics = (0, kernel_js_1.kageMetrics)(projectDir);
+        (0, node_fs_1.writeFileSync)(metricsPath, JSON.stringify(metrics, null, 2));
+    }
+    catch {
+        // non-fatal: viewer will show 404 for metrics if generation fails
+    }
     const url = `http://${host}:${port}/viewer/index.html?graph=${encodeURIComponent(graphPath)}&code=${encodeURIComponent(codePath)}&metrics=${encodeURIComponent(metricsPath)}&review=${encodeURIComponent(reviewPath)}&pending=${encodeURIComponent(pendingDir)}`;
     const server = (0, node_http_1.createServer)((req, res) => {
         const requestUrl = new URL(req.url ?? "/", `http://${host}:${port}`);

package/dist/index.js

@@ -189,6 +189,18 @@ function listTools() {
                 required: ["agent", "project_dir"],
             },
         },
+        {
+            name: "kage_verify_agent",
+            description: "Verify that Kage is truly active for the current agent: config, repo policy, indexes, recall, code graph, and this live MCP tool reachability.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    agent: { type: "string", enum: kernel_js_1.SETUP_AGENTS },
+                    project_dir: { type: "string" },
+                },
+                required: ["agent", "project_dir"],
+            },
+        },
         {
             name: "kage_graph_visual",
             description: "Export the repo-local Kage knowledge graph as Mermaid flowchart text for visual inspection.",
@@ -214,7 +226,7 @@ function listTools() {
         },
         {
             name: "kage_learn",
-            description: "Capture an actual reusable learning from the current session as a pending memory packet. Prefer this over diff proposal when the agent knows what was learned.",
+            description: "Capture an actual reusable learning from the current session as repo-local memory. Prefer this over diff proposal when the agent knows what was learned.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -233,7 +245,7 @@ function listTools() {
         },
         {
             name: "kage_capture",
-            description: "Create a pending repo-local Kage memory packet. This proposes memory only; human review is still required before sharing.",
+            description: "Create a repo-local Kage memory packet immediately. Org/global promotion still requires explicit human review.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -251,7 +263,7 @@ function listTools() {
         },
         {
             name: "kage_observe",
-            description: "Store an automatic local observation event from an agent session. Observations are privacy-scanned, deduplicated, and never auto-approved or published.",
+            description: "Store an automatic local observation event from an agent session. Observations are privacy-scanned, deduplicated, and never published automatically.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -273,7 +285,7 @@ function listTools() {
         },
         {
             name: "kage_distill",
-            description: "Distill stored observations for one session into pending memory candidates. Human review is still required before approved memory.",
+            description: "Distill stored observations for one session into repo-local memory candidates. Org/global promotion still requires explicit human review.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -443,7 +455,7 @@ function listTools() {
         },
         {
             name: "kage_propose_from_diff",
-            description: "Create or update a branch review summary and pending change-memory packet from local git status and diff metadata. Human review is required before it becomes shared repo memory.",
+            description: "Create or update a branch review summary and repo-local change-memory packet from local git status and diff metadata. Org/global promotion still requires explicit human review.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -601,6 +613,12 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_verify_agent") {
+        const result = (0, kernel_js_1.verifyAgentActivation)(String(args?.agent ?? ""), String(args?.project_dir ?? ""), { mcpToolReachable: true });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_graph_visual") {
         const result = (0, kernel_js_1.graphMermaid)(String(args?.project_dir ?? ""), Number(args?.limit ?? 40));
         return {
@@ -630,7 +648,7 @@ async function callTool(name, args) {
                 {
                     type: "text",
                     text: result.ok
-                        ? `Captured session learning: ${result.path}\nReview with: kage review --project ${args?.project_dir}`
+                        ? `Captured session learning: ${result.path}\nRepo-local memory is written immediately. Org/global promotion still requires explicit review.`
                         : `Learning capture blocked:\n${result.errors.map((error) => `- ${error}`).join("\n")}`,
                 },
             ],
@@ -653,7 +671,7 @@ async function callTool(name, args) {
                 {
                     type: "text",
                     text: result.ok
-                        ? `Captured pending packet: ${result.path}\nReview with: kage review --project ${args?.project_dir}`
+                        ? `Captured repo-local packet: ${result.path}\nOrg/global promotion still requires explicit review.`
                         : `Capture blocked:\n${result.errors.map((error) => `- ${error}`).join("\n")}`,
                 },
             ],
@@ -810,7 +828,7 @@ async function callTool(name, args) {
                 {
                     type: "text",
                     text: result.ok
-                        ? `Wrote branch review summary: ${result.path}\nCaptured pending change memory: ${result.packetPath ?? "(none)"}\nChanged files: ${result.changedFiles.join(", ")}`
+                        ? `Wrote branch review summary: ${result.path}\nCaptured repo-local change memory: ${result.packetPath ?? "(none)"}\nChanged files: ${result.changedFiles.join(", ")}`
                         : `Proposal blocked:\n${result.errors.map((error) => `- ${error}`).join("\n")}`,
                 },
             ],