context-vault 3.18.0 → 3.20.0

package/src/server.ts

@@ -11,6 +11,50 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 
+// Module-level shutdown coordination so pipe/uncaught handlers (below main())
+// can route through the graceful shutdown wired up inside main().
+let shutdownHandler: ((signal: string) => void) | null = null;
+let shutdownInProgress = false;
+
+function isPipeError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const e = err as { code?: string; message?: string };
+  if (e.code === 'EPIPE' || e.code === 'ERR_STREAM_DESTROYED' || e.code === 'ERR_STREAM_WRITE_AFTER_END') return true;
+  return typeof e.message === 'string' && /\bEPIPE\b/.test(e.message);
+}
+
+function handlePipeDisconnect(source: string): void {
+  if (shutdownInProgress) return;
+  if (shutdownHandler) {
+    try {
+      shutdownHandler(`EPIPE:${source}`);
+    } catch {
+      process.exit(0);
+    }
+  } else {
+    // Shutdown not wired yet (startup phase). Exit clean so WAL isn't dirtied.
+    process.exit(0);
+  }
+}
+
+// Catch broken-pipe writes to stdout/stderr so they route through graceful
+// shutdown instead of bubbling up as an `uncaughtException` that skips the
+// WAL checkpoint. Node raises EPIPE (not SIGPIPE) on pipe writes with no reader.
+process.stdout.on('error', (err) => {
+  if (isPipeError(err)) {
+    handlePipeDisconnect('stdout');
+  } else {
+    throw err;
+  }
+});
+process.stderr.on('error', (err) => {
+  if (isPipeError(err)) {
+    handlePipeDisconnect('stderr');
+  } else {
+    throw err;
+  }
+});
+
 import { resolveConfig } from '@context-vault/core/config';
 import type { LocalCtx } from './types.js';
 import { appendErrorLog } from './error-log.js';
@@ -206,7 +250,28 @@ async function main(): Promise<void> {
     }
 
     function shutdown(signal: string): void {
-      console.error(`[context-vault] Received ${signal}, shutting down...`);
+      // Idempotent: EPIPE from stdout error + uncaughtException can both fire
+      // during a single client disconnect. Second call becomes a no-op.
+      if (shutdownInProgress) return;
+      shutdownInProgress = true;
+
+      const isEpipe = signal.startsWith('EPIPE');
+      if (isEpipe) {
+        // Log a clean shutdown entry in place of the EPIPE uncaughtException
+        // that would otherwise have fired. Keeps the audit log readable.
+        appendErrorLog(config!.dataDir, {
+          timestamp: new Date().toISOString(),
+          error_type: 'EPIPE_shutdown',
+          message: `client pipe closed (${signal}); graceful shutdown`,
+          node_version: process.version,
+          platform: process.platform,
+          arch: process.arch,
+          cv_version: pkg.version,
+        });
+        console.error(`[context-vault] EPIPE shutdown: client disconnected (${signal})`);
+      } else {
+        console.error(`[context-vault] Received ${signal}, shutting down...`);
+      }
 
       if (ctx.activeOps.count > 0) {
         console.error(
@@ -232,6 +297,9 @@ async function main(): Promise<void> {
     process.on('SIGINT', () => shutdown('SIGINT'));
     process.on('SIGTERM', () => shutdown('SIGTERM'));
 
+    // Expose shutdown to module-level handlers (stdout error, uncaughtException).
+    shutdownHandler = shutdown;
+
     // RSS watchdog: kill the process if memory usage exceeds the cap.
     // Prevents runaway embedding/reindex operations from frying user systems.
     const MAX_RSS_BYTES = parseInt(process.env.CONTEXT_VAULT_MAX_RSS_MB || '1024', 10) * 1024 * 1024;
@@ -310,6 +378,13 @@ async function main(): Promise<void> {
 }
 
 process.on('uncaughtException', (err) => {
+  // EPIPE from a dead client pipe is not a crash; it's a disconnect.
+  // Route through graceful shutdown so the WAL is checkpointed.
+  if (isPipeError(err)) {
+    handlePipeDisconnect('uncaught');
+    return;
+  }
+
   const dataDir = join(homedir(), '.context-mcp');
   const logEntry = {
     timestamp: new Date().toISOString(),

package/src/tools/recall.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { ok } from '../helpers.js';
-import { isEmbedAvailable } from '@context-vault/core/embed';
+import { hybridSearch } from '@context-vault/core/search';
 import { getAutoMemory, findAutoMemoryOverlaps } from '../auto-memory.js';
 import { getRemoteClient, getTeamId, getPublicVaults } from '../remote.js';
 import type { LocalCtx, SharedCtx, ToolResult } from '../types.js';
+import type { SearchOptions } from '@context-vault/core/types';
 
-const SEMANTIC_SIMILARITY_THRESHOLD = 0.6;
 const CO_RETRIEVAL_WEIGHT_CAP = 50;
 
 const STOPWORDS = new Set([
@@ -31,14 +31,14 @@ const sessionSurfaced = new Map<string, Set<string>>();
 
 /**
  * Extract keywords from a signal string.
- * Split on whitespace, filter stopwords and words under 4 chars, keep top 10.
+ * Split on whitespace, filter stopwords and words under 2 chars, keep top 10.
  */
 export function extractKeywords(signal: string): string[] {
   const words = signal
     .toLowerCase()
     .replace(/[^a-z0-9\s_-]/g, ' ')
     .split(/\s+/)
-    .filter((w) => w.length >= 4 && !STOPWORDS.has(w));
+    .filter((w) => w.length >= 2 && !STOPWORDS.has(w));
 
   const seen = new Set<string>();
   const unique: string[] = [];
@@ -100,30 +100,48 @@ export async function handler(
     return result;
   }
 
-  // Build fast-path query: tag/title LIKE match for each keyword
-  const conditions: string[] = [];
-  const params: string[] = [];
-  for (const kw of keywords) {
-    conditions.push('(title LIKE ? OR tags LIKE ?)');
-    params.push(`%${kw}%`, `%${kw}%`);
-  }
-
-  const bucketClause = bucket ? ' AND tags LIKE ?' : '';
-  if (bucket) params.push(`%"bucket:${bucket}"%`);
+  // Build search query from signal, enriched by signal_type
+  let searchQuery = signal || '';
+  const searchOpts: SearchOptions = {
+    excludeEvents: true,
+    limit: limit * 3, // over-fetch to allow for session dedup + bucket filtering
+  };
 
-  const sql = `SELECT id, title, substr(body, 1, 100) as summary, kind, tags
-    FROM vault
-    WHERE indexed = 1
-      AND (expires_at IS NULL OR expires_at > datetime('now'))
-      AND superseded_by IS NULL
-      AND (${conditions.join(' OR ')})${bucketClause}
-    LIMIT 20`;
+  // Signal-type aware search options
+  switch (signal_type) {
+    case 'error':
+      // Errors should boost recent entries
+      searchOpts.decayDays = 7;
+      break;
+    case 'file':
+      // Extract path components and extension as additional search terms
+      searchQuery = signal
+        .replace(/[/\\]/g, ' ')
+        .replace(/\./g, ' ')
+        .trim();
+      break;
+    case 'task':
+      // Tasks benefit from wider search
+      searchOpts.limit = Math.max(searchOpts.limit!, limit * 5);
+      break;
+    // 'prompt': standard hybrid search, no modifications
+  }
 
-  let rows: any[];
-  try {
-    rows = ctx.db.prepare(sql).all(...params);
-  } catch {
-    rows = [];
+  // Run hybrid search (FTS + vector + tag lanes with RRF fusion)
+  let searchResults = await hybridSearch(ctx, searchQuery, searchOpts);
+
+  // Bucket-aware post-filtering
+  if (bucket) {
+    const bucketTag = `bucket:${bucket}`;
+    searchResults = searchResults.filter((r) => {
+      if (!r.tags) return false;
+      try {
+        const tags: string[] = typeof r.tags === 'string' ? JSON.parse(r.tags) : r.tags;
+        return tags.some((t) => t === bucketTag);
+      } catch {
+        return String(r.tags).includes(bucketTag);
+      }
+    });
   }
 
   // Session dedup
@@ -142,7 +160,7 @@ export async function handler(
     tags: string[];
   }> = [];
 
-  for (const row of rows) {
+  for (const row of searchResults) {
     if (hints.length >= limit) break;
 
     // Dedup check
@@ -151,21 +169,16 @@ export async function handler(
       continue;
     }
 
-    const entryTags: string[] = row.tags ? JSON.parse(row.tags) : [];
+    const entryTags: string[] = row.tags
+      ? (typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags)
+      : [];
 
-    // Score relevance: count how many keywords match title or tags
-    let matchCount = 0;
-    const titleLower = (row.title || '').toLowerCase();
-    const tagsLower = (row.tags || '').toLowerCase();
-    for (const kw of keywords) {
-      if (titleLower.includes(kw) || tagsLower.includes(kw)) matchCount++;
-    }
-    const relevance: 'high' | 'medium' = matchCount >= 2 ? 'high' : 'medium';
+    const relevance: 'high' | 'medium' = row.score >= 0.02 ? 'high' : 'medium';
 
     hints.push({
       id: row.id,
       title: row.title || '(untitled)',
-      summary: row.summary || '',
+      summary: row.body ? row.body.slice(0, 100) : '',
       relevance,
       kind: row.kind || 'knowledge',
       tags: entryTags,
@@ -261,79 +274,7 @@ export async function handler(
     }
   }
 
-  let method: 'tag_match' | 'semantic' | 'none' = hints.length > 0 ? 'tag_match' : 'none';
-
-  // Semantic fallback: when fast-path returns 0 results and signal is not file-based
-  if (hints.length === 0 && signal_type !== 'file' && isEmbedAvailable()) {
-    try {
-      const vecCount = (
-        ctx.db.prepare('SELECT COUNT(*) as c FROM vault_vec').get() as { c: number }
-      ).c;
-
-      if (vecCount > 0) {
-        const queryVec = await ctx.embed(signal);
-        if (queryVec) {
-          const vecRows = ctx.db
-            .prepare(
-              'SELECT v.rowid, v.distance FROM vault_vec v WHERE embedding MATCH ? ORDER BY distance LIMIT 5'
-            )
-            .all(queryVec) as { rowid: number; distance: number }[];
-
-          if (vecRows.length) {
-            const rowids = vecRows.map((vr) => vr.rowid);
-            const placeholders = rowids.map(() => '?').join(',');
-
-            let bucketFilter = '';
-            const hydrateParams: any[] = [...rowids];
-            if (bucket) {
-              bucketFilter = ' AND tags LIKE ?';
-              hydrateParams.push(`%"bucket:${bucket}"%`);
-            }
-
-            const hydrated = ctx.db
-              .prepare(
-                `SELECT rowid, id, title, substr(body, 1, 100) as summary, kind, tags FROM vault WHERE rowid IN (${placeholders}) AND indexed = 1 AND (expires_at IS NULL OR expires_at > datetime('now')) AND superseded_by IS NULL${bucketFilter}`
-              )
-              .all(...hydrateParams) as any[];
-
-            const byRowid = new Map<number, any>();
-            for (const row of hydrated) byRowid.set(row.rowid, row);
-
-            for (const vr of vecRows) {
-              if (hints.length >= limit) break;
-              const row = byRowid.get(vr.rowid);
-              if (!row) continue;
-
-              const similarity = Math.max(0, 1 - vr.distance / 2);
-              if (similarity < SEMANTIC_SIMILARITY_THRESHOLD) continue;
-
-              // Session dedup
-              if (sessionSet && !bypassDedup && sessionSet.has(row.id)) {
-                suppressed++;
-                continue;
-              }
-
-              const entryTags: string[] = row.tags ? JSON.parse(row.tags) : [];
-              hints.push({
-                id: row.id,
-                title: row.title || '(untitled)',
-                summary: row.summary || '',
-                relevance: similarity >= 0.8 ? 'high' : 'medium',
-                kind: row.kind || 'knowledge',
-                tags: entryTags,
-              });
-
-              if (sessionSet) sessionSet.add(row.id);
-            }
-
-            if (hints.length > 0) method = 'semantic';
-          }
-        }
-      }
-    } catch {
-      // Semantic fallback is best-effort; fast path already ran
-    }
-  }
+  const method: 'hybrid' | 'none' = hints.length > 0 ? 'hybrid' : 'none';
 
   const latency = Date.now() - start;
 

package/.claude-plugin/README.md

@@ -1,219 +0,0 @@
-# context-vault Claude Plugin
-
-Persistent memory and knowledge management for AI agents. Save decisions, insights, patterns, and context across sessions using semantic search and project-scoped buckets.
-
-## What is context-vault?
-
-context-vault is a local-first memory system that lets Claude persistently store and retrieve knowledge. Think of it as a personal knowledge base that follows you across sessions, projects, and contexts.
-
-### Key Features
-
-- **Persistent Memory** -- Save insights, decisions, patterns, and references across sessions
-- **Semantic Search** -- Find entries by meaning, not just keywords
-- **Project Buckets** -- Organize entries by project for easy scoping
-- **Team Vaults** -- Share knowledge with your team (requires hosted API)
-- **Deduplication** -- Automatic detection of similar entries
-- **Encoding Context** -- Future-proof your saves with metadata for discovery months later
-- **Snapshot Briefs** -- Consolidate scattered entries into a single context brief
-- **Recall Tracking** -- Monitor how often your entries are actually used
-
-## Installation
-
-Install via Claude Code:
-
-```
-/plugin install context-vault
-```
-
-For full setup with embedding model download and agent rules:
-
-```bash
-npx context-vault setup
-```
-
-## Quick Start
-
-### Save Your First Insight
-
-```javascript
-save_context({
-  kind: "insight",
-  title: "PostgreSQL connection pooling lesson",
-  body: "Connections without pooling exhausted at 100 concurrent users...",
-  tags: ["bucket:myproject", "database"],
-  encoding_context: { project: "myproject", arc: "scaling", task: "investigation" }
-})
-```
-
-### Load Context for a Task
-
-```javascript
-// At the start of a session, scope to your project and get an overview
-clear_context({
-  preload_bucket: "myproject",
-  max_tokens: 4000
-})
-
-// Then search for specific context
-get_context({
-  query: "how do we handle database scaling?",
-  buckets: ["myproject"]
-})
-```
-
-### Create a Context Brief
-
-```javascript
-create_snapshot({
-  topic: "API authentication decisions",
-  buckets: ["myproject"]
-})
-```
-
-## Commands
-
-Three slash commands for common vault workflows:
-
-- **/vault-status** -- Check vault health (entry counts, recall ratio, warnings)
-- **/vault-snapshot** -- Create a consolidated context brief for a topic
-- **/vault-cleanup** -- Triage stale entries, consolidate duplicates, manage growth
-
-## Skills
-
-Three skills teach Claude how to use the vault effectively:
-
-### 1. Memory Management
-When to save, what kind to use, how to tag entries, and how to keep your vault healthy.
-
-### 2. Knowledge Capture
-Session-end protocol: extract and save the insights and decisions you discovered.
-
-### 3. Context Assembly
-Load relevant knowledge at task start. Assemble context efficiently and scope to your project.
-
-## Use Cases
-
-### Personal Memory
-Save decisions and insights from your work, then access them months later.
-
-```javascript
-save_context({
-  kind: "decision",
-  title: "Chose SQLite + embeddings for local RAG",
-  body: "Evaluated: PostgreSQL (setup), Pinecone (cost), local SQLite (simplicity). Chose SQLite + sqlite-vec for full control and no external dependencies.",
-  tags: ["bucket:rag-project", "architecture", "database"],
-  tier: "durable"
-})
-```
-
-### Team Knowledge Sharing
-Capture lessons learned that the team should know, then publish to a shared vault.
-
-```javascript
-save_context({
-  kind: "pattern",
-  title: "Always test OAuth flow end-to-end on real device",
-  body: "Simulator behavior differs from real devices. Always test with physical phone before production.",
-  tags: ["bucket:mobile-team", "oauth", "testing"],
-  tier: "durable"
-})
-
-// Later, share to team vault
-publish_to_team({ id: "entry-id" })
-```
-
-### Project Onboarding
-Create a snapshot of all decisions and patterns for a new team member.
-
-```javascript
-create_snapshot({
-  topic: "project architecture and key decisions",
-  buckets: ["project-x"],
-  kinds: ["decision", "pattern"]
-})
-```
-
-## Tools Reference
-
-The plugin provides 14 MCP tools:
-
-### Read-Only (no side effects)
-- `list_context` -- Browse entries by kind, tags, date range
-- `context_status` -- Vault health dashboard (entry counts, recall stats, warnings)
-- `list_buckets` -- List all project buckets
-- `session_start` -- Load project context at session start
-
-### Read with Analytics (update access counters as side effect)
-- `get_context` -- Search vault by query, kind, bucket, or date. Updates `hit_count` and `recall_count` on returned entries.
-- `recall` -- Proactive context surfacing. Takes a `signal` (text) and `signal_type` (prompt/error/file/task), returns relevant hints. Records co-retrieval pairs.
-
-### Write (create new entries)
-- `save_context` -- Create or update an entry. Supports `encoding_context` for future discovery and `supersedes` to retire old entries.
-- `create_snapshot` -- Consolidate scattered entries into a single brief. Returns a confirmation with the new entry's ID and identity_key.
-- `ingest_url` -- Fetch a web page and save as a reference entry
-- `ingest_project` -- Scan a project directory and save metadata
-- `session_end` -- Capture session learnings (auto-save insights)
-- `publish_to_team` -- Copy an entry to your team vault
-
-### Destructive (modify or delete existing data)
-- `delete_context` -- Permanently remove an entry by ID
-- `clear_context` -- Reset session scope. With `preload_bucket`, returns recent entries from that bucket in the response.
-
-## Storage
-
-Data is stored in two locations:
-
-```
-~/.context-mcp/              # Data directory
-├── vault.db                  # SQLite database (entries, embeddings, FTS index)
-├── config.json               # User configuration
-└── telemetry.jsonl           # Local usage telemetry
-
-~/vault/ (or configured path)  # Vault directory (markdown source of truth)
-├── knowledge/                 # Decisions, insights, patterns, references
-├── entity/                    # People, projects, tools
-└── event/                     # Session logs, activity
-```
-
-Markdown files are the source of truth. The SQLite database is a derived index, rebuildable via `context-vault reindex`.
-
-## Privacy
-
-**Local-first:** All data stored locally on your machine. No network calls unless you explicitly enable hosted sync or team vaults.
-
-**Hosted sync (optional):** When configured, entries sync to your personal cloud vault (per-user isolated database). Team vault entries are shared only when you call `publish_to_team`.
-
-**Your vault is never accessed or indexed by third parties.** Full privacy policy: https://context-vault.com/privacy
-
-## Tips
-
-- **Encoding context is key:** Entries without `encoding_context` are rarely discovered later. Always include project, arc, and task.
-- **Check before saving:** Call `get_context` first to avoid duplicates. Duplicates hurt recall ratio.
-- **Use tiers wisely:** `durable` for architecture decisions, `working` (default) for active context, `ephemeral` for temp notes.
-- **Snapshot for scale:** If you have 20+ entries on a topic, create a snapshot instead of loading them individually.
-- **Recall ratio:** 20-30% is healthy. Run `/vault-status` to check yours.
-
-## Troubleshooting
-
-**"I can't find my entry"**
-- Check the right bucket: `get_context({ query: "...", buckets: ["myproject"] })`
-- Try a broader query: "authentication" instead of "OAuth 2.0 PKCE state handling"
-- Browse by kind: `list_context({ kind: "decision", tags: ["bucket:myproject"] })`
-
-**"Vault is growing too fast"**
-- Run `/vault-cleanup` to identify stale or duplicate entries
-- Create snapshots to consolidate large topics
-- Check for session/debug noise mixed with knowledge entries
-
-**"Embeddings not working"**
-- Run `context-vault reindex` to regenerate the embedding index
-- Run `context-vault doctor` for a full diagnostic
-
-## Support
-
-- GitHub: https://github.com/fellanH/context-vault/issues
-- Website: https://context-vault.com
-
-## License
-
-MIT

package/.claude-plugin/plugin.json

@@ -1,11 +0,0 @@
-{
-  "name": "context-vault",
-  "version": "3.10.0",
-  "description": "Persistent memory and knowledge management for AI agents. Save decisions, insights, patterns, and context across sessions. Semantic search, project-scoped buckets, team vaults, and recall tracking.",
-  "author": "Klarhimmel",
-  "homepage": "https://context-vault.com",
-  "repository": "https://github.com/fellanH/context-vault",
-  "license": "MIT",
-  "keywords": ["memory", "knowledge", "vault", "context", "mcp", "persistence", "recall"],
-  "categories": ["productivity", "knowledge-management", "developer-tools"]
-}

package/commands/vault-cleanup.md

@@ -1,43 +0,0 @@
-# /vault-cleanup — Vault Maintenance
-
-Identify stale, duplicate, or low-value entries and help the user clean up their vault.
-
-## Steps
-
-1. **Gather vault state.** Call `context_status()` to get entry counts, kind breakdown, recall stats, and warnings.
-
-2. **Identify cleanup candidates.** Use `list_context` to browse entries that may need attention:
-   ```
-   list_context({ kind: "session", limit: 20 })
-   list_context({ kind: "feedback", tags: ["auto-captured"], limit: 20 })
-   list_context({ kind: "observation", limit: 20 })
-   ```
-   Review results for entries with `recall_count: 0` (never recalled) and old `created_at` dates.
-
-3. **Check for duplicates.** Search for topics the user likely has many entries on:
-   ```
-   get_context({ query: "<suspected duplicate topic>", buckets: ["<project>"], limit: 15 })
-   ```
-   If multiple entries cover the same insight, suggest consolidating via `create_snapshot`.
-
-4. **Present a triage report.** For each category, show:
-   - Entry title, kind, created date, recall count
-   - Recommended action: **delete**, **consolidate**, **expire**, or **keep**
-
-5. **Execute only user-approved actions.** Wait for explicit confirmation before any deletion.
-
-## Available Actions
-
-| Action | How | When |
-|--------|-----|------|
-| **Delete** | `delete_context({ id: "<entry-id>" })` | Duplicates, noise, irrelevant entries |
-| **Consolidate** | `create_snapshot({ topic: "...", buckets: ["..."] })` | Many scattered entries on one topic |
-| **Set to expire** | `save_context({ id: "<entry-id>", tier: "ephemeral" })` | Stale but not worth deleting now |
-| **Supersede** | `save_context({ title: "...", body: "...", supersedes: ["<old-id>"] })` | Replace outdated with current |
-
-## Important
-
-- `delete_context` is **permanent and irreversible**. Always confirm with the user.
-- There is no bulk delete. Each deletion requires a separate call with a specific entry ID.
-- There is no "archive" or "soft delete." To deprioritize without deleting, set `tier: "ephemeral"`.
-- Do not reference tools or parameters that don't exist. Only use: `context_status`, `list_context`, `get_context`, `delete_context`, `save_context`, `create_snapshot`.

package/commands/vault-snapshot.md

@@ -1,43 +0,0 @@
-# /vault-snapshot — Create a Context Brief
-
-Consolidate scattered vault entries on a topic into a single brief.
-
-## Steps
-
-1. Ask the user what topic they want a snapshot of. Also ask which project bucket to scope to (if not obvious from context).
-
-2. Call `create_snapshot` with the topic as a **natural language search query** (not a slug):
-   ```
-   create_snapshot({
-     topic: "API authentication decisions and patterns",
-     buckets: ["project-name"],
-     kinds: ["decision", "pattern"],
-     tags: ["authentication"]
-   })
-   ```
-   All parameters except `topic` are optional. `kinds` filters by entry kind. `tags` adds tag filters. `buckets` scopes to a project.
-
-3. The tool returns a short confirmation (not the brief content):
-   ```
-   ✓ Snapshot created → id: <entry-id>
-     title: <topic> — Context Brief
-     identity_key: snapshot-<slugified-topic>
-     synthesized from: N entries
-   ```
-   The brief is saved to the vault as a `kind: brief` entry.
-
-4. To show the user the brief, make a follow-up call:
-   ```
-   get_context({ kind: "brief", identity_key: "snapshot-<slugified-topic>" })
-   ```
-
-5. Present the brief and offer next steps:
-   - "Share this with your team" via `publish_to_team({ id: "<entry-id>" })`
-   - "Create another snapshot on a related topic"
-   - "Search for more context" via `get_context`
-
-## Tips
-
-- The `topic` is used as a search query (hybrid FTS + semantic). Use descriptive natural language for best results. "API authentication decisions" works better than "api-auth".
-- If "no entries found," try a broader query or different bucket.
-- Snapshots are idempotent on `identity_key`. Re-running with the same topic updates the existing snapshot.

package/commands/vault-status.md

@@ -1,35 +0,0 @@
-# /vault-status — Vault Health Check
-
-Check the health and metrics of your context vault.
-
-## Steps
-
-1. Call `context_status()` (no arguments needed).
-2. The tool returns a structured markdown dashboard with sections for entries by kind, recall frequency, learning rate, stale knowledge, growth warnings, and suggested actions. Present it to the user.
-3. After presenting the dashboard, add your own analysis (see below).
-
-## Analysis Guidelines
-
-**Positive signals to highlight:**
-- High embedding coverage (>90%)
-- Active recall (recall:save ratio above 1:1)
-- Regular saves per session (>1.0)
-- No stale paths or startup errors
-
-**Warning signs to flag:**
-- Embedding coverage below 80%: suggest running `context-vault reindex`
-- Zero saves in 30 days: knowledge may be getting lost between sessions
-- Stale paths detected: auto-reindex will fix on next search
-- Growth warnings present: review the kind breakdown for noise (session, feedback entries dominating)
-- Stale knowledge entries: the tool flags entries not updated within their kind-specific staleness window (pattern: 180d, decision: 365d, reference: 90d)
-- Startup errors in the error log: point the user to the log path
-
-**Recall ratio (JSON block at the end of the dashboard):**
-- Below 0.10: most entries are never retrieved. Suggest better tagging, encoding_context, and snapshots.
-- Above 0.25: healthy.
-
-## Do NOT
-
-- Fabricate metrics or example output. Only report what the tool returns.
-- Suggest `npm run build` for any issue. The correct commands are `context-vault reindex`, `context-vault doctor`, or `context-vault setup`.
-- Invent thresholds. Use the warnings the tool itself generates.