@kentwynn/kgraph 0.1.22 → 0.1.24

package/README.md

@@ -107,19 +107,31 @@ kgraph "auth token refresh"
 kgraph doctor
 ```
 
-After useful AI work, assistants can save durable notes into `.kgraph/inbox/`. The next `kgraph` run processes those notes automatically. You can also process them directly with `kgraph update`.
+After useful AI work, assistants save durable runtime-capture notes into `.kgraph/inbox/`. These notes are not project documentation; they are KGraph input files that the next `kgraph` run processes automatically. You can also process them directly with `kgraph update`.
 
 Normal agent flow is intentionally small:
 
 ```bash
 kgraph "topic"
 # work normally
-# if repo files changed, write an inbox note when the change has future value
+# if repo files changed, write an inbox note before the final refresh
 kgraph
 ```
 
 Use `kgraph doctor --quality` and `kgraph repair --dry-run` only when stale or noisy cognition references start making context harder to trust.
 
+Agents can also report session activity so KGraph can estimate token waste:
+
+```bash
+kgraph session start --agent codex
+kgraph session read src/auth.ts --agent codex
+kgraph session write src/auth.ts --agent codex
+kgraph session end --agent codex
+kgraph session
+```
+
+This is optional. Claude Code can use generated hook scripts for automatic capture; other agents use the same commands through their managed instructions, rules, or prompts.
+
 ## Main Commands
 
 ```bash
@@ -167,6 +179,18 @@ kgraph impact "createSession" --json
 
 Show practical impact for a file, symbol, or topic: matched files/symbols, import users, callers, callees, ownership edges, related cognition, and risk hints.
 
+```bash
+kgraph session
+kgraph session --json
+kgraph session reset
+kgraph session start --agent codex
+kgraph session read src/auth.ts --agent codex
+kgraph session write src/auth.ts --agent codex
+kgraph session end --agent codex
+```
+
+Track agent-reported read/write activity, repeated reads, and estimated token cost. Supported agents are `codex`, `claude-code`, `copilot`, `cursor`, `gemini`, `windsurf`, and `cline`.
+
 ## Optional Step Commands
 
 These are useful for scripting, debugging, or when you want a single operation.
@@ -214,10 +238,21 @@ KGraph integrations are local files. They do not start background agents, call A
 
 ```bash
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
+kgraph integrate add copilot --mode always
+kgraph integrate set copilot --mode manual
 kgraph integrate list
 kgraph integrate remove cursor
 ```
 
+New integrations default to `always` mode because coding agents often under-classify small UI, route, button, and link changes as not needing repo context.
+
+| Mode | Behavior |
+| --- | --- |
+| `always` | Every chat in the repository starts with `kgraph "<topic>"`, even simple or conversational requests. |
+| `smart` | Runs KGraph automatically for repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests. Skips simple conversational requests that do not depend on repo knowledge. |
+| `manual` | Exposes KGraph commands and instructions, but the agent runs KGraph only when the user explicitly asks. |
+| `off` | Disables that integration and removes generated KGraph instruction blocks/command files. |
+
 | Tool | Files KGraph manages |
 | --- | --- |
 | Codex | `AGENTS.md`, `.agents/skills/kgraph/SKILL.md` |
@@ -248,6 +283,7 @@ All runtime data lives under `.kgraph/`:
 ├── cognition/
 ├── domains/
 ├── interactions/processed/
+├── sessions/
 └── context/
 ```
 

package/dist/cli/commands/doctor.js

@@ -115,6 +115,10 @@ export function printQualityReport(report) {
     console.log(`Unresolved call edges: ${report.unresolvedCallCount}`);
     console.log(`Duplicate cognition titles: ${report.duplicateTitleCount}`);
     console.log(`Generated files scanned: ${report.generatedFileScanCount}`);
+    console.log(`Expensive files: ${report.expensiveFileCount}`);
+    console.log(`Session repeated reads: ${report.sessionRepeatedReadCount}`);
+    console.log(`Session estimated read tokens: ${report.sessionEstimatedReadTokens}`);
+    console.log(`Session repeated-read tokens: ${report.sessionEstimatedRepeatedReadTokens}`);
     if (report.changes.length === 0) {
         return;
     }

package/dist/cli/commands/init.js

@@ -2,13 +2,14 @@ import { writeDefaultConfig } from "../../config/config.js";
 import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
 import { addIntegrations } from "../../integrations/integration-store.js";
 import { ensureWorkspace } from "../../storage/kgraph-paths.js";
-import { runCommand } from "../errors.js";
+import { KGraphError, runCommand } from "../errors.js";
 export function registerInitCommand(program) {
     program
         .command("init")
         .description("Initialize a .kgraph workspace")
         .option("--integration <name>", "Configure an AI tool integration", collectOption, [])
         .option("--integrations <names>", "Configure comma-separated AI tool integrations")
+        .option("--mode <mode>", "Integration mode: smart, always, manual, or off", "always")
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         const wroteConfig = await writeDefaultConfig(workspace);
@@ -18,8 +19,9 @@ export function registerInitCommand(program) {
             ...(options.integrations ? [options.integrations] : [])
         ]);
         if (names.length > 0) {
-            const changed = await addIntegrations(workspace, names);
-            console.log(`Configured integrations: ${changed.map((item) => item.name).join(", ")}`);
+            const mode = normalizeIntegrationMode(options.mode);
+            const changed = await addIntegrations(workspace, names, mode);
+            console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
         }
     }));
 }
@@ -27,3 +29,9 @@ function collectOption(value, previous) {
     previous.push(value);
     return previous;
 }
+function normalizeIntegrationMode(value) {
+    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+        return value;
+    }
+    throw new KGraphError("--mode must be smart, always, manual, or off.");
+}

package/dist/cli/commands/integrate.js

@@ -1,4 +1,4 @@
-import { addIntegrations, listIntegrations, removeIntegrations } from "../../integrations/integration-store.js";
+import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode } from "../../integrations/integration-store.js";
 import { normalizeIntegrationNames } from "../../integrations/integration-registry.js";
 import { assertWorkspace } from "../../storage/kgraph-paths.js";
 import { KGraphError, runCommand } from "../errors.js";
@@ -12,17 +12,38 @@ export function registerIntegrateCommand(program) {
             return;
         }
         for (const integration of integrations) {
-            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
+            console.log(`${integration.name} ${integration.enabled ? "enabled" : "disabled"} ${integration.mode} ${integration.targetPath} ${integration.targetExists ? "present" : "missing"}`);
         }
     }));
-    integrate.command("add").description("Add AI tool integrations").argument("<names...>").action((names) => runCommand(async () => {
+    integrate
+        .command("add")
+        .description("Add AI tool integrations")
+        .argument("<names...>")
+        .option("--mode <mode>", "smart, always, manual, or off", "always")
+        .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
         if (normalized.length === 0) {
             throw new KGraphError("Provide at least one integration name.");
         }
-        const changed = await addIntegrations(workspace, normalized);
-        console.log(`Configured integrations: ${changed.map((item) => item.name).join(", ")}`);
+        const mode = normalizeIntegrationMode(options.mode);
+        const changed = await addIntegrations(workspace, normalized, mode);
+        console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
+    }));
+    integrate
+        .command("set")
+        .description("Set AI tool integration mode")
+        .argument("<names...>")
+        .requiredOption("--mode <mode>", "smart, always, manual, or off")
+        .action((names, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const normalized = normalizeIntegrationNames(names);
+        if (normalized.length === 0) {
+            throw new KGraphError("Provide at least one integration name.");
+        }
+        const mode = normalizeIntegrationMode(options.mode);
+        const changed = await setIntegrationMode(workspace, normalized, mode);
+        console.log(`Updated integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(", ")}`);
     }));
     integrate.command("remove").description("Remove AI tool integrations").argument("<names...>").action((names) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
@@ -34,3 +55,9 @@ export function registerIntegrateCommand(program) {
         console.log(`Removed integrations: ${removed.join(", ")}`);
     }));
 }
+function normalizeIntegrationMode(value) {
+    if (value === "smart" || value === "always" || value === "manual" || value === "off") {
+        return value;
+    }
+    throw new KGraphError("--mode must be smart, always, manual, or off.");
+}

package/dist/cli/commands/session.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { buildSessionReport } from '../../session/session-store.js';
+export declare function registerSessionCommand(program: Command): void;
+export declare function renderSessionReport(report: Awaited<ReturnType<typeof buildSessionReport>>): string;

package/dist/cli/commands/session.js

@@ -0,0 +1,112 @@
+import { assertSessionAgent, buildSessionReport, recordSessionEvent, resetSession, } from '../../session/session-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerSessionCommand(program) {
+    const session = program
+        .command('session')
+        .description('Track agent read/write session activity and token estimates')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const report = await buildSessionReport(workspace);
+        console.log(options.json ? JSON.stringify(report, null, 2) : renderSessionReport(report));
+    }));
+    session
+        .command('start')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'start',
+            captureSource: normalizeSource(options.source),
+        });
+        console.log(`KGraph session started for ${event.agent}.`);
+    }));
+    session
+        .command('read <path>')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((filePath, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const maps = await readMaps(workspace);
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'read',
+            path: filePath,
+            captureSource: normalizeSource(options.source),
+            fileMap: maps.fileMap,
+        });
+        console.log(`KGraph recorded read: ${event.path}${event.repeated ? ' (repeated)' : ''}${event.tokenEstimate !== undefined ? ` ~${event.tokenEstimate} tokens` : ''}.`);
+    }));
+    session
+        .command('write <path>')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((filePath, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const maps = await readMaps(workspace);
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'write',
+            path: filePath,
+            captureSource: normalizeSource(options.source),
+            fileMap: maps.fileMap,
+        });
+        console.log(`KGraph recorded write: ${event.path}${event.tokenEstimate !== undefined ? ` ~${event.tokenEstimate} tokens` : ''}.`);
+    }));
+    session
+        .command('end')
+        .requiredOption('--agent <name>', 'KGraph integration agent name')
+        .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const event = await recordSessionEvent(workspace, {
+            agent: requireAgent(options.agent),
+            type: 'end',
+            captureSource: normalizeSource(options.source),
+        });
+        console.log(`KGraph session ended for ${event.agent}.`);
+    }));
+    session
+        .command('reset')
+        .description('Clear the current session tracker')
+        .action(() => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        await resetSession(workspace);
+        console.log('KGraph current session reset.');
+    }));
+}
+export function renderSessionReport(report) {
+    const lines = ['', 'KGraph Session', ''];
+    lines.push(`Active agents: ${report.activeAgents.length === 0 ? 'none' : report.activeAgents.map((agent) => agent.agent).join(', ')}`);
+    lines.push(`Reads: ${report.readCount}`);
+    lines.push(`Writes: ${report.writeCount}`);
+    lines.push(`Repeated reads: ${report.repeatedReadCount}`);
+    lines.push(`Estimated read tokens: ${report.estimatedReadTokens}`);
+    lines.push(`Estimated repeated-read tokens: ${report.estimatedRepeatedReadTokens}`);
+    lines.push('', 'Top Repeated Reads');
+    lines.push(...formatList(report.topRepeatedReads.map((item) => `- ${item.path} read ${item.count} times (~${item.estimatedTokens} tokens)`)));
+    lines.push('', 'Recent Events');
+    lines.push(...formatList(report.recentEvents.map((event) => `- ${event.agent} ${event.type}${event.path ? ` ${event.path}` : ''} [${event.captureSource}]`)));
+    lines.push('', 'Recent Ledger');
+    lines.push(...formatList(report.ledger.map((entry) => `- ${entry.agent} ${entry.readCount} reads, ${entry.writeCount} writes, ${entry.repeatedReadCount} repeated`)));
+    return lines.join('\n');
+}
+function requireAgent(value) {
+    if (!value) {
+        throw new KGraphError('--agent is required.');
+    }
+    return assertSessionAgent(value);
+}
+function normalizeSource(value) {
+    if (value === 'automatic' || value === 'agent-reported' || value === 'manual') {
+        return value;
+    }
+    throw new KGraphError('--source must be automatic, agent-reported, or manual.');
+}
+function formatList(items) {
+    return items.length > 0 ? items : ['- None'];
+}

package/dist/cli/commands/workflow.js

@@ -36,6 +36,11 @@ export async function runDefaultWorkflow(query) {
             files: scan.files.length,
             symbols: scan.symbols.length,
             cognitionNotes: update.processed.length,
+            integrations: config.integrations.map((integration) => ({
+                name: integration.name,
+                mode: integration.mode,
+                enabled: integration.enabled,
+            })),
         }));
         console.log('');
         for (const warning of [...scan.warnings, ...update.warnings]) {

package/dist/cli/help.d.ts

@@ -3,6 +3,12 @@ interface WorkflowBannerStats {
     files: number;
     symbols: number;
     cognitionNotes: number;
+    integrations?: WorkflowBannerIntegration[];
+}
+interface WorkflowBannerIntegration {
+    name: string;
+    mode: string;
+    enabled: boolean;
 }
 export declare function renderWorkflowBanner(stats: WorkflowBannerStats, useColor?: boolean): string;
 export {};

package/dist/cli/help.js

@@ -27,6 +27,8 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         theme.bold('Workflows'),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
+        command('session', 'Show agent read/write activity and token estimates'),
+        command('session read src/auth.ts --agent codex', 'Record an agent file read'),
         command('context "auth token refresh"', 'Optional: return context without scanning or updating'),
         command('impact "Button"', 'Show imports, callers, calls, cognition, and risk'),
         command('update', 'Optional: process only .kgraph/inbox Markdown cognition notes'),
@@ -39,8 +41,11 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         theme.bold('Integrations'),
         command('integrate list', 'Show configured AI tool integrations'),
-        command('integrate add gemini windsurf cline', 'Write KGraph instructions for AI tools'),
+        command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
+        command('integrate add copilot --mode always', 'Every Copilot chat starts with kgraph "<topic>"'),
+        command('integrate set copilot --mode manual', 'Only run KGraph when explicitly requested'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
+        command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
         '',
         theme.bold('Options'),
         command('-V, --version', 'Show version'),
@@ -58,6 +63,13 @@ export function renderRootHelp(useColor = supportsColor()) {
 export function renderWorkflowBanner(stats, useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
+    const integrationLine = stats.integrations && stats.integrations.length > 0
+        ? stats.integrations
+            .map((integration) => integration.enabled
+            ? `${integration.name}:${integration.mode}`
+            : `${integration.name}:off`)
+            .join(', ')
+        : 'none configured';
     return [
         '',
         theme.hex('#7dd3fc').bold(renderLogo()),
@@ -68,11 +80,13 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('files', String(stats.files)),
         command('symbols', String(stats.symbols)),
         command('cognition notes processed', String(stats.cognitionNotes)),
+        command('integration modes', integrationLine),
         '',
         theme.bold('Next'),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
         command('kgraph doctor --quality', 'Check cognition quality'),
+        command('kgraph session', 'Check session token waste'),
         command('kgraph --help', 'Show all commands'),
     ].join('\n');
 }

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { registerInitCommand } from './commands/init.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
 import { registerRepairCommand } from './commands/repair.js';
 import { registerScanCommand } from './commands/scan.js';
+import { registerSessionCommand } from './commands/session.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerVisualizeCommand } from './commands/visualize.js';
 import { runDefaultWorkflow } from './commands/workflow.js';
@@ -38,6 +39,7 @@ export function createProgram() {
     });
     registerInitCommand(program);
     registerScanCommand(program);
+    registerSessionCommand(program);
     registerUpdateCommand(program);
     registerContextCommand(program);
     registerImpactCommand(program);

package/dist/cognition/cognition-quality.d.ts

@@ -17,6 +17,10 @@ export interface CognitionQualityReport {
     unresolvedCallCount: number;
     duplicateTitleCount: number;
     generatedFileScanCount: number;
+    expensiveFileCount: number;
+    sessionRepeatedReadCount: number;
+    sessionEstimatedReadTokens: number;
+    sessionEstimatedRepeatedReadTokens: number;
     changes: CognitionRepairChange[];
 }
 export declare function analyzeCognitionQuality(workspace: KGraphWorkspace, maps: {

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 ||
@@ -14,11 +16,16 @@ export async function analyzeCognitionQuality(workspace, maps) {
         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) {
@@ -45,6 +52,10 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         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,
     };
 }
@@ -86,6 +97,9 @@ function countGeneratedScannedFiles(fileMap) {
         '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/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,34 +12,17 @@ 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. 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.
-6. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-7. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-8. 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.
-9. 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.
-10. 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.
-11. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-12. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review 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.
 
-The inbox note must use this structure:
-\`\`\`markdown
-# <Short Title>
+{{KGRAPH_CAPTURE_POLICY}}
 
-## Summary
-One or two sentences describing the durable change or finding.
-
-## Key Files
-- \`path/to/file.ts\` — what changed or why it matters
-
-## Key Symbols
-- \`FunctionName\` — what changed or why it matters
-
-## Decisions
-Any implementation or product decision future sessions should know.
-\`\`\`
+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.
+8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
 `,
         },
         {
@@ -70,6 +53,11 @@ Any implementation or product decision future sessions should know.
         {
             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\`.
 `,
         },
         {
@@ -77,6 +65,52 @@ Any implementation or product decision future sessions should know.
             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,13 +4,11 @@ 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.
+- 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, 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.
+{{KGRAPH_CAPTURE_POLICY}}
 - 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.