@kentwynn/kgraph 0.2.35 → 0.2.37

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

@@ -8,7 +8,7 @@ export interface HistoryEntry {
     author?: string;
 }
 export declare function registerHistoryCommand(program: Command): void;
-export declare function readHistoryEntries(processedPath: string, rootPath: string): Promise<HistoryEntry[]>;
+export declare function readHistoryEntries(processedPath: string, rootPath: string, cognitionPath?: string): Promise<HistoryEntry[]>;
 /**
  * Parses the UTC timestamp embedded in a processed interaction filename.
  * Filename format: 2026-05-09T09-36-06-247Z-slug.md

package/dist/cli/commands/history.js

@@ -3,8 +3,8 @@ import { execFile } from 'node:child_process';
 import { readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { assertWorkspace, pathExists } from '../../storage/kgraph-paths.js';
 import { rankByFields } from '../../context/ranking.js';
+import { assertWorkspace, pathExists } from '../../storage/kgraph-paths.js';
 import { KGraphError, runCommand } from '../errors.js';
 const execFileAsync = promisify(execFile);
 export function registerHistoryCommand(program) {
@@ -15,7 +15,7 @@ export function registerHistoryCommand(program) {
         .option('--json', 'Print JSON output')
         .action((queryParts = [], options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
-        const entries = await readHistoryEntries(workspace.processedInteractionsPath, workspace.rootPath);
+        const entries = await readHistoryEntries(workspace.processedInteractionsPath, workspace.rootPath, workspace.cognitionPath);
         const query = queryParts.join(' ').trim();
         const limit = options.last !== undefined ? parseInt(options.last, 10) : 0;
         if (options.last !== undefined && (isNaN(limit) || limit < 1)) {
@@ -44,29 +44,73 @@ export function registerHistoryCommand(program) {
         }
     }));
 }
-export async function readHistoryEntries(processedPath, rootPath) {
-    if (!(await pathExists(processedPath))) {
-        return [];
-    }
-    const dirents = await readdir(processedPath, { withFileTypes: true });
-    const filenames = dirents
-        .filter((e) => e.isFile() && e.name.endsWith('.md'))
-        .map((e) => e.name)
-        .sort(); // ISO-prefixed filenames sort chronologically
+export async function readHistoryEntries(processedPath, rootPath, cognitionPath) {
     const entries = [];
-    for (const filename of filenames) {
-        const timestamp = parseTimestampFromFilename(filename);
-        if (!timestamp)
-            continue;
-        const filePath = path.join(processedPath, filename);
-        const content = await readFile(filePath, 'utf8');
-        const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? filename;
-        const summary = content.match(/^## Summary\s+([\s\S]*?)(?:\n## |\n# |$)/m)?.[1]?.trim();
-        const relPath = path.relative(rootPath, filePath);
-        const author = await getGitAuthor(rootPath, relPath);
-        entries.push({ timestamp, filename, title, summary, text: content, author });
+    // Read inbox-processed interactions (raw notes archived from inbox by `kgraph update`)
+    if (await pathExists(processedPath)) {
+        const dirents = await readdir(processedPath, { withFileTypes: true });
+        const filenames = dirents
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+        for (const filename of filenames) {
+            const timestamp = parseTimestampFromFilename(filename);
+            if (!timestamp)
+                continue;
+            const filePath = path.join(processedPath, filename);
+            const content = await readFile(filePath, 'utf8');
+            const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? filename;
+            const summary = content
+                .match(/^## Summary\s+([\s\S]*?)(?:\n## |\n# |$)/m)?.[1]
+                ?.trim();
+            const relPath = path.relative(rootPath, filePath);
+            const author = await getGitAuthor(rootPath, relPath);
+            entries.push({
+                timestamp,
+                filename,
+                title,
+                summary,
+                text: content,
+                author,
+            });
+        }
+    }
+    // Also include conclude/session-conclude notes from the cognition store.
+    // These bypass the inbox → update pipeline so they never land in interactions/processed/,
+    // but they are still durable knowledge events that belong in the history timeline.
+    if (cognitionPath && (await pathExists(cognitionPath))) {
+        const dirents = await readdir(cognitionPath, { withFileTypes: true });
+        const filenames = dirents
+            .filter((e) => e.isFile() && e.name.endsWith('.md'))
+            .map((e) => e.name)
+            .sort();
+        for (const filename of filenames) {
+            // inbox-source notes are already represented via interactions/processed/
+            const filePath = path.join(cognitionPath, filename);
+            const content = await readFile(filePath, 'utf8');
+            const source = content.match(/^Source:\s*(.+)$/m)?.[1]?.trim();
+            if (source === 'inbox')
+                continue;
+            const timestamp = parseTimestampFromFilename(filename);
+            if (!timestamp)
+                continue;
+            const title = content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? filename;
+            const summary = content
+                .match(/^## Summary\s+([\s\S]*?)(?:\n## |\n# |$)/m)?.[1]
+                ?.trim();
+            const relPath = path.relative(rootPath, filePath);
+            const author = await getGitAuthor(rootPath, relPath);
+            entries.push({
+                timestamp,
+                filename,
+                title,
+                summary,
+                text: content,
+                author,
+            });
+        }
     }
-    return entries;
+    return entries.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
 }
 /**
  * Parses the UTC timestamp embedded in a processed interaction filename.
@@ -85,7 +129,7 @@ export function renderHistory(entries, useColor = supportsColor(), query = '') {
     const chalk = new Chalk({ level: useColor ? 3 : 0 });
     if (entries.length === 0) {
         return ('\n' +
-            chalk.dim('  No processed cognition notes found. Write Markdown notes to .kgraph/inbox/ and run `kgraph update`.') +
+            chalk.dim('  No cognition history found. Capture knowledge with `kgraph conclude` or write notes to .kgraph/inbox/ and run `kgraph update`.') +
             '\n');
     }
     const header = `  ${chalk.bold('KGraph History')}  ${chalk.dim(`· ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}${query ? ` matching "${query}"` : ''}`)}`;

package/dist/cli/commands/pack.js

@@ -28,19 +28,22 @@ export function registerPackCommand(program) {
         const agent = options.agent ??
             command.getOptionValue('agent') ??
             findCommandOption(command, 'agent');
+        const [config, maps] = await Promise.all([
+            loadConfig(workspace),
+            readMaps(workspace),
+        ]);
+        const response = await queryContext(workspace, config, maps, task);
+        const pack = buildContextPack(response, budget, workspace.rootPath);
         if (agent) {
+            const omittedTokens = pack.omitted.reduce((sum, item) => sum + item.tokenEstimate, 0);
             await recordSessionEvent(workspace, {
                 agent: assertSessionAgent(agent),
                 type: 'context',
                 captureSource: 'automatic',
+                packUsedTokens: pack.usedTokens,
+                packOmittedTokens: omittedTokens,
             });
         }
-        const [config, maps] = await Promise.all([
-            loadConfig(workspace),
-            readMaps(workspace),
-        ]);
-        const response = await queryContext(workspace, config, maps, task);
-        const pack = buildContextPack(response, budget, workspace.rootPath);
         const pendingInboxFiles = (await listInboxNotes(workspace)).map((file) => path.relative(workspace.rootPath, file).split(path.sep).join('/'));
         if (pendingInboxFiles.length > 0) {
             pack.pendingInbox = {
@@ -104,6 +107,13 @@ export function renderPackText(pack) {
             lines.push(`  ◌ ${pack.omitted.length - omitted.length} more omitted items`);
         }
     }
+    if (pack.warnings.length > 0) {
+        lines.push('● Warnings');
+        for (const warning of pack.warnings) {
+            lines.push(`  ⚠ ${warning}`);
+        }
+        lines.push('');
+    }
     lines.push('', '● Next', '  agents should consume this command with --json for the full ContextPack contract');
     return lines.join('\n');
 }
@@ -116,6 +126,12 @@ function appendGroup(lines, title, items) {
     for (const item of items.slice(0, 6)) {
         lines.push(`  ● ${item.title} (~${item.tokenEstimate} tokens)`);
         lines.push(`    because ${formatReasons(item.reasons)}`);
+        if (item.kind === 'file') {
+            const data = item.data;
+            if (data.content !== undefined) {
+                lines.push(`    content inline (~${item.tokenEstimate} tokens)`);
+            }
+        }
         if (item.kind === 'file-range') {
             const data = item.data;
             if (data.path && data.startLine != null && data.endLine != null) {

package/dist/cli/commands/session.js

@@ -13,7 +13,9 @@ export function registerSessionCommand(program) {
         .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));
+        console.log(options.json
+            ? JSON.stringify(report, null, 2)
+            : renderSessionReport(report));
     }));
     session
         .command('start')
@@ -112,10 +114,25 @@ export function renderSessionReport(report) {
     lines.push(`Repeated reads: ${report.repeatedReadCount}`);
     lines.push(`Estimated read tokens: ${report.estimatedReadTokens}`);
     lines.push(`Estimated repeated-read tokens: ${report.estimatedRepeatedReadTokens}`);
+    lines.push('');
+    lines.push('Pack Usage');
+    lines.push(`  Pack calls: ${report.packCallCount}`);
+    lines.push(`  Tokens used: ${report.totalPackUsedTokens}`);
+    lines.push(`  Tokens filtered: ${report.totalPackOmittedTokens}`);
+    if (report.packCallCount > 0 && report.totalPackOmittedTokens > 0) {
+        const total = report.totalPackUsedTokens + report.totalPackOmittedTokens;
+        const pct = Math.round((report.totalPackOmittedTokens / total) * 100);
+        lines.push(`  Filter rate: ${pct}% of candidate tokens excluded from context`);
+    }
     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(...formatList(report.recentEvents.map((event) => {
+        const packInfo = event.packUsedTokens !== undefined
+            ? ` [used:${event.packUsedTokens} filtered:${event.packOmittedTokens ?? 0}]`
+            : '';
+        return `- ${event.agent} ${event.type}${event.path ? ` ${event.path}` : ''}${packInfo} [${event.captureSource}]`;
+    })));
     lines.push('', 'Recent Ledger');
     lines.push(...formatList(report.ledger.map((entry) => `- ${entry.agent} ${entry.readCount} reads, ${entry.writeCount} writes, ${entry.repeatedReadCount} repeated`)));
     lines.push('', 'Next');
@@ -144,7 +161,9 @@ function findCommandOption(command, name) {
     return undefined;
 }
 function normalizeSource(value) {
-    if (value === 'automatic' || value === 'agent-reported' || value === 'manual') {
+    if (value === 'automatic' ||
+        value === 'agent-reported' ||
+        value === 'manual') {
         return value;
     }
     throw new KGraphError('--source must be automatic, agent-reported, or manual.');
@@ -153,7 +172,9 @@ function formatList(items) {
     return items.length > 0 ? items : ['- None'];
 }
 function sessionNextActions(report) {
-    if (report.readCount === 0 && report.writeCount === 0) {
+    if (report.packCallCount === 0 &&
+        report.readCount === 0 &&
+        report.writeCount === 0) {
         return [
             '- Start tracking with `kgraph session start --agent <name>`.',
             '- Record meaningful reads/writes with `kgraph session read <path> --agent <name>` and `kgraph session write <path> --agent <name>`.',

package/dist/cli/commands/visualize.js

@@ -2,10 +2,11 @@ import { exec } from 'node:child_process';
 import { createServer } from 'node:http';
 import { loadConfig } from '../../config/config.js';
 import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
+import { readSessionState } from '../../session/session-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { buildGraph } from '../../visualization/graph-builder.js';
-import { renderHtml } from '../../visualization/html-template.js';
+import { renderHtml, } from '../../visualization/html-template.js';
 import { KGraphError, runCommand } from '../errors.js';
 export function registerVisualizeCommand(program) {
     program
@@ -22,14 +23,36 @@ export function registerVisualizeCommand(program) {
         if (!(await mapsExist(workspace))) {
             throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
-        const maps = await readMaps(workspace);
+        const [maps, sessionState] = await Promise.all([
+            readMaps(workspace),
+            readSessionState(workspace),
+        ]);
         const { atoms } = await refreshKnowledgeAtomStatuses(workspace, {
             fileMap: maps.fileMap,
             symbolMap: maps.symbolMap,
         });
         await loadConfig(workspace); // ensure workspace is valid
+        const contextEvents = sessionState.events.filter((e) => e.type === 'context');
+        const sessionVizData = sessionState.events.length > 0
+            ? {
+                activeAgents: Object.values(sessionState.active).map((a) => a.agent),
+                packCallCount: contextEvents.length,
+                totalPackUsedTokens: contextEvents.reduce((sum, e) => sum + (e.packUsedTokens ?? 0), 0),
+                totalPackOmittedTokens: contextEvents.reduce((sum, e) => sum + (e.packOmittedTokens ?? 0), 0),
+                readCount: sessionState.events.filter((e) => e.type === 'read')
+                    .length,
+                writeCount: sessionState.events.filter((e) => e.type === 'write').length,
+                contextEvents: contextEvents.map((e) => ({
+                    agent: e.agent,
+                    packUsedTokens: e.packUsedTokens ?? 0,
+                    packOmittedTokens: e.packOmittedTokens ?? 0,
+                    timestamp: e.timestamp,
+                    captureSource: e.captureSource,
+                })),
+            }
+            : undefined;
         const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, atoms);
-        const html = renderHtml(graphData, workspace.rootPath);
+        const html = renderHtml(graphData, workspace.rootPath, sessionVizData);
         await serveGraph(html, port, options.open);
     }));
 }

package/dist/config/config.js

@@ -33,6 +33,7 @@ export const DEFAULT_CONFIG = {
         '.windsurf',
         '.clinerules',
         '.github/copilot-instructions.md',
+        '.github/agents',
         '.github/prompts',
         'AGENTS.md',
         'CLAUDE.md',

package/dist/context/context-pack.js

@@ -63,6 +63,23 @@ export function buildContextPack(response, budget, rootPath) {
             omitted.push(candidate);
         }
     }
+    // Enrich selected file items with inline content so agents have the source without
+    // a second read. This mirrors how symbol and file-range items already embed excerpts.
+    // Only files that passed the budget check are read — omitted files are left as metadata.
+    if (rootPath) {
+        for (const item of items) {
+            if (item.kind !== 'file')
+                continue;
+            const data = item.data;
+            try {
+                const content = readFileSync(path.join(rootPath, data.path), 'utf8');
+                item.data = { ...data, content };
+            }
+            catch {
+                // best-effort — leave as metadata-only if file cannot be read
+            }
+        }
+    }
     return {
         task: response.query,
         budget,

package/dist/context/context-query.js

@@ -1,9 +1,8 @@
-import { getRecentlyCommittedFiles, getWorkingTreeChangesDetailed, isGitRepo, } from '../scanner/git-utils.js';
-import { readDomainRecords } from '../storage/cognition-store.js';
-import { readSessionState } from '../session/session-store.js';
 import { atomToCognitionNote, refreshKnowledgeAtomStatuses, } from '../knowledge/atom-store.js';
-import { rankByFields } from './ranking.js';
-import { tokenize } from './ranking.js';
+import { getCurrentCommit, getRecentlyCommittedFiles, getWorkingTreeChangesDetailed, isGitRepo, } from '../scanner/git-utils.js';
+import { readSessionState } from '../session/session-store.js';
+import { readDomainRecords } from '../storage/cognition-store.js';
+import { rankByFields, tokenize } from './ranking.js';
 export async function queryContext(workspace, config, maps, query) {
     const refreshedAtoms = await refreshKnowledgeAtomStatuses(workspace, {
         fileMap: maps.fileMap,
@@ -22,6 +21,7 @@ export async function queryContext(workspace, config, maps, query) {
     // Collect git changes before file ranking so dirty files can influence ranking,
     // not just appear later as a low-token pack item.
     const knownFilePaths = new Set(maps.fileMap.files.map((f) => f.path));
+    const warnings = [];
     const gitChanges = [];
     if (await isGitRepo(workspace.rootPath)) {
         const workingTreeChanges = await getWorkingTreeChangesDetailed(workspace.rootPath);
@@ -54,6 +54,14 @@ export async function queryContext(workspace, config, maps, query) {
                 reason: 'changed in recent commits',
             });
         }
+        const currentCommit = await getCurrentCommit(workspace.rootPath);
+        if (currentCommit &&
+            maps.fileMap.scannedAtCommit &&
+            currentCommit !== maps.fileMap.scannedAtCommit) {
+            const shortCurrent = currentCommit.slice(0, 7);
+            const shortScanned = maps.fileMap.scannedAtCommit.slice(0, 7);
+            warnings.push(`Structural maps were last scanned at commit ${shortScanned}; HEAD is now ${shortCurrent}. Run \`kgraph scan\` to refresh file and symbol relationships.`);
+        }
     }
     const gitChangedPaths = new Set(gitChanges.map((change) => change.path));
     const relevantCognition = rankByFields(query, atoms.filter((atom) => atom.status !== 'archived'), [
@@ -263,7 +271,7 @@ export async function queryContext(workspace, config, maps, query) {
         nearbySymbolExplanations,
         gitChanges,
         staleReferences,
-        warnings: [],
+        warnings,
     };
 }
 function applyFileRankAdjustments(ranked, context) {

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

@@ -6,9 +6,16 @@ export const claudeCodeAdapter = {
     instructions: `## KGraph Workflow
 
 ${numberedWorkflow('claude-code', {
-        sessionQualifier: 'native hooks also report session activity when configured',
+        sessionQualifier: 'native hooks also report session activity automatically',
     })}
 `,
+    configFiles: [
+        {
+            path: '.claude/settings.json',
+            merge: mergeClaudeHooks,
+            remove: removeClaudeHooks,
+        },
+    ],
     commandFiles: [
         {
             path: '.claude/commands/kgraph.md',
@@ -106,6 +113,88 @@ ${numberedWorkflow('claude-code')}
     ],
     obsoleteCommandFiles: [],
 };
+const KGRAPH_HOOK_MARKER = 'kgraph-session';
+const CLAUDE_HOOK_REGISTRATIONS = [
+    {
+        event: 'UserPromptSubmit',
+        entry: {
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-start.cjs',
+                },
+            ],
+        },
+    },
+    {
+        event: 'PreToolUse',
+        entry: {
+            matcher: 'Read',
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-pre-read.cjs',
+                },
+            ],
+        },
+    },
+    {
+        event: 'PostToolUse',
+        entry: {
+            matcher: 'Write|Edit|MultiEdit',
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-post-write.cjs',
+                },
+            ],
+        },
+    },
+    {
+        event: 'Stop',
+        entry: {
+            hooks: [
+                {
+                    type: 'command',
+                    command: 'node .claude/hooks/kgraph-session-stop.cjs',
+                },
+            ],
+        },
+    },
+];
+function mergeClaudeHooks(existing) {
+    const settings = { ...existing };
+    const hooks = typeof settings.hooks === 'object' && settings.hooks !== null
+        ? { ...settings.hooks }
+        : {};
+    for (const { event, entry } of CLAUDE_HOOK_REGISTRATIONS) {
+        const entries = (hooks[event] ?? []);
+        const alreadyPresent = entries.some((e) => e.hooks.some((h) => h.command.includes(KGRAPH_HOOK_MARKER)));
+        if (!alreadyPresent) {
+            hooks[event] = [...entries, entry];
+        }
+    }
+    settings.hooks = hooks;
+    return settings;
+}
+function removeClaudeHooks(existing) {
+    if (typeof existing.hooks !== 'object' || existing.hooks === null)
+        return existing;
+    const settings = { ...existing };
+    const hooks = { ...settings.hooks };
+    for (const event of Object.keys(hooks)) {
+        hooks[event] = hooks[event].filter((entry) => !entry.hooks.some((h) => h.command.includes(KGRAPH_HOOK_MARKER)));
+        if (hooks[event].length === 0) {
+            delete hooks[event];
+        }
+    }
+    if (Object.keys(hooks).length === 0) {
+        const { hooks: _removed, ...rest } = settings;
+        return rest;
+    }
+    settings.hooks = hooks;
+    return settings;
+}
 function hookScript(event) {
     const pathArg = event === 'read' || event === 'write'
         ? `const payload = readPayload();

package/dist/integrations/agent-skills.js

@@ -45,7 +45,7 @@ name: kgraph-pack
 description: Build a budget-aware KGraph context pack
 ---
 
-Run \`kgraph pack "<topic>" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons. When a symbol item includes an \`excerpt\` field, you already have the source — do not read that file for the symbol.
+Run \`kgraph pack "<topic>" --budget 8000 --json --agent $AGENT\` to build a machine-readable context pack and record lightweight session context. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons. When a symbol item includes an \`excerpt\` field or a file item includes a \`content\` field, you already have the source inline — do not read that file separately.
 `,
     },
     {

package/dist/integrations/instruction-blocks.js

@@ -36,7 +36,7 @@ export function applyContextPolicy(content, mode, agentName) {
         .replaceAll(KGRAPH_CAPTURE_POLICY_PLACEHOLDER, renderCapturePolicy(agentName));
 }
 export function renderContextPolicy(mode, agentName) {
-    const useResultBoundary = 'Use the returned KGraph ContextPack items as the first-pass source of truth. Prefer source ranges, atoms, git changes, and inclusion reasons from the pack before broad repository search. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file or range is identified, do not retry malformed shell commands with broader variants, and do not run broad `find`, recursive `grep`, or repeated full-file dumps after KGraph has narrowed the target.';
+    const useResultBoundary = 'Use the returned KGraph ContextPack items as the first-pass source of truth. Prefer source ranges, atoms, git changes, and inclusion reasons from the pack before broad repository search. When a file item includes a `content` field or a symbol item includes an `excerpt` field, that IS the source — do not read the file separately. Do not rerun the same KGraph query just to tail or reformat output, do not continue broad repository search after the target file or range is identified, do not retry malformed shell commands with broader variants, and do not run broad `find`, recursive `grep`, or repeated full-file dumps after KGraph has narrowed the target.';
     const packCommand = agentName
         ? `kgraph pack "<topic>" --budget 8000 --json --agent ${agentName}`
         : 'kgraph pack "<topic>" --budget 8000 --json';
@@ -54,7 +54,7 @@ export function renderContextPolicy(mode, agentName) {
         case 'always':
             return `Every chat in this repository must use the correct KGraph command before answering or exploring files. ${routing} For normal repo context, code navigation, debugging, review, or edits, run \`${packCommand}\`. If that pack reports pending inbox notes, run \`${rootCommand}\` or \`kgraph update\` before relying on history or newly captured atoms. Infer the topic from the user's message. This records a lightweight KGraph session context event for the agent. ${useResultBoundary}`;
         case 'manual':
-            return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack. If the user explicitly asks for KGraph history, inbox/update, knowledge, or doctor, run that specific KGraph command instead of pack.';
+            return `Do not run KGraph automatically. Run \`${packCommand}\` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack. If the user explicitly asks for KGraph history, inbox/update, knowledge, or doctor, run that specific KGraph command instead of pack.`;
         case 'off':
             return 'KGraph is disabled for this integration.';
         case 'smart':

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

@@ -5,12 +5,21 @@ export interface IntegrationAdapter {
     targetPath: string;
     instructions: string;
     commandFiles?: IntegrationCommandFile[];
+    configFiles?: IntegrationConfigFile[];
     obsoleteCommandFiles?: string[];
 }
 export interface IntegrationCommandFile {
     path: string;
     content: string;
 }
+export interface IntegrationConfigFile {
+    /** Repo-relative path to a JSON config file (e.g. `.claude/settings.json`). */
+    path: string;
+    /** Merge KGraph entries into the existing parsed JSON object and return the result. */
+    merge: (existing: Record<string, unknown>) => Record<string, unknown>;
+    /** Remove KGraph entries from the existing parsed JSON and return the result. */
+    remove: (existing: Record<string, unknown>) => Record<string, unknown>;
+}
 export declare function listIntegrationAdapters(): IntegrationAdapter[];
 export declare function getIntegrationAdapter(name: string): IntegrationAdapter;
 export declare function normalizeIntegrationNames(values: string[] | undefined): IntegrationName[];

package/dist/integrations/integration-store.js

@@ -32,6 +32,7 @@ export async function addIntegrations(workspace, names, mode = 'always') {
         if (mode === 'off') {
             await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
             await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+            await removeIntegrationConfigFiles(workspace.rootPath, adapter.configFiles ?? []);
         }
         else {
             await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode, adapter.name));
@@ -43,6 +44,7 @@ export async function addIntegrations(workspace, names, mode = 'always') {
             for (const file of adapter.commandFiles ?? []) {
                 writtenCommandFiles.add(file.path);
             }
+            await upsertIntegrationConfigFiles(workspace.rootPath, adapter.configFiles ?? []);
         }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         changed.push(next);
@@ -74,6 +76,7 @@ export async function removeIntegrations(workspace, names) {
         await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
         await removeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).filter((file) => !retainedPaths.has(file.path)));
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
+        await removeIntegrationConfigFiles(workspace.rootPath, adapter.configFiles ?? []);
         removed.push(adapter.name);
     }
     config.integrations = config.integrations.filter((integration) => !removeNames.has(integration.name));
@@ -133,3 +136,42 @@ async function pruneEmptyParents(rootPath, startDir) {
         }
     }
 }
+async function upsertIntegrationConfigFiles(rootPath, configFiles) {
+    for (const configFile of configFiles) {
+        const fullPath = path.join(rootPath, configFile.path);
+        let existing = {};
+        if (await pathExists(fullPath)) {
+            try {
+                existing = JSON.parse(await readFile(fullPath, 'utf8'));
+            }
+            catch {
+                existing = {};
+            }
+        }
+        const next = configFile.merge(existing);
+        await mkdir(path.dirname(fullPath), { recursive: true });
+        await writeFile(fullPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    }
+}
+async function removeIntegrationConfigFiles(rootPath, configFiles) {
+    for (const configFile of configFiles) {
+        const fullPath = path.join(rootPath, configFile.path);
+        if (!(await pathExists(fullPath)))
+            continue;
+        let existing = {};
+        try {
+            existing = JSON.parse(await readFile(fullPath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        const next = configFile.remove(existing);
+        if (Object.keys(next).length === 0) {
+            await rm(fullPath, { force: true });
+            await pruneEmptyParents(rootPath, path.dirname(fullPath));
+        }
+        else {
+            await writeFile(fullPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+        }
+    }
+}

package/dist/integrations/workflow-steps.js

@@ -20,12 +20,16 @@ const DECISION_CONTEXT = `## Feature intent — choose based on the situation
 
 **compact** exists to merge redundant knowledge. Consider it when you store something that feels overlapping with what pack already showed.
 
-**scan** exists to refresh maps after structural changes. The root workflow handles this automatically unless you created, deleted, or renamed many files outside of kgraph commands.`;
+**scan** exists to refresh maps after structural changes. The root workflow handles this automatically unless you created, deleted, or renamed many files outside of kgraph commands.
+
+**history** exists to answer "what did we do" and "when did this happen" questions. Use \`kgraph history "<topic>"\` when the user asks about prior work, decisions, or the sequence of changes — it covers the full timeline regardless of whether knowledge was captured via \`conclude\`, \`--capture\`, or inbox notes. Use \`kgraph knowledge list\` when the user wants the structured claim and evidence for an atom. Use \`kgraph pack\` when the user needs context to start or continue coding work. These three serve different intents: timeline vs. structured memory vs. coding context.
+
+**budget** exists to control how much source context pack delivers. On large or complex projects, raise \`--budget\` (e.g. \`--budget 16000\`) when pack omits files or symbols that feel relevant — the default 8000 was tuned for small projects. When pack includes file items with a \`content\` field, the budget was already spent delivering that source inline; do not re-read those files.`;
 const DOCTOR_STEP = `Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.`;
-const IMPACT_STEP = `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.`;
+const IMPACT_STEP = `Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when the user asks what was done before, who made a decision, or what the sequence of changes was.`;
 const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/noisy atom refs need fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.`;
 const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks duplicated, noisy, or stale. Run \`kgraph compact\` only when the user asks to merge/archive cognition.`;
-const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.`;
+const HISTORY_STEP = `Run \`kgraph history "<topic>"\` when the user asks what was done, decided, or changed — it covers the full timeline including notes captured via \`conclude\`, \`--capture\`, and inbox. Prefer history over \`knowledge list\` when the question is about sequence, timing, or authorship rather than atom details.`;
 const KNOWLEDGE_STEP = `Run \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\` when the user asks what KGraph remembers or atom provenance/lifecycle matters.`;
 const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
 const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files.`;
@@ -45,7 +49,7 @@ function sessionStep(agentName, qualifier) {
 export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
 2. {{KGRAPH_CONTEXT_POLICY}}
-3. When the pack includes a symbol with an \`excerpt\` field, you already have the source code — do not read that file again for that symbol. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
+3. When a pack item includes an \`excerpt\` field (symbol) or a \`content\` field (file), you already have the source code inline — do not read that file separately. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
 4. ${EXPLORATION_BOUNDARY_STEP}
 5. ${VERIFY_EDIT_STEP}
 6. ${smartRootStep(agentName)}
@@ -71,7 +75,7 @@ ${DECISION_CONTEXT}`;
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
-- When the pack includes a symbol with an \`excerpt\` field, you already have the source code — do not read that file again for that symbol. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
+- When a pack item includes an \`excerpt\` field (symbol) or a \`content\` field (file), you already have the source code inline — do not read that file separately. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}
 - ${smartRootStep(agentName)}

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

@@ -11,5 +11,7 @@ export declare function recordSessionEvent(workspace: KGraphWorkspace, input: {
     path?: string;
     captureSource: SessionCaptureSource;
     fileMap?: FileMap;
+    packUsedTokens?: number;
+    packOmittedTokens?: number;
 }): Promise<SessionEvent>;
 export declare function buildSessionReport(workspace: KGraphWorkspace): Promise<SessionReport>;

package/dist/session/session-store.js

@@ -63,6 +63,12 @@ export async function recordSessionEvent(workspace, input) {
         ...(normalizedPath ? { path: normalizedPath } : {}),
         ...(tokenEstimate !== undefined ? { tokenEstimate } : {}),
         ...(repeated !== undefined ? { repeated } : {}),
+        ...(input.type === 'context' && input.packUsedTokens !== undefined
+            ? { packUsedTokens: input.packUsedTokens }
+            : {}),
+        ...(input.type === 'context' && input.packOmittedTokens !== undefined
+            ? { packOmittedTokens: input.packOmittedTokens }
+            : {}),
         captureSource: input.captureSource,
         timestamp: now,
     };
@@ -90,6 +96,7 @@ export async function buildSessionReport(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);
+    const contextEvents = state.events.filter((event) => event.type === 'context');
     return {
         activeAgents: Object.values(state.active),
         readCount: readEvents.length,
@@ -97,6 +104,9 @@ export async function buildSessionReport(workspace) {
         repeatedReadCount: repeatedReads.length,
         estimatedReadTokens: sumTokens(readEvents),
         estimatedRepeatedReadTokens: sumTokens(repeatedReads),
+        packCallCount: contextEvents.length,
+        totalPackUsedTokens: contextEvents.reduce((sum, e) => sum + (e.packUsedTokens ?? 0), 0),
+        totalPackOmittedTokens: contextEvents.reduce((sum, e) => sum + (e.packOmittedTokens ?? 0), 0),
         topRepeatedReads: topRepeatedReads(readEvents),
         recentEvents: state.events.slice(-10),
         ledger: ledger.slice(-10),

package/dist/types/session.d.ts

@@ -9,6 +9,8 @@ export interface SessionEvent {
     path?: string;
     tokenEstimate?: number;
     repeated?: boolean;
+    packUsedTokens?: number;
+    packOmittedTokens?: number;
     captureSource: SessionCaptureSource;
     timestamp: string;
 }
@@ -41,6 +43,9 @@ export interface SessionReport {
     repeatedReadCount: number;
     estimatedReadTokens: number;
     estimatedRepeatedReadTokens: number;
+    packCallCount: number;
+    totalPackUsedTokens: number;
+    totalPackOmittedTokens: number;
     topRepeatedReads: Array<{
         path: string;
         count: number;

package/dist/visualization/html-template.d.ts

@@ -1,2 +1,17 @@
 import type { GraphData } from './graph-builder.js';
-export declare function renderHtml(graphData: GraphData, rootPath: string): string;
+export interface SessionVizData {
+    activeAgents: string[];
+    packCallCount: number;
+    totalPackUsedTokens: number;
+    totalPackOmittedTokens: number;
+    readCount: number;
+    writeCount: number;
+    contextEvents: Array<{
+        agent: string;
+        packUsedTokens: number;
+        packOmittedTokens: number;
+        timestamp: string;
+        captureSource: string;
+    }>;
+}
+export declare function renderHtml(graphData: GraphData, rootPath: string, sessionData?: SessionVizData): string;

package/dist/visualization/html-template.js

@@ -1,8 +1,11 @@
-export function renderHtml(graphData, rootPath) {
+export function renderHtml(graphData, rootPath, sessionData) {
     const repoName = escAttr(rootPath.split(/[\\/]/).pop() ?? 'Repository');
     const { meta } = graphData;
     // Prevent </script> tag injection from embedded JSON
-    const safeData = JSON.stringify(graphData).replace(/<\/script>/gi, '<\\/script>');
+    const safeData = JSON.stringify(graphData).replace(/<\/script>/gi, '<\/script>');
+    const safeSessionData = sessionData
+        ? JSON.stringify(sessionData).replace(/<\/script>/gi, '<\/script>')
+        : null;
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -46,6 +49,31 @@ select:hover,button:hover{background:#475569}
 .li-dia{width:10px;height:10px;transform:rotate(45deg);flex-shrink:0;display:inline-block}
 .li-sep{width:1px;height:14px;background:#334155;flex-shrink:0}
 .li-head{font-size:11px;color:#475569;font-weight:700;letter-spacing:.04em}
+#session-panel{width:310px;background:#1e293b;border-left:1px solid #334155;display:none;flex-direction:column;overflow:hidden;flex-shrink:0}
+#session-panel.open{display:flex}
+#btn-session{color:#7dd3fc;border-color:#3b82f6}
+#btn-session.active,#btn-session:hover{background:#1e3a5f!important;color:#7dd3fc;border-color:#3b82f6}
+#sp-head{display:flex;align-items:center;padding:12px 14px;border-bottom:1px solid #334155;gap:8px;flex-shrink:0}
+#sp-title{font-weight:600;font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:#7dd3fc;flex-shrink:0}
+#sp-agents{color:#475569;font-size:11px;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#sp-close2{background:none!important;border:none!important;color:#64748b;font-size:17px;line-height:1;cursor:pointer;padding:0 2px;flex-shrink:0;box-shadow:none}
+#sp-close2:hover{color:#e2e8f0}
+#sp-body{padding:14px;overflow-y:auto;flex:1;display:flex;flex-direction:column;gap:16px}
+.sp-summary{display:grid;grid-template-columns:1fr 1fr;gap:6px}
+.sp-metric{background:#0f172a;border:1px solid #334155;border-radius:5px;padding:8px 10px}
+.sp-metric-val{font-size:18px;font-weight:700;color:#f1f5f9;line-height:1;font-variant-numeric:tabular-nums}
+.sp-metric-val.accent{color:#7dd3fc}
+.sp-metric-lbl{font-size:10px;color:#64748b;margin-top:3px;text-transform:uppercase;letter-spacing:.05em}
+.sp-group-lbl{font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.07em;color:#475569;padding-bottom:6px;margin-bottom:2px;border-bottom:1px solid #1e293b}
+.sp-call-row{display:flex;align-items:center;gap:8px;padding:5px 0;border-bottom:1px solid #0f172a}
+.sp-call-row:last-child{border-bottom:none}
+.sp-call-time{font-size:10px;color:#475569;flex-shrink:0;width:44px}
+.sp-call-bar-wrap{flex:1;background:#0f172a;border-radius:2px;height:6px;overflow:hidden}
+.sp-call-bar{background:#3b82f6;height:100%;border-radius:2px;min-width:2px}
+.sp-call-toks{font-size:11px;color:#94a3b8;flex-shrink:0;width:60px;text-align:right}
+.sp-io-row{display:flex;gap:6px}
+.sp-io-box{flex:1;background:#0f172a;border:1px solid #334155;border-radius:5px;padding:8px 10px;text-align:center}
+.sp-io-val{font-size:18px;font-weight:700;color:#f1f5f9}.sp-io-lbl{font-size:10px;color:#64748b;margin-top:2px;text-transform:uppercase;letter-spacing:.05em}
 </style>
 </head>
 <body>
@@ -63,6 +91,7 @@ select:hover,button:hover{background:#475569}
     </select>
     <button id="btn-fit" title="Fit graph to viewport">\u229f Fit</button>
     <button id="btn-png" title="Download as PNG">\u2193 PNG</button>
+${sessionData ? `    <button id="btn-session" title="View session stats">\u26a1 Session</button>` : ''}
   </div>
 </div>
 <div id="main">
@@ -74,6 +103,16 @@ select:hover,button:hover{background:#475569}
     </div>
     <div id="sb-body"></div>
   </div>
+${sessionData
+        ? `  <div id="session-panel">
+    <div id="sp-head">
+      <span id="sp-title">\u26a1 Session</span>
+      <span id="sp-agents">${sessionData.activeAgents.length ? sessionData.activeAgents.join(' \xb7 ') : 'session recorded'}</span>
+      <button id="sp-close2" title="Close">\u00d7</button>
+    </div>
+    <div id="sp-body"></div>
+  </div>`
+        : ''}
 </div>
 <div id="legend">
   <span class="li-head">Files</span>
@@ -294,6 +333,8 @@ select:hover,button:hover{background:#475569}
     document.getElementById('sb-type').textContent = d.type === 'atom' ? 'Knowledge Atom' : 'File';
     document.getElementById('sb-body').innerHTML = d.type === 'atom' ? renderAtomPanel(d) : renderFilePanel(d);
     document.getElementById('sidebar').classList.add('open');
+    var sp = document.getElementById('session-panel');
+    if (sp) { sp.classList.remove('open'); var sb = document.getElementById('btn-session'); if (sb) { sb.classList.remove('active'); sessionPanelOpen = false; } }
   });
 
   cy.on('tap', function (evt) {
@@ -337,6 +378,83 @@ select:hover,button:hover{background:#475569}
     a.click();
     document.body.removeChild(a);
   });
+${safeSessionData
+        ? `
+  var SESSION_DATA = ${safeSessionData};
+  var sessionRendered = false;
+  var sessionPanelOpen = false;
+
+  function fmt(n) {
+    return n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n);
+  }
+
+  function renderSessionPanel() {
+    var d = SESSION_DATA;
+    var total = d.totalPackUsedTokens + d.totalPackOmittedTokens;
+    var filterRate = total > 0 ? Math.round((d.totalPackOmittedTokens / total) * 100) : 0;
+    var avgToks = d.packCallCount > 0 ? Math.round(d.totalPackUsedTokens / d.packCallCount) : 0;
+    var filterCell = filterRate > 0
+      ? '<div class="sp-metric"><div class="sp-metric-val accent">' + filterRate + '%</div><div class="sp-metric-lbl">Filtered</div></div>'
+      : '<div class="sp-metric"><div class="sp-metric-val" style="font-size:11px;color:#475569;line-height:1.4">None</div><div class="sp-metric-lbl">Filtered</div></div>';
+    var summaryHtml =
+      '<div class="sp-summary">' +
+      '<div class="sp-metric"><div class="sp-metric-val">' + d.packCallCount + '</div><div class="sp-metric-lbl">Pack calls</div></div>' +
+      '<div class="sp-metric"><div class="sp-metric-val accent">' + fmt(d.totalPackUsedTokens) + '</div><div class="sp-metric-lbl">Tokens used</div></div>' +
+      '<div class="sp-metric"><div class="sp-metric-val">' + fmt(avgToks) + '</div><div class="sp-metric-lbl">Avg / call</div></div>' +
+      filterCell +
+      '</div>';
+    var maxUsed = 0;
+    d.contextEvents.forEach(function (e) { if ((e.packUsedTokens || 0) > maxUsed) maxUsed = e.packUsedTokens || 0; });
+    var callRows = '';
+    if (d.contextEvents.length > 0) {
+      callRows = '<div><div class="sp-group-lbl">Pack calls (' + d.contextEvents.length + ')</div>';
+      d.contextEvents.forEach(function (e) {
+        var used = e.packUsedTokens || 0;
+        var filt = e.packOmittedTokens || 0;
+        var barPct = maxUsed > 0 ? Math.round(used / maxUsed * 100) : 100;
+        var ts = e.timestamp ? new Date(e.timestamp).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : '';
+        var filtLabel = filt > 0 ? ' <span style="color:#ef4444">-' + fmt(filt) + '</span>' : '';
+        callRows +=
+          '<div class="sp-call-row">' +
+          '<span class="sp-call-time">' + esc(ts) + '</span>' +
+          '<div class="sp-call-bar-wrap"><div class="sp-call-bar" style="width:' + barPct + '%"></div></div>' +
+          '<span class="sp-call-toks">' + fmt(used) + filtLabel + '</span>' +
+          '</div>';
+      });
+      callRows += '</div>';
+    }
+    var ioHtml =
+      '<div><div class="sp-group-lbl">File access</div>' +
+      '<div class="sp-io-row">' +
+      '<div class="sp-io-box"><div class="sp-io-val">' + d.readCount + '</div><div class="sp-io-lbl">Reads</div></div>' +
+      '<div class="sp-io-box"><div class="sp-io-val">' + d.writeCount + '</div><div class="sp-io-lbl">Writes</div></div>' +
+      '</div></div>';
+    document.getElementById('sp-body').innerHTML = summaryHtml + callRows + ioHtml;
+  }
+
+  document.getElementById('btn-session').addEventListener('click', function () {
+    var panel = document.getElementById('session-panel');
+    sessionPanelOpen = !sessionPanelOpen;
+    if (sessionPanelOpen) {
+      panel.classList.add('open');
+      this.classList.add('active');
+      if (!sessionRendered) {
+        renderSessionPanel();
+        sessionRendered = true;
+      }
+    } else {
+      panel.classList.remove('open');
+      this.classList.remove('active');
+    }
+  });
+
+  document.getElementById('sp-close2').addEventListener('click', function () {
+    document.getElementById('session-panel').classList.remove('open');
+    document.getElementById('btn-session').classList.remove('active');
+    sessionPanelOpen = false;
+  });
+`
+        : ''}
 })();
 </script>
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {