@kentwynn/kgraph 0.2.10 → 0.2.12

package/dist/cli/commands/repair.js

@@ -6,8 +6,8 @@ import { printQualityReport } from './doctor.js';
 export function registerRepairCommand(program) {
     program
         .command('repair')
-        .description('Clean noisy stale references from KGraph cognition')
-        .option('--dry-run', 'Show proposed cognition cleanup without writing files')
+        .description('Clean noisy stale references from KGraph knowledge atoms')
+        .option('--dry-run', 'Show proposed atom cleanup without writing files')
         .action((options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         if (!(await mapsExist(workspace))) {
@@ -21,7 +21,7 @@ export function registerRepairCommand(program) {
         console.log('');
         printQualityReport(report);
         if (report.changes.length === 0) {
-            console.log('No noisy cognition references found.');
+            console.log('No noisy atom references found.');
         }
         else if (options.dryRun) {
             console.log('');

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/commands/visualize.js

@@ -1,7 +1,7 @@
 import { exec } from 'node:child_process';
 import { createServer } from 'node:http';
 import { loadConfig } from '../../config/config.js';
-import { readCognitionNotes } from '../../storage/cognition-store.js';
+import { refreshKnowledgeAtomStatuses } from '../../knowledge/atom-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { buildGraph } from '../../visualization/graph-builder.js';
@@ -22,12 +22,13 @@ export function registerVisualizeCommand(program) {
         if (!(await mapsExist(workspace))) {
             throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
         }
-        const [maps, cognition] = await Promise.all([
-            readMaps(workspace),
-            readCognitionNotes(workspace),
-        ]);
+        const maps = await readMaps(workspace);
+        const { atoms } = await refreshKnowledgeAtomStatuses(workspace, {
+            fileMap: maps.fileMap,
+            symbolMap: maps.symbolMap,
+        });
         await loadConfig(workspace); // ensure workspace is valid
-        const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, cognition);
+        const graphData = buildGraph(maps.fileMap, maps.symbolMap, maps.dependencyMap, maps.relationshipMap, atoms);
         const html = renderHtml(graphData, workspace.rootPath);
         await serveGraph(html, port, options.open);
     }));

package/dist/cli/help.js

@@ -22,7 +22,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('init --integrations codex,gemini', 'Initialize and connect AI tools'),
         '',
         theme.bold('Daily workflow'),
-        command('kgraph', 'Refresh scan maps and process pending cognition notes'),
+        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'),
@@ -30,15 +30,19 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('session', 'Show agent read/write activity and token estimates'),
         command('session read src/auth.ts --agent codex', 'Record an agent file read'),
         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('conclude "auth refresh gotcha"', 'Store typed engineering knowledge'),
+        command('compact', 'Merge duplicate atoms 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'),
+        command('impact "Button"', 'Show imports, callers, calls, knowledge, and risk'),
+        command('update', 'Optional: process only .kgraph/inbox capture notes'),
         command('doctor', 'Check workspace health and next actions'),
-        command('doctor --quality', 'Report stale/noisy cognition references'),
-        command('repair --dry-run', 'Preview cognition reference cleanup'),
-        command('repair', 'Clean noisy stale cognition references'),
+        command('doctor --quality', 'Report stale/noisy atom references'),
+        command('repair --dry-run', 'Preview atom reference cleanup'),
+        command('repair', 'Clean noisy stale atom references'),
         command('uninstall', 'Preview repo-local KGraph removal'),
         command('uninstall --yes', 'Remove .kgraph/ and managed integrations'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
@@ -46,7 +50,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         '',
         theme.bold('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 gemini windsurf cline', 'Write KGraph instructions using smart mode by default'),
         command('integrate add copilot --mode always', 'Every Copilot chat starts with kgraph "<topic>"'),
         command('integrate set copilot --mode manual', 'Only run KGraph when explicitly requested'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
@@ -87,13 +91,15 @@ export function renderWorkflowBanner(stats, useColor = supportsColor()) {
                 ? ` (${stats.skippedFiles} unchanged, skipped)`
                 : '')),
         command('symbols', String(stats.symbols)),
-        command('cognition notes processed', String(stats.cognitionNotes)),
+        command('capture notes processed', String(stats.cognitionNotes)),
         command('integration modes', integrationLine),
         '',
         theme.bold('Next'),
         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 doctor --quality', 'Check atom 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-quality.d.ts

@@ -9,6 +9,11 @@ export interface CognitionRepairChange {
     nextStatus: ReferenceStatus;
 }
 export interface CognitionQualityReport {
+    atomCount: number;
+    staleAtomCount: number;
+    needsReviewAtomCount: number;
+    archivedAtomCount: number;
+    duplicateAtomTopicCount: number;
     noteCount: number;
     mixedOrStaleCount: number;
     noisyFileRefCount: number;

package/dist/cognition/cognition-quality.js

@@ -1,9 +1,13 @@
 import { mkdir, rename } from 'node:fs/promises';
 import path from 'node:path';
+import { atomToCognitionNote, refreshKnowledgeAtomStatuses, writeKnowledgeAtoms, } from '../knowledge/atom-store.js';
 import { buildSessionReport } from '../session/session-store.js';
-import { overwriteDomainRecord, readCognitionNotes, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
+import { overwriteDomainRecord, readDomainRecords, writeCognitionNote, } from '../storage/cognition-store.js';
 export async function analyzeCognitionQuality(workspace, maps) {
-    const notes = await readCognitionNotes(workspace);
+    const refreshed = await refreshKnowledgeAtomStatuses(workspace, { fileMap: maps.fileMap, symbolMap: maps.symbolMap }, true);
+    const atoms = refreshed.atoms;
+    const activeAtoms = atoms.filter((atom) => atom.status !== 'archived');
+    const notes = activeAtoms.map(atomToCognitionNote);
     const session = await buildSessionReport(workspace);
     const changes = notes
         .map((note) => analyzeNote(note, maps))
@@ -11,13 +15,18 @@ export async function analyzeCognitionQuality(workspace, maps) {
         change.removedSymbolRefs.length > 0);
     const orphanedNoteCount = notes.filter((note) => note.referencesStatus === 'stale').length;
     return {
+        atomCount: activeAtoms.length,
+        staleAtomCount: activeAtoms.filter((atom) => atom.status === 'stale').length,
+        needsReviewAtomCount: activeAtoms.filter((atom) => atom.status === 'needs-review').length,
+        archivedAtomCount: atoms.filter((atom) => atom.status === 'archived').length,
+        duplicateAtomTopicCount: countDuplicateAtomTopics(activeAtoms),
         noteCount: notes.length,
         mixedOrStaleCount: notes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
         noisySymbolRefCount: changes.reduce((total, change) => total + change.removedSymbolRefs.length, 0),
         unresolvedLocalImportCount: countUnresolvedLocalImports(maps.dependencyMap),
         unresolvedCallCount: countUnresolvedCalls(maps.symbolMap, maps.relationshipMap),
-        duplicateTitleCount: countDuplicateTitles(notes),
+        duplicateTitleCount: countDuplicateAtomTopics(activeAtoms),
         generatedFileScanCount: countGeneratedScannedFiles(maps.fileMap),
         expensiveFileCount: countExpensiveFiles(maps.fileMap),
         sessionRepeatedReadCount: session.repeatedReadCount,
@@ -28,10 +37,14 @@ export async function analyzeCognitionQuality(workspace, maps) {
     };
 }
 export async function repairCognition(workspace, maps, dryRun = false) {
-    const notes = await readCognitionNotes(workspace);
+    const refreshed = await refreshKnowledgeAtomStatuses(workspace, { fileMap: maps.fileMap, symbolMap: maps.symbolMap }, dryRun);
+    const atoms = refreshed.atoms;
+    const activeAtoms = atoms.filter((atom) => atom.status !== 'archived');
+    const notes = activeAtoms.map(atomToCognitionNote);
     const session = await buildSessionReport(workspace);
     const nextNotes = [];
     const changes = [];
+    const changesById = new Map();
     for (const note of notes) {
         const change = analyzeNote(note, maps);
         const nextNote = applyChange(note, change);
@@ -39,6 +52,7 @@ export async function repairCognition(workspace, maps, dryRun = false) {
         if (change.removedFileRefs.length > 0 ||
             change.removedSymbolRefs.length > 0) {
             changes.push(change);
+            changesById.set(change.noteId, change);
             if (!dryRun) {
                 await writeCognitionNote(workspace, nextNote);
             }
@@ -47,8 +61,58 @@ export async function repairCognition(workspace, maps, dryRun = false) {
     // Archive fully-orphaned notes (all refs dead) so they no longer appear in context
     const orphanedNotes = nextNotes.filter((note) => note.referencesStatus === 'stale');
     if (!dryRun && (changes.length > 0 || orphanedNotes.length > 0)) {
+        const now = new Date().toISOString();
+        const nextAtoms = atoms.map((atom) => {
+            if (atom.status === 'archived')
+                return atom;
+            const change = changesById.get(atom.id);
+            if (!change && !orphanedNotes.some((note) => note.id === atom.id)) {
+                return atom;
+            }
+            if (orphanedNotes.some((note) => note.id === atom.id)) {
+                return {
+                    ...atom,
+                    status: 'archived',
+                    confidence: 'low',
+                    lifecycle: { ...atom.lifecycle, archivedAt: now },
+                    provenance: { ...atom.provenance, updatedAt: now },
+                };
+            }
+            const removedFiles = new Set(change?.removedFileRefs ?? []);
+            const removedSymbols = new Set(change?.removedSymbolRefs ?? []);
+            const nextStatus = atomStatusFromReferenceStatus(change?.nextStatus ?? 'current');
+            return {
+                ...atom,
+                status: nextStatus,
+                confidence: atom.confidence === 'low' && atom.status === 'stale' && nextStatus !== 'stale'
+                    ? 'medium'
+                    : atom.confidence,
+                scopeRefs: {
+                    ...atom.scopeRefs,
+                    files: atom.scopeRefs.files.filter((file) => !removedFiles.has(file)),
+                    symbols: atom.scopeRefs.symbols.filter((symbol) => !removedSymbols.has(symbol)),
+                },
+                evidenceRefs: atom.evidenceRefs.filter((ref) => {
+                    if (ref.type === 'file')
+                        return !removedFiles.has(ref.path);
+                    if (ref.type === 'symbol')
+                        return !removedSymbols.has(ref.name);
+                    return true;
+                }),
+                lifecycle: {
+                    ...atom.lifecycle,
+                    invalidatedBy: change?.nextStatus === 'current'
+                        ? undefined
+                        : atom.lifecycle.invalidatedBy,
+                },
+                provenance: { ...atom.provenance, updatedAt: now },
+            };
+        });
+        await writeKnowledgeAtoms(workspace, nextAtoms);
         // Exclude fully-orphaned notes from domain records — they are being archived
-        await repairDomainRecords(workspace, nextNotes.filter((n) => n.referencesStatus !== 'stale'), maps);
+        await repairDomainRecords(workspace, nextAtoms
+            .filter((atom) => atom.status !== 'archived')
+            .map(atomToCognitionNote), maps);
     }
     if (!dryRun) {
         for (const note of orphanedNotes) {
@@ -57,6 +121,11 @@ export async function repairCognition(workspace, maps, dryRun = false) {
     }
     const orphanedNoteCount = orphanedNotes.length;
     return {
+        atomCount: activeAtoms.length,
+        staleAtomCount: nextNotes.filter((note) => note.referencesStatus === 'stale').length,
+        needsReviewAtomCount: nextNotes.filter((note) => note.referencesStatus === 'mixed').length,
+        archivedAtomCount: atoms.filter((atom) => atom.status === 'archived').length + orphanedNoteCount,
+        duplicateAtomTopicCount: countDuplicateTitles(nextNotes),
         noteCount: notes.length,
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,
         noisyFileRefCount: changes.reduce((total, change) => total + change.removedFileRefs.length, 0),
@@ -98,6 +167,23 @@ function countDuplicateTitles(notes) {
     }
     return duplicates.size;
 }
+function countDuplicateAtomTopics(atoms) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const atom of atoms) {
+        const key = [
+            atom.type,
+            atom.topic.trim().toLowerCase(),
+            atom.claim.trim().toLowerCase(),
+        ].join('\0');
+        if (!atom.topic.trim())
+            continue;
+        if (seen.has(key))
+            duplicates.add(key);
+        seen.add(key);
+    }
+    return duplicates.size;
+}
 function countGeneratedScannedFiles(fileMap) {
     return fileMap.files.filter((file) => [
         '.agents/',
@@ -175,6 +261,13 @@ function evaluateReferenceStatus(relatedFiles, relatedSymbols, maps) {
         return 'stale';
     return 'mixed';
 }
+function atomStatusFromReferenceStatus(status) {
+    if (status === 'current')
+        return 'active';
+    if (status === 'mixed')
+        return 'needs-review';
+    return 'stale';
+}
 function isNoisyFileRef(ref) {
     return (!ref.includes('/') && /^[A-Z][A-Za-z0-9_-]*\.[A-Za-z0-9_-]+$/.test(ref));
 }

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) {

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;