@kentwynn/kgraph 0.2.9 → 0.2.11

package/README.md

@@ -222,12 +222,39 @@ kgraph conclude "auth refresh requires rotating the session cookie" \
 
 Store durable engineering memory directly. Cognition is typed as `finding`, `decision`, `gotcha`, `summary`, or `relationship`, and confidence is `high`, `medium`, or `low`. Keep conclusions concise: preserve expensive-to-rediscover knowledge, not raw chain-of-thought, speculative exploration, or temporary reasoning.
 
+KGraph stores these conclusions as canonical knowledge atoms under `.kgraph/knowledge/` while keeping existing Markdown cognition files readable for compatibility.
+
+```bash
+kgraph knowledge list
+kgraph knowledge list --type finding --topic auth --json
+kgraph knowledge get <atom-id>
+kgraph knowledge archive <atom-id>
+kgraph knowledge supersede <old-id> <new-id>
+```
+
+Inspect and manage canonical knowledge atoms. Archive and supersede update lifecycle metadata; they do not delete history.
+
+```bash
+kgraph stale
+kgraph stale --json
+kgraph blame <atom-id>
+```
+
+Refresh atom lifecycle status against the current scan and inspect atom provenance. Changed file hashes move atoms to `needs-review`; deleted files or missing symbols move atoms to `stale`; `blame` shows the source command, agent/session/commit, evidence refs, and lifecycle links.
+
+```bash
+kgraph pack "auth token refresh" --budget 8000
+kgraph pack "auth token refresh" --budget 8000 --json
+```
+
+Build a budget-aware context pack from files, symbols, relationships, git changes, session history, and knowledge atoms. JSON output is the stable machine-readable contract for agents.
+
 ```bash
 kgraph compact --dry-run
 kgraph compact
 ```
 
-Merge duplicate cognition records and archive low-confidence stale entries. Compaction keeps memory inspectable under `.kgraph/cognition/` while reducing low-value noise in future context responses.
+Merge duplicate knowledge atoms and archive low-confidence stale entries. Compaction operates on `.kgraph/knowledge/atoms.jsonl` first, then regenerates indexes and compatibility domain records so future context responses use the atom lifecycle as the source of truth.
 
 ## Optional Step Commands
 
@@ -327,10 +354,14 @@ All runtime data lives under `.kgraph/`:
 ├── domains/
 ├── interactions/processed/
 ├── sessions/
+├── knowledge/
+│   ├── atoms.jsonl
+│   ├── schema.json
+│   └── indexes/
 └── context/
 ```
 
-The files are local, inspectable, and human-readable. Core KGraph functionality is free. There is no database, telemetry, cloud service, account, API key, embedding service, model provider, or source-code upload.
+The files are local, inspectable, and human-readable. `knowledge/atoms.jsonl` is the canonical durable-memory store; Markdown cognition remains a compatibility and input layer. Core KGraph functionality is free. There is no database, telemetry, cloud service, account, API key, embedding service, model provider, or source-code upload.
 
 ## Language Support
 

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerBlameCommand(program: Command): void;

package/dist/cli/commands/blame.js

@@ -0,0 +1,52 @@
+import { readKnowledgeAtoms } from '../../knowledge/atom-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerBlameCommand(program) {
+    program
+        .command('blame <atomId>')
+        .description('Show who or what created a knowledge atom and why it exists')
+        .option('--json', 'Print JSON output')
+        .action((atomId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const atom = (await readKnowledgeAtoms(workspace)).find((candidate) => candidate.id === atomId);
+        if (!atom)
+            throw new KGraphError(`Knowledge atom not found: ${atomId}`);
+        const result = {
+            id: atom.id,
+            topic: atom.topic,
+            claim: atom.claim,
+            provenance: atom.provenance,
+            evidenceRefs: atom.evidenceRefs,
+            lifecycle: atom.lifecycle,
+        };
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`# ${atom.topic}`);
+        console.log('');
+        console.log(`ID: ${atom.id}`);
+        console.log(`Claim: ${atom.claim}`);
+        console.log(`Source: ${atom.provenance.sourceCommand}`);
+        if (atom.provenance.agent)
+            console.log(`Agent: ${atom.provenance.agent}`);
+        if (atom.provenance.sessionId) {
+            console.log(`Session: ${atom.provenance.sessionId}`);
+        }
+        if (atom.provenance.commit)
+            console.log(`Commit: ${atom.provenance.commit}`);
+        console.log(`Created: ${atom.provenance.createdAt}`);
+        if (atom.provenance.updatedAt)
+            console.log(`Updated: ${atom.provenance.updatedAt}`);
+        console.log('');
+        console.log('Evidence:');
+        for (const ref of atom.evidenceRefs) {
+            console.log(`- ${JSON.stringify(ref)}`);
+        }
+        if (atom.lifecycle.supersededBy || atom.lifecycle.supersedes.length > 0) {
+            console.log('');
+            console.log('Lifecycle:');
+            console.log(JSON.stringify(atom.lifecycle, null, 2));
+        }
+    }));
+}

package/dist/cli/commands/doctor.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { analyzeCognitionQuality, } from '../../cognition/cognition-quality.js';
 import { loadConfig } from '../../config/config.js';
 import { listIntegrations } from '../../integrations/integration-store.js';
+import { validateKnowledgeStore } from '../../knowledge/atom-store.js';
 import { getCurrentCommit, isGitRepo } from '../../scanner/git-utils.js';
 import { assertWorkspace, pathExists, resolveWorkspace, } from '../../storage/kgraph-paths.js';
 import { mapPaths, mapsExist, readMaps } from '../../storage/map-store.js';
@@ -76,6 +77,22 @@ export function registerDoctorCommand(program) {
                 detail: missing.join(', '),
             });
         }
+        const knowledgeIssues = await validateKnowledgeStore(workspace, maps
+            ? { fileMap: maps.fileMap, symbolMap: maps.symbolMap }
+            : undefined);
+        checks.push({
+            label: 'knowledge',
+            ok: knowledgeIssues.length === 0,
+            detail: knowledgeIssues.length === 0
+                ? 'knowledge atoms, schema, and refs are valid'
+                : knowledgeIssues
+                    .slice(0, 3)
+                    .map((issue) => issue.message)
+                    .join('; ') +
+                    (knowledgeIssues.length > 3
+                        ? `; and ${knowledgeIssues.length - 3} more`
+                        : ''),
+        });
         const inboxCount = await countMarkdownFiles(workspace.inboxPath);
         checks.push({
             label: 'inbox',

package/dist/cli/commands/init.js

@@ -1,6 +1,7 @@
 import { loadConfig, writeDefaultConfig } from '../../config/config.js';
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations } from '../../integrations/integration-store.js';
+import { ensureKnowledgeStore } from '../../knowledge/atom-store.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
 import { ensureWorkspace } from '../../storage/kgraph-paths.js';
 import { readMaps, writeMaps } from '../../storage/map-store.js';
@@ -17,6 +18,7 @@ export function registerInitCommand(program) {
         .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'smart')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
+        await ensureKnowledgeStore(workspace);
         const wroteConfig = await writeDefaultConfig(workspace);
         console.log(wroteConfig
             ? 'Initialized .kgraph workspace.'

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerKnowledgeCommand(program: Command): void;

package/dist/cli/commands/knowledge.js

@@ -0,0 +1,137 @@
+import { readKnowledgeAtoms, updateKnowledgeAtom, } from '../../knowledge/atom-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerKnowledgeCommand(program) {
+    const knowledge = program
+        .command('knowledge')
+        .description('Manage canonical KGraph knowledge atoms');
+    knowledge
+        .command('list')
+        .option('--type <type>', 'Filter by atom type')
+        .option('--topic <topic>', 'Filter by topic substring')
+        .option('--status <status>', 'Filter by active, stale, needs-review, or archived')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const atoms = filterAtoms(await readKnowledgeAtoms(workspace), options);
+        if (options.json) {
+            console.log(JSON.stringify(atoms, null, 2));
+            return;
+        }
+        console.log('KGraph Knowledge');
+        console.log('');
+        for (const atom of atoms) {
+            console.log(`- ${atom.id} [${atom.type}, ${atom.confidence}, ${atom.status}] ${atom.topic}`);
+            console.log(`  ${atom.claim}`);
+        }
+        if (atoms.length === 0)
+            console.log('- None');
+    }));
+    knowledge
+        .command('get <atomId>')
+        .option('--json', 'Print JSON output')
+        .action((atomId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const atom = await requireAtom(workspace, atomId);
+        if (options.json) {
+            console.log(JSON.stringify(atom, null, 2));
+            return;
+        }
+        console.log(`# ${atom.topic}`);
+        console.log('');
+        console.log(`ID: ${atom.id}`);
+        console.log(`Type: ${atom.type}`);
+        console.log(`Confidence: ${atom.confidence}`);
+        console.log(`Status: ${atom.status}`);
+        console.log(`Claim: ${atom.claim}`);
+        if (atom.summary)
+            console.log(`Summary: ${atom.summary}`);
+        console.log('');
+        console.log('Evidence:');
+        for (const ref of atom.evidenceRefs) {
+            console.log(`- ${JSON.stringify(ref)}`);
+        }
+        console.log('');
+        console.log('Provenance:');
+        console.log(JSON.stringify(atom.provenance, null, 2));
+        console.log('');
+        console.log('Lifecycle:');
+        console.log(JSON.stringify(atom.lifecycle, null, 2));
+    }));
+    knowledge
+        .command('archive <atomId>')
+        .option('--json', 'Print JSON output')
+        .action((atomId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const now = new Date().toISOString();
+        const atom = await updateKnowledgeAtom(workspace, atomId, (current) => ({
+            ...current,
+            status: 'archived',
+            provenance: { ...current.provenance, updatedAt: now },
+            lifecycle: { ...current.lifecycle, archivedAt: now },
+        }));
+        console.log(options.json
+            ? JSON.stringify(atom, null, 2)
+            : `Archived knowledge atom: ${atom.id}`);
+    }));
+    knowledge
+        .command('supersede <oldId> <newId>')
+        .option('--json', 'Print JSON output')
+        .action((oldId, newId, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        await requireAtom(workspace, newId);
+        const now = new Date().toISOString();
+        const oldAtom = await updateKnowledgeAtom(workspace, oldId, (current) => ({
+            ...current,
+            status: 'archived',
+            provenance: { ...current.provenance, updatedAt: now },
+            lifecycle: {
+                ...current.lifecycle,
+                supersededBy: newId,
+                archivedAt: now,
+            },
+        }));
+        const newAtom = await updateKnowledgeAtom(workspace, newId, (current) => ({
+            ...current,
+            provenance: { ...current.provenance, updatedAt: now },
+            lifecycle: {
+                ...current.lifecycle,
+                supersedes: [...new Set([...current.lifecycle.supersedes, oldId])],
+            },
+        }));
+        const result = { old: oldAtom, new: newAtom };
+        console.log(options.json
+            ? JSON.stringify(result, null, 2)
+            : `Superseded ${oldId} with ${newId}`);
+    }));
+}
+async function requireAtom(workspace, atomId) {
+    const atom = (await readKnowledgeAtoms(workspace)).find((candidate) => candidate.id === atomId);
+    if (!atom)
+        throw new KGraphError(`Knowledge atom not found: ${atomId}`);
+    return atom;
+}
+function filterAtoms(atoms, options) {
+    return atoms.filter((atom) => {
+        if (options.type && atom.type !== options.type)
+            return false;
+        if (options.status &&
+            atom.status !== normalizeStatus(options.status)) {
+            return false;
+        }
+        if (options.topic &&
+            !atom.topic.toLowerCase().includes(options.topic.toLowerCase())) {
+            return false;
+        }
+        return true;
+    });
+}
+function normalizeStatus(value) {
+    if (value === 'active' ||
+        value === 'stale' ||
+        value === 'needs-review' ||
+        value === 'archived') {
+        return value;
+    }
+    throw new KGraphError('--status must be active, stale, needs-review, or archived.');
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerPackCommand(program: Command): void;

package/dist/cli/commands/pack.js

@@ -0,0 +1,49 @@
+import { buildContextPack } from '../../context/context-pack.js';
+import { queryContext } from '../../context/context-query.js';
+import { loadConfig } from '../../config/config.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../../storage/map-store.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerPackCommand(program) {
+    program
+        .command('pack <task>')
+        .description('Build a budget-aware KGraph context pack for a task')
+        .option('--budget <tokens>', 'Maximum estimated tokens to include', '8000')
+        .option('--json', 'Print JSON output')
+        .action((task, options) => runCommand(async () => {
+        if (!task.trim())
+            throw new KGraphError('Task cannot be empty.');
+        const budget = Number.parseInt(options.budget ?? '8000', 10);
+        if (!Number.isFinite(budget) || budget < 1) {
+            throw new KGraphError('--budget must be a positive integer.');
+        }
+        const workspace = await assertWorkspace(process.cwd());
+        if (!(await mapsExist(workspace))) {
+            throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+        }
+        const [config, maps] = await Promise.all([
+            loadConfig(workspace),
+            readMaps(workspace),
+        ]);
+        const response = await queryContext(workspace, config, maps, task);
+        const pack = buildContextPack(response, budget);
+        if (options.json) {
+            console.log(JSON.stringify(pack, null, 2));
+            return;
+        }
+        console.log(`# KGraph Context Pack`);
+        console.log('');
+        console.log(`Task: ${pack.task}`);
+        console.log(`Budget: ${pack.budget}`);
+        console.log(`Used: ${pack.usedTokens}`);
+        console.log('');
+        for (const item of pack.items) {
+            console.log(`- [${item.kind}] ${item.title} (~${item.tokenEstimate} tokens)`);
+            console.log(`  because ${item.reasons.slice(0, 3).join('; ')}`);
+        }
+        if (pack.omitted.length > 0) {
+            console.log('');
+            console.log(`Omitted: ${pack.omitted.length} item(s) over budget`);
+        }
+    }));
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerStaleCommand(program: Command): void;

package/dist/cli/commands/stale.js

@@ -0,0 +1,33 @@
+import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
+import { readMaps } from '../../storage/map-store.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { runCommand } from '../errors.js';
+export function registerStaleCommand(program) {
+    program
+        .command('stale')
+        .description('Show knowledge atoms invalidated by changed or missing refs')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const maps = await readMaps(workspace);
+        const result = await refreshKnowledgeAtomStatuses(workspace, {
+            fileMap: maps.fileMap,
+            symbolMap: maps.symbolMap,
+        });
+        const atoms = result.atoms.filter((atom) => atom.status === 'stale' || atom.status === 'needs-review');
+        if (options.json) {
+            console.log(JSON.stringify({ updated: result.updated, atoms }, null, 2));
+            return;
+        }
+        console.log('KGraph Stale Knowledge');
+        console.log('');
+        for (const atom of atoms) {
+            console.log(`- ${atom.id} [${atom.type}, ${atom.confidence}, ${atom.status}] ${atom.topic}`);
+            for (const reason of atom.lifecycle.invalidatedBy ?? []) {
+                console.log(`  - ${reason}`);
+            }
+        }
+        if (atoms.length === 0)
+            console.log('- None');
+    }));
+}

package/dist/cli/help.js

@@ -32,6 +32,10 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('session end --agent codex --conclude', 'End tracking and store a durable session summary'),
         command('conclude "auth refresh gotcha"', 'Store typed engineering cognition'),
         command('compact', 'Merge duplicate cognition and archive stale noise'),
+        command('knowledge list', 'Inspect canonical knowledge atoms'),
+        command('pack "auth task" --budget 8000', 'Build a budget-aware context pack'),
+        command('stale', 'Show atoms invalidated by changed or missing refs'),
+        command('blame <atom-id>', 'Show atom provenance and evidence'),
         command('context "auth token refresh"', 'Optional: return context without scanning or updating'),
         command('impact "Button"', 'Show imports, callers, calls, cognition, and risk'),
         command('update', 'Optional: process only .kgraph/inbox Markdown cognition notes'),
@@ -94,6 +98,8 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
         command('kgraph "auth token refresh"', 'Return compact context for a topic'),
         command('kgraph doctor', 'Check workspace health'),
         command('kgraph doctor --quality', 'Check cognition quality'),
+        command('kgraph knowledge list', 'Inspect knowledge atoms'),
+        command('kgraph pack "auth task"', 'Build budget-aware context'),
         command('kgraph session', 'Check session token waste'),
         command('kgraph --help', 'Show all commands'),
     ].join('\n');

package/dist/cli/index.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { registerBlameCommand } from './commands/blame.js';
 import { registerCompactCommand } from './commands/compact.js';
 import { registerConcludeCommand } from './commands/conclude.js';
 import { registerContextCommand } from './commands/context.js';
@@ -11,9 +12,12 @@ import { registerHistoryCommand } from './commands/history.js';
 import { registerImpactCommand } from './commands/impact.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
+import { registerKnowledgeCommand } from './commands/knowledge.js';
+import { registerPackCommand } from './commands/pack.js';
 import { registerRepairCommand } from './commands/repair.js';
 import { registerScanCommand } from './commands/scan.js';
 import { registerSessionCommand } from './commands/session.js';
+import { registerStaleCommand } from './commands/stale.js';
 import { registerUninstallCommand } from './commands/uninstall.js';
 import { registerUpdateCommand } from './commands/update.js';
 import { registerVisualizeCommand } from './commands/visualize.js';
@@ -46,6 +50,10 @@ export function createProgram() {
     registerCompactCommand(program);
     registerUpdateCommand(program);
     registerContextCommand(program);
+    registerPackCommand(program);
+    registerKnowledgeCommand(program);
+    registerStaleCommand(program);
+    registerBlameCommand(program);
     registerImpactCommand(program);
     registerIntegrateCommand(program);
     registerVisualizeCommand(program);

package/dist/cognition/cognition-updater.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { archiveInboxNote, listInboxNotes, readCognitionNotes, slugify, writeCognitionNote, writeDomainRecord, } from '../storage/cognition-store.js';
 import { parseMarkdownNote } from './markdown-note-parser.js';
+import { createKnowledgeAtom } from '../knowledge/atom-store.js';
 export async function updateCognition(workspace, currentMaps, dryRun = false) {
     const inboxNotes = await listInboxNotes(workspace);
     const processed = [];
@@ -38,6 +39,19 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
                 await archiveInboxNote(workspace, inboxPath, timestamp);
                 await writeCognitionNote(workspace, note);
                 await writeDomainRecord(workspace, toDomainRecord(note, currentMaps));
+                await createKnowledgeAtom(workspace, {
+                    type: note.kind,
+                    topic: note.title,
+                    claim: note.summary ?? note.title,
+                    summary: note.summary,
+                    confidence: note.confidence,
+                    files: note.relatedFiles,
+                    symbols: note.relatedSymbols,
+                    domains: note.domain ? [note.domain] : [],
+                    sourceCommand: 'update',
+                    createdAt: note.createdAt,
+                    idSeed: note.id,
+                });
             }
         }
         catch (error) {