@kentwynn/kgraph 0.2.10 → 0.2.12

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: [
         {
@@ -22,12 +22,32 @@ ${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are una
         },
         {
             path: '.claude/commands/kgraph-repair.md',
-            content: `Run \`kgraph repair --dry-run\` first and summarize the proposed cognition cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
+            content: `Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
 `,
         },
         {
             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.
 `,
         },
         {
@@ -47,7 +67,7 @@ ${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are una
         },
         {
             path: '.claude/commands/kgraph-impact.md',
-            content: `Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
+            content: `Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
 `,
         },
         {

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
@@ -46,7 +46,7 @@ agent: agent
 argument-hint: "--dry-run or apply"
 ---
 
-Run \`kgraph repair --dry-run\` first and summarize the proposed cognition cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
+Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
 `,
         },
         {
@@ -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.
 `,
         },
         {
@@ -122,7 +165,7 @@ agent: agent
 argument-hint: "File, symbol, or topic"
 ---
 
-Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related cognition, and risk hints.
+Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
 `,
         },
         {

package/dist/integrations/workflow-steps.js

@@ -4,9 +4,12 @@
  */
 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 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 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 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;
+};