@kentwynn/kgraph 0.2.27 → 0.2.29

package/README.md

@@ -163,10 +163,12 @@ kgraph doctor
 
 After useful AI work, assistants save durable runtime-capture notes into `.kgraph/inbox/`. These notes are not project documentation; they are KGraph input files that the next `kgraph` run processes automatically. You can also process them directly with `kgraph update`.
 
-Normal agent flow is intentionally small:
+Normal agent flow is intentionally small. For coding context, agents use the
+machine-readable pack. When memory refresh or inbox processing matters, they use
+the root workflow or `kgraph update`.
 
 ```bash
-kgraph "topic"
+kgraph pack "topic" --budget 8000 --json --agent codex
 # work normally
 kgraph "topic" --final --agent codex
 # if final check requires capture:
@@ -175,6 +177,10 @@ kgraph "topic" --capture "durable conclusion" --capture-file path/to/file.ts --c
 
 `kgraph "<topic>"` is the smart root workflow: it refreshes maps, processes capture notes, reports memory health, and returns focused context. Agents can pass `--agent <name>` to record a lightweight session context event. Agents can still use `kgraph pack "<topic>" --budget 8000 --json --agent <name>` when they need the stable machine-readable `ContextPack` contract with atoms, source ranges, git changes, omitted items, token estimates, and inclusion reasons.
 
+`pack` does not process `.kgraph/inbox/`. If a pack reports pending inbox notes,
+run `kgraph "<topic>" --agent <name>` or `kgraph update` before relying on
+`kgraph history` or newly captured atoms.
+
 Use `kgraph doctor` after setup and before trusting a repo's saved intelligence. It checks initialization, maps, pending inbox notes, integration targets, and actionable quality problems. Use `kgraph doctor --quality` and `kgraph repair --dry-run` when stale or noisy atom references start making context harder to trust.
 
 Agents can also report session activity so KGraph can estimate token waste:
@@ -381,12 +387,12 @@ kgraph integrate list
 kgraph integrate remove cursor
 ```
 
-New integrations default to `always` mode, so every chat in the repository starts with `kgraph "<topic>"`. Use `--mode smart` to run KGraph only for repo-specific work, or `--mode manual` to run only when explicitly asked.
+New integrations default to `always` mode, so every chat in the repository starts with the matching KGraph command. Use `--mode smart` to run KGraph only for repo-specific work, or `--mode manual` to run only when explicitly asked.
 
 | Mode     | Behavior                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `always` | Every chat in the repository starts with `kgraph "<topic>"`, even simple or conversational requests.                                                                                                    |
-| `smart`  | Runs KGraph automatically for repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests. Skips simple conversational requests that do not depend on repo knowledge. |
+| `always` | Every chat in the repository starts with the matching KGraph command. Normal coding context uses `kgraph pack`; history, inbox/update, knowledge, and doctor requests route to their specific commands. |
+| `smart`  | Runs the matching KGraph command automatically for repo-specific coding, debugging, architecture, refactor, review, history, inbox/update, knowledge, health, or file-exploration requests. Skips simple conversational requests that do not depend on repo knowledge. |
 | `manual` | Exposes KGraph commands and instructions, but the agent runs KGraph only when the user explicitly asks.                                                                                                 |
 | `off`    | Disables that integration and removes generated KGraph instruction blocks/command files.                                                                                                                |
 

package/dist/cli/commands/knowledge.js

@@ -1,4 +1,4 @@
-import { atomToCognitionNote, readKnowledgeAtoms, updateKnowledgeAtom, } from '../../knowledge/atom-store.js';
+import { atomToCognitionNote, readKnowledgeAtoms, updateKnowledgeAtom, updateKnowledgeAtoms, } from '../../knowledge/atom-store.js';
 import { rebuildDomainRecords } from '../../cognition/domain-records.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { readMaps } from '../../storage/map-store.js';
@@ -82,28 +82,43 @@ export function registerKnowledgeCommand(program) {
         .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 = await updateKnowledgeAtoms(workspace, (atoms) => {
+            const oldIndex = atoms.findIndex((atom) => atom.id === oldId);
+            const newIndex = atoms.findIndex((atom) => atom.id === newId);
+            if (oldIndex === -1) {
+                throw new KGraphError(`Knowledge atom not found: ${oldId}`);
+            }
+            if (newIndex === -1) {
+                throw new KGraphError(`Knowledge atom not found: ${newId}`);
+            }
+            const nextAtoms = [...atoms];
+            nextAtoms[oldIndex] = {
+                ...nextAtoms[oldIndex],
+                status: 'archived',
+                provenance: { ...nextAtoms[oldIndex].provenance, updatedAt: now },
+                lifecycle: {
+                    ...nextAtoms[oldIndex].lifecycle,
+                    supersededBy: newId,
+                    archivedAt: now,
+                },
+            };
+            nextAtoms[newIndex] = {
+                ...nextAtoms[newIndex],
+                provenance: { ...nextAtoms[newIndex].provenance, updatedAt: now },
+                lifecycle: {
+                    ...nextAtoms[newIndex].lifecycle,
+                    supersedes: [
+                        ...new Set([...nextAtoms[newIndex].lifecycle.supersedes, oldId]),
+                    ],
+                },
+            };
+            return {
+                atoms: nextAtoms,
+                result: { old: nextAtoms[oldIndex], new: nextAtoms[newIndex] },
+            };
+        });
         await rebuildActiveDomainRecords(workspace);
-        const result = { old: oldAtom, new: newAtom };
         console.log(options.json
             ? JSON.stringify(result, null, 2)
             : `Superseded ${oldId} with ${newId}`);

package/dist/cli/commands/pack.js

@@ -1,8 +1,10 @@
+import path from 'node:path';
 import { buildContextPack } from '../../context/context-pack.js';
 import { queryContext } from '../../context/context-query.js';
 import { loadConfig } from '../../config/config.js';
 import { assertSessionAgent, recordSessionEvent, } from '../../session/session-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { listInboxNotes } from '../../storage/cognition-store.js';
 import { mapsExist, readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
 export function registerPackCommand(program) {
@@ -39,6 +41,17 @@ export function registerPackCommand(program) {
         ]);
         const response = await queryContext(workspace, config, maps, task);
         const pack = buildContextPack(response, budget, workspace.rootPath);
+        const pendingInboxFiles = (await listInboxNotes(workspace)).map((file) => path.relative(workspace.rootPath, file));
+        if (pendingInboxFiles.length > 0) {
+            pack.pendingInbox = {
+                count: pendingInboxFiles.length,
+                files: pendingInboxFiles,
+            };
+            pack.warnings = [
+                ...pack.warnings,
+                `Pending inbox notes are not processed by pack. Run \`kgraph "${task}"${agent ? ` --agent ${agent}` : ''}\` or \`kgraph update\` before relying on history or newly captured atoms.`,
+            ];
+        }
         if (options.json) {
             console.log(JSON.stringify(pack, null, 2));
             return;
@@ -69,6 +82,9 @@ export function renderPackText(pack) {
         `  omitted     ${pack.omitted.length}`,
         ``,
     ];
+    if (pack.pendingInbox && pack.pendingInbox.count > 0) {
+        lines.push(`● Pending Inbox`, `  ${pack.pendingInbox.count} note${pack.pendingInbox.count === 1 ? '' : 's'} waiting; pack does not process inbox notes`, `  run kgraph "${pack.task}" or kgraph update before relying on history/new atoms`, ``);
+    }
     appendGroup(lines, 'Atoms', pack.items.filter((item) => item.kind === 'atom'));
     appendGroup(lines, 'Git Changes', pack.items.filter((item) => item.kind === 'git-change'));
     appendGroup(lines, 'Source Ranges', pack.items.filter((item) => item.kind === 'file-range'));

package/dist/cli/commands/uninstall.js

@@ -1,10 +1,11 @@
-import { rm } from 'node:fs/promises';
+import { readdir, rm, rmdir } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig } from '../../config/config.js';
 import { removeIntegrations } from '../../integrations/integration-store.js';
 import { pathExists, resolveWorkspace } from '../../storage/kgraph-paths.js';
 import { runCommand } from '../errors.js';
 const LEGACY_GENERATED_FILES = [
+    '.agents/generated/kgraph.md',
     '.github/agents/kgraph.agent.md',
     '.github/kgraph.agent.md',
 ];
@@ -44,7 +45,26 @@ export function registerUninstallCommand(program) {
     }));
 }
 async function removeLegacyGeneratedFiles(rootPath) {
-    await Promise.all(LEGACY_GENERATED_FILES.map((filePath) => rm(path.join(rootPath, filePath), { force: true })));
+    for (const filePath of LEGACY_GENERATED_FILES) {
+        const fullPath = path.join(rootPath, filePath);
+        await rm(fullPath, { force: true });
+        await pruneEmptyParents(rootPath, path.dirname(fullPath));
+    }
+}
+async function pruneEmptyParents(rootPath, startDir) {
+    let dir = startDir;
+    while (dir !== rootPath && dir.startsWith(rootPath)) {
+        try {
+            const entries = await readdir(dir);
+            if (entries.length > 0)
+                break;
+            await rmdir(dir);
+            dir = path.dirname(dir);
+        }
+        catch {
+            break;
+        }
+    }
 }
 function printUninstallPreview(input) {
     console.log('KGraph Uninstall Preview');

package/dist/cli/commands/workflow.js

@@ -227,7 +227,24 @@ function atomsHaveReplacementSignal(a, b) {
             bSymbols.add(ref.name);
     }
     const symbolOverlap = [...aSymbols].some((symbol) => bSymbols.has(symbol));
-    return symbolOverlap || meaningfulTopicOverlap(a.topic, b.topic);
+    if (symbolOverlap)
+        return true;
+    if (!atomsShareFile(a, b))
+        return false;
+    return meaningfulTopicOverlap(a.topic, b.topic);
+}
+function atomsShareFile(a, b) {
+    const aFiles = new Set(a.scopeRefs.files);
+    for (const ref of a.evidenceRefs) {
+        if (ref.type === 'file')
+            aFiles.add(ref.path);
+    }
+    const bFiles = new Set(b.scopeRefs.files);
+    for (const ref of b.evidenceRefs) {
+        if (ref.type === 'file')
+            bFiles.add(ref.path);
+    }
+    return [...aFiles].some((file) => bFiles.has(file));
 }
 function meaningfulTopicOverlap(a, b) {
     const weakTokens = new Set([
@@ -239,6 +256,10 @@ function meaningfulTopicOverlap(a, b) {
         'new',
         'old',
         'review',
+        'check',
+        'current',
+        'session',
+        'smoke',
         'update',
         'with',
     ]);

package/dist/cognition/cognition-quality.js

@@ -13,7 +13,7 @@ export async function analyzeCognitionQuality(workspace, maps) {
         .map((note) => analyzeNote(note, maps))
         .filter((change) => change.removedFileRefs.length > 0 ||
         change.removedSymbolRefs.length > 0);
-    const orphanedNoteCount = notes.filter((note) => note.referencesStatus === 'stale').length;
+    const orphanedNoteCount = notes.filter((note) => analyzeNote(note, maps).nextStatus === 'stale').length;
     return {
         atomCount: activeAtoms.length,
         staleAtomCount: activeAtoms.filter((atom) => atom.status === 'stale').length,
@@ -64,54 +64,55 @@ 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');
+    const now = new Date().toISOString();
+    const orphanedNoteIds = new Set(orphanedNotes.map((note) => note.id));
+    const nextAtoms = atoms.map((atom) => {
+        if (atom.status === 'archived')
+            return atom;
+        const change = changesById.get(atom.id);
+        if (!change && !orphanedNoteIds.has(atom.id)) {
+            return atom;
+        }
+        if (orphanedNoteIds.has(atom.id)) {
             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,
-                },
+                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 },
+        };
+    });
+    if (!dryRun && (changes.length > 0 || orphanedNotes.length > 0)) {
         await writeKnowledgeAtoms(workspace, nextAtoms);
         // Exclude fully-orphaned notes from domain records — they are being archived
         await repairDomainRecords(workspace, nextAtoms
@@ -126,9 +127,9 @@ 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,
+        staleAtomCount: nextAtoms.filter((atom) => atom.status === 'stale').length,
+        needsReviewAtomCount: nextAtoms.filter((atom) => atom.status === 'needs-review').length,
+        archivedAtomCount: nextAtoms.filter((atom) => atom.status === 'archived').length,
         duplicateAtomTopicCount: countDuplicateTitles(nextNotes),
         noteCount: notes.length,
         mixedOrStaleCount: nextNotes.filter((note) => ['mixed', 'stale', 'unresolved'].includes(note.referencesStatus)).length,

package/dist/integrations/instruction-blocks.js

@@ -40,16 +40,26 @@ export function renderContextPolicy(mode, agentName) {
     const packCommand = agentName
         ? `kgraph pack "<topic>" --budget 8000 --json --agent ${agentName}`
         : 'kgraph pack "<topic>" --budget 8000 --json';
+    const rootCommand = agentName
+        ? `kgraph "<topic>" --agent ${agentName}`
+        : 'kgraph "<topic>"';
+    const routing = [
+        'Command routing comes first.',
+        'If the user asks about prior work, previous decisions, timeline, or history, run `kgraph history "<topic>"` instead of pack.',
+        'If the user asks what KGraph remembers, atom provenance, or durable knowledge, run `kgraph knowledge list --topic "<topic>"` or `kgraph knowledge get <atom-id>` instead of pack.',
+        `If the user asks to process inbox notes, pending capture, refresh memory, or update cognition, run \`${rootCommand}\` or low-level \`kgraph update\` instead of pack.`,
+        'If the user asks for setup, health, broken integrations, or quality, run `kgraph doctor` or `kgraph doctor --quality` instead of pack.',
+    ].join(' ');
     switch (mode) {
         case 'always':
-            return `Every chat in this repository must start by running \`${packCommand}\` before answering or exploring files. Infer the topic from the user's message; no exceptions, including simple or conversational requests. This records a lightweight KGraph session context event for the agent. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
+            return `Every chat in this repository must use the correct KGraph command before answering or exploring files. ${routing} For normal repo context, code navigation, debugging, review, or edits, run \`${packCommand}\`. If that pack reports pending inbox notes, run \`${rootCommand}\` or \`kgraph update\` before relying on history or newly captured atoms. Infer the topic from the user's message. This records a lightweight KGraph session context event for the agent. ${useResultBoundary}`;
         case 'manual':
-            return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack.';
+            return 'Do not run KGraph automatically. Run `kgraph pack "<topic>" --budget 8000 --json` only when the user explicitly asks for KGraph context, invokes KGraph, or needs a machine-readable repo-memory pack. If the user explicitly asks for KGraph history, inbox/update, knowledge, or doctor, run that specific KGraph command instead of pack.';
         case 'off':
             return 'KGraph is disabled for this integration.';
         case 'smart':
         default:
-            return `For repo-specific coding, debugging, architecture, refactor, review, or file-exploration requests, run \`${packCommand}\` before broad repository exploration. Infer the topic from the user's message. This records a lightweight KGraph session context event only when KGraph is actually used. Skip KGraph for simple conversational requests that do not depend on repo knowledge. Use \`kgraph "<topic>"\` only when a human-readable briefing is explicitly needed. ${useResultBoundary}`;
+            return `For repo-specific coding, debugging, architecture, refactor, review, file-exploration, history, inbox/update, knowledge, or health requests, run the matching KGraph command before broad repository exploration. ${routing} For normal repo context, code navigation, debugging, review, or edits, run \`${packCommand}\`. If that pack reports pending inbox notes, run \`${rootCommand}\` or \`kgraph update\` before relying on history or newly captured atoms. Infer the topic from the user's message. This records a lightweight KGraph session context event only when KGraph is actually used. Skip KGraph for simple conversational requests that do not depend on repo knowledge. ${useResultBoundary}`;
     }
 }
 export function renderCapturePolicy(agentName) {
@@ -68,7 +78,7 @@ export function renderCapturePolicy(agentName) {
 - Use \`.kgraph/inbox/<slug>.md\` only when a longer structured note is clearer than a single \`kgraph conclude\` command.
 - A \`.kgraph/inbox/*.md\` note is KGraph runtime capture, not project documentation. It is allowed by this workflow unless the user explicitly says not to capture to KGraph.
 - Do not skip capture for meaningful UI text, button, link, route, styling, or small file edits. Skip capture only when no reusable repository knowledge was created.
-- Do not run KGraph repeatedly. Run it once at the start with \`kgraph pack "<topic>" --budget 8000 --json${agentName ? ` --agent ${agentName}` : ''}\` for agent-readable context. If repo files changed, run \`${finalCommand}\` once before the final answer.
+- Do not run KGraph repeatedly. At the start, run the one KGraph command that matches the request: \`kgraph history "<topic>"\` for history, \`kgraph update\` or \`kgraph "<topic>"${agentName ? ` --agent ${agentName}` : ''}\` for inbox/update, and \`kgraph pack "<topic>" --budget 8000 --json${agentName ? ` --agent ${agentName}` : ''}\` for normal coding context. If repo files changed, run \`${finalCommand}\` once before the final answer.
 - After the final \`kgraph\` run, mention whether durable cognition was stored or processed.
 
 When using an inbox note, use this structure:

package/dist/integrations/integration-store.js

@@ -98,6 +98,7 @@ async function removeIntegrationInstructions(rootPath, targetPath, integrationNa
     const next = removeManagedBlock(existing, integrationName);
     if (next.trim().length === 0) {
         await rm(fullPath, { force: true });
+        await pruneEmptyParents(rootPath, path.dirname(fullPath));
         return;
     }
     await writeFile(fullPath, next, 'utf8');
@@ -114,19 +115,21 @@ async function removeIntegrationCommandFiles(rootPath, files) {
         const filePath = typeof file === 'string' ? file : file.path;
         const fullPath = path.join(rootPath, filePath);
         await rm(fullPath, { force: true, recursive: true });
-        // Remove empty parent directories up to (but not including) rootPath
-        let dir = path.dirname(fullPath);
-        while (dir !== rootPath && dir.startsWith(rootPath)) {
-            try {
-                const entries = await readdir(dir);
-                if (entries.length > 0)
-                    break;
-                await rmdir(dir);
-                dir = path.dirname(dir);
-            }
-            catch {
+        await pruneEmptyParents(rootPath, path.dirname(fullPath));
+    }
+}
+async function pruneEmptyParents(rootPath, startDir) {
+    let dir = startDir;
+    while (dir !== rootPath && dir.startsWith(rootPath)) {
+        try {
+            const entries = await readdir(dir);
+            if (entries.length > 0)
                 break;
-            }
+            await rmdir(dir);
+            dir = path.dirname(dir);
+        }
+        catch {
+            break;
         }
     }
 }

package/dist/integrations/workflow-steps.js

@@ -9,14 +9,15 @@ const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks dupl
 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.`;
 function packStep(agentName) {
-    return `Treat \`kgraph pack "<task>" --budget 8000 --json --agent ${agentName}\` as the primary agent contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. Use human \`kgraph "<topic>" --agent ${agentName}\` output only when the user explicitly wants a briefing.`;
+    return `For normal coding context, treat \`kgraph pack "<task>" --budget 8000 --json --agent ${agentName}\` as the machine-readable context contract: use atoms, source ranges, git changes, omitted items, and inclusion reasons from the ContextPack before reading files. If the pack reports pending inbox notes, run \`kgraph "<topic>" --agent ${agentName}\` or \`kgraph update\` before relying on history or newly captured atoms.`;
 }
 function smartRootStep(agentName) {
-    return `Prefer the root workflow for normal agent work: run \`kgraph "<topic>" --agent ${agentName}\` when a human-readable refresh/context briefing is needed; run \`kgraph "<topic>" --final --agent ${agentName}\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent ${agentName}\` when the final check requires durable knowledge.`;
+    return `Use the root workflow when refresh or memory processing matters: run \`kgraph "<topic>" --agent ${agentName}\` to refresh maps, process inbox notes, and return a briefing; run \`kgraph "<topic>" --final --agent ${agentName}\` before the final answer when repository files changed; run \`kgraph "<topic>" --capture "<durable conclusion>" --capture-file <path> --capture-symbol <name> --agent ${agentName}\` when the final check requires durable knowledge.`;
 }
 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.`;
 const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files. Use \`rg --files\` and quoted paths when a path must be located.`;
 const VERIFY_EDIT_STEP = `After editing, verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.`;
+const ROUTING_STEP = `Route explicit KGraph requests to the matching command before any default context lookup: history/prior work -> \`kgraph history "<topic>"\`; inbox/pending capture/process notes/update cognition -> \`kgraph "<topic>"\` or \`kgraph update\`; remembered knowledge/atoms/provenance -> \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\`; setup/health -> \`kgraph doctor\`.`;
 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}.`;
@@ -28,23 +29,24 @@ function sessionStep(agentName, qualifier) {
 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. ${EXPLORATION_BOUNDARY_STEP}
-5. ${VERIFY_EDIT_STEP}
-6. ${smartRootStep(agentName)}
-7. ${packStep(agentName)}
-8. ${KNOWLEDGE_STEP}
-9. ${DOCTOR_STEP}
-10. ${STALE_STEP}
-11. ${sessionStep(agentName, options.sessionQualifier)}
-12. ${IMPACT_STEP}
+3. ${ROUTING_STEP}
+4. Use the returned files, symbols, relationships, and cognition before broad exploration.
+5. ${EXPLORATION_BOUNDARY_STEP}
+6. ${VERIFY_EDIT_STEP}
+7. ${smartRootStep(agentName)}
+8. ${packStep(agentName)}
+9. ${KNOWLEDGE_STEP}
+10. ${DOCTOR_STEP}
+11. ${STALE_STEP}
+12. ${sessionStep(agentName, options.sessionQualifier)}
+13. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-13. ${REPAIR_STEP}
-14. ${COMPACT_STEP}
-15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-16. ${HISTORY_STEP}`;
+14. ${REPAIR_STEP}
+15. ${COMPACT_STEP}
+16. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+17. ${HISTORY_STEP}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -52,6 +54,7 @@ export function numberedWorkflow(agentName, options = {}) {
  */
 export function bulletWorkflow(agentName, options = {}) {
     return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${ROUTING_STEP}
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}
 - ${smartRootStep(agentName)}

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

@@ -41,6 +41,10 @@ export declare function createKnowledgeAtom(workspace: KGraphWorkspace, input: A
 }): 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 updateKnowledgeAtoms<T>(workspace: KGraphWorkspace, updater: (atoms: KnowledgeAtom[]) => {
+    atoms: KnowledgeAtom[];
+    result: T;
+}): Promise<T>;
 export declare function refreshKnowledgeAtomStatuses(workspace: KGraphWorkspace, maps: {
     fileMap: FileMap;
     symbolMap: SymbolMap;

package/dist/knowledge/atom-store.js

@@ -1,5 +1,7 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { KGraphError } from '../cli/errors.js';
 import { getCurrentCommit } from '../scanner/git-utils.js';
 import { readCognitionNotes } from '../storage/cognition-store.js';
@@ -17,7 +19,7 @@ export async function ensureKnowledgeStore(workspace) {
         });
     }
     if (!(await pathExists(atomsPath(workspace)))) {
-        await writeFile(atomsPath(workspace), '', 'utf8');
+        await atomicWriteFile(atomsPath(workspace), '');
     }
 }
 export async function readKnowledgeAtoms(workspace) {
@@ -45,16 +47,21 @@ export function parseAtomsJsonl(raw) {
     return atoms;
 }
 export async function writeKnowledgeAtoms(workspace, atoms) {
+    await withKnowledgeWriteLock(workspace, () => writeKnowledgeAtomsUnlocked(workspace, atoms));
+}
+async function writeKnowledgeAtomsUnlocked(workspace, atoms) {
     await ensureKnowledgeStore(workspace);
-    await writeFile(atomsPath(workspace), atoms.map((atom) => JSON.stringify(atom)).join('\n') +
-        (atoms.length > 0 ? '\n' : ''), 'utf8');
+    await atomicWriteFile(atomsPath(workspace), atoms.map((atom) => JSON.stringify(atom)).join('\n') +
+        (atoms.length > 0 ? '\n' : ''));
     await writeKnowledgeIndexes(workspace, atoms);
     await touchSchema(workspace);
 }
 export async function appendKnowledgeAtom(workspace, atom) {
-    const atoms = await readAtomsFile(workspace);
-    atoms.push(atom);
-    await writeKnowledgeAtoms(workspace, atoms);
+    await withKnowledgeWriteLock(workspace, async () => {
+        const atoms = await readAtomsFile(workspace);
+        atoms.push(atom);
+        await writeKnowledgeAtomsUnlocked(workspace, atoms);
+    });
     return atom;
 }
 export async function createKnowledgeAtom(workspace, input, maps) {
@@ -103,28 +110,51 @@ export async function migrateLegacyCognitionToAtoms(workspace) {
         if (existingIds.has(id))
             continue;
         if (existing.some((atom) => atom.topic === note.title &&
-            atom.claim === (note.summary ?? note.title) &&
-            atom.provenance.createdAt === note.createdAt)) {
+            atom.claim === (note.summary ?? note.title))) {
             continue;
         }
         migrated.push(legacyNoteToAtom(note, id));
     }
     if (migrated.length > 0) {
-        await writeKnowledgeAtoms(workspace, [...existing, ...migrated]);
+        await withKnowledgeWriteLock(workspace, async () => {
+            const current = await readAtomsFile(workspace);
+            const currentIds = new Set(current.map((atom) => atom.id));
+            const nextMigrated = migrated.filter((atom) => !currentIds.has(atom.id) &&
+                !current.some((existing) => existing.topic === atom.topic &&
+                    existing.claim === atom.claim));
+            if (nextMigrated.length > 0) {
+                await writeKnowledgeAtomsUnlocked(workspace, [
+                    ...current,
+                    ...nextMigrated,
+                ]);
+            }
+        });
     }
     else {
         await writeKnowledgeIndexes(workspace, existing);
     }
 }
 export async function updateKnowledgeAtom(workspace, atomId, updater) {
-    const atoms = await readKnowledgeAtoms(workspace);
-    const index = atoms.findIndex((atom) => atom.id === atomId);
-    if (index === -1) {
-        throw new KGraphError(`Knowledge atom not found: ${atomId}`);
-    }
-    atoms[index] = updater(atoms[index]);
-    await writeKnowledgeAtoms(workspace, atoms);
-    return atoms[index];
+    await migrateLegacyCognitionToAtoms(workspace);
+    return withKnowledgeWriteLock(workspace, async () => {
+        const atoms = await readAtomsFile(workspace);
+        const index = atoms.findIndex((atom) => atom.id === atomId);
+        if (index === -1) {
+            throw new KGraphError(`Knowledge atom not found: ${atomId}`);
+        }
+        atoms[index] = updater(atoms[index]);
+        await writeKnowledgeAtomsUnlocked(workspace, atoms);
+        return atoms[index];
+    });
+}
+export async function updateKnowledgeAtoms(workspace, updater) {
+    await migrateLegacyCognitionToAtoms(workspace);
+    return withKnowledgeWriteLock(workspace, async () => {
+        const current = await readAtomsFile(workspace);
+        const { atoms, result } = updater(current);
+        await writeKnowledgeAtomsUnlocked(workspace, atoms);
+        return result;
+    });
 }
 export async function refreshKnowledgeAtomStatuses(workspace, maps, dryRun = false) {
     const atoms = await readKnowledgeAtoms(workspace);
@@ -414,9 +444,9 @@ async function writeKnowledgeIndexes(workspace, atoms) {
     await mkdir(indexesPath(workspace), { recursive: true });
     const indexes = buildIndexes(atoms);
     await Promise.all([
-        writeFile(path.join(indexesPath(workspace), 'terms.json'), JSON.stringify(indexes.terms, null, 2) + '\n', 'utf8'),
-        writeFile(path.join(indexesPath(workspace), 'refs.json'), JSON.stringify(indexes.refs, null, 2) + '\n', 'utf8'),
-        writeFile(path.join(indexesPath(workspace), 'topics.json'), JSON.stringify(indexes.topics, null, 2) + '\n', 'utf8'),
+        atomicWriteFile(path.join(indexesPath(workspace), 'terms.json'), JSON.stringify(indexes.terms, null, 2) + '\n'),
+        atomicWriteFile(path.join(indexesPath(workspace), 'refs.json'), JSON.stringify(indexes.refs, null, 2) + '\n'),
+        atomicWriteFile(path.join(indexesPath(workspace), 'topics.json'), JSON.stringify(indexes.topics, null, 2) + '\n'),
     ]);
 }
 function buildIndexes(atoms) {
@@ -454,7 +484,7 @@ async function readSchema(workspace) {
 }
 async function writeSchema(workspace, schema) {
     await mkdir(workspace.knowledgePath, { recursive: true });
-    await writeFile(schemaPath(workspace), JSON.stringify(schema, null, 2) + '\n', 'utf8');
+    await atomicWriteFile(schemaPath(workspace), JSON.stringify(schema, null, 2) + '\n');
 }
 function buildAtomId(createdAt, seed) {
     return `${createdAt.replace(/[:.]/g, '-')}-${slugify(seed) || 'atom'}`;
@@ -484,3 +514,32 @@ function schemaPath(workspace) {
 function indexesPath(workspace) {
     return path.join(workspace.knowledgePath, 'indexes');
 }
+async function atomicWriteFile(targetPath, content) {
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    const tempPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
+    await writeFile(tempPath, content, 'utf8');
+    await rename(tempPath, targetPath);
+}
+async function withKnowledgeWriteLock(workspace, operation) {
+    await mkdir(workspace.knowledgePath, { recursive: true });
+    const lockPath = path.join(workspace.knowledgePath, '.write.lock');
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            await mkdir(lockPath);
+            break;
+        }
+        catch (error) {
+            if (Date.now() - startedAt > 10_000) {
+                throw new KGraphError('Timed out waiting for KGraph knowledge write lock.');
+            }
+            await delay(50);
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await rm(lockPath, { recursive: true, force: true });
+    }
+}

package/dist/types/knowledge.d.ts

@@ -89,4 +89,8 @@ export interface ContextPack {
     items: ContextPackItem[];
     omitted: ContextPackItem[];
     warnings: string[];
+    pendingInbox?: {
+        count: number;
+        files: string[];
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {