@kentwynn/kgraph 0.1.22 → 0.1.23

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,17 +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. 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 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,14 +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. 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.
-4. At the end of any session that changed repository files, check the KGraph capture workflow before finishing.
-5. If the file change has future value, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\`; otherwise explicitly skip capture as trivial.
-6. 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.
-7. 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.
-8. 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
@@ -92,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:
@@ -124,6 +125,17 @@ 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\`.
 `,
         },
         {

package/dist/integrations/adapters/cursor.js

@@ -9,13 +9,14 @@ 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.
+- 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, 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.
+- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

package/dist/integrations/adapters/gemini.js

@@ -4,13 +4,14 @@ 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.
+- 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, 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.
+- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

package/dist/integrations/adapters/windsurf.js

@@ -4,13 +4,14 @@ 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.
+- 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, 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.
+- 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\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.

package/dist/integrations/instruction-blocks.d.ts

@@ -1,2 +1,6 @@
+import type { IntegrationMode } from "../types/config.js";
+export declare const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLICY}}";
 export declare function upsertManagedBlock(content: string, integrationName: string, instructions: string): string;
 export declare function removeManagedBlock(content: string, integrationName: string): string;
+export declare function applyContextPolicy(content: string, mode: IntegrationMode): string;
+export declare function renderContextPolicy(mode: IntegrationMode): string;

package/dist/integrations/instruction-blocks.js

@@ -1,5 +1,6 @@
 const MARKER_PREFIX = "<!--";
 const MARKER_SUFFIX = "-->";
+export const KGRAPH_CONTEXT_POLICY_PLACEHOLDER = "{{KGRAPH_CONTEXT_POLICY}}";
 export function upsertManagedBlock(content, integrationName, instructions) {
     const normalized = content.trimEnd();
     const block = renderManagedBlock(integrationName, instructions);
@@ -25,3 +26,19 @@ function managedBlockPattern(integrationName) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+export function applyContextPolicy(content, mode) {
+    return content.replaceAll(KGRAPH_CONTEXT_POLICY_PLACEHOLDER, renderContextPolicy(mode));
+}
+export function renderContextPolicy(mode) {
+    switch (mode) {
+        case "always":
+            return 'Every chat in this repository must start by running `kgraph "<topic>"` before answering or exploring files. Infer the topic from the user\'s message; no exceptions, including simple or conversational requests.';
+        case "manual":
+            return 'Do not run KGraph automatically. Run `kgraph "<topic>"` only when the user explicitly asks for KGraph context or invokes the KGraph command.';
+        case "off":
+            return "KGraph is disabled for this integration.";
+        case "smart":
+        default:
+            return 'For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run `kgraph "<topic>"` before broad repository exploration. Infer the topic from the user\'s message. Skip KGraph for simple conversational requests that do not depend on repo knowledge.';
+    }
+}

package/dist/integrations/integration-store.d.ts

@@ -1,10 +1,12 @@
-import type { IntegrationConfig, IntegrationName, KGraphWorkspace } from "../types/config.js";
+import type { IntegrationConfig, IntegrationMode, IntegrationName, KGraphWorkspace } from "../types/config.js";
 export interface IntegrationStatus {
     name: IntegrationName;
     enabled: boolean;
+    mode: IntegrationMode;
     targetPath: string;
     targetExists: boolean;
 }
 export declare function listIntegrations(workspace: KGraphWorkspace): Promise<IntegrationStatus[]>;
-export declare function addIntegrations(workspace: KGraphWorkspace, names: IntegrationName[]): Promise<IntegrationConfig[]>;
+export declare function addIntegrations(workspace: KGraphWorkspace, names: IntegrationName[], mode?: IntegrationMode): Promise<IntegrationConfig[]>;
+export declare function setIntegrationMode(workspace: KGraphWorkspace, names: IntegrationName[], mode: IntegrationMode): Promise<IntegrationConfig[]>;
 export declare function removeIntegrations(workspace: KGraphWorkspace, names: IntegrationName[]): Promise<IntegrationName[]>;

package/dist/integrations/integration-store.js

@@ -3,18 +3,19 @@ import path from "node:path";
 import { loadConfig, saveConfig } from "../config/config.js";
 import { pathExists } from "../storage/kgraph-paths.js";
 import { getIntegrationAdapter } from "./integration-registry.js";
-import { removeManagedBlock, upsertManagedBlock } from "./instruction-blocks.js";
+import { applyContextPolicy, removeManagedBlock, upsertManagedBlock } from "./instruction-blocks.js";
 export async function listIntegrations(workspace) {
     const config = await loadConfig(workspace);
     const statuses = await Promise.all(config.integrations.map(async (integration) => ({
         name: integration.name,
         enabled: integration.enabled,
+        mode: integration.mode,
         targetPath: integration.targetPath,
         targetExists: await pathExists(path.join(workspace.rootPath, integration.targetPath))
     })));
     return statuses.sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function addIntegrations(workspace, names) {
+export async function addIntegrations(workspace, names, mode = "always") {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];
@@ -22,19 +23,32 @@ export async function addIntegrations(workspace, names) {
         const adapter = getIntegrationAdapter(name);
         const next = {
             name: adapter.name,
-            enabled: true,
+            enabled: mode !== "off",
+            mode,
             targetPath: adapter.targetPath
         };
         byName.set(adapter.name, next);
-        await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, adapter.instructions);
+        if (mode === "off") {
+            await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
+            await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+        }
+        else {
+            await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
+            await writeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).map((file) => ({
+                ...file,
+                content: applyContextPolicy(file.content, mode)
+            })));
+        }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
-        await writeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
         changed.push(next);
     }
     config.integrations = [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
     await saveConfig(workspace, config);
     return changed;
 }
+export async function setIntegrationMode(workspace, names, mode) {
+    return addIntegrations(workspace, names, mode);
+}
 export async function removeIntegrations(workspace, names) {
     const config = await loadConfig(workspace);
     const removeNames = new Set(names);

package/dist/scanner/repo-scanner.js

@@ -10,6 +10,7 @@ import { extractJvmSymbols } from './jvm-symbol-extractor.js';
 import { extractPythonSymbols } from './python-symbol-extractor.js';
 import { extractRustSymbols } from './rust-symbol-extractor.js';
 import { extractTsSymbols } from './ts-symbol-extractor.js';
+import { estimateTokens } from '../session/token-estimator.js';
 const C_EXTS = new Set(['.c', '.h', '.cpp', '.cc', '.cxx', '.hpp', '.hxx']);
 const JVM_EXTS = new Set(['.java', '.kt', '.kts']);
 function extractSymbols(text, repoPath) {
@@ -73,6 +74,7 @@ export async function scanRepository(rootPath, config, previous) {
                 sizeBytes: info.size,
                 modifiedAt: info.mtime.toISOString(),
                 contentHash,
+                tokenEstimate: estimateTokens(text, repoPath),
                 scanStatus: isPreciseLanguage(repoPath, config) ? 'mapped' : 'generic',
                 warnings: [],
             };

package/dist/session/session-store.d.ts

@@ -0,0 +1,15 @@
+import type { KGraphWorkspace } from '../types/config.js';
+import type { FileMap } from '../types/maps.js';
+import type { SessionAgent, SessionCaptureSource, SessionEvent, SessionEventType, SessionLedgerEntry, SessionReport, SessionState } from '../types/session.js';
+export declare function assertSessionAgent(value: string): SessionAgent;
+export declare function readSessionState(workspace: KGraphWorkspace): Promise<SessionState>;
+export declare function resetSession(workspace: KGraphWorkspace): Promise<void>;
+export declare function readSessionLedger(workspace: KGraphWorkspace): Promise<SessionLedgerEntry[]>;
+export declare function recordSessionEvent(workspace: KGraphWorkspace, input: {
+    agent: SessionAgent;
+    type: SessionEventType;
+    path?: string;
+    captureSource: SessionCaptureSource;
+    fileMap?: FileMap;
+}): Promise<SessionEvent>;
+export declare function buildSessionReport(workspace: KGraphWorkspace): Promise<SessionReport>;

package/dist/session/session-store.js

@@ -0,0 +1,170 @@
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getIntegrationAdapter } from '../integrations/integration-registry.js';
+import { pathExists } from '../storage/kgraph-paths.js';
+import { KGraphError } from '../cli/errors.js';
+import { estimateTokens } from './token-estimator.js';
+const EMPTY_STATE = {
+    active: {},
+    events: [],
+    updatedAt: '',
+};
+export function assertSessionAgent(value) {
+    return getIntegrationAdapter(value).name;
+}
+export async function readSessionState(workspace) {
+    const filePath = currentPath(workspace);
+    if (!(await pathExists(filePath))) {
+        return { ...EMPTY_STATE, active: {}, events: [] };
+    }
+    return JSON.parse(await readFile(filePath, 'utf8'));
+}
+export async function resetSession(workspace) {
+    await rm(currentPath(workspace), { force: true });
+}
+export async function readSessionLedger(workspace) {
+    const filePath = ledgerPath(workspace);
+    if (!(await pathExists(filePath))) {
+        return [];
+    }
+    return JSON.parse(await readFile(filePath, 'utf8'));
+}
+export async function recordSessionEvent(workspace, input) {
+    const now = new Date().toISOString();
+    const state = await readSessionState(workspace);
+    const active = state.active[input.agent] ?? {
+        agent: input.agent,
+        sessionId: `${input.agent}-${now.replace(/[:.]/g, '-')}`,
+        startedAt: now,
+        lastEventAt: now,
+    };
+    const normalizedPath = input.path ? normalizeRepoPath(input.path) : undefined;
+    const tokenEstimate = normalizedPath && (input.type === 'read' || input.type === 'write')
+        ? await estimatePathTokens(workspace, normalizedPath, input.fileMap)
+        : undefined;
+    const repeated = input.type === 'read' && normalizedPath
+        ? state.events.some((event) => event.agent === input.agent &&
+            event.type === 'read' &&
+            event.path === normalizedPath)
+        : undefined;
+    const event = {
+        id: `${now}-${state.events.length + 1}`,
+        agent: input.agent,
+        type: input.type,
+        ...(normalizedPath ? { path: normalizedPath } : {}),
+        ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),
+        ...(repeated !== undefined ? { repeated } : {}),
+        captureSource: input.captureSource,
+        timestamp: now,
+    };
+    if (input.type === 'start') {
+        state.active[input.agent] = active;
+    }
+    else if (!state.active[input.agent]) {
+        state.active[input.agent] = active;
+    }
+    state.active[input.agent].lastEventAt = now;
+    state.events.push(event);
+    state.updatedAt = now;
+    if (input.type === 'end') {
+        await appendLedgerEntry(workspace, summarizeAgentSession(input.agent, state, now));
+        delete state.active[input.agent];
+    }
+    await writeSessionState(workspace, state);
+    return event;
+}
+export async function buildSessionReport(workspace) {
+    const [state, ledger] = await Promise.all([
+        readSessionState(workspace),
+        readSessionLedger(workspace),
+    ]);
+    const readEvents = state.events.filter((event) => event.type === 'read');
+    const writeEvents = state.events.filter((event) => event.type === 'write');
+    const repeatedReads = readEvents.filter((event) => event.repeated);
+    return {
+        activeAgents: Object.values(state.active),
+        readCount: readEvents.length,
+        writeCount: writeEvents.length,
+        repeatedReadCount: repeatedReads.length,
+        estimatedReadTokens: sumTokens(readEvents),
+        estimatedRepeatedReadTokens: sumTokens(repeatedReads),
+        topRepeatedReads: topRepeatedReads(readEvents),
+        recentEvents: state.events.slice(-10),
+        ledger: ledger.slice(-10),
+    };
+}
+async function estimatePathTokens(workspace, repoPath, fileMap) {
+    const mapped = fileMap?.files.find((file) => file.path === repoPath);
+    if (mapped?.tokenEstimate !== undefined) {
+        return mapped.tokenEstimate;
+    }
+    const fullPath = path.join(workspace.rootPath, repoPath);
+    try {
+        const info = await stat(fullPath);
+        if (!info.isFile()) {
+            return undefined;
+        }
+        const content = await readFile(fullPath, 'utf8');
+        return estimateTokens(content, repoPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeSessionState(workspace, state) {
+    await mkdir(workspace.sessionsPath, { recursive: true });
+    await writeFile(currentPath(workspace), `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+async function appendLedgerEntry(workspace, entry) {
+    const ledger = await readSessionLedger(workspace);
+    ledger.push(entry);
+    await mkdir(workspace.sessionsPath, { recursive: true });
+    await writeFile(ledgerPath(workspace), `${JSON.stringify(ledger, null, 2)}\n`, 'utf8');
+}
+function summarizeAgentSession(agent, state, endedAt) {
+    const active = state.active[agent];
+    if (!active) {
+        throw new KGraphError(`No active session for agent "${agent}".`);
+    }
+    const events = state.events.filter((event) => event.agent === agent && event.timestamp >= active.startedAt);
+    const reads = events.filter((event) => event.type === 'read');
+    const repeatedReads = reads.filter((event) => event.repeated);
+    return {
+        sessionId: active.sessionId,
+        agent,
+        startedAt: active.startedAt,
+        endedAt,
+        readCount: reads.length,
+        writeCount: events.filter((event) => event.type === 'write').length,
+        repeatedReadCount: repeatedReads.length,
+        estimatedReadTokens: sumTokens(reads),
+        estimatedRepeatedReadTokens: sumTokens(repeatedReads),
+    };
+}
+function topRepeatedReads(events) {
+    const byPath = new Map();
+    for (const event of events) {
+        if (!event.path)
+            continue;
+        const current = byPath.get(event.path) ?? { path: event.path, count: 0, estimatedTokens: 0 };
+        current.count += 1;
+        current.estimatedTokens += event.tokenEstimate ?? 0;
+        byPath.set(event.path, current);
+    }
+    return [...byPath.values()]
+        .filter((item) => item.count > 1)
+        .sort((left, right) => right.estimatedTokens - left.estimatedTokens)
+        .slice(0, 5);
+}
+function sumTokens(events) {
+    return events.reduce((total, event) => total + (event.tokenEstimate ?? 0), 0);
+}
+function normalizeRepoPath(value) {
+    return value.split(path.sep).join('/').replace(/^\.\//, '');
+}
+function currentPath(workspace) {
+    return path.join(workspace.sessionsPath, 'current.json');
+}
+function ledgerPath(workspace) {
+    return path.join(workspace.sessionsPath, 'ledger.json');
+}

package/dist/session/token-estimator.d.ts

@@ -0,0 +1 @@
+export declare function estimateTokens(content: string, filePath?: string): number;

package/dist/session/token-estimator.js

@@ -0,0 +1,17 @@
+export function estimateTokens(content, filePath = '') {
+    if (content.length === 0) {
+        return 0;
+    }
+    const ratio = tokenRatio(filePath);
+    return Math.max(1, Math.ceil(content.length / ratio));
+}
+function tokenRatio(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith('.md') || lower.endsWith('.txt'))
+        return 4.8;
+    if (lower.endsWith('.json') || lower.endsWith('.yaml') || lower.endsWith('.yml'))
+        return 3.8;
+    if (lower.endsWith('.html') || lower.endsWith('.css'))
+        return 3.6;
+    return 4.0;
+}

package/dist/storage/kgraph-paths.js

@@ -7,7 +7,8 @@ const WORKSPACE_DIRS = [
     "domains",
     "inbox",
     "interactions/processed",
-    "context"
+    "context",
+    "sessions"
 ];
 export function resolveWorkspace(rootPath = process.cwd()) {
     const kgraphPath = path.join(rootPath, ".kgraph");
@@ -20,7 +21,8 @@ export function resolveWorkspace(rootPath = process.cwd()) {
         domainsPath: path.join(kgraphPath, "domains"),
         inboxPath: path.join(kgraphPath, "inbox"),
         processedInteractionsPath: path.join(kgraphPath, "interactions", "processed"),
-        contextPath: path.join(kgraphPath, "context")
+        contextPath: path.join(kgraphPath, "context"),
+        sessionsPath: path.join(kgraphPath, "sessions")
     };
 }
 export async function pathExists(targetPath) {

package/dist/types/config.d.ts

@@ -13,9 +13,11 @@ export interface DomainHint {
     tags?: string[];
 }
 export type IntegrationName = "claude-code" | "cline" | "codex" | "copilot" | "cursor" | "gemini" | "windsurf";
+export type IntegrationMode = "smart" | "always" | "manual" | "off";
 export interface IntegrationConfig {
     name: IntegrationName;
     enabled: boolean;
+    mode: IntegrationMode;
     targetPath: string;
 }
 export interface KGraphWorkspace {
@@ -28,4 +30,5 @@ export interface KGraphWorkspace {
     inboxPath: string;
     processedInteractionsPath: string;
     contextPath: string;
+    sessionsPath: string;
 }

package/dist/types/maps.d.ts

@@ -10,6 +10,7 @@ export interface RepositoryFile {
     sizeBytes: number;
     modifiedAt?: string;
     contentHash: string;
+    tokenEstimate?: number;
     scanStatus: ScanStatus;
     warnings: string[];
 }

package/dist/types/session.d.ts

@@ -0,0 +1,51 @@
+import type { IntegrationName } from './config.js';
+export type SessionAgent = IntegrationName;
+export type SessionEventType = 'start' | 'read' | 'write' | 'end';
+export type SessionCaptureSource = 'automatic' | 'agent-reported' | 'manual';
+export interface SessionEvent {
+    id: string;
+    agent: SessionAgent;
+    type: SessionEventType;
+    path?: string;
+    tokenEstimate?: number;
+    repeated?: boolean;
+    captureSource: SessionCaptureSource;
+    timestamp: string;
+}
+export interface AgentSession {
+    agent: SessionAgent;
+    sessionId: string;
+    startedAt: string;
+    lastEventAt: string;
+}
+export interface SessionState {
+    active: Record<string, AgentSession>;
+    events: SessionEvent[];
+    updatedAt: string;
+}
+export interface SessionLedgerEntry {
+    sessionId: string;
+    agent: SessionAgent;
+    startedAt: string;
+    endedAt: string;
+    readCount: number;
+    writeCount: number;
+    repeatedReadCount: number;
+    estimatedReadTokens: number;
+    estimatedRepeatedReadTokens: number;
+}
+export interface SessionReport {
+    activeAgents: AgentSession[];
+    readCount: number;
+    writeCount: number;
+    repeatedReadCount: number;
+    estimatedReadTokens: number;
+    estimatedRepeatedReadTokens: number;
+    topRepeatedReads: Array<{
+        path: string;
+        count: number;
+        estimatedTokens: number;
+    }>;
+    recentEvents: SessionEvent[];
+    ledger: SessionLedgerEntry[];
+}

package/dist/types/session.js

@@ -0,0 +1 @@
+export {};

package/dist/visualization/graph-builder.d.ts

@@ -10,6 +10,7 @@ export interface GraphData {
         fileCount: number;
         symbolCount: number;
         cognitionCount: number;
+        tokenEstimate: number;
         generatedAt: string;
     };
 }