@kentwynn/kgraph 0.2.5 → 0.2.6

package/README.md

@@ -133,7 +133,7 @@ Agents can also report session activity so KGraph can estimate token waste:
 kgraph session start --agent codex
 kgraph session read src/auth.ts --agent codex
 kgraph session write src/auth.ts --agent codex
-kgraph session end --agent codex
+kgraph session end --agent codex --conclude --topic "auth session work"
 kgraph session
 ```
 
@@ -204,10 +204,30 @@ kgraph session start --agent codex
 kgraph session read src/auth.ts --agent codex
 kgraph session write src/auth.ts --agent codex
 kgraph session end --agent codex
+kgraph session end --agent codex --conclude --topic "auth token refresh"
 ```
 
 Track agent-reported read/write activity, repeated reads, and estimated token cost. Supported agents are `codex`, `claude-code`, `copilot`, `cursor`, `gemini`, `windsurf`, and `cline`.
-The text report now includes next actions, such as using `kgraph context "<topic>"` before repeated broad file inspection.
+The text report now includes next actions, such as using `kgraph context "<topic>"` before repeated broad file inspection. Add `--conclude` to store a durable session summary with touched files attached as related cognition.
+
+```bash
+kgraph conclude "auth refresh requires rotating the session cookie" \
+  --type gotcha \
+  --confidence high \
+  --domain auth \
+  --file src/auth.ts \
+  --symbol refreshSession \
+  --note "The refresh path must update both the access token and cookie expiry."
+```
+
+Store durable engineering memory directly. Cognition is typed as `finding`, `decision`, `gotcha`, `summary`, or `relationship`, and confidence is `high`, `medium`, or `low`. Keep conclusions concise: preserve expensive-to-rediscover knowledge, not raw chain-of-thought, speculative exploration, or temporary reasoning.
+
+```bash
+kgraph compact --dry-run
+kgraph compact
+```
+
+Merge duplicate cognition records and archive low-confidence stale entries. Compaction keeps memory inspectable under `.kgraph/cognition/` while reducing low-value noise in future context responses.
 
 ## Optional Step Commands
 

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

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

package/dist/cli/commands/compact.js

@@ -0,0 +1,27 @@
+import { compactCognition } from '../../cognition/compact.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { runCommand } from '../errors.js';
+export function registerCompactCommand(program) {
+    program
+        .command('compact')
+        .description('Merge duplicate cognition and archive low-value stale entries')
+        .option('--dry-run', 'Preview compaction without changing files')
+        .option('--json', 'Print JSON output')
+        .action((options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const result = await compactCognition(workspace, Boolean(options.dryRun));
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(options.dryRun ? 'KGraph Compact Preview' : 'KGraph Compact Complete');
+        console.log(`Merged duplicate groups: ${result.merged.length}`);
+        console.log(`Archived stale low-confidence notes: ${result.archived.length}`);
+        for (const item of result.merged) {
+            console.log(`- merged ${item.sourceIds.length} notes into ${item.title}`);
+        }
+        for (const item of result.archived) {
+            console.log(`- archived ${item.title}: ${item.reason}`);
+        }
+    }));
+}

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

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+import type { CognitionConfidence, CognitionKind } from '../../types/cognition.js';
+export declare function registerConcludeCommand(program: Command): void;
+export declare function normalizeKind(value: string | undefined): CognitionKind;
+export declare function normalizeConfidence(value: string | undefined): CognitionConfidence;

package/dist/cli/commands/conclude.js

@@ -0,0 +1,57 @@
+import { concludeTopic } from '../../cognition/conclusion.js';
+import { assertWorkspace } from '../../storage/kgraph-paths.js';
+import { KGraphError, runCommand } from '../errors.js';
+export function registerConcludeCommand(program) {
+    program
+        .command('conclude <topic>')
+        .description('Store durable typed engineering cognition for this repo')
+        .option('--type <type>', 'finding, decision, gotcha, summary, or relationship', 'summary')
+        .option('--confidence <level>', 'high, medium, or low', 'medium')
+        .option('--domain <name>', 'Domain name for this cognition')
+        .option('--tag <tag>', 'Tag to attach; repeatable', collect, [])
+        .option('--file <path>', 'Related repo file; repeatable', collect, [])
+        .option('--symbol <name>', 'Related symbol; repeatable', collect, [])
+        .option('--note <text>', 'Concise durable conclusion text')
+        .option('--json', 'Print JSON output')
+        .action((topic, options) => runCommand(async () => {
+        const workspace = await assertWorkspace(process.cwd());
+        const note = await concludeTopic(workspace, {
+            topic,
+            body: options.note,
+            kind: normalizeKind(options.type),
+            confidence: normalizeConfidence(options.confidence),
+            domain: options.domain,
+            tags: options.tag ?? [],
+            relatedFiles: options.file ?? [],
+            relatedSymbols: options.symbol ?? [],
+            source: 'conclude',
+        });
+        if (options.json) {
+            console.log(JSON.stringify(note, null, 2));
+            return;
+        }
+        console.log(`Stored ${note.kind} cognition: ${note.title}`);
+        console.log(`Confidence: ${note.confidence}`);
+        console.log(`Status: ${note.referencesStatus}`);
+    }));
+}
+export function normalizeKind(value) {
+    if (value === 'finding' ||
+        value === 'decision' ||
+        value === 'gotcha' ||
+        value === 'summary' ||
+        value === 'relationship') {
+        return value;
+    }
+    throw new KGraphError('--type must be finding, decision, gotcha, summary, or relationship.');
+}
+export function normalizeConfidence(value) {
+    if (value === 'high' || value === 'medium' || value === 'low') {
+        return value;
+    }
+    throw new KGraphError('--confidence must be high, medium, or low.');
+}
+function collect(value, previous) {
+    previous.push(value);
+    return previous;
+}

package/dist/cli/commands/context.js

@@ -49,7 +49,7 @@ export function renderContextMarkdown(response) {
         return `- ${s.name} (${kindInfo}) in ${s.filePath}${lineRange} because ${formatReasons(item.reasons)}`;
     })));
     lines.push('', '## Relevant Cognition', '');
-    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.referencesStatus}] because ${formatReasons(item.reasons)}`)));
+    lines.push(...formatList(response.relevantCognition.map((item) => `- ${item.item.title} [${item.item.kind ?? 'summary'}, ${item.item.confidence ?? 'medium'}, ${item.item.referencesStatus}] because ${formatReasons(item.reasons)}`)));
     lines.push('', '## Relationships', '');
     lines.push(...formatGroupedRelationships(response.relationships, response.relationshipExplanations));
     lines.push('', '## Nearby Symbols (1-hop imports)', '');

package/dist/cli/commands/session.js

@@ -1,7 +1,9 @@
+import { buildActiveSessionConclusion, concludeTopic, } from '../../cognition/conclusion.js';
 import { assertSessionAgent, buildSessionReport, recordSessionEvent, resetSession, } from '../../session/session-store.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { readMaps } from '../../storage/map-store.js';
 import { KGraphError, runCommand } from '../errors.js';
+import { normalizeConfidence, normalizeKind } from './conclude.js';
 export function registerSessionCommand(program) {
     const session = program
         .command('session')
@@ -62,14 +64,32 @@ export function registerSessionCommand(program) {
         .command('end')
         .requiredOption('--agent <name>', 'KGraph integration agent name')
         .option('--source <source>', 'automatic, agent-reported, or manual', 'manual')
+        .option('--conclude', 'Store a durable typed summary for this session')
+        .option('--topic <topic>', 'Conclusion topic when using --conclude')
+        .option('--type <type>', 'finding, decision, gotcha, summary, or relationship', 'summary')
+        .option('--confidence <level>', 'high, medium, or low', 'medium')
+        .option('--note <text>', 'Concise durable conclusion text')
         .action((options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
+        let pendingConclusion;
+        if (options.conclude) {
+            pendingConclusion = await buildActiveSessionConclusion(workspace, requireAgent(options.agent), {
+                topic: options.topic ?? `${options.agent} session summary`,
+                body: options.note,
+                kind: normalizeKind(options.type),
+                confidence: normalizeConfidence(options.confidence),
+            });
+        }
         const event = await recordSessionEvent(workspace, {
             agent: requireAgent(options.agent),
             type: 'end',
             captureSource: normalizeSource(options.source),
         });
         console.log(`KGraph session ended for ${event.agent}.`);
+        if (pendingConclusion) {
+            const note = await concludeTopic(workspace, pendingConclusion);
+            console.log(`Stored session cognition: ${note.title}`);
+        }
     }));
     session
         .command('reset')

package/dist/cli/help.js

@@ -29,6 +29,9 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('scan', 'Optional: refresh only file, symbol, import, and relationship maps'),
         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('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'),

package/dist/cli/index.js

@@ -3,6 +3,8 @@ import { Command } from 'commander';
 import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { registerCompactCommand } from './commands/compact.js';
+import { registerConcludeCommand } from './commands/conclude.js';
 import { registerContextCommand } from './commands/context.js';
 import { registerDoctorCommand } from './commands/doctor.js';
 import { registerHistoryCommand } from './commands/history.js';
@@ -40,6 +42,8 @@ export function createProgram() {
     registerInitCommand(program);
     registerScanCommand(program);
     registerSessionCommand(program);
+    registerConcludeCommand(program);
+    registerCompactCommand(program);
     registerUpdateCommand(program);
     registerContextCommand(program);
     registerImpactCommand(program);

package/dist/cognition/cognition-updater.js

@@ -29,6 +29,7 @@ export async function updateCognition(workspace, currentMaps, dryRun = false) {
                     .split(path.sep)
                     .join('/'),
                 createdAt: new Date().toISOString(),
+                source: 'inbox',
                 referencesStatus: evaluateReferenceStatus(parsed.relatedFiles, parsed.relatedSymbols, currentMaps),
             };
             processed.push(note);
@@ -73,6 +74,7 @@ export async function refreshCognitionReferenceStatuses(workspace, currentMaps)
             await writeCognitionNote(workspace, {
                 ...note,
                 relatedSymbols,
+                updatedAt: new Date().toISOString(),
                 referencesStatus: nextStatus,
             });
         }

package/dist/cognition/compact.d.ts

@@ -0,0 +1,14 @@
+import type { KGraphWorkspace } from '../types/config.js';
+export interface CompactResult {
+    merged: Array<{
+        targetId: string;
+        sourceIds: string[];
+        title: string;
+    }>;
+    archived: Array<{
+        id: string;
+        title: string;
+        reason: string;
+    }>;
+}
+export declare function compactCognition(workspace: KGraphWorkspace, dryRun?: boolean): Promise<CompactResult>;

package/dist/cognition/compact.js

@@ -0,0 +1,167 @@
+import { mkdir, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { overwriteDomainRecord, readCognitionNotes, 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 result = { merged: [], archived: [] };
+    const consumed = new Set();
+    const archived = new Set();
+    const mergedNotes = [];
+    for (const group of groups.filter((items) => items.length > 1)) {
+        const merged = mergeNotes(group, {
+            files: maps.fileMap.files,
+            symbols: maps.symbolMap.symbols,
+        });
+        const sourceIds = group.map((note) => note.id);
+        result.merged.push({
+            targetId: merged.id,
+            sourceIds,
+            title: merged.title,
+        });
+        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}`);
+            }
+        }
+    }
+    for (const note of notes) {
+        if (consumed.has(note.id))
+            continue;
+        if (note.confidence === 'low' &&
+            (note.referencesStatus === 'stale' || note.referencesStatus === 'unresolved')) {
+            result.archived.push({
+                id: note.id,
+                title: note.title,
+                reason: 'low-confidence stale cognition',
+            });
+            archived.add(note.id);
+            if (!dryRun) {
+                await archiveNote(workspace, note, 'low-confidence-stale');
+            }
+        }
+    }
+    if (!dryRun && (consumed.size > 0 || archived.size > 0)) {
+        const activeNotes = [
+            ...notes.filter((note) => !consumed.has(note.id) && !archived.has(note.id)),
+            ...mergedNotes,
+        ];
+        await rebuildDomainRecords(workspace, activeNotes, {
+            files: maps.fileMap.files,
+            symbols: maps.symbolMap.symbols,
+        });
+    }
+    return result;
+}
+function groupDuplicates(notes) {
+    const byKey = new Map();
+    for (const note of notes) {
+        if (note.supersededBy)
+            continue;
+        const key = [
+            note.kind ?? 'summary',
+            note.domain ?? 'general',
+            normalizeTitle(note.title),
+            normalizeText(note.summary ?? ''),
+            stableList(note.relatedFiles),
+            stableList(note.relatedSymbols),
+        ].join('\0');
+        const group = byKey.get(key) ?? [];
+        group.push(note);
+        byKey.set(key, group);
+    }
+    return [...byKey.values()];
+}
+function mergeNotes(notes, currentMaps) {
+    const sorted = [...notes].sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    const base = sorted[sorted.length - 1];
+    const now = new Date().toISOString();
+    const id = `${now.replace(/[:.]/g, '-')}-${slugify(base.title) || 'compacted'}`;
+    const summaries = unique(sorted
+        .map((note) => note.summary)
+        .filter((summary) => Boolean(summary?.trim())));
+    const relatedFiles = unique(sorted.flatMap((note) => note.relatedFiles));
+    const relatedSymbols = unique(sorted.flatMap((note) => note.relatedSymbols));
+    return {
+        ...base,
+        id,
+        source: 'compact',
+        createdAt: now,
+        updatedAt: now,
+        supersedes: sorted.map((note) => note.id),
+        supersededBy: undefined,
+        confidence: highestConfidence(sorted.map((note) => note.confidence)),
+        relatedFiles,
+        relatedSymbols,
+        tags: unique(sorted.flatMap((note) => note.tags)),
+        summary: summaries[0] ?? base.summary,
+        sections: {
+            Summary: summaries.map((summary) => `- ${summary}`).join('\n'),
+            'Compacted From': sorted.map((note) => `- ${note.id}`).join('\n'),
+        },
+        warnings: unique(sorted.flatMap((note) => note.warnings)),
+        referencesStatus: evaluateReferenceStatus(relatedFiles, relatedSymbols, currentMaps),
+    };
+}
+async function rebuildDomainRecords(workspace, notes, currentMaps) {
+    const existingDomains = await readDomainRecords(workspace);
+    const existingByName = new Map(existingDomains.map((domain) => [domain.name, domain]));
+    const domainNames = new Set([
+        ...existingDomains.map((domain) => domain.name),
+        ...notes.map((note) => note.domain ?? 'general'),
+    ]);
+    const fileSet = new Set(currentMaps.files.map((file) => file.path));
+    const symbolSet = new Set(currentMaps.symbols.map((symbol) => symbol.name));
+    for (const name of domainNames) {
+        const relatedNotes = notes.filter((note) => (note.domain ?? 'general') === name);
+        const existing = existingByName.get(name);
+        const next = {
+            name,
+            description: existing?.description,
+            pathHints: unique(relatedNotes.flatMap((note) => note.relatedFiles)),
+            tags: unique(relatedNotes.flatMap((note) => note.tags)),
+            files: unique(relatedNotes
+                .flatMap((note) => note.relatedFiles)
+                .filter((file) => fileSet.has(file))),
+            symbols: unique(relatedNotes
+                .flatMap((note) => note.relatedSymbols)
+                .filter((symbol) => symbolSet.has(symbol))),
+            cognitionNotes: relatedNotes.map((note) => note.id),
+        };
+        await overwriteDomainRecord(workspace, next);
+    }
+}
+async function archiveNote(workspace, note, reason) {
+    const source = path.join(workspace.cognitionPath, `${note.id}.md`);
+    if (!(await pathExists(source)))
+        return;
+    const archivedDir = path.join(workspace.cognitionPath, 'archived');
+    await mkdir(archivedDir, { recursive: true });
+    await rename(source, path.join(archivedDir, `${reason}-${note.id}.md`));
+}
+function highestConfidence(values) {
+    if (values.includes('high'))
+        return 'high';
+    if (values.includes('medium'))
+        return 'medium';
+    return 'low';
+}
+function normalizeTitle(value) {
+    return normalizeText(value);
+}
+function normalizeText(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+function stableList(values) {
+    return [...values].sort().join('\0');
+}
+function unique(items) {
+    return [...new Set(items)];
+}

package/dist/cognition/conclusion.d.ts

@@ -0,0 +1,16 @@
+import type { CognitionConfidence, CognitionKind, CognitionNote, CognitionSource } from '../types/cognition.js';
+import type { KGraphWorkspace } from '../types/config.js';
+export interface ConclusionInput {
+    topic: string;
+    body?: string;
+    kind?: CognitionKind;
+    confidence?: CognitionConfidence;
+    domain?: string;
+    tags?: string[];
+    relatedFiles?: string[];
+    relatedSymbols?: string[];
+    source: CognitionSource;
+}
+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>;
+export declare function buildActiveSessionConclusion(workspace: KGraphWorkspace, agent: string, input: Omit<ConclusionInput, 'source' | 'relatedFiles' | 'relatedSymbols'>): Promise<ConclusionInput>;

package/dist/cognition/conclusion.js

@@ -0,0 +1,96 @@
+import { readMaps } from '../storage/map-store.js';
+import { slugify, writeCognitionNote, writeDomainRecord } from '../storage/cognition-store.js';
+import { KGraphError } from '../cli/errors.js';
+import { evaluateReferenceStatus } from './cognition-updater.js';
+import { readSessionState } from '../session/session-store.js';
+export async function concludeTopic(workspace, input) {
+    const maps = await readMaps(workspace);
+    const now = new Date().toISOString();
+    const timestamp = now.replace(/[:.]/g, '-');
+    const title = input.topic.trim();
+    const summary = normalizeBody(input.body) ?? title;
+    const note = {
+        title,
+        kind: input.kind ?? 'summary',
+        confidence: input.confidence ?? 'medium',
+        domain: input.domain,
+        tags: input.tags ?? [],
+        summary,
+        sections: {
+            Summary: summary,
+            ...(input.relatedFiles?.length ? { 'Related Files': input.relatedFiles.map((file) => `- ${file}`).join('\n') } : {}),
+            ...(input.relatedSymbols?.length ? { 'Key Symbols': input.relatedSymbols.map((symbol) => `- \`${symbol}\``).join('\n') } : {}),
+        },
+        relatedFiles: input.relatedFiles ?? [],
+        relatedSymbols: input.relatedSymbols ?? [],
+        warnings: [],
+        id: `${timestamp}-${slugify(title) || 'conclusion'}`,
+        sourceInboxPath: '',
+        processedPath: `.kgraph/cognition/${timestamp}-${slugify(title) || 'conclusion'}.md`,
+        createdAt: now,
+        source: input.source,
+        referencesStatus: evaluateReferenceStatus(input.relatedFiles ?? [], input.relatedSymbols ?? [], { files: maps.fileMap.files, symbols: maps.symbolMap.symbols }),
+    };
+    await writeCognitionNote(workspace, note);
+    await writeDomainRecord(workspace, toDomainRecord(note, {
+        files: maps.fileMap.files,
+        symbols: maps.symbolMap.symbols,
+    }));
+    return note;
+}
+export async function concludeActiveSession(workspace, agent, input) {
+    return concludeTopic(workspace, await buildActiveSessionConclusion(workspace, agent, input));
+}
+export async function buildActiveSessionConclusion(workspace, agent, input) {
+    const state = await readSessionState(workspace);
+    const active = state.active[agent];
+    if (!active) {
+        throw new KGraphError(`No active session for agent "${agent}".`);
+    }
+    const events = state.events.filter((event) => event.agent === agent && event.timestamp >= active.startedAt);
+    const touchedFiles = [
+        ...new Set(events
+            .filter((event) => event.type === 'read' || event.type === 'write')
+            .map((event) => event.path)
+            .filter((file) => Boolean(file))),
+    ];
+    const writtenFiles = [
+        ...new Set(events
+            .filter((event) => event.type === 'write')
+            .map((event) => event.path)
+            .filter((file) => Boolean(file))),
+    ];
+    const body = [
+        normalizeBody(input.body) ?? `Session concluded for ${input.topic}.`,
+        touchedFiles.length
+            ? `Touched files: ${touchedFiles.join(', ')}.`
+            : undefined,
+        writtenFiles.length
+            ? `Changed files: ${writtenFiles.join(', ')}.`
+            : undefined,
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+    return {
+        ...input,
+        body,
+        source: 'session-conclude',
+        relatedFiles: touchedFiles,
+    };
+}
+function normalizeBody(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function toDomainRecord(note, currentMaps) {
+    const fileSet = new Set(currentMaps.files.map((file) => file.path));
+    const symbolSet = new Set(currentMaps.symbols.map((symbol) => symbol.name));
+    return {
+        name: note.domain ?? 'general',
+        pathHints: note.relatedFiles,
+        tags: note.tags,
+        files: note.relatedFiles.filter((file) => fileSet.has(file)),
+        symbols: note.relatedSymbols.filter((symbol) => symbolSet.has(symbol)),
+        cognitionNotes: [note.id],
+    };
+}

package/dist/cognition/markdown-note-parser.js

@@ -10,6 +10,8 @@ export function parseMarkdownNote(markdown) {
     const combined = Object.values(sections).join('\n');
     return {
         title,
+        kind: normalizeKind(frontmatter.type ?? frontmatter.kind, warnings),
+        confidence: normalizeConfidence(frontmatter.confidence, warnings),
         domain: typeof frontmatter.domain === 'string' ? frontmatter.domain : undefined,
         tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
         summary: sections.Summary,
@@ -19,6 +21,28 @@ export function parseMarkdownNote(markdown) {
         warnings,
     };
 }
+function normalizeKind(value, warnings) {
+    if (value === 'finding' ||
+        value === 'decision' ||
+        value === 'gotcha' ||
+        value === 'summary' ||
+        value === 'relationship') {
+        return value;
+    }
+    if (value !== undefined) {
+        warnings.push(`Unsupported cognition type "${String(value)}"; defaulted to summary.`);
+    }
+    return 'summary';
+}
+function normalizeConfidence(value, warnings) {
+    if (value === 'high' || value === 'medium' || value === 'low') {
+        return value;
+    }
+    if (value !== undefined) {
+        warnings.push(`Unsupported confidence "${String(value)}"; defaulted to medium.`);
+    }
+    return 'medium';
+}
 function splitFrontmatter(markdown, warnings) {
     if (!markdown.startsWith('---\n')) {
         return { frontmatter: {}, body: markdown };

package/dist/context/context-query.js

@@ -1,9 +1,14 @@
 import { getRecentlyCommittedFiles, getWorkingTreeChangesDetailed, isGitRepo, } from '../scanner/git-utils.js';
 import { readCognitionNotes, readDomainRecords, } from '../storage/cognition-store.js';
+import { readSessionState } from '../session/session-store.js';
 import { rankByFields } from './ranking.js';
 export async function queryContext(workspace, config, maps, query) {
     const cognition = await readCognitionNotes(workspace);
     const domains = await readDomainRecords(workspace);
+    const session = await readSessionState(workspace);
+    const sessionTouchedPaths = new Set(session.events
+        .map((event) => event.path)
+        .filter((path) => Boolean(path)));
     const max = config.maxContextItems;
     let relevantFiles = rankByFields(query, maps.fileMap.files, [
         { name: 'path', value: (file) => file.path },
@@ -11,7 +16,12 @@ export async function queryContext(workspace, config, maps, query) {
     ])
         .map((ranked) => ({
         ...ranked,
-        score: ranked.score - Math.floor((ranked.item.tokenEstimate ?? 0) / 2000),
+        score: ranked.score -
+            Math.floor((ranked.item.tokenEstimate ?? 0) / 2000) +
+            (sessionTouchedPaths.has(ranked.item.path) ? 3 : 0),
+        reasons: sessionTouchedPaths.has(ranked.item.path)
+            ? [...ranked.reasons, 'touched in current session']
+            : ranked.reasons,
     }))
         .sort((a, b) => b.score - a.score)
         .slice(0, max);
@@ -23,12 +33,17 @@ export async function queryContext(workspace, config, maps, query) {
     ]).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 },
-    ]).slice(0, max);
+    ])
+        .map((ranked) => applyCognitionRankAdjustments(ranked))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, max);
     const matchedDomains = rankByFields(query, domains, [
         { name: 'name', value: (domain) => domain.name },
         { name: 'tags', value: (domain) => domain.tags },
@@ -277,6 +292,36 @@ function explainRelationships(relationships, context) {
         return { relationship, reasons: [...reasons] };
     });
 }
+function applyCognitionRankAdjustments(ranked) {
+    const reasons = [...ranked.reasons];
+    let score = ranked.score;
+    if (ranked.item.confidence === 'high') {
+        score += 3;
+        reasons.push('high confidence cognition');
+    }
+    else if (ranked.item.confidence === 'low') {
+        score -= 2;
+        reasons.push('low confidence penalty');
+    }
+    if (ranked.item.referencesStatus === 'current') {
+        score += 2;
+        reasons.push('current references');
+    }
+    else if (ranked.item.referencesStatus === 'mixed') {
+        score -= 1;
+        reasons.push('mixed reference penalty');
+    }
+    else if (ranked.item.referencesStatus === 'stale' ||
+        ranked.item.referencesStatus === 'unresolved') {
+        score -= 4;
+        reasons.push('stale reference penalty');
+    }
+    if (ranked.item.kind === 'decision' || ranked.item.kind === 'gotcha') {
+        score += 1;
+        reasons.push(`${ranked.item.kind} cognition`);
+    }
+    return { ...ranked, score, reasons };
+}
 function dependenciesForImportedSymbol(symbol, dependencies) {
     return dependencies
         .filter((dependency) => dependency.kind === 'local' &&

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 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 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: [
         {
@@ -23,6 +23,11 @@ ${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.
+`,
+        },
+        {
+            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.
 `,
         },
         {
@@ -47,7 +52,12 @@ ${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are una
         },
         {
             path: '.claude/commands/kgraph-session.md',
-            content: `Use \`kgraph session\` to inspect session read/write/token estimates. Record meaningful events with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code\`.
+            content: `Use \`kgraph session\` to inspect session read/write/token estimates. Record meaningful events with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code --conclude --topic "<topic>"\` when durable session memory is useful.
+`,
+        },
+        {
+            path: '.claude/commands/kgraph-conclude.md',
+            content: `Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
 `,
         },
         {

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 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 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, 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, scan, update, conclude, compact, impact, history, and session commands to ground responses in durable local knowledge.
 tools:
   - run_in_terminal
   - read_file
@@ -47,6 +47,17 @@ 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.
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-compact.prompt.md',
+            content: `---
+description: Merge duplicate KGraph cognition and archive stale low-value entries
+agent: agent
+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.
 `,
         },
         {
@@ -90,6 +101,17 @@ argument-hint: "Brief description of what was done"
 Capture this session into KGraph cognition.
 
 {{KGRAPH_CAPTURE_POLICY}}
+`,
+        },
+        {
+            path: '.github/prompts/kgraph-conclude.prompt.md',
+            content: `---
+description: Store a typed durable KGraph engineering conclusion
+agent: agent
+argument-hint: "Topic plus optional type, confidence, files, and symbols"
+---
+
+Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
 `,
         },
         {
@@ -111,7 +133,7 @@ agent: agent
 argument-hint: "start, read <path>, write <path>, end, or status"
 ---
 
-Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot\`.
+Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot --conclude --topic "<topic>"\` when durable session memory is useful.
 `,
         },
         {

package/dist/integrations/instruction-blocks.js

@@ -50,14 +50,20 @@ export function renderContextPolicy(mode) {
 }
 export function renderCapturePolicy() {
     return `Capture policy:
-- At the end of any session that changed repository files, write one concise Markdown note to \`.kgraph/inbox/<slug>.md\` before finishing.
-- A \`.kgraph/inbox/*.md\` note is KGraph runtime capture, not project documentation. It is allowed and required by this workflow unless the user explicitly says not to capture to KGraph.
-- Do not skip capture for UI text, button, link, route, styling, or small file edits. Skip capture only when no repository files changed.
+- At the end of any session that changed repository files, store durable engineering memory with \`kgraph conclude "<topic>" --type <finding|decision|gotcha|summary|relationship> --confidence <high|medium|low>\` or \`kgraph session end --agent <agent> --conclude --topic "<topic>"\`.
+- Preserve only expensive-to-rediscover findings, decisions, gotchas, summaries, and relationships. Do not store raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
+- 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 "<topic>"\`. If repo files changed, write the inbox note first, then run \`kgraph\` once at the end.
-- After the final \`kgraph\` run, mention whether the inbox note was processed.
+- After the final \`kgraph\` run, mention whether durable cognition was stored or processed.
 
-The inbox note must use this structure:
+When using an inbox note, use this structure:
 \`\`\`markdown
+---
+type: finding
+confidence: medium
+---
 # <Short Title>
 
 ## Summary

package/dist/integrations/workflow-steps.js

@@ -5,9 +5,10 @@
 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 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.`;
 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}\``;
+    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}.`;
 }
 /**
@@ -25,8 +26,9 @@ export function numberedWorkflow(agentName, options = {}) {
 {{KGRAPH_CAPTURE_POLICY}}
 
 7. ${REPAIR_STEP}
-8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-9. ${HISTORY_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}`;
 }
 /**
  * Returns the bullet-list workflow for rules files.
@@ -39,6 +41,7 @@ export function bulletWorkflow(agentName, options = {}) {
 - ${IMPACT_STEP}
 {{KGRAPH_CAPTURE_POLICY}}
 - ${REPAIR_STEP}
+- ${COMPACT_STEP}
 - Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
 - ${HISTORY_STEP}`;
 }

package/dist/session/session-store.js

@@ -32,6 +32,9 @@ export async function readSessionLedger(workspace) {
 export async function recordSessionEvent(workspace, input) {
     const now = new Date().toISOString();
     const state = await readSessionState(workspace);
+    if (input.type === 'end' && !state.active[input.agent]) {
+        throw new KGraphError(`No active session for agent "${input.agent}".`);
+    }
     // Auto-close any open session for this agent before starting a new one so
     // the ledger entry is never silently lost on repeated start calls.
     if (input.type === 'start' && state.active[input.agent]) {

package/dist/storage/cognition-store.js

@@ -53,7 +53,7 @@ export async function readCognitionNotes(workspace) {
         const raw = await readFile(filePath, "utf8");
         const encoded = parseEmbeddedJson(raw);
         if (encoded) {
-            notes.push(encoded);
+            notes.push(normalizeCognitionNote(encoded));
         }
     }
     return notes;
@@ -80,6 +80,30 @@ function parseEmbeddedJson(raw) {
     const encoded = raw.match(/```json\n([\s\S]*?)\n```/);
     return encoded ? JSON.parse(encoded[1]) : undefined;
 }
+function normalizeCognitionNote(note) {
+    const title = note.title ?? 'Untitled Cognition Note';
+    return {
+        title,
+        kind: note.kind ?? 'summary',
+        confidence: note.confidence ?? 'medium',
+        domain: note.domain,
+        tags: note.tags ?? [],
+        summary: note.summary,
+        sections: note.sections ?? {},
+        relatedFiles: note.relatedFiles ?? [],
+        relatedSymbols: note.relatedSymbols ?? [],
+        warnings: note.warnings ?? [],
+        id: (note.id ?? slugify(title)) || 'cognition-note',
+        sourceInboxPath: note.sourceInboxPath ?? '',
+        processedPath: note.processedPath ?? '',
+        createdAt: note.createdAt ?? '',
+        updatedAt: note.updatedAt,
+        source: note.source ?? 'inbox',
+        supersedes: note.supersedes,
+        supersededBy: note.supersededBy,
+        referencesStatus: note.referencesStatus ?? 'unresolved',
+    };
+}
 function mergeDomainRecords(existing, next) {
     return {
         ...existing,
@@ -109,7 +133,7 @@ function renderCognitionNote(note) {
     const sectionText = Object.entries(note.sections)
         .map(([heading, content]) => `## ${heading}\n\n${content.trim()}`)
         .join("\n\n");
-    return `# ${note.title}\n\nStatus: ${note.referencesStatus}\n\n${sectionText}\n\n## KGraph Metadata\n\n\`\`\`json\n${JSON.stringify(note, null, 2)}\n\`\`\`\n`;
+    return `# ${note.title}\n\nType: ${note.kind ?? 'summary'}\nConfidence: ${note.confidence ?? 'medium'}\nStatus: ${note.referencesStatus}\nSource: ${note.source ?? 'inbox'}\n\n${sectionText}\n\n## KGraph Metadata\n\n\`\`\`json\n${JSON.stringify(note, null, 2)}\n\`\`\`\n`;
 }
 function renderDomainRecord(domain) {
     return `# ${domain.name}\n\n${domain.description ?? ""}\n\n## Files\n\n${domain.files

package/dist/types/cognition.d.ts

@@ -1,7 +1,12 @@
 import type { CodeSymbol, Relationship, RepositoryFile } from './maps.js';
 export type ReferenceStatus = 'current' | 'stale' | 'unresolved' | 'mixed';
+export type CognitionKind = 'finding' | 'decision' | 'gotcha' | 'summary' | 'relationship';
+export type CognitionConfidence = 'high' | 'medium' | 'low';
+export type CognitionSource = 'inbox' | 'conclude' | 'session-conclude' | 'compact';
 export interface ParsedCognitionNote {
     title: string;
+    kind: CognitionKind;
+    confidence: CognitionConfidence;
     domain?: string;
     tags: string[];
     summary?: string;
@@ -15,6 +20,10 @@ export interface CognitionNote extends ParsedCognitionNote {
     sourceInboxPath: string;
     processedPath: string;
     createdAt: string;
+    updatedAt?: string;
+    source: CognitionSource;
+    supersedes?: string[];
+    supersededBy?: string;
     referencesStatus: ReferenceStatus;
 }
 export interface DomainRecord {

package/package.json

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