@kentwynn/kgraph 0.1.21 → 0.1.23

package/dist/cognition/cognition-quality.js

@@ -1,6 +1,8 @@
 import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
+import { buildSessionReport } from '../session/session-store.js';
 export async function analyzeCognitionQuality(workspace, maps) {
     const notes = await readCognitionNotes(workspace);
+    const session = await buildSessionReport(workspace);
     const changes = notes
         .map((note) => analyzeNote(note, maps))
         .filter((change) => change.removedFileRefs.length > 0 ||
@@ -10,11 +12,20 @@ export async function analyzeCognitionQuality(workspace, maps) {
         mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
+        unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
+        unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
+        duplicateTitleCount: countDuplicateTitles(notes),
+        generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
+        expensiveFileCount: countExpensiveFiles(maps.fileMap),
+        sessionRepeatedReadCount: session.repeatedReadCount,
+        sessionEstimatedReadTokens: session.estimatedReadTokens,
+        sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
         changes,
     };
 }
 export async function repairCognition(workspace, maps, dryRun = false) {
     const notes = await readCognitionNotes(workspace);
+    const session = await buildSessionReport(workspace);
     const nextNotes = [];
     const changes = [];
     for (const note of notes) {
@@ -37,9 +48,58 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
+        unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
+        unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
+        duplicateTitleCount: countDuplicateTitles(nextNotes),
+        generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
+        expensiveFileCount: countExpensiveFiles(maps.fileMap),
+        sessionRepeatedReadCount: session.repeatedReadCount,
+        sessionEstimatedReadTokens: session.estimatedReadTokens,
+        sessionEstimatedRepeatedReadTokens: session.estimatedRepeatedReadTokens,
         changes,
     };
 }
+function countUnresolvedLocalImports(dependencyMap) {
+    return (dependencyMap?.dependencies.filter((dependency) => dependency.kind === 'local' && !dependency.resolvedFile).length ?? 0);
+}
+function countUnresolvedCalls(symbolMap, relationshipMap) {
+    const symbolIds = new Set(symbolMap.symbols.map((symbol) => symbol.id));
+    const symbolNames = new Set(symbolMap.symbols.map((symbol) => symbol.name));
+    return (relationshipMap?.relationships.filter((relationship) => relationship.relationshipType === 'calls' &&
+        relationship.targetType === 'symbol' &&
+        !symbolIds.has(relationship.targetId) &&
+        !symbolNames.has(relationship.targetId) &&
+        ![...symbolNames].some((name) => relationship.targetId.endsWith(`#${name}`))).length ?? 0);
+}
+function countDuplicateTitles(notes) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const note of notes) {
+        const key = note.title.trim().toLowerCase();
+        if (!key)
+            continue;
+        if (seen.has(key))
+            duplicates.add(key);
+        seen.add(key);
+    }
+    return duplicates.size;
+}
+function countGeneratedScannedFiles(fileMap) {
+    return fileMap.files.filter((file) => [
+        '.agents/',
+        '.claude/',
+        '.cursor/',
+        '.windsurf/',
+        '.clinerules/',
+        '.github/prompts/',
+        'AGENTS.md',
+        'CLAUDE.md',
+        'GEMINI.md',
+    ].some((prefix) => file.path === prefix || file.path.startsWith(prefix))).length;
+}
+function countExpensiveFiles(fileMap) {
+    return fileMap.files.filter((file) => (file.tokenEstimate ?? 0) >= 1000).length;
+}
 function analyzeNote(note, maps) {
     const filePaths = new Set(maps.fileMap.files.map((file) => file.path));
     const symbolNames = new Set(maps.symbolMap.symbols.map((symbol) => symbol.name));

package/dist/config/config.js

@@ -150,8 +150,14 @@ function normalizeIntegrations(value) {
         integrations.push({
             name: candidate.name,
             enabled: candidate.enabled !== false,
+            mode: normalizeIntegrationMode(candidate.mode),
             targetPath: candidate.targetPath,
         });
     }
     return integrations;
 }
+function normalizeIntegrationMode(value) {
+    return value === 'always' || value === 'manual' || value === 'off'
+        ? value
+        : 'smart';
+}

package/dist/context/context-query.js

@@ -12,6 +12,7 @@ export async function queryContext(workspace, config, maps, query) {
         { name: 'name', value: (symbol) => symbol.name },
         { name: 'path', value: (symbol) => symbol.filePath },
         { name: 'kind', value: (symbol) => symbol.kind },
+        { name: 'parent', value: (symbol) => symbol.parentName },
     ]).slice(0, max);
     const relevantCognition = rankByFields(query, cognition, [
         { name: 'title', value: (note) => note.title },

package/dist/context/impact.d.ts

@@ -0,0 +1,20 @@
+import type { CognitionNote } from '../types/cognition.js';
+import type { DependencyMap, FileMap, Relationship, RelationshipMap, SymbolMap } from '../types/maps.js';
+import { type Ranked } from './ranking.js';
+export interface ImpactResponse {
+    query: string;
+    files: Ranked<FileMap['files'][number]>[];
+    symbols: Ranked<SymbolMap['symbols'][number]>[];
+    importedBy: string[];
+    callers: Relationship[];
+    calls: Relationship[];
+    ownership: Relationship[];
+    relatedCognition: CognitionNote[];
+    risk: string[];
+}
+export declare function analyzeImpact(query: string, maps: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+    dependencyMap: DependencyMap;
+    relationshipMap: RelationshipMap;
+}, cognition: CognitionNote[], max?: number): ImpactResponse;

package/dist/context/impact.js

@@ -0,0 +1,72 @@
+import { rankByFields } from './ranking.js';
+export function analyzeImpact(query, maps, cognition, max = 8) {
+    const files = rankByFields(query, maps.fileMap.files, [
+        { name: 'path', value: (file) => file.path },
+        { name: 'language', value: (file) => file.language },
+    ]).slice(0, max);
+    const symbols = rankByFields(query, maps.symbolMap.symbols, [
+        { name: 'name', value: (symbol) => symbol.name },
+        { name: 'path', value: (symbol) => symbol.filePath },
+        { name: 'kind', value: (symbol) => symbol.kind },
+        { name: 'parent', value: (symbol) => symbol.parentName },
+    ]).slice(0, max);
+    const filePaths = new Set([
+        ...files.map((file) => file.item.path),
+        ...symbols.map((symbol) => symbol.item.filePath),
+    ]);
+    const symbolIds = new Set(symbols.map((symbol) => symbol.item.id));
+    const symbolNames = new Set(symbols.map((symbol) => symbol.item.name));
+    const importHints = new Set([
+        ...[...filePaths].map((file) => basenameWithoutExtension(file).toLowerCase()),
+        ...[...symbolNames].map((name) => name.toLowerCase()),
+    ]);
+    const importedBy = unique(maps.dependencyMap.dependencies
+        .filter((dep) => (dep.resolvedFile && filePaths.has(dep.resolvedFile)) ||
+        [...importHints].some((hint) => hint && dep.specifier.toLowerCase().includes(hint)))
+        .map((dep) => dep.fromFile)).slice(0, max);
+    const calls = maps.relationshipMap.relationships
+        .filter((rel) => rel.relationshipType === 'calls' &&
+        (symbolIds.has(rel.sourceId) || symbolNames.has(rel.sourceId)))
+        .slice(0, max);
+    const callers = maps.relationshipMap.relationships
+        .filter((rel) => rel.relationshipType === 'calls' &&
+        (symbolIds.has(rel.targetId) || symbolNames.has(rel.targetId) || [...symbolNames].some((name) => rel.targetId.endsWith(`#${name}`))))
+        .slice(0, max);
+    const ownership = maps.relationshipMap.relationships
+        .filter((rel) => rel.relationshipType === 'symbol-contains' &&
+        (symbolIds.has(rel.sourceId) || symbolIds.has(rel.targetId)))
+        .slice(0, max);
+    const relatedCognition = cognition
+        .filter((note) => note.relatedFiles.some((file) => filePaths.has(file)) ||
+        note.relatedSymbols.some((symbol) => symbolNames.has(symbol) || symbolIds.has(symbol)))
+        .slice(0, max);
+    const risk = [];
+    if (importedBy.length > 2)
+        risk.push(`Shared file imported by ${importedBy.length} files`);
+    if (callers.length > 2)
+        risk.push(`Symbol called by ${callers.length} known callers`);
+    if (relatedCognition.some((note) => note.referencesStatus !== 'current')) {
+        risk.push('Related cognition has stale or mixed references');
+    }
+    if (calls.some((rel) => rel.confidence === 'low') || callers.some((rel) => rel.confidence === 'low')) {
+        risk.push('Some call relationships are low confidence');
+    }
+    return {
+        query,
+        files,
+        symbols,
+        importedBy,
+        callers,
+        calls,
+        ownership,
+        relatedCognition,
+        risk,
+    };
+}
+function unique(items) {
+    return [...new Set(items)];
+}
+function basenameWithoutExtension(filePath) {
+    const basename = filePath.split('/').pop() ?? filePath;
+    return basename.replace(/\.[^.]+$/, '');
+}

package/dist/context/ranking.js

@@ -1,9 +1,9 @@
 export function tokenize(query) {
-    return query
+    return expandTokens(query
         .toLowerCase()
         .split(/[^a-z0-9_$./-]+/)
         .map((token) => token.trim())
-        .filter(Boolean);
+        .filter(Boolean));
 }
 export function rankByFields(query, items, fields) {
     const tokens = tokenize(query);
@@ -14,14 +14,19 @@ export function rankByFields(query, items, fields) {
         for (const field of fields) {
             const value = field.value(item);
             const values = Array.isArray(value) ? value : value ? [value] : [];
-            const haystack = values.join(' ').toLowerCase();
+            const haystack = values.flatMap((value) => [value, splitIdentifier(value).join(' ')]).join(' ').toLowerCase();
             for (const token of tokens) {
                 if (haystack.includes(token)) {
-                    const baseScore = field.name === 'path' || field.name === 'name' ? 3 : 1;
+                    const baseScore = field.name === 'path' || field.name === 'name'
+                        ? 4
+                        : field.name === 'summary' || field.name === 'title'
+                            ? 2
+                            : 1;
                     const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
                     const wordBoundary = new RegExp(`\\b${escaped}\\b`).test(haystack);
-                    score += baseScore + (wordBoundary ? 2 : 0);
-                    reasons.push(`${field.name} matched "${token}"${wordBoundary ? ' (exact)' : ''}`);
+                    const exactValue = values.some((value) => value.toLowerCase() === token);
+                    score += baseScore + (wordBoundary ? 2 : 0) + (exactValue ? 4 : 0);
+                    reasons.push(`${field.name} matched "${token}"${wordBoundary || exactValue ? ' (exact)' : ''}`);
                 }
             }
         }
@@ -30,3 +35,13 @@ export function rankByFields(query, items, fields) {
         .filter((ranked) => ranked.score > 0)
         .sort((a, b) => b.score - a.score);
 }
+function expandTokens(tokens) {
+    return [...new Set(tokens.flatMap((token) => [token, ...splitIdentifier(token)]))];
+}
+function splitIdentifier(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[^A-Za-z0-9_$]+/)
+        .map((part) => part.toLowerCase())
+        .filter((part) => part.length > 1);
+}

package/dist/integrations/adapters/claude-code.js

@@ -4,7 +4,7 @@ export const claudeCodeAdapter = {
     targetPath: 'CLAUDE.md',
     instructions: `## KGraph Workflow
 
-Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intelligence and load focused context. Use /kgraph for the full automated workflow. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
+{{KGRAPH_CONTEXT_POLICY}} Use /kgraph for the full automated workflow. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
     commandFiles: [
         {
@@ -12,16 +12,18 @@ Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intell
             content: `Use KGraph persistent repo intelligence for the current request.
 
 1. Infer the topic from the user's request.
-2. Run \`kgraph "<topic>"\`. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
+2. {{KGRAPH_CONTEXT_POLICY}}
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
 4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-6. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-7. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-8. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
-9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-10. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-11. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+5. Track meaningful session activity with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code\` when native hooks are unavailable.
+6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+7. At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+8. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+9. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+10. After the final \`kgraph\` run, mention whether the inbox note was processed.
+11. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+13. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -64,13 +66,69 @@ Any implementation or product decision future sessions should know.
         {
             path: '.claude/commands/kgraph-visualize.md',
             content: `Run \`kgraph visualize\` to start an interactive dependency graph at http://localhost:4242. Opens in browser automatically. Use \`--no-open\` to print URL only, \`--port <n>\` for a custom port.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-impact.md',
+            content: `Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-session.md',
+            content: `Use \`kgraph session\` to inspect session read/write/token estimates. Record meaningful events with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code\`.
 `,
         },
         {
             path: '.claude/commands/kgraph-history.md',
-            content: `Run \`kgraph history\` to show a timeline of all processed cognition sessions. Includes git author attribution when available. Use \`--last <n>\` to limit entries, \`--json\` for machine-readable output.
+            content: `Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to show processed cognition sessions. Includes git author attribution when available. Use \`--last <n>\` to limit entries, \`--json\` for machine-readable output.
 `,
         },
+        {
+            path: '.claude/hooks/kgraph-session-start.cjs',
+            content: hookScript('start'),
+        },
+        {
+            path: '.claude/hooks/kgraph-session-pre-read.cjs',
+            content: hookScript('read'),
+        },
+        {
+            path: '.claude/hooks/kgraph-session-post-write.cjs',
+            content: hookScript('write'),
+        },
+        {
+            path: '.claude/hooks/kgraph-session-stop.cjs',
+            content: hookScript('end'),
+        },
     ],
     obsoleteCommandFiles: [],
 };
+function hookScript(event) {
+    const pathArg = event === 'read' || event === 'write'
+        ? `const payload = readPayload();
+const filePath = payload?.tool_input?.file_path || payload?.toolInput?.file_path || payload?.file_path;
+if (!filePath) process.exit(0);
+args.push(filePath);`
+        : '';
+    return `#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+
+function readPayload() {
+  try {
+    const chunks = [];
+    let chunk;
+    while ((chunk = require('node:fs').readFileSync(0, { encoding: 'utf8' }))) {
+      chunks.push(chunk);
+      break;
+    }
+    return chunks.join('') ? JSON.parse(chunks.join('')) : {};
+  } catch {
+    return {};
+  }
+}
+
+const args = ['session', '${event}', '--agent', 'claude-code', '--source', 'automatic'];
+${pathArg}
+const result = spawnSync('kgraph', args, { stdio: 'ignore' });
+process.exit(result.status || 0);
+`;
+}

package/dist/integrations/adapters/cline.js

@@ -4,14 +4,16 @@ export const clineAdapter = {
     targetPath: '.clinerules/kgraph.md',
     instructions: `# KGraph Workflow
 
-- **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+- {{KGRAPH_CONTEXT_POLICY}}
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-- If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-- Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+- Track meaningful session activity with \`kgraph session start --agent cline\`, \`kgraph session read <path> --agent cline\`, \`kgraph session write <path> --agent cline\`, and \`kgraph session end --agent cline\`.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- After the final \`kgraph\` run, mention whether the inbox note was processed.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
 };

package/dist/integrations/adapters/codex.js

@@ -4,14 +4,14 @@ export const codexAdapter = {
     targetPath: 'AGENTS.md',
     instructions: `## KGraph Workflow
 
-Before exploring the repository, run \`kgraph "<topic>"\` to refresh repo intelligence and load focused context. The /kgraph skill handles the full automated workflow. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
+{{KGRAPH_CONTEXT_POLICY}} The /kgraph skill handles the full automated workflow. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
     commandFiles: [
         {
             path: '.agents/skills/kgraph/SKILL.md',
             content: `---
 name: kgraph
-description: Use KGraph persistent repo intelligence before broad repository exploration. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
+description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
 ---
 
 # KGraph Skill
@@ -19,16 +19,18 @@ description: Use KGraph persistent repo intelligence before broad repository exp
 Workflow:
 
 1. Infer the current topic from the user request.
-2. Run \`kgraph "<topic>"\` before broad repo exploration. This refreshes maps, processes pending inbox notes, and returns focused context in one command.
+2. {{KGRAPH_CONTEXT_POLICY}}
 3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
 4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-6. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-7. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-8. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
-9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-10. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-11. Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+5. Track meaningful session activity with \`kgraph session start --agent codex\`, \`kgraph session read <path> --agent codex\`, \`kgraph session write <path> --agent codex\`, and \`kgraph session end --agent codex\`.
+6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+7. At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+8. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+9. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+10. After the final \`kgraph\` run, mention whether the inbox note was processed.
+11. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+13. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 
 The inbox note must use this structure:
 \`\`\`markdown

package/dist/integrations/adapters/copilot.js

@@ -4,13 +4,15 @@ export const copilotAdapter = {
     targetPath: '.github/copilot-instructions.md',
     instructions: `## KGraph Workflow
 
-1. **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+1. {{KGRAPH_CONTEXT_POLICY}}
 2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-3. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-4. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-5. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-6. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
-7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+3. Track meaningful session activity with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot\`.
+4. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+5. At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+6. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+7. Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+8. After the final \`kgraph\` run, mention whether the inbox note was processed.
+9. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 
 The inbox note must use this structure:
 \`\`\`markdown
@@ -91,9 +93,9 @@ argument-hint: "Brief description of what was done"
 
 Capture this session into KGraph cognition.
 
-1. For any completed code or repo-file change, check whether it has future value before finishing.
-2. Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-3. Write one Markdown note to \`.kgraph/inbox/<slug>.md\` using the structure below. Use the user's message as context, but keep the note factual and concise.
+1. For any completed code or repo-file change, write one Markdown note to \`.kgraph/inbox/<slug>.md\` using the structure below.
+2. Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+3. Use the user's message as context, but keep the note factual and concise.
 4. Run \`kgraph\` once to process the note and refresh maps. Use \`kgraph update\` only when you intentionally want inbox processing without a scan.
 
 Note structure:
@@ -112,6 +114,28 @@ One or two sentences describing what was done.
 ## Decisions
 Any architectural or implementation decisions made.
 \`\`\`
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-impact.prompt.md',
+            content: `---
+description: Show KGraph change impact for a file, symbol, or topic
+agent: agent
+argument-hint: "File, symbol, or topic"
+---
+
+Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-session.prompt.md',
+            content: `---
+description: Track KGraph session read/write activity and token estimates
+agent: agent
+argument-hint: "start, read <path>, write <path>, end, or status"
+---
+
+Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot\`.
 `,
         },
         {
@@ -119,9 +143,10 @@ Any architectural or implementation decisions made.
             content: `---
 description: Show timeline of KGraph cognition sessions with git attribution
 agent: agent
+argument-hint: "Optional topic"
 ---
 
-Run \`kgraph history\` to display the timeline of all processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
+Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
 `,
         },
     ],

package/dist/integrations/adapters/cursor.js

@@ -9,15 +9,17 @@ alwaysApply: true
 
 ## KGraph Workflow
 
-- **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+- {{KGRAPH_CONTEXT_POLICY}}
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-- If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-- Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+- Track meaningful session activity with \`kgraph session start --agent cursor\`, \`kgraph session read <path> --agent cursor\`, \`kgraph session write <path> --agent cursor\`, and \`kgraph session end --agent cursor\`.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- After the final \`kgraph\` run, mention whether the inbox note was processed.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
     obsoleteCommandFiles: ['.cursor/rules/kgraph-commands.mdc'],
 };

package/dist/integrations/adapters/gemini.js

@@ -4,14 +4,16 @@ export const geminiAdapter = {
     targetPath: 'GEMINI.md',
     instructions: `## KGraph Workflow
 
-- **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+- {{KGRAPH_CONTEXT_POLICY}}
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-- If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-- Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+- Track meaningful session activity with \`kgraph session start --agent gemini\`, \`kgraph session read <path> --agent gemini\`, \`kgraph session write <path> --agent gemini\`, and \`kgraph session end --agent gemini\`.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- After the final \`kgraph\` run, mention whether the inbox note was processed.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
 };

package/dist/integrations/adapters/windsurf.js

@@ -4,14 +4,16 @@ export const windsurfAdapter = {
     targetPath: '.windsurf/rules/kgraph.md',
     instructions: `# KGraph Workflow
 
-- **Before exploring the repository**, run \`kgraph "<topic>"\` to refresh maps, process pending inbox notes, and load focused repo intelligence. Use the returned files, symbols, relationships, and cognition before any broad exploration.
+- {{KGRAPH_CONTEXT_POLICY}}
 - Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-- If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-- Skip capture only for read-only work, trivial formatting, typo-only docs, dependency-only churn, mechanical cleanup with no future value, or sessions where no repo files changed.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write any needed inbox note first, then run \`kgraph\` once at the end.
+- Track meaningful session activity with \`kgraph session start --agent windsurf\`, \`kgraph session read <path> --agent windsurf\`, \`kgraph session write <path> --agent windsurf\`, and \`kgraph session end --agent windsurf\`.
+- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
+- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+- Do not run KGraph repeatedly. Run it once at the start with \`kgraph "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
+- After the final \`kgraph\` run, mention whether the inbox note was processed.
 - Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` to review the timeline of past cognition sessions with git author attribution.
+- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
 };