@kentwynn/kgraph 0.2.9 → 0.2.11

package/dist/cognition/compact.js

@@ -1,58 +1,89 @@
 import { mkdir, rename } from 'node:fs/promises';
 import path from 'node:path';
-import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, slugify, writeCognitionNote, } from '../storage/cognition-store.js';
+import { atomToCognitionNote, refreshKnowledgeAtomStatuses, writeKnowledgeAtoms, } from '../knowledge/atom-store.js';
+import { overwriteDomainRecord, readDomainRecords, slugify, writeCognitionNote, } from '../storage/cognition-store.js';
 import { pathExists } from '../storage/kgraph-paths.js';
 import { readMaps } from '../storage/map-store.js';
 import { evaluateReferenceStatus } from './cognition-updater.js';
 export async function compactCognition(workspace, dryRun = false) {
-    const notes = await readCognitionNotes(workspace);
     const maps = await readMaps(workspace);
-    const groups = groupDuplicates(notes);
+    const refreshed = await refreshKnowledgeAtomStatuses(workspace, { fileMap: maps.fileMap, symbolMap: maps.symbolMap }, dryRun);
+    const atoms = refreshed.atoms;
+    const groups = groupDuplicateAtoms(atoms);
     const result = { merged: [], archived: [] };
     const consumed = new Set();
     const archived = new Set();
-    const mergedNotes = [];
+    const mergedAtoms = [];
     for (const group of groups.filter((items) => items.length > 1)) {
-        const merged = mergeNotes(group, {
+        const merged = mergeAtoms(group, {
             files: maps.fileMap.files,
             symbols: maps.symbolMap.symbols,
         });
-        const sourceIds = group.map((note) => note.id);
+        const sourceIds = group.map((atom) => atom.id);
         result.merged.push({
             targetId: merged.id,
             sourceIds,
-            title: merged.title,
+            title: merged.topic,
         });
         sourceIds.forEach((id) => consumed.add(id));
-        mergedNotes.push(merged);
-        if (!dryRun) {
-            await writeCognitionNote(workspace, merged);
-            for (const note of group) {
-                await archiveNote(workspace, note, `superseded-by-${merged.id}`);
-            }
-        }
+        mergedAtoms.push(merged);
     }
-    for (const note of notes) {
-        if (consumed.has(note.id))
+    for (const atom of atoms) {
+        if (consumed.has(atom.id) || atom.status === 'archived')
             continue;
-        if (note.confidence === 'low' &&
-            (note.referencesStatus === 'stale' || note.referencesStatus === 'unresolved')) {
+        if (atom.confidence === 'low' &&
+            (atom.status === 'stale' || atom.status === 'needs-review')) {
             result.archived.push({
-                id: note.id,
-                title: note.title,
-                reason: 'low-confidence stale cognition',
+                id: atom.id,
+                title: atom.topic,
+                reason: `low-confidence ${atom.status} atom`,
             });
-            archived.add(note.id);
-            if (!dryRun) {
-                await archiveNote(workspace, note, 'low-confidence-stale');
-            }
+            archived.add(atom.id);
         }
     }
     if (!dryRun && (consumed.size > 0 || archived.size > 0)) {
-        const activeNotes = [
-            ...notes.filter((note) => !consumed.has(note.id) && !archived.has(note.id)),
-            ...mergedNotes,
+        const now = new Date().toISOString();
+        const nextAtoms = [
+            ...atoms.map((atom) => {
+                if (consumed.has(atom.id)) {
+                    const merged = mergedAtoms.find((candidate) => candidate.lifecycle.supersedes.includes(atom.id));
+                    return {
+                        ...atom,
+                        status: 'archived',
+                        confidence: 'low',
+                        lifecycle: {
+                            ...atom.lifecycle,
+                            supersededBy: merged?.id,
+                            archivedAt: now,
+                        },
+                        provenance: { ...atom.provenance, updatedAt: now },
+                    };
+                }
+                if (archived.has(atom.id)) {
+                    return {
+                        ...atom,
+                        status: 'archived',
+                        lifecycle: { ...atom.lifecycle, archivedAt: now },
+                        provenance: { ...atom.provenance, updatedAt: now },
+                    };
+                }
+                return atom;
+            }),
+            ...mergedAtoms,
         ];
+        await writeKnowledgeAtoms(workspace, nextAtoms);
+        for (const atom of [...atoms.filter((item) => consumed.has(item.id) || archived.has(item.id)), ...mergedAtoms]) {
+            const note = atomToCognitionNote(atom);
+            if (mergedAtoms.some((merged) => merged.id === atom.id)) {
+                await writeCognitionNote(workspace, note);
+            }
+            else {
+                await archiveNote(workspace, note, consumed.has(atom.id) ? `superseded-by-${note.supersededBy ?? 'compact'}` : 'low-confidence-stale');
+            }
+        }
+        const activeNotes = nextAtoms
+            .filter((atom) => atom.status !== 'archived')
+            .map(atomToCognitionNote);
         await rebuildDomainRecords(workspace, activeNotes, {
             files: maps.fileMap.files,
             symbols: maps.symbolMap.symbols,
@@ -60,6 +91,59 @@ export async function compactCognition(workspace, dryRun = false) {
     }
     return result;
 }
+function groupDuplicateAtoms(atoms) {
+    const byKey = new Map();
+    for (const atom of atoms) {
+        if (atom.status === 'archived' || atom.lifecycle.supersededBy)
+            continue;
+        const key = [
+            atom.type,
+            atom.scopeRefs.domains[0] ?? 'general',
+            normalizeText(atom.topic),
+            normalizeText(atom.claim),
+            stableList(atom.scopeRefs.files),
+            stableList(atom.scopeRefs.symbols),
+        ].join('\0');
+        const group = byKey.get(key) ?? [];
+        group.push(atom);
+        byKey.set(key, group);
+    }
+    return [...byKey.values()];
+}
+function mergeAtoms(atoms, currentMaps) {
+    const sorted = [...atoms].sort((left, right) => left.provenance.createdAt.localeCompare(right.provenance.createdAt));
+    const base = sorted[sorted.length - 1];
+    const now = new Date().toISOString();
+    const id = `${now.replace(/[:.]/g, '-')}-${slugify(base.topic) || 'compacted'}`;
+    const summaries = unique(sorted
+        .map((atom) => atom.summary ?? atom.claim)
+        .filter((summary) => Boolean(summary?.trim())));
+    const files = unique(sorted.flatMap((atom) => atom.scopeRefs.files));
+    const symbols = unique(sorted.flatMap((atom) => atom.scopeRefs.symbols));
+    const domains = unique(sorted.flatMap((atom) => atom.scopeRefs.domains));
+    const packages = unique(sorted.flatMap((atom) => atom.scopeRefs.packages));
+    const status = atomStatusFromReferenceStatus(evaluateReferenceStatus(files, symbols, currentMaps));
+    return {
+        ...base,
+        id,
+        claim: summaries[0] ?? base.claim,
+        summary: summaries.join('\n'),
+        confidence: highestConfidence(sorted.map((atom) => atom.confidence)),
+        status,
+        evidenceRefs: uniqueEvidence(sorted.flatMap((atom) => atom.evidenceRefs)),
+        scopeRefs: { files, symbols, domains, packages },
+        provenance: {
+            sourceCommand: 'compact',
+            agent: base.provenance.agent,
+            sessionId: base.provenance.sessionId,
+            commit: base.provenance.commit,
+            createdAt: now,
+        },
+        lifecycle: {
+            supersedes: sorted.map((atom) => atom.id),
+        },
+    };
+}
 function groupDuplicates(notes) {
     const byKey = new Map();
     for (const note of notes) {
@@ -153,6 +237,23 @@ function highestConfidence(values) {
         return 'medium';
     return 'low';
 }
+function atomStatusFromReferenceStatus(status) {
+    if (status === 'current')
+        return 'active';
+    if (status === 'mixed')
+        return 'needs-review';
+    return 'stale';
+}
+function uniqueEvidence(items) {
+    const seen = new Set();
+    return items.filter((item) => {
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
 function normalizeTitle(value) {
     return normalizeText(value);
 }

package/dist/cognition/conclusion.d.ts

@@ -10,6 +10,8 @@ export interface ConclusionInput {
     relatedFiles?: string[];
     relatedSymbols?: string[];
     source: CognitionSource;
+    agent?: string;
+    sessionId?: string;
 }
 export declare function concludeTopic(workspace: KGraphWorkspace, input: ConclusionInput): Promise<CognitionNote>;
 export declare function concludeActiveSession(workspace: KGraphWorkspace, agent: string, input: Omit<ConclusionInput, 'source' | 'relatedFiles' | 'relatedSymbols'>): Promise<CognitionNote>;

package/dist/cognition/conclusion.js

@@ -1,6 +1,7 @@
 import { readMaps } from '../storage/map-store.js';
 import { slugify, writeCognitionNote, writeDomainRecord } from '../storage/cognition-store.js';
 import { KGraphError } from '../cli/errors.js';
+import { createKnowledgeAtom } from '../knowledge/atom-store.js';
 import { evaluateReferenceStatus } from './cognition-updater.js';
 import { readSessionState } from '../session/session-store.js';
 export async function concludeTopic(workspace, input) {
@@ -36,6 +37,25 @@ export async function concludeTopic(workspace, input) {
         files: maps.fileMap.files,
         symbols: maps.symbolMap.symbols,
     }));
+    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: input.source === 'session-conclude'
+            ? 'session-conclude'
+            : input.source === 'compact'
+                ? 'compact'
+                : 'conclude',
+        agent: input.agent,
+        sessionId: input.sessionId,
+        createdAt: note.createdAt,
+        idSeed: note.id,
+    }, maps);
     return note;
 }
 export async function concludeActiveSession(workspace, agent, input) {
@@ -76,6 +96,8 @@ export async function buildActiveSessionConclusion(workspace, agent, input) {
         body,
         source: 'session-conclude',
         relatedFiles: touchedFiles,
+        agent,
+        sessionId: active.sessionId,
     };
 }
 function normalizeBody(value) {

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

@@ -0,0 +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;

package/dist/context/context-pack.js

@@ -0,0 +1,71 @@
+import { estimateTokens } from '../session/token-estimator.js';
+export function buildContextPack(response, budget) {
+    const candidates = [
+        ...response.relevantFiles.map((ranked) => ({
+            kind: 'file',
+            id: ranked.item.path,
+            title: ranked.item.path,
+            tokenEstimate: ranked.item.tokenEstimate ?? 0,
+            reasons: ranked.reasons,
+            data: ranked.item,
+        })),
+        ...response.relevantSymbols.map((ranked) => ({
+            kind: 'symbol',
+            id: ranked.item.id,
+            title: ranked.item.name,
+            tokenEstimate: 20,
+            reasons: ranked.reasons,
+            data: ranked.item,
+        })),
+        ...response.relevantCognition.map((ranked) => ({
+            kind: 'atom',
+            id: ranked.item.id,
+            title: ranked.item.title,
+            tokenEstimate: estimateTokens([ranked.item.title, ranked.item.summary ?? ''].join('\n'), `${ranked.item.id}.md`),
+            reasons: ranked.reasons,
+            data: ranked.item,
+        })),
+        ...response.relationships.map((relationship) => ({
+            kind: 'relationship',
+            id: [
+                relationship.sourceId,
+                relationship.relationshipType,
+                relationship.targetId,
+            ].join(' -> '),
+            title: `${relationship.sourceId} ${relationship.relationshipType} ${relationship.targetId}`,
+            tokenEstimate: 16,
+            reasons: response.relationshipExplanations?.find((item) => item.relationship.sourceId === relationship.sourceId &&
+                item.relationship.targetId === relationship.targetId &&
+                item.relationship.relationshipType === relationship.relationshipType)?.reasons ?? ['related graph edge'],
+            data: relationship,
+        })),
+        ...(response.gitChanges ?? []).map((change) => ({
+            kind: 'git-change',
+            id: change.path,
+            title: `${change.status}: ${change.path}`,
+            tokenEstimate: 12,
+            reasons: [change.reason],
+            data: change,
+        })),
+    ];
+    const items = [];
+    const omitted = [];
+    let usedTokens = 0;
+    for (const candidate of candidates) {
+        if (usedTokens + candidate.tokenEstimate <= budget) {
+            items.push(candidate);
+            usedTokens += candidate.tokenEstimate;
+        }
+        else {
+            omitted.push(candidate);
+        }
+    }
+    return {
+        task: response.query,
+        budget,
+        usedTokens,
+        items,
+        omitted,
+        warnings: response.warnings,
+    };
+}

package/dist/context/context-query.js

@@ -1,9 +1,17 @@
 import { getRecentlyCommittedFiles, getWorkingTreeChangesDetailed, isGitRepo, } from '../scanner/git-utils.js';
-import { readCognitionNotes, readDomainRecords, } from '../storage/cognition-store.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';
 export async function queryContext(workspace, config, maps, query) {
-    const cognition = await readCognitionNotes(workspace);
+    const refreshedAtoms = await refreshKnowledgeAtomStatuses(workspace, {
+        fileMap: maps.fileMap,
+        symbolMap: maps.symbolMap,
+    });
+    const atoms = refreshedAtoms.atoms;
+    const cognition = atoms
+        .filter((atom) => atom.status !== 'archived')
+        .map(atomToCognitionNote);
     const domains = await readDomainRecords(workspace);
     const session = await readSessionState(workspace);
     const sessionTouchedPaths = new Set(session.events
@@ -31,17 +39,23 @@ export async function queryContext(workspace, config, maps, query) {
         { name: 'kind', value: (symbol) => symbol.kind },
         { name: 'parent', value: (symbol) => symbol.parentName },
     ]).slice(0, max);
-    const relevantCognition = rankByFields(query, cognition, [
-        { name: 'title', value: (note) => note.title },
-        { name: 'type', value: (note) => note.kind },
-        { name: 'confidence', value: (note) => note.confidence },
-        { name: 'domain', value: (note) => note.domain },
-        { name: 'tags', value: (note) => note.tags },
-        { name: 'files', value: (note) => note.relatedFiles },
-        { name: 'symbols', value: (note) => note.relatedSymbols },
-        { name: 'summary', value: (note) => note.summary },
+    const relevantCognition = rankByFields(query, atoms.filter((atom) => atom.status !== 'archived'), [
+        { name: 'topic', value: (atom) => atom.topic },
+        { name: 'claim', value: (atom) => atom.claim },
+        { name: 'type', value: (atom) => atom.type },
+        { name: 'confidence', value: (atom) => atom.confidence },
+        { name: 'status', value: (atom) => atom.status },
+        { name: 'source', value: (atom) => atom.provenance.sourceCommand },
+        { name: 'domains', value: (atom) => atom.scopeRefs.domains },
+        { name: 'files', value: (atom) => atom.scopeRefs.files },
+        { name: 'symbols', value: (atom) => atom.scopeRefs.symbols },
+        { name: 'summary', value: (atom) => atom.summary },
     ])
-        .map((ranked) => applyCognitionRankAdjustments(ranked))
+        .map((ranked) => applyAtomRankAdjustments(ranked))
+        .map((ranked) => ({
+        ...ranked,
+        item: atomToCognitionNote(ranked.item),
+    }))
         .sort((a, b) => b.score - a.score)
         .slice(0, max);
     const matchedDomains = rankByFields(query, domains, [
@@ -292,33 +306,44 @@ function explainRelationships(relationships, context) {
         return { relationship, reasons: [...reasons] };
     });
 }
-function applyCognitionRankAdjustments(ranked) {
+function applyAtomRankAdjustments(ranked) {
     const reasons = [...ranked.reasons];
     let score = ranked.score;
     if (ranked.item.confidence === 'high') {
+        score += 4;
+        reasons.push('high confidence atom');
+    }
+    else if (ranked.item.confidence === 'medium') {
+        score += 1;
+        reasons.push('medium confidence atom');
+    }
+    else {
+        score -= 3;
+        reasons.push('low confidence penalty');
+    }
+    if (ranked.item.status === 'active') {
         score += 3;
-        reasons.push('high confidence cognition');
+        reasons.push('active atom evidence');
     }
-    else if (ranked.item.confidence === 'low') {
+    else if (ranked.item.status === 'needs-review') {
         score -= 2;
-        reasons.push('low confidence penalty');
+        reasons.push('needs-review stale penalty');
     }
-    if (ranked.item.referencesStatus === 'current') {
+    else if (ranked.item.status === 'stale') {
+        score -= 6;
+        reasons.push('stale atom penalty');
+    }
+    if (ranked.item.type === 'decision' || ranked.item.type === 'gotcha') {
         score += 2;
-        reasons.push('current references');
+        reasons.push(`${ranked.item.type} atom`);
     }
-    else if (ranked.item.referencesStatus === 'mixed') {
+    if (ranked.item.provenance.sourceCommand === 'legacy-migration') {
         score -= 1;
-        reasons.push('mixed reference penalty');
-    }
-    else if (ranked.item.referencesStatus === 'stale' ||
-        ranked.item.referencesStatus === 'unresolved') {
-        score -= 4;
-        reasons.push('stale reference penalty');
+        reasons.push('legacy compatibility atom');
     }
-    if (ranked.item.kind === 'decision' || ranked.item.kind === 'gotcha') {
-        score += 1;
-        reasons.push(`${ranked.item.kind} cognition`);
+    if (ranked.item.lifecycle.supersededBy) {
+        score -= 8;
+        reasons.push('superseded atom penalty');
     }
     return { ...ranked, score, reasons };
 }

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

@@ -5,7 +5,7 @@ export const claudeCodeAdapter = {
     targetPath: 'CLAUDE.md',
     instructions: `## KGraph Workflow
 
-{{KGRAPH_CONTEXT_POLICY}} Use /kgraph for the full automated workflow. Run \`kgraph conclude\` for durable typed engineering memory and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
+{{KGRAPH_CONTEXT_POLICY}} Use /kgraph for the full automated workflow. Run \`kgraph pack "<task>" --budget 8000 --json\` for a machine-readable token-budgeted context pack, \`kgraph knowledge list\` or \`kgraph knowledge get <atom-id>\` to inspect durable atoms, \`kgraph stale\` and \`kgraph blame <atom-id>\` when lifecycle/provenance matters, \`kgraph conclude\` for durable typed engineering memory, and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
     commandFiles: [
         {
@@ -28,6 +28,26 @@ ${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are una
         {
             path: '.claude/commands/kgraph-compact.md',
             content: `Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-pack.md',
+            content: `Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-knowledge.md',
+            content: `Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-stale.md',
+            content: `Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-blame.md',
+            content: `Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
 `,
         },
         {

package/dist/integrations/adapters/codex.js

@@ -5,7 +5,7 @@ export const codexAdapter = {
     targetPath: 'AGENTS.md',
     instructions: `## KGraph Workflow
 
-{{KGRAPH_CONTEXT_POLICY}} The /kgraph skill handles the full automated workflow. Run \`kgraph conclude\` for durable typed engineering memory and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
+{{KGRAPH_CONTEXT_POLICY}} The /kgraph skill handles the full automated workflow. Run \`kgraph pack "<task>" --budget 8000 --json\` for a machine-readable token-budgeted context pack, \`kgraph knowledge list\` or \`kgraph knowledge get <atom-id>\` to inspect durable atoms, \`kgraph stale\` and \`kgraph blame <atom-id>\` when lifecycle/provenance matters, \`kgraph conclude\` for durable typed engineering memory, and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
     commandFiles: [
         {

package/dist/integrations/adapters/copilot.js

@@ -12,7 +12,7 @@ ${numberedWorkflow('copilot')}
             path: '.github/agents/kgraph.agent.md',
             content: `---
 name: kgraph
-description: Use KGraph persistent repo intelligence to answer questions about this codebase. Runs kgraph context, scan, update, conclude, compact, impact, history, and session commands to ground responses in durable local knowledge.
+description: Use KGraph persistent repo intelligence to answer questions about this codebase. Runs kgraph context, pack, knowledge, stale, blame, scan, update, conclude, compact, impact, history, and session commands to ground responses in durable local knowledge.
 tools:
   - run_in_terminal
   - read_file
@@ -58,6 +58,49 @@ argument-hint: "--dry-run or apply"
 ---
 
 Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-pack.prompt.md',
+            content: `---
+description: Build a budget-aware KGraph context pack
+agent: agent
+argument-hint: "Task description"
+---
+
+Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-knowledge.prompt.md',
+            content: `---
+description: Inspect or manage KGraph canonical knowledge atoms
+agent: agent
+argument-hint: "list, get <atom-id>, archive <atom-id>, or supersede <old-id> <new-id>"
+---
+
+Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-stale.prompt.md',
+            content: `---
+description: Show KGraph knowledge invalidated by changed or missing refs
+agent: agent
+---
+
+Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-blame.prompt.md',
+            content: `---
+description: Show KGraph atom provenance and evidence
+agent: agent
+argument-hint: "Atom id"
+---
+
+Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
 `,
         },
         {

package/dist/integrations/workflow-steps.js

@@ -7,6 +7,9 @@ const IMPACT_STEP = `Run \`kgraph impact "<file-or-symbol>"\` when the user asks
 const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.`;
 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 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 PACK_STEP = `Run \`kgraph pack "<task>" --budget 8000 --json\` when an agent needs a machine-readable, token-budgeted context pack instead of human Markdown context.`;
+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.`;
 function sessionStep(agentName, qualifier) {
     const base = `Track meaningful session activity with \`kgraph session start --agent ${agentName}\`, \`kgraph session read <path> --agent ${agentName}\`, \`kgraph session write <path> --agent ${agentName}\`, and \`kgraph session end --agent ${agentName} --conclude --topic "<topic>"\` when durable session memory is useful`;
     return qualifier ? `${base} ${qualifier}.` : `${base}.`;
@@ -19,16 +22,19 @@ export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
 2. {{KGRAPH_CONTEXT_POLICY}}
 3. Use the returned files, symbols, relationships, and cognition before broad exploration.
-4. ${DOCTOR_STEP}
-5. ${sessionStep(agentName, options.sessionQualifier)}
-6. ${IMPACT_STEP}
+4. ${PACK_STEP}
+5. ${KNOWLEDGE_STEP}
+6. ${DOCTOR_STEP}
+7. ${STALE_STEP}
+8. ${sessionStep(agentName, options.sessionQualifier)}
+9. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-7. ${REPAIR_STEP}
-8. ${COMPACT_STEP}
-9. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-10. ${HISTORY_STEP}`;
+10. ${REPAIR_STEP}
+11. ${COMPACT_STEP}
+12. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+13. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -36,7 +42,10 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${PACK_STEP}
+- ${KNOWLEDGE_STEP}
 - ${DOCTOR_STEP}
+- ${STALE_STEP}
 - ${sessionStep(agentName, options.sessionQualifier)}
 - ${IMPACT_STEP}
 {{KGRAPH_CAPTURE_POLICY}}

package/dist/knowledge/atom-store.d.ts

@@ -0,0 +1,60 @@
+import type { CognitionConfidence, CognitionNote } from '../types/cognition.js';
+import type { KGraphWorkspace } from '../types/config.js';
+import type { KnowledgeAtom, KnowledgeValidationIssue } from '../types/knowledge.js';
+import type { FileMap, SymbolMap } from '../types/maps.js';
+export declare const KNOWLEDGE_SCHEMA_VERSION = 1;
+export interface AtomInput {
+    type: KnowledgeAtom['type'];
+    topic: string;
+    claim: string;
+    summary?: string;
+    confidence?: CognitionConfidence;
+    files?: string[];
+    symbols?: string[];
+    domains?: string[];
+    packages?: string[];
+    sourceCommand: KnowledgeAtom['provenance']['sourceCommand'];
+    agent?: string;
+    sessionId?: string;
+    commit?: string;
+    createdAt?: string;
+    idSeed?: string;
+}
+export interface AtomStatusRefreshResult {
+    atoms: KnowledgeAtom[];
+    updated: Array<{
+        atomId: string;
+        previousStatus: KnowledgeAtom['status'];
+        nextStatus: KnowledgeAtom['status'];
+        reasons: string[];
+    }>;
+}
+export declare function ensureKnowledgeStore(workspace: KGraphWorkspace): Promise<void>;
+export declare function readKnowledgeAtoms(workspace: KGraphWorkspace): Promise<KnowledgeAtom[]>;
+export declare function readAtomsFile(workspace: KGraphWorkspace): Promise<KnowledgeAtom[]>;
+export declare function parseAtomsJsonl(raw: string): KnowledgeAtom[];
+export declare function writeKnowledgeAtoms(workspace: KGraphWorkspace, atoms: KnowledgeAtom[]): Promise<void>;
+export declare function appendKnowledgeAtom(workspace: KGraphWorkspace, atom: KnowledgeAtom): Promise<KnowledgeAtom>;
+export declare function createKnowledgeAtom(workspace: KGraphWorkspace, input: AtomInput, maps?: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+}): Promise<KnowledgeAtom>;
+export declare function migrateLegacyCognitionToAtoms(workspace: KGraphWorkspace): Promise<void>;
+export declare function updateKnowledgeAtom(workspace: KGraphWorkspace, atomId: string, updater: (atom: KnowledgeAtom) => KnowledgeAtom): Promise<KnowledgeAtom>;
+export declare function refreshKnowledgeAtomStatuses(workspace: KGraphWorkspace, maps: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+}, dryRun?: boolean): Promise<AtomStatusRefreshResult>;
+export declare function validateKnowledgeStore(workspace: KGraphWorkspace, maps?: {
+    fileMap: FileMap;
+    symbolMap: SymbolMap;
+}): Promise<KnowledgeValidationIssue[]>;
+export declare function atomToCognitionNote(atom: KnowledgeAtom): CognitionNote;
+export declare function knowledgePaths(workspace: KGraphWorkspace): {
+    atoms: string;
+    schema: string;
+    indexes: string;
+    terms: string;
+    refs: string;
+    topics: string;
+};