@kage-core/kage-graph-mcp 1.1.31 → 1.1.33

package/README.md

@@ -44,8 +44,9 @@ Restart your agent once after setup so MCP tools reload.
 - memory-code links so project knowledge points at the code it affects
 - decision intelligence for why-memory coverage, stale/weak packets, and
   important files that still lack linked repo knowledge
-- lightweight workspace recall across sibling repos, including package and
-  route-contract links when existing code graphs expose them
+- lightweight workspace recall across sibling repos, including package,
+  route-contract, topic/event contract, and git co-change links when existing
+  local evidence exposes them
 - local git intelligence for risk, reviewers, contributor profiles, co-change
   warnings, ownership silos, and module health
 - `AGENTS.md` bootstrap instructions so agents recall context automatically

package/dist/cli.js

@@ -849,6 +849,18 @@ async function main() {
                 console.log(`- ${contract.provider_repo} ${contract.method} ${contract.path} -> ${contract.consumer_repo}/${contract.consumer_file}`);
             }
         }
+        if (result.topic_contracts.length) {
+            console.log("Topic/event contracts:");
+            for (const contract of result.topic_contracts.slice(0, 10)) {
+                console.log(`- ${contract.producer_repo} ${contract.topic} -> ${contract.consumer_repo}/${contract.consumer_file}`);
+            }
+        }
+        if (result.co_changes.length) {
+            console.log("Cross-repo co-changes:");
+            for (const link of result.co_changes.slice(0, 10)) {
+                console.log(`- ${link.source_repo}/${link.source_file} <-> ${link.target_repo}/${link.target_file} (${link.frequency}x, strength ${link.strength})`);
+            }
+        }
         if (result.warnings.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;

package/dist/index.js

@@ -322,7 +322,7 @@ function listTools() {
         },
         {
             name: "kage_workspace",
-            description: "Summarize a local multi-repo workspace: discovered git repos, Kage memory coverage, code graph counts, and package dependencies between repos. Use when a task spans multiple sibling repos.",
+            description: "Summarize a local multi-repo workspace: discovered git repos, Kage memory coverage, code graph counts, package dependencies, route contracts, topic/event contracts, and cross-repo co-change links between repos. Use when a task spans multiple sibling repos.",
             inputSchema: {
                 type: "object",
                 properties: {

package/dist/kernel.js

@@ -6487,6 +6487,207 @@ function workspaceRouteContracts(workspaceDir, repos) {
         .sort((a, b) => a.provider_repo.localeCompare(b.provider_repo) || a.path.localeCompare(b.path) || a.consumer_repo.localeCompare(b.consumer_repo))
         .slice(0, 50);
 }
+const TOPIC_PRODUCER_METHODS = "publish|produce|send|emit|enqueue|dispatch";
+const TOPIC_CONSUMER_METHODS = "subscribe|consume|listen|handle";
+function likelyWorkspaceTopic(value) {
+    const topic = value.trim();
+    if (topic.length < 3 || topic.length > 120)
+        return false;
+    if (topic.startsWith("/") || /^https?:\/\//i.test(topic))
+        return false;
+    if (/\s/.test(topic))
+        return false;
+    if (/[.:-]/.test(topic))
+        return true;
+    if (/_/.test(topic) && /^[a-z0-9_]+$/i.test(topic))
+        return true;
+    return /\b(created|updated|deleted|requested|completed|failed|received|changed)$/i.test(topic);
+}
+function extractWorkspaceTopicMentions(repo, file, text) {
+    const mentions = [];
+    const patterns = [
+        { role: "producer", regex: new RegExp(`\\b(?:${TOPIC_PRODUCER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+        { role: "producer", regex: new RegExp(`\\.(?:${TOPIC_PRODUCER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+        { role: "consumer", regex: new RegExp(`\\b(?:${TOPIC_CONSUMER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+        { role: "consumer", regex: new RegExp(`\\.(?:${TOPIC_CONSUMER_METHODS})\\s*\\(\\s*["'\`]([^"'\`]+)["'\`]`, "gi") },
+    ];
+    for (const pattern of patterns) {
+        for (const match of text.matchAll(pattern.regex)) {
+            const topic = match[1]?.trim();
+            if (!topic || !likelyWorkspaceTopic(topic))
+                continue;
+            mentions.push({
+                repo,
+                file,
+                topic,
+                role: pattern.role,
+                evidence: `${file} ${pattern.role === "producer" ? "publishes" : "subscribes to"} ${topic}`,
+            });
+        }
+    }
+    return mentions;
+}
+function workspaceTopicContracts(workspaceDir, repos) {
+    const mentions = [];
+    for (const repo of repos) {
+        const repoRoot = repo.path === "." ? workspaceDir : (0, node_path_1.join)(workspaceDir, repo.path);
+        const graph = readCurrentCodeGraph(repoRoot);
+        if (!graph)
+            continue;
+        for (const file of graph.files) {
+            if (!["source", "config", "manifest"].includes(file.kind))
+                continue;
+            if (file.size_bytes > MAX_CODE_FILE_BYTES)
+                continue;
+            const absolutePath = (0, node_path_1.join)(repoRoot, file.path);
+            if (!(0, node_fs_1.existsSync)(absolutePath))
+                continue;
+            try {
+                mentions.push(...extractWorkspaceTopicMentions(repo.alias, file.path, (0, node_fs_1.readFileSync)(absolutePath, "utf8")));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    const producers = mentions.filter((mention) => mention.role === "producer");
+    const consumers = mentions.filter((mention) => mention.role === "consumer");
+    const contracts = [];
+    const seen = new Set();
+    for (const producer of producers) {
+        for (const consumer of consumers) {
+            if (producer.topic !== consumer.topic || producer.repo === consumer.repo)
+                continue;
+            const key = `${producer.repo}\0${producer.file}\0${consumer.repo}\0${consumer.file}\0${producer.topic}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            contracts.push({
+                topic: producer.topic,
+                producer_repo: producer.repo,
+                producer_file: producer.file,
+                consumer_repo: consumer.repo,
+                consumer_file: consumer.file,
+                confidence: /[.:/-]/.test(producer.topic) ? "high" : "medium",
+                evidence: `${producer.evidence}; ${consumer.evidence}`,
+            });
+        }
+    }
+    return contracts
+        .sort((a, b) => a.topic.localeCompare(b.topic) || a.producer_repo.localeCompare(b.producer_repo) || a.consumer_repo.localeCompare(b.consumer_repo))
+        .slice(0, 50);
+}
+function workspaceGitCommits(repo, repoRoot, limit = 250) {
+    const graph = readCurrentCodeGraph(repoRoot);
+    const graphPaths = new Set(graph?.files.map((file) => file.path) ?? []);
+    if (!graphPaths.size)
+        return [];
+    const raw = readGit(repoRoot, ["log", `-${limit}`, "--format=__KAGE_COMMIT__%x1f%an <%ae>%x1f%ct%x1f%cI", "--name-only", "--no-renames"]) ?? "";
+    const records = [];
+    let current = null;
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        if (line.startsWith("__KAGE_COMMIT__")) {
+            if (current?.files.length)
+                records.push(current);
+            const [, author = "", timestamp = "0", iso = ""] = line.split("\x1f");
+            current = {
+                repo: repo.alias,
+                author: author.trim(),
+                timestamp: Number(timestamp) || 0,
+                iso: iso.trim() || null,
+                files: [],
+            };
+            continue;
+        }
+        if (current && graphPaths.has(line) && !isNoisePath(line))
+            current.files.push(line);
+    }
+    if (current?.files.length)
+        records.push(current);
+    return records;
+}
+function workspaceCoChanges(workspaceDir, repos) {
+    const recordsByAuthor = new Map();
+    for (const repo of repos) {
+        const repoRoot = repo.path === "." ? workspaceDir : (0, node_path_1.join)(workspaceDir, repo.path);
+        for (const record of workspaceGitCommits(repo, repoRoot)) {
+            if (!record.author || !record.timestamp || !record.files.length)
+                continue;
+            const list = recordsByAuthor.get(record.author) ?? [];
+            list.push(record);
+            recordsByAuthor.set(record.author, list);
+        }
+    }
+    const windowSeconds = 24 * 60 * 60;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const pairs = new Map();
+    const pairKey = (left, leftFile, right, rightFile) => {
+        const a = { repo: left.repo, file: leftFile };
+        const b = { repo: right.repo, file: rightFile };
+        if (`${a.repo}/${a.file}` <= `${b.repo}/${b.file}`)
+            return { key: `${a.repo}\0${a.file}\0${b.repo}\0${b.file}`, source: a, target: b };
+        return { key: `${b.repo}\0${b.file}\0${a.repo}\0${a.file}`, source: b, target: a };
+    };
+    for (const [author, records] of recordsByAuthor.entries()) {
+        const ordered = records.slice().sort((a, b) => a.timestamp - b.timestamp);
+        for (let i = 0; i < ordered.length; i += 1) {
+            const left = ordered[i];
+            for (let j = i + 1; j < ordered.length; j += 1) {
+                const right = ordered[j];
+                const delta = right.timestamp - left.timestamp;
+                if (delta > windowSeconds)
+                    break;
+                if (left.repo === right.repo)
+                    continue;
+                const ageDays = Math.max(0, (nowSeconds - Math.max(left.timestamp, right.timestamp)) / 86400);
+                const weight = Number((1 / (1 + ageDays / 180)).toFixed(3));
+                for (const leftFile of unique(left.files).slice(0, 20)) {
+                    for (const rightFile of unique(right.files).slice(0, 20)) {
+                        const { key, source, target } = pairKey(left, leftFile, right, rightFile);
+                        const existing = pairs.get(key) ?? {
+                            source_repo: source.repo,
+                            source_file: source.file,
+                            target_repo: target.repo,
+                            target_file: target.file,
+                            frequency: 0,
+                            strength: 0,
+                            last_seen_at: null,
+                            last_timestamp: 0,
+                            authors: new Set(),
+                        };
+                        existing.frequency += 1;
+                        existing.strength = Number((existing.strength + weight).toFixed(3));
+                        existing.authors.add(author);
+                        const seenAt = Math.max(left.timestamp, right.timestamp);
+                        if (seenAt > existing.last_timestamp) {
+                            existing.last_timestamp = seenAt;
+                            existing.last_seen_at = right.timestamp >= left.timestamp ? right.iso : left.iso;
+                        }
+                        pairs.set(key, existing);
+                    }
+                }
+            }
+        }
+    }
+    return [...pairs.values()]
+        .map((pair) => ({
+        source_repo: pair.source_repo,
+        source_file: pair.source_file,
+        target_repo: pair.target_repo,
+        target_file: pair.target_file,
+        frequency: pair.frequency,
+        strength: Number(pair.strength.toFixed(3)),
+        last_seen_at: pair.last_seen_at,
+        authors: [...pair.authors].sort(),
+        evidence: `${pair.source_repo}/${pair.source_file} and ${pair.target_repo}/${pair.target_file} changed near each other ${pair.frequency} time(s) by ${pair.authors.size} author(s).`,
+    }))
+        .filter((pair) => pair.frequency > 0)
+        .sort((a, b) => b.strength - a.strength || b.frequency - a.frequency || a.source_repo.localeCompare(b.source_repo) || a.source_file.localeCompare(b.source_file))
+        .slice(0, 50);
+}
 function kageWorkspace(projectDir) {
     const root = (0, node_path_1.resolve)(projectDir);
     const warnings = [];
@@ -6512,6 +6713,8 @@ function kageWorkspace(projectDir) {
         return { ...rest, dependencies_on_workspace_repos: deps };
     });
     const routeContracts = workspaceRouteContracts(root, repos);
+    const topicContracts = workspaceTopicContracts(root, repos);
+    const coChanges = workspaceCoChanges(root, repos);
     if (repos.length && repos.every((repo) => !repo.indexed))
         warnings.push("Workspace repos were found, but none has .agent_memory yet. Run kage init or kage refresh in each repo you want searchable.");
     return {
@@ -6521,8 +6724,10 @@ function kageWorkspace(projectDir) {
         repos,
         package_dependencies: packageDependencies.sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to)),
         route_contracts: routeContracts,
+        topic_contracts: topicContracts,
+        co_changes: coChanges,
         warnings,
-        summary: `${repos.length} repo(s), ${repos.filter((repo) => repo.indexed).length} with Kage memory, ${packageDependencies.length} workspace package dependenc${packageDependencies.length === 1 ? "y" : "ies"}, ${routeContracts.length} route contract link(s).`,
+        summary: `${repos.length} repo(s), ${repos.filter((repo) => repo.indexed).length} with Kage memory, ${packageDependencies.length} workspace package dependenc${packageDependencies.length === 1 ? "y" : "ies"}, ${routeContracts.length} route contract link(s), ${topicContracts.length} topic contract link(s), ${coChanges.length} cross-repo co-change link(s).`,
     };
 }
 function kageWorkspaceRecall(projectDir, query, limit = 8) {

package/package.json

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

package/viewer/app.js

@@ -2619,6 +2619,8 @@
       var repos = Array.isArray(workspace.repos) ? workspace.repos : [];
       var deps = Array.isArray(workspace.package_dependencies) ? workspace.package_dependencies : [];
       var contracts = Array.isArray(workspace.route_contracts) ? workspace.route_contracts : [];
+      var topics = Array.isArray(workspace.topic_contracts) ? workspace.topic_contracts : [];
+      var coChanges = Array.isArray(workspace.co_changes) ? workspace.co_changes : [];
       cards.push({
         title: "Workspace",
         kicker: "multi-repo memory",
@@ -2627,7 +2629,9 @@
           ["Repos", String(repos.length)],
           ["Indexed", String(repos.filter(function (repo) { return repo.indexed; }).length)],
           ["Package deps", String(deps.length)],
-          ["Route links", String(contracts.length)]
+          ["Route links", String(contracts.length)],
+          ["Topic links", String(topics.length)],
+          ["Co-changes", String(coChanges.length)]
         ].concat(repos.slice(0, 2).map(function (repo) { return [repo.alias, repo.approved_packets + " packets, " + repo.code_files + " files"]; }))
       });
     }