context-vault 2.13.0 → 2.14.0

package/assets/skills/compile-context/skill.md

@@ -0,0 +1,45 @@
+---
+name: compile-context
+description: >
+  Compiles scattered vault entries on a topic into a single authoritative brief
+  for isolated retrieval in a fresh context window. Use when starting a new work
+  session on a project, preparing a handoff, or loading focused context without
+  noise. Also audits for stale or contradicting entries.
+  Triggers: "compile context", "create a brief", "context snapshot", "context bucket",
+  "make a brief for X", "load context for X".
+---
+
+# compile-context skill
+
+When the user asks to compile context or create a brief for a topic, call `create_snapshot` to synthesize a context brief from the vault.
+
+## Step 1 — Identify the topic
+
+If the user provided a topic or project name, use it. If not, ask:
+
+> "What topic or project should I compile context for?"
+
+Derive a slug: lowercase, hyphens, no spaces (e.g. `neonode`, `context-vault`, `klarhimmel-infra`).
+
+## Step 2 — Call create_snapshot
+
+Call `create_snapshot` with:
+
+- `topic`: the topic name the user provided
+- `identity_key`: `snapshot-<slug>` (e.g. `snapshot-context-vault`)
+- `tags` (optional): any relevant tags the user mentions
+- `kinds` (optional): restrict to specific entry kinds if the user requests it
+
+The tool handles retrieval, deduplication, LLM synthesis, and saving automatically.
+
+## Step 3 — Report
+
+After the tool returns, tell the user:
+
+- The ULID of the saved brief
+- How many entries were synthesized
+- The exact call to retrieve it in a future session:
+  ```
+  get_context(identity_key: "snapshot-<slug>")
+  ```
+- Suggest pinning the identity key in the relevant CLAUDE.md or MEMORY.md for zero-cost retrieval in fresh windows.

package/bin/cli.js

@@ -235,7 +235,9 @@ ${bold("Commands:")}
   ${cyan("connect")} --key cv_...  Connect AI tools to hosted vault
   ${cyan("switch")} local|hosted      Switch between local and hosted MCP modes
   ${cyan("serve")}                 Start the MCP server (used by AI clients)
-  ${cyan("hooks")} install|remove  Install or remove Claude Code memory hook
+  ${cyan("hooks")} install|uninstall  Install or remove Claude Code memory hook
+  ${cyan("claude")} install|uninstall  Alias for hooks install|uninstall
+  ${cyan("skills")} install          Install bundled Claude Code skills
   ${cyan("flush")}                 Check vault health and confirm DB is accessible
   ${cyan("recall")}                Search vault from a Claude Code hook (reads stdin)
   ${cyan("reindex")}               Rebuild search index from knowledge files
@@ -731,6 +733,37 @@ async function runSetup() {
     }
   }
 
+  // Claude Code skills (opt-in)
+  if (claudeConfigured && !isNonInteractive) {
+    console.log();
+    console.log(dim("  Install Claude Code skills? (recommended)"));
+    console.log(
+      dim("  compile-context — compile vault entries into a project brief"),
+    );
+    console.log();
+    const skillAnswer = await prompt(
+      "  Install Claude Code skills? (Y/n):",
+      "Y",
+    );
+    const installSkillsFlag = skillAnswer.toLowerCase() !== "n";
+    if (installSkillsFlag) {
+      try {
+        const names = installSkills();
+        if (names.length > 0) {
+          for (const name of names) {
+            console.log(`\n  ${green("+")} ${name} skill installed`);
+          }
+        }
+      } catch (e) {
+        console.log(`\n  ${red("x")} Skills install failed: ${e.message}`);
+      }
+    } else {
+      console.log(
+        dim(`  Skipped — install later: context-vault skills install`),
+      );
+    }
+  }
+
   // Seed entry
   const seeded = createSeedEntries(resolvedVaultDir);
   if (seeded > 0) {
@@ -2126,16 +2159,25 @@ async function runRecall() {
     const results = await hybridSearch(ctx, query, { limit: 5 });
     if (!results.length) return;
 
-    const lines = ["## Context Vault\n"];
+    const MAX_TOTAL = 2000;
+    const ENTRY_BODY_LIMIT = 400;
+    const entries = [];
+    let totalChars = 0;
+
     for (const r of results) {
       const entryTags = r.tags ? JSON.parse(r.tags) : [];
-      lines.push(`### ${r.title || "(untitled)"} [${r.kind}]`);
-      if (entryTags.length) lines.push(`tags: ${entryTags.join(", ")}`);
-      lines.push(r.body?.slice(0, 400) + (r.body?.length > 400 ? "..." : ""));
-      lines.push("");
+      const tagsAttr = entryTags.length ? ` tags="${entryTags.join(",")}"` : "";
+      const body = r.body?.slice(0, ENTRY_BODY_LIMIT) ?? "";
+      const entry = `<entry kind="${r.kind || "knowledge"}"${tagsAttr}>\n${body}\n</entry>`;
+      if (totalChars + entry.length > MAX_TOTAL) break;
+      entries.push(entry);
+      totalChars += entry.length;
     }
 
-    process.stdout.write(lines.join("\n"));
+    if (!entries.length) return;
+
+    const block = `<context-vault>\n${entries.join("\n")}\n</context-vault>\n`;
+    process.stdout.write(block);
   } catch {
     // fail silently — never interrupt the user's workflow
   } finally {
@@ -2176,6 +2218,38 @@ async function runFlush() {
   }
 }
 
+/**
+ * Copies all skills from the bundled assets/skills/ directory into ~/.claude/skills/.
+ * Returns an array of installed skill names.
+ */
+function installSkills() {
+  const assetsSkillsDir = join(ROOT, "assets", "skills");
+  const targetDir = join(HOME, ".claude", "skills");
+
+  if (!existsSync(assetsSkillsDir)) return [];
+
+  const skillNames = readdirSync(assetsSkillsDir).filter((name) => {
+    try {
+      return statSync(join(assetsSkillsDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  const installed = [];
+  for (const skillName of skillNames) {
+    const srcDir = join(assetsSkillsDir, skillName);
+    const destDir = join(targetDir, skillName);
+    mkdirSync(destDir, { recursive: true });
+    const files = readdirSync(srcDir);
+    for (const file of files) {
+      copyFileSync(join(srcDir, file), join(destDir, file));
+    }
+    installed.push(skillName);
+  }
+  return installed;
+}
+
 /** Returns the path to Claude Code's global settings.json */
 function claudeSettingsPath() {
   return join(HOME, ".claude", "settings.json");
@@ -2321,110 +2395,175 @@ function removeClaudeHook() {
   return true;
 }
 
-async function runHooks() {
+async function runSkills() {
   const sub = args[1];
 
   if (sub === "install") {
+    console.log();
     try {
-      const installed = installClaudeHook();
-      if (installed) {
-        console.log(`\n  ${green("✓")} Claude Code memory hook installed.\n`);
-        console.log(
-          dim(
-            "  On every prompt, context-vault searches your vault for relevant entries",
-          ),
-        );
-        console.log(
-          dim(
-            "  and injects them as additional context alongside Claude's native memory.",
-          ),
-        );
-        console.log(
-          dim(`\n  To remove: ${cyan("context-vault hooks remove")}`),
-        );
+      const names = installSkills();
+      if (names.length === 0) {
+        console.log(`  ${yellow("!")} No bundled skills found.\n`);
       } else {
-        console.log(`\n  ${yellow("!")} Hook already installed.\n`);
-      }
-    } catch (e) {
-      console.error(`\n  ${red("x")} Failed to install hook: ${e.message}\n`);
-      process.exit(1);
-    }
-    console.log();
-
-    // Prompt for optional session auto-flush (SessionEnd) hook
-    const installFlush =
-      flags.has("--flush") ||
-      (await prompt(
-        "  Install session auto-flush hook? (runs context-vault flush at session end) (y/N):",
-        "n",
-      ));
-    const shouldInstallFlush =
-      installFlush === true ||
-      (typeof installFlush === "string" &&
-        installFlush.toLowerCase().startsWith("y"));
-
-    if (shouldInstallFlush) {
-      try {
-        const flushInstalled = installSessionEndHook();
-        if (flushInstalled) {
-          console.log(
-            `\n  ${green("✓")} Session auto-flush hook installed (SessionEnd).\n`,
-          );
+        for (const name of names) {
           console.log(
-            dim(
-              "  At the end of each session, context-vault flush confirms the vault is healthy.",
-            ),
-          );
-        } else {
-          console.log(
-            `\n  ${yellow("!")} Session auto-flush hook already installed.\n`,
+            `  ${green("+")} ${name} — installed to ~/.claude/skills/${name}/`,
           );
         }
-      } catch (e) {
-        console.error(
-          `\n  ${red("x")} Failed to install session flush hook: ${e.message}\n`,
-        );
-        process.exit(1);
-      }
-      console.log();
-    }
-  } else if (sub === "remove") {
-    try {
-      const removed = removeClaudeHook();
-      if (removed) {
-        console.log(`\n  ${green("✓")} Claude Code memory hook removed.\n`);
-      } else {
-        console.log(`\n  ${yellow("!")} Hook not found — nothing to remove.\n`);
+        console.log();
+        console.log(dim("  Skills are active immediately in Claude Code."));
+        console.log(dim(`  Trigger with: /${names.join(", /")}`));
       }
     } catch (e) {
-      console.error(`\n  ${red("x")} Failed to remove hook: ${e.message}\n`);
+      console.error(`  ${red("x")} Skills install failed: ${e.message}\n`);
       process.exit(1);
     }
+    console.log();
+  } else {
+    console.log(`
+  ${bold("context-vault skills")} <install>
+
+  Manage bundled Claude Code skills.
+
+${bold("Commands:")}
+  ${cyan("skills install")}   Copy bundled skills into ~/.claude/skills/
+
+${bold("Bundled skills:")}
+  ${cyan("compile-context")}  Compile vault entries into a project brief using create_snapshot
+`);
+  }
+}
+
+async function runHooksInstall() {
+  try {
+    const installed = installClaudeHook();
+    if (installed) {
+      console.log(
+        `\n  ${green("✓")} Hook installed. Context vault will inject relevant entries on every prompt.\n`,
+      );
+      console.log(
+        dim(
+          "  On every prompt, context-vault searches your vault for relevant entries",
+        ),
+      );
+      console.log(
+        dim(
+          "  and injects them as a <context-vault> block before Claude sees your message.",
+        ),
+      );
+      console.log(
+        dim(`\n  To remove: ${cyan("context-vault hooks uninstall")}`),
+      );
+    } else {
+      console.log(`\n  ${yellow("!")} Hook already installed.\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ${red("x")} Failed to install hook: ${e.message}\n`);
+    process.exit(1);
+  }
+  console.log();
 
+  const installFlush =
+    flags.has("--flush") ||
+    (await prompt(
+      "  Install SessionEnd flush hook? (saves vault health summary at session end) (y/N):",
+      "n",
+    ));
+  const shouldInstallFlush =
+    installFlush === true ||
+    (typeof installFlush === "string" &&
+      installFlush.toLowerCase().startsWith("y"));
+
+  if (shouldInstallFlush) {
     try {
-      const flushRemoved = removeSessionEndHook();
-      if (flushRemoved) {
+      const flushInstalled = installSessionEndHook();
+      if (flushInstalled) {
+        console.log(`\n  ${green("✓")} SessionEnd flush hook installed.\n`);
         console.log(
-          `\n  ${green("✓")} Session auto-flush hook removed (SessionEnd).\n`,
+          dim(
+            "  At the end of each session, context-vault flush confirms the vault is healthy.",
+          ),
+        );
+      } else {
+        console.log(
+          `\n  ${yellow("!")} SessionEnd flush hook already installed.\n`,
         );
       }
     } catch (e) {
       console.error(
-        `\n  ${red("x")} Failed to remove session flush hook: ${e.message}\n`,
+        `\n  ${red("x")} Failed to install session flush hook: ${e.message}\n`,
       );
+      process.exit(1);
     }
+    console.log();
+  }
+}
+
+async function runHooksUninstall() {
+  try {
+    const removed = removeClaudeHook();
+    if (removed) {
+      console.log(`\n  ${green("✓")} Claude Code memory hook removed.\n`);
+    } else {
+      console.log(`\n  ${yellow("!")} Hook not found — nothing to remove.\n`);
+    }
+  } catch (e) {
+    console.error(`\n  ${red("x")} Failed to remove hook: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  try {
+    const flushRemoved = removeSessionEndHook();
+    if (flushRemoved) {
+      console.log(`\n  ${green("✓")} SessionEnd flush hook removed.\n`);
+    }
+  } catch (e) {
+    console.error(
+      `\n  ${red("x")} Failed to remove session flush hook: ${e.message}\n`,
+    );
+  }
+}
+
+async function runHooks() {
+  const sub = args[1];
+
+  if (sub === "install") {
+    await runHooksInstall();
+  } else if (sub === "remove" || sub === "uninstall") {
+    await runHooksUninstall();
   } else {
     console.log(`
-  ${bold("context-vault hooks")} <install|remove>
+  ${bold("context-vault hooks")} <install|uninstall>
 
   Manage the Claude Code memory hook integration.
   When installed, context-vault automatically searches your vault on every user
-  prompt and injects relevant entries as additional context.
+  prompt and injects relevant entries as a <context-vault> XML block.
 
 ${bold("Commands:")}
-  ${cyan("hooks install")}   Write UserPromptSubmit hook to ~/.claude/settings.json
-                  Also prompts to install a SessionEnd auto-flush hook
-  ${cyan("hooks remove")}    Remove the recall hook and SessionEnd flush hook
+  ${cyan("hooks install")}     Write UserPromptSubmit hook to ~/.claude/settings.json
+                    Also prompts to install a SessionEnd flush hook
+  ${cyan("hooks uninstall")}   Remove the recall hook and SessionEnd flush hook
+`);
+  }
+}
+
+async function runClaude() {
+  const sub = args[1];
+
+  if (sub === "install") {
+    await runHooksInstall();
+  } else if (sub === "uninstall" || sub === "remove") {
+    await runHooksUninstall();
+  } else {
+    console.log(`
+  ${bold("context-vault claude")} <install|uninstall>
+
+  Manage the Claude Code memory hook integration.
+  Alias for ${cyan("context-vault hooks install|uninstall")}.
+
+${bold("Commands:")}
+  ${cyan("claude install")}     Write UserPromptSubmit hook to ~/.claude/settings.json
+  ${cyan("claude uninstall")}   Remove the recall hook and SessionEnd flush hook
 `);
   }
 }
@@ -2652,6 +2791,12 @@ async function main() {
     case "hooks":
       await runHooks();
       break;
+    case "claude":
+      await runClaude();
+      break;
+    case "skills":
+      await runSkills();
+      break;
     case "flush":
       await runFlush();
       break;

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

@@ -1,6 +1,6 @@
 {
   "name": "@context-vault/core",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "type": "module",
   "description": "Shared core: capture, index, retrieve, tools, and utilities for context-vault",
   "main": "src/index.js",

package/node_modules/@context-vault/core/src/server/tools/create-snapshot.js

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import { hybridSearch } from "../../retrieve/index.js";
+import { captureAndIndex } from "../../capture/index.js";
+import { normalizeKind } from "../../core/files.js";
+import { ok, err, ensureVaultExists } from "../helpers.js";
+
+const NOISE_KINDS = new Set(["prompt-history", "task-notification"]);
+const SYNTHESIS_MODEL = "claude-haiku-4-5-20251001";
+const MAX_ENTRIES_FOR_SYNTHESIS = 40;
+const MAX_BODY_PER_ENTRY = 600;
+
+export const name = "create_snapshot";
+
+export const description =
+  "Pull all relevant vault entries matching a topic, run an LLM synthesis pass to deduplicate and structure them into a context brief, then save and return the brief's ULID. The brief is saved as kind: 'brief' with a deterministic identity_key for retrieval.";
+
+export const inputSchema = {
+  topic: z.string().describe("The topic or project name to snapshot"),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe("Optional tag filters — entries must match at least one"),
+  kinds: z
+    .array(z.string())
+    .optional()
+    .describe("Optional kind filters to restrict which entry types are pulled"),
+  identity_key: z
+    .string()
+    .optional()
+    .describe(
+      "Deterministic key for the saved brief (defaults to slugified topic). Use the same key to overwrite a previous snapshot.",
+    ),
+};
+
+function buildSynthesisPrompt(topic, entries) {
+  const entriesBlock = entries
+    .map((e, i) => {
+      const tags = e.tags ? JSON.parse(e.tags) : [];
+      const tagStr = tags.length ? tags.join(", ") : "none";
+      const body = e.body
+        ? e.body.slice(0, MAX_BODY_PER_ENTRY) +
+          (e.body.length > MAX_BODY_PER_ENTRY ? "…" : "")
+        : "(no body)";
+      return [
+        `### Entry ${i + 1} [${e.kind}] id: ${e.id}`,
+        `tags: ${tagStr}`,
+        `updated: ${e.updated_at || e.created_at || "unknown"}`,
+        body,
+      ].join("\n");
+    })
+    .join("\n\n");
+
+  return `You are a knowledge synthesis assistant. Given the following vault entries about "${topic}", produce a structured context brief.
+
+Deduplicate overlapping information, resolve any contradictions (note them in Audit Notes), and organise the content into the sections below. Keep each section concise and actionable. Omit sections that have no relevant content.
+
+Output ONLY the markdown document — no preamble, no explanation.
+
+Required format:
+# ${topic} — Context Brief
+## Status
+(current state of the topic)
+## Key Decisions
+(architectural or strategic decisions made)
+## Patterns & Conventions
+(recurring patterns, coding conventions, standards)
+## Active Constraints
+(known limitations, hard requirements, deadlines)
+## Open Questions
+(unresolved questions or areas needing investigation)
+## Audit Notes
+(contradictions detected, stale entries flagged with their ids)
+
+---
+VAULT ENTRIES:
+
+${entriesBlock}`;
+}
+
+async function callLlm(prompt) {
+  const { Anthropic } = await import("@anthropic-ai/sdk");
+  const client = new Anthropic();
+  const message = await client.messages.create({
+    model: SYNTHESIS_MODEL,
+    max_tokens: 2048,
+    messages: [{ role: "user", content: prompt }],
+  });
+  const block = message.content.find((b) => b.type === "text");
+  if (!block) throw new Error("LLM returned no text content");
+  return block.text;
+}
+
+function slugifyTopic(topic) {
+  return topic
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 120);
+}
+
+export async function handler(
+  { topic, tags, kinds, identity_key },
+  ctx,
+  { ensureIndexed },
+) {
+  const { config } = ctx;
+  const userId = ctx.userId !== undefined ? ctx.userId : undefined;
+
+  const vaultErr = ensureVaultExists(config);
+  if (vaultErr) return vaultErr;
+
+  if (!topic?.trim()) {
+    return err("Required: topic (non-empty string)", "INVALID_INPUT");
+  }
+
+  await ensureIndexed();
+
+  const normalizedKinds = kinds?.map(normalizeKind) ?? [];
+
+  let candidates = [];
+
+  if (normalizedKinds.length > 0) {
+    for (const kindFilter of normalizedKinds) {
+      const rows = await hybridSearch(ctx, topic, {
+        kindFilter,
+        limit: Math.ceil(MAX_ENTRIES_FOR_SYNTHESIS / normalizedKinds.length),
+        userIdFilter: userId,
+        includeSuperseeded: false,
+      });
+      candidates.push(...rows);
+    }
+    const seen = new Set();
+    candidates = candidates.filter((r) => {
+      if (seen.has(r.id)) return false;
+      seen.add(r.id);
+      return true;
+    });
+  } else {
+    candidates = await hybridSearch(ctx, topic, {
+      limit: MAX_ENTRIES_FOR_SYNTHESIS,
+      userIdFilter: userId,
+      includeSuperseeded: false,
+    });
+  }
+
+  if (tags?.length) {
+    candidates = candidates.filter((r) => {
+      const entryTags = r.tags ? JSON.parse(r.tags) : [];
+      return tags.some((t) => entryTags.includes(t));
+    });
+  }
+
+  const noiseIds = candidates
+    .filter((r) => NOISE_KINDS.has(r.kind))
+    .map((r) => r.id);
+
+  const synthesisEntries = candidates.filter((r) => !NOISE_KINDS.has(r.kind));
+
+  if (synthesisEntries.length === 0) {
+    return err(
+      `No entries found for topic "${topic}" to synthesize. Try a broader topic or different tags.`,
+      "NO_ENTRIES",
+    );
+  }
+
+  let briefBody;
+  try {
+    const prompt = buildSynthesisPrompt(topic, synthesisEntries);
+    briefBody = await callLlm(prompt);
+  } catch (e) {
+    return err(
+      `LLM synthesis failed: ${e.message}. Ensure ANTHROPIC_API_KEY is set.`,
+      "LLM_ERROR",
+    );
+  }
+
+  const effectiveIdentityKey =
+    identity_key ?? `snapshot-${slugifyTopic(topic)}`;
+
+  const briefTags = [
+    "snapshot",
+    ...(tags ?? []),
+    ...(normalizedKinds.length > 0 ? [] : []),
+  ];
+
+  const supersedes = noiseIds.length > 0 ? noiseIds : undefined;
+
+  const entry = await captureAndIndex(ctx, {
+    kind: "brief",
+    title: `${topic} — Context Brief`,
+    body: briefBody,
+    tags: briefTags,
+    source: "create_snapshot",
+    identity_key: effectiveIdentityKey,
+    supersedes,
+    userId,
+    meta: {
+      topic,
+      entry_count: synthesisEntries.length,
+      noise_superseded: noiseIds.length,
+      synthesized_from: synthesisEntries.map((e) => e.id),
+    },
+  });
+
+  const parts = [
+    `✓ Snapshot created → id: ${entry.id}`,
+    `  title: ${entry.title}`,
+    `  identity_key: ${effectiveIdentityKey}`,
+    `  synthesized from: ${synthesisEntries.length} entries`,
+    noiseIds.length > 0
+      ? `  noise superseded: ${noiseIds.length} entries`
+      : null,
+    "",
+    "_Retrieve with: get_context(kind: 'brief', identity_key: '" +
+      effectiveIdentityKey +
+      "')_",
+  ]
+    .filter((l) => l !== null)
+    .join("\n");
+
+  return ok(parts);
+}

package/node_modules/@context-vault/core/src/server/tools.js

@@ -12,6 +12,7 @@ import * as submitFeedback from "./tools/submit-feedback.js";
 import * as ingestUrl from "./tools/ingest-url.js";
 import * as contextStatus from "./tools/context-status.js";
 import * as clearContext from "./tools/clear-context.js";
+import * as createSnapshot from "./tools/create-snapshot.js";
 
 const toolModules = [
   getContext,
@@ -22,6 +23,7 @@ const toolModules = [
   ingestUrl,
   contextStatus,
   clearContext,
+  createSnapshot,
 ];
 
 const TOOL_TIMEOUT_MS = 60_000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-vault",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "type": "module",
   "description": "Persistent memory for AI agents — saves and searches knowledge across sessions",
   "bin": {
@@ -17,6 +17,7 @@
     "prepack": "node scripts/prepack.js"
   },
   "files": [
+    "assets/",
     "bin/",
     "src/",
     "scripts/",
@@ -55,7 +56,7 @@
     "@context-vault/core"
   ],
   "dependencies": {
-    "@context-vault/core": "^2.13.0",
+    "@context-vault/core": "^2.14.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "sqlite-vec": "^0.1.0"
   }