@kentwynn/kgraph 0.2.14 → 0.2.16

package/README.md

@@ -4,6 +4,8 @@ Persistent repository intelligence for AI coding tools.
 
 KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable knowledge atoms from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
 
+The CLI presents this as **Atom Core**: lightweight local atoms plus deterministic repo maps, context packs, and session history that remain inspectable under `.kgraph/`.
+
 ## The Workflow
 
 Use KGraph in two steps:

package/dist/cli/commands/context.js

@@ -25,11 +25,20 @@ export function registerContextCommand(program) {
     }));
 }
 export function renderContextMarkdown(response) {
-    const lines = [`# KGraph Context`, ``, `Query: ${response.query}`, ``];
-    lines.push('## Matched Domains', '');
-    lines.push(...formatList(response.matchedDomains.map((item) => `- ${item.item.name} because ${formatReasons(item.reasons)}`)));
-    lines.push('', '## Relevant Files', '');
-    lines.push(...formatList(response.relevantFiles.map((item) => {
+    const lines = [
+        `KGraph Context · ${response.query}`,
+        `local-first · deterministic · inspectable`,
+        ``,
+        `● Signal`,
+        `  confidence   ${contextConfidence(response)}`,
+        `  source       ${contextSources(response).join(' + ') || 'file map'}`,
+        `  warnings     ${response.warnings.length > 0 ? response.warnings.length : 'none'}`,
+        ``,
+    ];
+    lines.push('● Matched Domains', '');
+    lines.push(...formatList(response.matchedDomains.map((item) => atomLine(item.item.name, formatReasons(item.reasons)))));
+    lines.push('', '● Source', '');
+    lines.push(...formatList(limited(response.relevantFiles, 5).map((item) => {
         const f = item.item;
         const meta = [
             f.language,
@@ -37,32 +46,34 @@ export function renderContextMarkdown(response) {
         ]
             .filter(Boolean)
             .join(', ');
-        return `- ${f.path}${meta ? ` [${meta}]` : ''} because ${formatReasons(item.reasons)}`;
+        return atomLine(`${f.path}${meta ? ` [${meta}]` : ''}`, formatReasons(item.reasons));
     })));
-    lines.push('', '## Relevant Symbols', '');
-    lines.push(...formatList(response.relevantSymbols.map((item) => {
+    appendMore(lines, response.relevantFiles.length, 5, 'source item');
+    lines.push('', '● Symbols', '');
+    lines.push(...formatList(limited(response.relevantSymbols, 6).map((item) => {
         const s = item.item;
         const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(item.reasons)}`;
+        return atomLine(`${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`, formatReasons(item.reasons));
     })));
-    lines.push('', '## Relevant Cognition', '');
-    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}] because ${formatReasons(item.reasons)}`)));
-    lines.push('', '## Relationships', '');
-    lines.push(...formatGroupedRelationships(response.relationships, response.relationshipExplanations));
-    lines.push('', '## Nearby Symbols (1-hop imports)', '');
+    appendMore(lines, response.relevantSymbols.length, 6, 'symbol');
+    lines.push('', '● Atoms', '');
+    lines.push(...formatList(response.relevantCognition.map((item) => atomLine(`${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}]`, formatReasons(item.reasons)))));
+    lines.push('', '● Graph', '');
+    lines.push(...formatGroupedRelationships(relevantGraphRelationships(response), response.relationshipExplanations));
+    lines.push('', '● Nearby Symbols (1-hop imports)', '');
     lines.push(...formatList(nearbySymbolItems(response).map(({ symbol: s, reasons }) => {
         const kindInfo = [s.kind, s.parentName].filter(Boolean).join(', ');
         const lineRange = s.startLine != null && s.endLine != null
             ? `:${s.startLine}-${s.endLine}`
             : '';
-        return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(reasons)}`;
+        return atomLine(`${s.name} (${kindInfo}) in ${s.filePath}${lineRange}`, formatReasons(reasons));
     })));
-    lines.push('', '## Stale References', '');
-    lines.push(...formatList(response.staleReferences.map((ref) => `- ${ref}`)));
-    lines.push('', '## Recent Git Changes', '');
+    lines.push('', '● Stale References', '');
+    lines.push(...formatList(response.staleReferences.map((ref) => `  ◌ ${ref}`)));
+    lines.push('', '● Recent Git Changes', '');
     if (response.gitChanges && response.gitChanges.length > 0) {
         const staged = response.gitChanges.filter((c) => c.status === 'staged');
         const unstaged = response.gitChanges.filter((c) => c.status === 'unstaged');
@@ -70,22 +81,29 @@ export function renderContextMarkdown(response) {
         if (staged.length > 0) {
             lines.push('Staged:');
             for (const c of staged)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
         if (unstaged.length > 0) {
             lines.push('Unstaged:');
             for (const c of unstaged)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
         if (recent.length > 0) {
             lines.push('Recent commits:');
             for (const c of recent)
-                lines.push(`  ${c.path} (${c.reason})`);
+                lines.push(`  ● ${c.path} (${c.reason})`);
         }
     }
     else {
         lines.push('- None');
     }
+    lines.push('', '● Next', '');
+    if (response.relevantFiles.some((item) => (item.item.tokenEstimate ?? 0) > 4000)) {
+        lines.push(`  use budgeted source ranges: kgraph pack "${response.query}" --budget 4000`);
+    }
+    else {
+        lines.push(`  read the ranked source, edit, verify, conclude only if durable knowledge changed`);
+    }
     return lines.join('\n');
 }
 function formatGroupedRelationships(relationships, explanations) {
@@ -105,33 +123,49 @@ function formatGroupedRelationships(relationships, explanations) {
     const lines = [];
     if (imports.length > 0) {
         lines.push('Imports:');
-        for (const r of imports) {
+        for (const r of imports.slice(0, 6)) {
             lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, imports.length, 6, 'import edge');
     }
     if (calls.length > 0) {
         lines.push('Calls:');
-        for (const r of calls) {
+        for (const r of calls.slice(0, 6)) {
             lines.push(`  ${r.sourceId} → ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, calls.length, 6, 'call edge');
     }
     if (contains.length > 0) {
         lines.push('Contains:');
-        for (const r of contains) {
+        for (const r of contains.slice(0, 6)) {
             lines.push(`  ${r.sourceId} contains ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, contains.length, 6, 'containment edge');
     }
     if (other.length > 0) {
         lines.push('Other:');
-        for (const r of other) {
+        for (const r of other.slice(0, 6)) {
             lines.push(`  ${r.sourceId} ${r.relationshipType} ${r.targetId}${formatRelationshipReason(r, reasonsByRelationship)}`);
         }
+        appendMore(lines, other.length, 6, 'graph edge');
     }
     return lines.length > 0 ? lines : ['- None'];
 }
 function formatList(items) {
     return items.length > 0 ? items : ['- None'];
 }
+function limited(items, count) {
+    return items.slice(0, count);
+}
+function appendMore(lines, total, shown, label) {
+    const remaining = total - shown;
+    if (remaining > 0) {
+        lines.push(`  ◌ ${remaining} more ${label}${remaining === 1 ? '' : 's'} omitted from display`);
+    }
+}
+function atomLine(title, detail) {
+    return `  ● ${title}\n    because ${detail}`;
+}
 function formatReasons(reasons) {
     if (reasons.length === 0) {
         return 'it is near the query';
@@ -151,6 +185,39 @@ function nearbySymbolItems(response) {
         reasons: ['exported symbol from 1-hop import'],
     }));
 }
+function relevantGraphRelationships(response) {
+    const anchorPaths = response.relevantFiles
+        .filter((item) => !item.reasons.some((reason) => reason.includes('generic path-only match penalty')))
+        .slice(0, 3)
+        .map((item) => item.item.path);
+    const paths = anchorPaths.length > 0
+        ? anchorPaths
+        : response.relevantFiles.slice(0, 1).map((item) => item.item.path);
+    if (paths.length === 0)
+        return response.relationships;
+    return response.relationships.filter((relationship) => paths.some((path) => relationship.sourceId.includes(path) ||
+        relationship.targetId.includes(path)));
+}
+function contextConfidence(response) {
+    const confidence = response.relevantCognition
+        .map((item) => item.item.confidence)
+        .find(Boolean);
+    return confidence ?? (response.relevantFiles.length > 0 ? 'medium' : 'low');
+}
+function contextSources(response) {
+    const sources = [];
+    if (response.relevantCognition.length > 0)
+        sources.push('atom');
+    if ((response.gitChanges ?? []).length > 0)
+        sources.push('git change');
+    if (response.relevantSymbols.length > 0)
+        sources.push('symbol');
+    if (relevantGraphRelationships(response).length > 0)
+        sources.push('graph');
+    if (response.relevantFiles.length > 0)
+        sources.push('file');
+    return sources;
+}
 function formatRelationshipReason(relationship, reasonsByRelationship) {
     const reasons = reasonsByRelationship.get(relationshipKey(relationship));
     return reasons && reasons.length > 0

package/dist/cli/commands/pack.js

@@ -26,7 +26,7 @@ export function registerPackCommand(program) {
             readMaps(workspace),
         ]);
         const response = await queryContext(workspace, config, maps, task);
-        const pack = buildContextPack(response, budget);
+        const pack = buildContextPack(response, budget, workspace.rootPath);
         if (options.json) {
             console.log(JSON.stringify(pack, null, 2));
             return;

package/dist/cli/help.js

@@ -1,31 +1,32 @@
 import { Chalk } from 'chalk';
-import figlet from 'figlet';
 export function renderRootHelp(useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
-    const logo = renderLogo();
+    const accent = atomAccent(theme);
     return [
         '',
-        theme.hex('#7dd3fc').bold(logo),
+        renderAtomLogo(theme),
         '',
-        `  ${theme.bold('KGraph')} ${theme.dim('Persistent repo intelligence for AI coding tools')}`,
+        renderSignalPanel(theme, [
+            ['purpose', 'durable engineering memory for AI coding tools'],
+            ['storage', '.kgraph/ atoms, maps, indexes, and session history'],
+            ['stance', 'local-first · deterministic-first · inspectable'],
+            ['agents', 'Codex · Copilot · Cursor · Claude Code · Gemini · Windsurf · Cline'],
+        ]),
         '',
-        `  ${theme.hex('#c084fc')('Build a local knowledge layer that helps Codex, Copilot, Cursor,')}`,
-        `  ${theme.hex('#c084fc')('Claude Code, Gemini, Windsurf, and Cline reuse repo intelligence.')}`,
-        '',
-        theme.bold('Usage'),
+        sectionTitle(theme, `${accent} Usage`),
         '  kgraph [topic]',
         '  kgraph <command> [options]',
         '',
-        theme.bold('Start'),
+        sectionTitle(theme, `${accent} Start`),
         command('init', 'Required once: create .kgraph/ workspace'),
         command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
         '',
-        theme.bold('Daily workflow'),
+        sectionTitle(theme, `${accent} Daily workflow`),
         command('kgraph', 'Refresh scan maps and process pending capture notes'),
         command('kgraph "auth token refresh"', 'Refresh everything and return compact context for a topic'),
         '',
-        theme.bold('Workflows'),
+        sectionTitle(theme, `${accent} Workflows`),
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
         command('session', 'Show agent read/write activity and token estimates'),
         command('session read src/auth.ts --agent codex', 'Record an agent file read'),
@@ -48,7 +49,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
         '',
-        theme.bold('Integrations'),
+        sectionTitle(theme, `${accent} Integrations`),
         command('integrate list', 'Show configured AI tool integrations'),
         command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
         command('integrate add copilot --mode smart', 'Run KGraph for repo-specific Copilot work only'),
@@ -56,21 +57,24 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),
         '',
-        theme.bold('Options'),
+        sectionTitle(theme, `${accent} Options`),
         command('-V, --version', 'Show version'),
         command('-h, --help', 'Show this help'),
         '',
-        `${theme.yellow('Examples')}`,
+        sectionTitle(theme, `${accent} Examples`),
         '  kgraph init --integrations codex,copilot,cursor,claude-code,gemini,windsurf,cline',
         '  kgraph "blog admin token usage"',
+        '  kgraph pack "about page update" --budget 4000',
         '  kgraph doctor',
         '',
         theme.dim('Docs: https://github.com/kentwynn/KGraph#readme'),
+        theme.dim('Powered by Kent Wynn: https://kentwynn.com'),
         '',
     ].join('\n');
 }
 export function renderWorkflowBanner(stats, useColor = supportsColor()) {
     const theme = new Chalk({ level: useColor ? 3 : 0 });
+    const accent = atomAccent(theme);
     const command = (name, description) => `  ${theme.green(name.padEnd(42))} ${description}`;
     const integrationLine = stats.integrations && stats.integrations.length > 0
         ? stats.integrations
@@ -81,11 +85,11 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         : 'none configured';
     return [
         '',
-        theme.hex('#7dd3fc').bold(renderLogo()),
+        renderAtomLogo(theme),
         '',
-        `  ${theme.bold('KGraph')} ${theme.dim('repo intelligence refreshed')}`,
+        `  ${theme.bold('KGraph')} ${theme.dim('· repo intelligence refreshed')}`,
         '',
-        theme.bold('Refresh Complete'),
+        sectionTitle(theme, `${accent} Refresh Complete`),
         command('files', String(stats.files) +
             (stats.skippedFiles
                 ? ` (${stats.skippedFiles} unchanged, skipped)`
@@ -94,7 +98,7 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('capture notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),
         '',
-        theme.bold('Next'),
+        sectionTitle(theme, `${accent} Next`),
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
         command('kgraph doctor --quality', 'Check atom quality'),
@@ -104,17 +108,27 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('kgraph --help', 'Show all commands'),
     ].join('\n');
 }
-function renderLogo() {
-    try {
-        return figlet.textSync('KGraph', {
-            font: 'ANSI Shadow',
-            horizontalLayout: 'default',
-            verticalLayout: 'default',
-        });
-    }
-    catch {
-        return 'KGraph';
-    }
+function renderAtomLogo(theme) {
+    const title = `${theme.hex('#38bdf8').bold('KGraph')} ${theme.dim('·')} ${theme.hex('#c084fc').bold('Atom Core')}`;
+    const atom = theme.hex('#22d3ee').bold('⚛');
+    const memory = theme.hex('#a78bfa')('persistent repo intelligence for AI coding tools');
+    return [
+        `  ${atom}  ${theme.dim('atoms · evidence · context packs')}`,
+        `     ${title}`,
+        `     ${memory}`,
+    ].join('\n');
+}
+function renderSignalPanel(theme, rows) {
+    const labelWidth = Math.max(...rows.map(([label]) => label.length));
+    return rows
+        .map(([label, value]) => `  ${theme.hex('#22d3ee')('●')} ${theme.bold(label.padEnd(labelWidth))}  ${theme.dim(value)}`)
+        .join('\n');
+}
+function sectionTitle(theme, title) {
+    return theme.bold(title);
+}
+function atomAccent(theme) {
+    return theme.hex('#22d3ee')('●');
 }
 function supportsColor() {
     return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;

package/dist/context/context-pack.d.ts

@@ -1,3 +1,3 @@
 import type { ContextResponse } from '../types/cognition.js';
 import type { ContextPack } from '../types/knowledge.js';
-export declare function buildContextPack(response: ContextResponse, budget: number): ContextPack;
+export declare function buildContextPack(response: ContextResponse, budget: number, rootPath?: string): ContextPack;

package/dist/context/context-pack.js

@@ -1,5 +1,8 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import { estimateTokens } from '../session/token-estimator.js';
-export function buildContextPack(response, budget) {
+import { tokenize } from './ranking.js';
+export function buildContextPack(response, budget, rootPath) {
     const candidates = [
         ...response.relevantFiles.map((ranked) => ({
             kind: 'file',
@@ -9,6 +12,7 @@ export function buildContextPack(response, budget) {
             reasons: ranked.reasons,
             data: ranked.item,
         })),
+        ...buildFileRangeCandidates(response, budget, rootPath),
         ...response.relevantSymbols.map((ranked) => ({
             kind: 'symbol',
             id: ranked.item.id,
@@ -76,15 +80,17 @@ function comparePackCandidates(left, right) {
 function packPriority(item) {
     let score = 0;
     if (item.kind === 'atom')
-        score += 40;
+        score += 1000;
     if (item.kind === 'git-change')
-        score += 35;
+        score += 900;
+    if (item.kind === 'file-range')
+        score += 800;
     if (item.kind === 'symbol')
-        score += 25;
+        score += 300;
     if (item.kind === 'file')
-        score += 15;
+        score += 200;
     if (item.kind === 'relationship')
-        score += 5;
+        score += 100;
     if (item.reasons.some((reason) => reason.includes('matched atom')))
         score += 30;
     if (item.reasons.some((reason) => reason.includes('current git change')))
@@ -96,3 +102,104 @@ function packPriority(item) {
     score -= Math.floor(item.tokenEstimate / 2000);
     return score;
 }
+const GENERIC_RANGE_TOKENS = new Set([
+    'app',
+    'code',
+    'component',
+    'file',
+    'page',
+    'repo',
+    'work',
+]);
+function buildFileRangeCandidates(response, budget, rootPath) {
+    if (!rootPath)
+        return [];
+    const queryTokens = tokenize(response.query).filter((token) => token.length >= 3 && !GENERIC_RANGE_TOKENS.has(token));
+    if (queryTokens.length === 0)
+        return [];
+    const maxRangeTokens = Math.max(250, Math.min(1200, Math.floor(budget / 3)));
+    const candidates = [];
+    for (const rankedFile of response.relevantFiles.slice(0, 8)) {
+        const file = rankedFile.item;
+        const fileTokens = file.tokenEstimate ?? 0;
+        if (fileTokens <= Math.max(1000, Math.floor(budget / 2)))
+            continue;
+        const fullPath = path.join(rootPath, file.path);
+        if (!existsSync(fullPath))
+            continue;
+        let content = '';
+        try {
+            content = readFileSync(fullPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const ranges = selectQueryRanges(content, queryTokens, maxRangeTokens, file.path);
+        for (const range of ranges) {
+            const lines = content.split(/\r?\n/).slice(range.start - 1, range.end);
+            const excerpt = lines.join('\n');
+            candidates.push({
+                kind: 'file-range',
+                id: `${file.path}:${range.start}-${range.end}`,
+                title: `${file.path}:${range.start}-${range.end}`,
+                tokenEstimate: estimateTokens(excerpt, file.path),
+                reasons: [
+                    ...rankedFile.reasons,
+                    `range selected from oversized file`,
+                    `line text matched ${range.tokens.map((token) => `"${token}"`).join(', ')}`,
+                ],
+                data: {
+                    path: file.path,
+                    startLine: range.start,
+                    endLine: range.end,
+                    excerpt,
+                },
+            });
+        }
+    }
+    return candidates;
+}
+function selectQueryRanges(content, queryTokens, maxRangeTokens, filePath) {
+    const lines = content.split(/\r?\n/);
+    const hits = [];
+    for (const [index, line] of lines.entries()) {
+        const lower = line.toLowerCase();
+        const matched = queryTokens.filter((token) => lower.includes(token));
+        if (matched.length === 0)
+            continue;
+        hits.push({
+            start: Math.max(1, index + 1 - 8),
+            end: Math.min(lines.length, index + 1 + 8),
+            tokens: matched,
+        });
+    }
+    const ranges = mergeRanges(hits);
+    return ranges
+        .sort((left, right) => right.tokens.length - left.tokens.length)
+        .slice(0, 3)
+        .map((range) => trimRangeToBudget(range, lines, maxRangeTokens, filePath));
+}
+function mergeRanges(ranges) {
+    const merged = [];
+    for (const range of ranges.sort((left, right) => left.start - right.start)) {
+        const current = merged.at(-1);
+        if (!current || range.start > current.end + 3) {
+            merged.push({ ...range, tokens: [...new Set(range.tokens)] });
+            continue;
+        }
+        current.end = Math.max(current.end, range.end);
+        current.tokens = [...new Set([...current.tokens, ...range.tokens])];
+    }
+    return merged;
+}
+function trimRangeToBudget(range, lines, maxRangeTokens, filePath) {
+    let start = range.start;
+    let end = Math.min(range.end, start + 79);
+    while (end > start + 4) {
+        const excerpt = lines.slice(start - 1, end).join('\n');
+        if (estimateTokens(excerpt, filePath) <= maxRangeTokens)
+            break;
+        end -= 5;
+    }
+    return { ...range, start, end };
+}

package/dist/types/knowledge.d.ts

@@ -75,7 +75,7 @@ export interface KnowledgeValidationIssue {
     atomId?: string;
 }
 export interface ContextPackItem {
-    kind: 'file' | 'symbol' | 'atom' | 'relationship' | 'git-change';
+    kind: 'file' | 'file-range' | 'symbol' | 'atom' | 'relationship' | 'git-change';
     id: string;
     title: string;
     tokenEstimate: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -47,7 +47,6 @@
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "fast-glob": "^3.3.2",
-    "figlet": "^1.11.0",
     "tree-sitter-c": "^0.24.1",
     "tree-sitter-c-sharp": "^0.23.5",
     "tree-sitter-cpp": "^0.23.4",