context-vault 3.5.0 → 3.6.0

package/dist/tools/session-end.js

@@ -0,0 +1,288 @@
+import { z } from 'zod';
+import { captureAndIndex } from '@context-vault/core/capture';
+import { execSync } from 'node:child_process';
+import { ok, ensureVaultExists } from '../helpers.js';
+const DEFAULT_SIMILARITY_THRESHOLD = 0.85;
+const MAX_ENTRIES_PER_SESSION = 5;
+const PROMPT_TEMPLATE = `## Session End: Knowledge Capture
+
+Before this session ends, take a moment to capture what was learned.
+
+**Answer these questions (skip any that don't apply):**
+
+1. **What was accomplished?**
+   List the key outcomes of this session.
+
+2. **What was learned?** (most important)
+   Non-obvious findings, gotchas, or discoveries that would save time in a future session.
+   Skip anything derivable from reading the code or git history.
+
+3. **What decisions were made and why?**
+   Architectural choices, trade-offs, or scope decisions with their rationale.
+
+4. **What would save time for the next session?**
+   Blockers, context that took a while to build, or shortcuts discovered.
+
+**Then call \`session_end\` again with your summary and any discrete discoveries:**
+
+\`\`\`
+session_end({
+  summary: "your summary text",
+  discoveries: [
+    { title: "Short descriptive title", body: "What was learned and why it matters", kind: "insight" },
+    { title: "Decision: chose X over Y", body: "Rationale and trade-offs", kind: "decision" }
+  ]
+})
+\`\`\``;
+function detectProject() {
+    try {
+        const remote = execSync('git remote get-url origin 2>/dev/null', {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (remote) {
+            const match = remote.match(/\/([^/]+?)(?:\.git)?$/);
+            if (match)
+                return match[1];
+        }
+    }
+    catch { }
+    try {
+        const cwd = process.cwd();
+        const parts = cwd.split(/[/\\]/);
+        return parts[parts.length - 1];
+    }
+    catch { }
+    return null;
+}
+function classifyDiscovery(body) {
+    const lower = body.toLowerCase();
+    if (/chose|decided|picked|went with|trade.?off|alternative/i.test(lower))
+        return 'architectural';
+    if (/bug|fix|error|crash|broke|regression/i.test(lower))
+        return 'bugfix';
+    if (/pattern|convention|approach|technique/i.test(lower))
+        return 'pattern';
+    if (/api|endpoint|library|framework|dependency/i.test(lower))
+        return 'integration';
+    return 'general';
+}
+function extractInsightsFromSummary(summary) {
+    const insights = [];
+    const sections = summary.split(/\n(?=#+\s|(?:\d+\.|\*|-)\s+\*\*)/);
+    for (const section of sections) {
+        const lower = section.toLowerCase();
+        if (/\blearned\b|\bdiscover|\bgotcha|\bnon.?obvious|\bsurpris|\bunexpect|\bworkaround/.test(lower)) {
+            const lines = section.split('\n').filter(l => l.trim());
+            const bullets = lines.filter(l => /^\s*[-*]\s/.test(l));
+            if (bullets.length > 0) {
+                for (const bullet of bullets) {
+                    const text = bullet.replace(/^\s*[-*]\s+/, '').trim();
+                    if (text.length > 20) {
+                        insights.push({
+                            title: text.length > 120 ? text.slice(0, 117) + '...' : text,
+                            body: text,
+                            kind: 'insight',
+                        });
+                    }
+                }
+            }
+            else if (section.trim().length > 30) {
+                const firstLine = lines[0]?.replace(/^#+\s*/, '').trim() || 'Session insight';
+                insights.push({
+                    title: firstLine.length > 120 ? firstLine.slice(0, 117) + '...' : firstLine,
+                    body: section.trim(),
+                    kind: 'insight',
+                });
+            }
+        }
+        if (/\bdecision|\bdecided|\bchose|\btrade.?off/.test(lower)) {
+            const lines = section.split('\n').filter(l => l.trim());
+            const bullets = lines.filter(l => /^\s*[-*]\s/.test(l));
+            if (bullets.length > 0) {
+                for (const bullet of bullets) {
+                    const text = bullet.replace(/^\s*[-*]\s+/, '').trim();
+                    if (text.length > 20) {
+                        insights.push({
+                            title: text.length > 120 ? text.slice(0, 117) + '...' : text,
+                            body: text,
+                            kind: 'decision',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return insights.slice(0, MAX_ENTRIES_PER_SESSION);
+}
+async function deduplicateAndSave(entries, ctx) {
+    const saved = [];
+    const skipped = [];
+    for (const entry of entries) {
+        const embeddingText = [entry.title, entry.body].filter(Boolean).join(' ');
+        let isDuplicate = false;
+        try {
+            const embedding = await ctx.embed(embeddingText);
+            if (embedding) {
+                const vecCount = ctx.db.prepare('SELECT COUNT(*) as c FROM vault_vec').get()?.c ?? 0;
+                if (vecCount > 0) {
+                    const vecRows = ctx.db
+                        .prepare('SELECT v.rowid, v.distance FROM vault_vec v WHERE embedding MATCH ? ORDER BY distance LIMIT 3')
+                        .all(embedding, 3);
+                    for (const vr of vecRows) {
+                        const similarity = Math.max(0, 1 - vr.distance / 2);
+                        if (similarity >= DEFAULT_SIMILARITY_THRESHOLD) {
+                            const row = ctx.db
+                                .prepare('SELECT id, title FROM vault WHERE rowid = ?')
+                                .get(vr.rowid);
+                            if (row) {
+                                isDuplicate = true;
+                                skipped.push({
+                                    title: entry.title,
+                                    reason: `similar to "${row.title || row.id}" (${(similarity * 100).toFixed(0)}%)`,
+                                });
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch { }
+        if (isDuplicate)
+            continue;
+        try {
+            const result = await captureAndIndex(ctx, {
+                kind: entry.kind,
+                title: entry.title,
+                body: entry.body,
+                tags: entry.tags,
+                tier: entry.tier,
+                meta: entry.meta,
+                source: 'session-end',
+            });
+            saved.push({ id: result.id, title: entry.title, kind: entry.kind });
+        }
+        catch (e) {
+            skipped.push({
+                title: entry.title,
+                reason: `save failed: ${e.message}`,
+            });
+        }
+    }
+    return { saved, skipped };
+}
+export const name = 'session_end';
+export const description = 'End-of-session knowledge capture. Call when a session ends to extract and save insights, decisions, and learnings. If called without a summary, returns a prompt template to guide the agent through knowledge capture.';
+export const inputSchema = {
+    summary: z
+        .string()
+        .optional()
+        .describe('Session summary text covering what was accomplished, learned, decided, and what would help next time.'),
+    discoveries: z
+        .array(z.object({
+        title: z.string().describe('Short descriptive title for this discovery'),
+        body: z.string().describe('What was learned and why it matters'),
+        kind: z
+            .enum(['insight', 'decision', 'pattern', 'reference'])
+            .optional()
+            .describe('Entry kind (default: insight)'),
+    }))
+        .optional()
+        .describe('Explicit discoveries to save. Each becomes a vault entry with deduplication.'),
+    project: z
+        .string()
+        .optional()
+        .describe('Project name for bucket tagging. Auto-detected from git remote if not provided.'),
+};
+export async function handler({ summary, discoveries, project }, ctx, { ensureIndexed }) {
+    const { config } = ctx;
+    const vaultErr = ensureVaultExists(config);
+    if (vaultErr)
+        return vaultErr;
+    if (!summary && (!discoveries || discoveries.length === 0)) {
+        return ok(PROMPT_TEMPLATE);
+    }
+    await ensureIndexed({ blocking: false });
+    const effectiveProject = project?.trim() || detectProject();
+    const bucketTag = effectiveProject ? `bucket:${effectiveProject}` : null;
+    const baseTags = ['auto-session', ...(bucketTag ? [bucketTag] : [])];
+    const entriesToSave = [];
+    if (discoveries?.length) {
+        for (const d of discoveries.slice(0, MAX_ENTRIES_PER_SESSION)) {
+            const kind = d.kind || 'insight';
+            entriesToSave.push({
+                title: d.title,
+                body: d.body,
+                kind,
+                tags: [...baseTags],
+                tier: kind === 'decision' ? 'durable' : 'working',
+                meta: {
+                    discovery_type: classifyDiscovery(d.body),
+                    source: 'session-end-explicit',
+                },
+            });
+        }
+    }
+    if (summary) {
+        const extracted = extractInsightsFromSummary(summary);
+        const remainingSlots = MAX_ENTRIES_PER_SESSION - entriesToSave.length;
+        for (const e of extracted.slice(0, remainingSlots)) {
+            entriesToSave.push({
+                title: e.title,
+                body: e.body,
+                kind: e.kind,
+                tags: [...baseTags],
+                tier: e.kind === 'decision' ? 'durable' : 'working',
+                meta: {
+                    discovery_type: classifyDiscovery(e.body),
+                    source: 'session-end-extracted',
+                },
+            });
+        }
+        entriesToSave.push({
+            title: `Session: ${effectiveProject || 'unknown'} ${new Date().toISOString().slice(0, 10)}`,
+            body: summary,
+            kind: 'session',
+            tags: [...baseTags],
+            tier: 'ephemeral',
+            meta: {
+                source: 'session-end',
+                discoveries_explicit: discoveries?.length ?? 0,
+                discoveries_extracted: extractInsightsFromSummary(summary).length,
+            },
+        });
+    }
+    if (entriesToSave.length === 0) {
+        return ok('No save-worthy content found in the provided summary. Session recorded without vault entries.');
+    }
+    const { saved, skipped } = await deduplicateAndSave(entriesToSave, ctx);
+    const lines = ['## Session End Summary\n'];
+    if (saved.length > 0) {
+        lines.push(`### Saved (${saved.length})\n`);
+        for (const s of saved) {
+            lines.push(`- **${s.title}** (\`${s.kind}\`) \`${s.id}\``);
+        }
+        lines.push('');
+    }
+    if (skipped.length > 0) {
+        lines.push(`### Skipped (${skipped.length})\n`);
+        for (const s of skipped) {
+            lines.push(`- **${s.title}**: ${s.reason}`);
+        }
+        lines.push('');
+    }
+    if (saved.length === 0 && skipped.length > 0) {
+        lines.push('_All discoveries matched existing entries. No new entries created._');
+    }
+    const result = ok(lines.join('\n'));
+    result._meta = {
+        project: effectiveProject,
+        saved_count: saved.length,
+        skipped_count: skipped.length,
+        saved_ids: saved.map(s => s.id),
+    };
+    return result;
+}
+//# sourceMappingURL=session-end.js.map

package/dist/tools/session-end.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-end.js","sourceRoot":"","sources":["../../src/tools/session-end.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,EAAE,EAAO,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAG3D,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAC1C,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAElC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BjB,CAAC;AAER,SAAS,aAAa;IACpB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,uCAAuC,EAAE;YAC/D,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;YACpD,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IAEV,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IAEV,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,wDAAwD,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,eAAe,CAAC;IACjG,IAAI,uCAAuC,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzE,IAAI,wCAAwC,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3E,IAAI,4CAA4C,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,aAAa,CAAC;IACnF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,0BAA0B,CAAC,OAAe;IACjD,MAAM,QAAQ,GAAyD,EAAE,CAAC;IAE1E,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACnE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QAEpC,IAAI,kFAAkF,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnG,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACxD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAExD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;oBACtD,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;wBACrB,QAAQ,CAAC,IAAI,CAAC;4BACZ,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI;4BAC5D,IAAI,EAAE,IAAI;4BACV,IAAI,EAAE,SAAS;yBAChB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;gBACtC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,iBAAiB,CAAC;gBAC9E,QAAQ,CAAC,IAAI,CAAC;oBACZ,KAAK,EAAE,SAAS,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS;oBAC3E,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;oBACpB,IAAI,EAAE,SAAS;iBAChB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,2CAA2C,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACxD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAExD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;oBACtD,IAAI,IAAI,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;wBACrB,QAAQ,CAAC,IAAI,CAAC;4BACZ,KAAK,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI;4BAC5D,IAAI,EAAE,IAAI;4BACV,IAAI,EAAE,UAAU;yBACjB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC;AACpD,CAAC;AAED,KAAK,UAAU,kBAAkB,CAC/B,OAA2H,EAC3H,GAAa;IAEb,MAAM,KAAK,GAAuD,EAAE,CAAC;IACrE,MAAM,OAAO,GAA6C,EAAE,CAAC;IAE7D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,aAAa,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1E,IAAI,WAAW,GAAG,KAAK,CAAC;QAExB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;YACjD,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,QAAQ,GAAI,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,qCAAqC,CAAC,CAAC,GAAG,EAAU,EAAE,CAAC,IAAI,CAAC,CAAC;gBAC9F,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;oBACjB,MAAM,OAAO,GAAU,GAAG,CAAC,EAAE;yBAC1B,OAAO,CACN,+FAA+F,CAChG;yBACA,GAAG,CAAC,SAAS,EAAE,CAAC,CAAU,CAAC;oBAE9B,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;wBACzB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAI,EAAE,CAAC,QAAmB,GAAG,CAAC,CAAC,CAAC;wBAChE,IAAI,UAAU,IAAI,4BAA4B,EAAE,CAAC;4BAC/C,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE;iCACf,OAAO,CAAC,6CAA6C,CAAC;iCACtD,GAAG,CAAC,EAAE,CAAC,KAAK,CAAQ,CAAC;4BACxB,IAAI,GAAG,EAAE,CAAC;gCACR,WAAW,GAAG,IAAI,CAAC;gCACnB,OAAO,CAAC,IAAI,CAAC;oCACX,KAAK,EAAE,KAAK,CAAC,KAAK;oCAClB,MAAM,EAAE,eAAe,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;iCAClF,CAAC,CAAC;gCACH,MAAM;4BACR,CAAC;wBACH,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAA,CAAC;QAEV,IAAI,WAAW;YAAE,SAAS;QAE1B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,GAAG,EAAE;gBACxC,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,MAAM,EAAE,aAAa;aACtB,CAAC,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACtE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,OAAO,CAAC,IAAI,CAAC;gBACX,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,MAAM,EAAE,gBAAiB,CAAW,CAAC,OAAO,EAAE;aAC/C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG,aAAa,CAAC;AAElC,MAAM,CAAC,MAAM,WAAW,GACtB,yNAAyN,CAAC;AAE5N,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,uGAAuG,CACxG;IACH,WAAW,EAAE,CAAC;SACX,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;QACxE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QAChE,IAAI,EAAE,CAAC;aACJ,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;aACrD,QAAQ,EAAE;aACV,QAAQ,CAAC,+BAA+B,CAAC;KAC7C,CAAC,CACH;SACA,QAAQ,EAAE;SACV,QAAQ,CACP,8EAA8E,CAC/E;IACH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,iFAAiF,CAAC;CAC/F,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAuB,EACtD,GAAa,EACb,EAAE,aAAa,EAAa;IAE5B,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAEvB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,WAAW,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,CAAC,eAAe,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,aAAa,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAEzC,MAAM,gBAAgB,GAAG,OAAO,EAAE,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;IAC5D,MAAM,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,UAAU,gBAAgB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,MAAM,QAAQ,GAAG,CAAC,cAAc,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAErE,MAAM,aAAa,GAOd,EAAE,CAAC;IAER,IAAI,WAAW,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC;gBACjB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI;gBACJ,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC;gBACnB,IAAI,EAAE,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;gBACjD,IAAI,EAAE;oBACJ,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC;oBACzC,MAAM,EAAE,sBAAsB;iBAC/B;aACF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,SAAS,GAAG,0BAA0B,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,cAAc,GAAG,uBAAuB,GAAG,aAAa,CAAC,MAAM,CAAC;QACtE,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC;YACnD,aAAa,CAAC,IAAI,CAAC;gBACjB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC;gBACnB,IAAI,EAAE,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;gBACnD,IAAI,EAAE;oBACJ,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC;oBACzC,MAAM,EAAE,uBAAuB;iBAChC;aACF,CAAC,CAAC;QACL,CAAC;QAED,aAAa,CAAC,IAAI,CAAC;YACjB,KAAK,EAAE,YAAY,gBAAgB,IAAI,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;YAC3F,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,CAAC,GAAG,QAAQ,CAAC;YACnB,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE;gBACJ,MAAM,EAAE,aAAa;gBACrB,oBAAoB,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;gBAC9C,qBAAqB,EAAE,0BAA0B,CAAC,OAAO,CAAC,CAAC,MAAM;aAClE;SACF,CAAC,CAAC;IACL,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,CAAC,+FAA+F,CAAC,CAAC;IAC7G,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,kBAAkB,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAExE,MAAM,KAAK,GAAG,CAAC,0BAA0B,CAAC,CAAC;IAE3C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,cAAc,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC;QAC5C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QAC7D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,gBAAgB,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC;QAChD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,MAAM,GAAe,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAChD,MAAM,CAAC,KAAK,GAAG;QACb,OAAO,EAAE,gBAAgB;QACzB,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,aAAa,EAAE,OAAO,CAAC,MAAM;QAC7B,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChC,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/node_modules/@context-vault/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "type": "module",
   "description": "Pure local engine: capture, index, search, and utilities for context-vault",
   "main": "dist/main.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
@@ -63,7 +63,7 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^3.5.0",
+    "@context-vault/core": "^3.6.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "adm-zip": "^0.5.16",
     "sqlite-vec": "^0.1.0"

package/src/register-tools.ts

@@ -21,6 +21,7 @@ import * as createSnapshot from './tools/create-snapshot.js';
 import * as sessionStart from './tools/session-start.js';
 import * as listBuckets from './tools/list-buckets.js';
 import * as ingestProject from './tools/ingest-project.js';
+import * as sessionEnd from './tools/session-end.js';
 
 const toolModules = [
   getContext,
@@ -33,6 +34,7 @@ const toolModules = [
   clearContext,
   createSnapshot,
   sessionStart,
+  sessionEnd,
   listBuckets,
 ];
 

package/src/tools/context-status.ts

@@ -14,6 +14,47 @@ function relativeTime(ts: number): string {
   return `${hrs} hour${hrs === 1 ? '' : 's'} ago`;
 }
 
+interface LearningRate {
+  saved7d: number;
+  saved30d: number;
+  sessions30d: number;
+  savesPerSession: string;
+  recalls30d: number;
+  recallToSaveRatio: string;
+}
+
+function computeLearningRate(ctx: LocalCtx): LearningRate | null {
+  try {
+    const saved7d = (ctx.db.prepare(
+      `SELECT COUNT(*) as c FROM vault WHERE created_at >= datetime('now', '-7 days') AND kind NOT IN ('bucket', 'session', 'brief')`
+    ).get() as any)?.c ?? 0;
+
+    const saved30d = (ctx.db.prepare(
+      `SELECT COUNT(*) as c FROM vault WHERE created_at >= datetime('now', '-30 days') AND kind NOT IN ('bucket', 'session', 'brief')`
+    ).get() as any)?.c ?? 0;
+
+    const sessions30d = (ctx.db.prepare(
+      `SELECT COUNT(*) as c FROM vault WHERE created_at >= datetime('now', '-30 days') AND kind = 'session'`
+    ).get() as any)?.c ?? 0;
+
+    const savesPerSession = sessions30d > 0
+      ? (saved30d / sessions30d).toFixed(1)
+      : '0.0';
+
+    const recalls30d = (ctx.db.prepare(
+      `SELECT SUM(recall_count) as c FROM vault WHERE last_recalled_at >= datetime('now', '-30 days')`
+    ).get() as any)?.c ?? 0;
+
+    const recallToSaveRatio = saved30d > 0
+      ? `${(recalls30d / saved30d).toFixed(1)}:1`
+      : recalls30d > 0 ? `${recalls30d}:0 (all recall, no save)` : 'n/a';
+
+    return { saved7d, saved30d, sessions30d, savesPerSession, recalls30d, recallToSaveRatio };
+  } catch {
+    return null;
+  }
+}
+
 export const name = 'context_status';
 
 export const description =
@@ -114,6 +155,30 @@ export function handler(_args: Record<string, any>, ctx: LocalCtx): ToolResult {
       }
     }
 
+    const learningRate = computeLearningRate(ctx);
+    if (learningRate) {
+      lines.push(``, `### Learning Rate`);
+      lines.push(`| Metric | Value |`);
+      lines.push(`|---|---|`);
+      lines.push(`| **Saved (7 days)** | ${learningRate.saved7d} |`);
+      lines.push(`| **Saved (30 days)** | ${learningRate.saved30d} |`);
+      lines.push(`| **Sessions (30 days)** | ${learningRate.sessions30d} |`);
+      if (learningRate.sessions30d > 0) {
+        lines.push(`| **Saves per session** | ${learningRate.savesPerSession} |`);
+      }
+      if (learningRate.recalls30d > 0 || learningRate.saved30d > 0) {
+        lines.push(`| **Recalls (30 days)** | ${learningRate.recalls30d} |`);
+        lines.push(`| **Recall:save ratio** | ${learningRate.recallToSaveRatio} |`);
+      }
+      if (learningRate.saved30d === 0) {
+        lines.push('');
+        lines.push('_No entries saved in 30 days. Knowledge may be getting lost between sessions._');
+      } else if (learningRate.sessions30d > 0 && learningRate.savesPerSession === '0.0') {
+        lines.push('');
+        lines.push('_Very low save rate. Consider using `session_end` to capture learnings._');
+      }
+    }
+
     if (status.stalePaths) {
       lines.push(``);
       lines.push(`### ⚠ Stale Paths`);

package/src/tools/get-context.ts

@@ -243,6 +243,22 @@ function checkStaleness(entry: any): { stale: boolean; stale_reason: string } |
   return null;
 }
 
+const ERROR_TERMS = /\b(error|bug|fix|debug|failing|broken|crash|exception|issue|wrong|unexpected|stacktrace|traceback)\b/i;
+
+function generateSaveHint(query: string | undefined, resultCount: number): string | null {
+  if (!query) return null;
+
+  if (ERROR_TERMS.test(query)) {
+    return 'If you solve this, save the root cause and fix as an insight.';
+  }
+
+  if (resultCount === 0) {
+    return 'No existing entries for this topic. If you learn something useful, save it for future sessions.';
+  }
+
+  return null;
+}
+
 export const name = 'get_context';
 
 export const description =
@@ -743,6 +759,12 @@ export async function handler(
   if (consolidationSuggestions.length > 0) {
     meta.consolidation_suggestions = consolidationSuggestions;
   }
+
+  const saveHint = generateSaveHint(query, filtered.length);
+  if (saveHint) {
+    meta.save_hint = saveHint;
+  }
+
   result._meta = meta;
   return result;
 }

package/src/tools/save-context.ts

@@ -249,6 +249,27 @@ function validateSaveInput({
   return null;
 }
 
+function enrichDecisionMeta(
+  mergedMeta: Record<string, any>,
+  title: string | undefined,
+  body: string | undefined
+): void {
+  const combined = [title, body].filter(Boolean).join(' ').toLowerCase();
+
+  if (/\b(architect|infra|schema|database|api|stack|deploy|migration)\b/.test(combined)) {
+    mergedMeta.decision_type = 'architectural';
+  } else if (/\b(scope|feature|requirement|priority|roadmap|milestone)\b/.test(combined)) {
+    mergedMeta.decision_type = 'product';
+  } else if (/\b(convention|style|naming|lint|format|pattern)\b/.test(combined)) {
+    mergedMeta.decision_type = 'convention';
+  } else {
+    mergedMeta.decision_type = 'general';
+  }
+
+  mergedMeta.alternatives_noted = /\b(alternative|instead of|over|rather than|compared to|vs\.?|versus|option|considered)\b/i.test(combined);
+  mergedMeta.has_rationale = /\b(because|reason|rationale|why|trade.?off|benefit|downside|pro|con)\b/i.test(combined);
+}
+
 export const name = 'save_context';
 
 export const description =
@@ -587,6 +608,10 @@ export async function handler(
     mergedMeta.encoding_context = parsedCtx.text;
   }
 
+  if (normalizedKind === 'decision') {
+    enrichDecisionMeta(mergedMeta, title, body);
+  }
+
   const finalMeta = Object.keys(mergedMeta).length ? mergedMeta : undefined;
 
   const effectiveTier = tier ?? defaultTierFor(normalizedKind);