@kentwynn/kgraph 0.2.34 → 0.2.36

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

@@ -104,6 +104,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 +123,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/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/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';

package/dist/integrations/workflow-steps.js

@@ -2,11 +2,34 @@
  * Shared KGraph workflow step strings used across all AI tool adapters.
  * Update here once instead of in each adapter file.
  */
+const DECISION_CONTEXT = `## Feature intent — choose based on the situation
+
+**Sessions** exist to preserve the journey when exploration, evaluation, or multi-step reasoning produced knowledge that the outcome alone cannot capture. The path matters when a future agent might face the same fork.
+
+**Inbox notes** exist for structured multi-section knowledge that cannot fit a single --capture sentence. Architecture decisions with rationale, multi-file change summaries with interconnections, or design tradeoffs with rejected alternatives.
+
+**--capture / conclude** exists for atomic durable conclusions — one sentence, evidence-linked. Prefer this for most captures.
+
+**--domain and --tag** exist so future queries find knowledge by area, not just by word match. Add them when the knowledge clearly belongs to an identifiable architectural boundary.
+
+**knowledge supersede** exists to evolve knowledge without duplicating. When new understanding contradicts or refines an existing atom, supersede it.
+
+**stale** exists to surface atoms whose evidence no longer holds. Consider it after your edits touched code that pack showed as atom-referenced.
+
+**impact** exists to reveal blast radius. Consider it before destructive changes to public interfaces — renames, deletions, signature changes.
+
+**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.
+
+**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.`;
@@ -26,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)}
@@ -42,7 +65,9 @@ export function numberedWorkflow(agentName, options = {}) {
 13. ${REPAIR_STEP}
 14. ${COMPACT_STEP}
 15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph locally with PNG export.
-16. ${HISTORY_STEP}`;
+16. ${HISTORY_STEP}
+
+${DECISION_CONTEXT}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -50,7 +75,7 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 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)}
@@ -64,5 +89,7 @@ export function bulletWorkflow(agentName, options = {}) {
 - ${REPAIR_STEP}
 - ${COMPACT_STEP}
 - Run \`kgraph visualize\` to open the interactive dependency graph locally with PNG export.
-- ${HISTORY_STEP}`;
+- ${HISTORY_STEP}
+
+${DECISION_CONTEXT}`;
 }

package/package.json

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