context-vault 3.10.0 → 3.12.0

package/.claude-plugin/README.md

@@ -0,0 +1,219 @@
+# 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

@@ -0,0 +1,11 @@
+{
+  "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/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "context-vault": {
+      "command": "context-vault",
+      "args": ["serve"]
+    }
+  }
+}
+

package/bin/cli.js

@@ -85,6 +85,48 @@ function isNpx() {
   return ROOT.includes('/_npx/') || ROOT.includes('\\_npx\\');
 }
 
+/** Check if a global install of context-vault exists on PATH (not npx cache) */
+function hasGlobalInstall() {
+  try {
+    const cmd = platform() === 'win32' ? 'where context-vault' : 'which context-vault';
+    const which = execSync(cmd, { encoding: 'utf-8', stdio: 'pipe', timeout: 3000 }).trim();
+    return !!which && !which.includes('/_npx/') && !which.includes('\\_npx\\');
+  } catch { return false; }
+}
+
+/**
+ * Determine the best server config for tool MCP configs.
+ * Priority: global binary > npx fallback > local dev path.
+ * Even when running via npx, prefer the global binary if it exists
+ * (e.g., we just installed it during setup).
+ */
+function getServerConfig(vaultDir) {
+  const serverArgs = ['serve'];
+  if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
+
+  if (hasGlobalInstall()) {
+    return { command: 'context-vault', args: serverArgs };
+  }
+  if (isNpx()) {
+    return {
+      command: 'npx',
+      args: ['-y', 'context-vault', 'serve', ...(vaultDir ? ['--vault-dir', vaultDir] : [])],
+      env: { NODE_OPTIONS: '--no-warnings=ExperimentalWarning' },
+    };
+  }
+  if (isInstalledPackage()) {
+    return { command: 'context-vault', args: serverArgs };
+  }
+  // Local dev clone
+  const nodeArgs = [SERVER_PATH];
+  if (vaultDir) nodeArgs.push('--vault-dir', vaultDir);
+  return {
+    command: process.execPath,
+    args: nodeArgs,
+    env: { NODE_OPTIONS: '--no-warnings=ExperimentalWarning' },
+  };
+}
+
 /** Detect user experience level based on dev environment signals */
 function detectUserExperience() {
   if (isNonInteractive) return 'developer';
@@ -760,6 +802,58 @@ async function runSetup() {
     console.log();
   }
 
+  // Global install: when running via npx, offer to install globally so the
+  // MCP server binary is on PATH. This makes tool configs reliable (no npx
+  // cache dependency) and startup faster (no npx overhead on every spawn).
+  if (isNpx() && !isDryRun) {
+    const hasGlobal = (() => {
+      try {
+        const cmd = platform() === 'win32' ? 'where context-vault' : 'which context-vault';
+        const which = execSync(cmd, { encoding: 'utf-8', stdio: 'pipe', timeout: 3000 }).trim();
+        // Verify it's not pointing back to the npx cache
+        return which && !which.includes('/_npx/') && !which.includes('\\_npx\\');
+      } catch { return false; }
+    })();
+
+    if (!hasGlobal) {
+      if (!isNonInteractive) {
+        console.log(dim('  context-vault needs a permanent install to run as an MCP server.'));
+        console.log(dim('  Without it, AI tools must re-download the package on every launch.\n'));
+        const installAnswer = await prompt('  Install globally via npm? (Y/n):', 'Y');
+        if (installAnswer.toLowerCase() !== 'n') {
+          console.log();
+          try {
+            console.log(dim('  Installing context-vault globally...\n'));
+            execSync('npm install -g context-vault@' + VERSION, {
+              stdio: 'inherit',
+              timeout: 120000,
+            });
+            console.log(`\n  ${green('✓')} Installed context-vault v${VERSION} globally\n`);
+          } catch (e) {
+            console.log(`\n  ${yellow('!')} Global install failed: ${e.message}`);
+            console.log(dim('  Falling back to npx-based config. You can install later:'));
+            console.log(dim('  npm install -g context-vault\n'));
+          }
+        } else {
+          console.log(dim('\n  Skipped. MCP configs will use npx (slower startup).\n'));
+        }
+      } else {
+        // Non-interactive (--yes): auto-install globally
+        try {
+          console.log(dim('  Installing context-vault globally...\n'));
+          execSync('npm install -g context-vault@' + VERSION, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 120000,
+          });
+          console.log(`  ${green('✓')} Installed context-vault v${VERSION} globally\n`);
+        } catch (e) {
+          console.log(`  ${yellow('!')} Global install failed: ${e.message}`);
+          console.log(dim('  Continuing with npx-based config.\n'));
+        }
+      }
+    }
+  }
+
   // Detect tools
   console.log(dim(`  [1/7]`) + bold(' Detecting tools...\n'));
   verbose(userLevel, 'Scanning for AI tools on this machine.');
@@ -1480,53 +1574,13 @@ async function configureClaude(tool, vaultDir) {
   }
 
   try {
-    if (isNpx()) {
-      const serverArgs = ['-y', 'context-vault', 'serve'];
-      if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
-      execFileSync(
-        'claude',
-        [
-          'mcp',
-          'add',
-          '-s',
-          'user',
-          'context-vault',
-          '-e',
-          'NODE_OPTIONS=--no-warnings=ExperimentalWarning',
-          '--',
-          'npx',
-          ...serverArgs,
-        ],
-        { stdio: 'pipe', env }
-      );
-    } else if (isInstalledPackage()) {
-      const serverArgs = ['serve'];
-      if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
-      execFileSync(
-        'claude',
-        ['mcp', 'add', '-s', 'user', 'context-vault', '--', 'context-vault', ...serverArgs],
-        { stdio: 'pipe', env }
-      );
-    } else {
-      const nodeArgs = [SERVER_PATH];
-      if (vaultDir) nodeArgs.push('--vault-dir', vaultDir);
-      execFileSync(
-        'claude',
-        [
-          'mcp',
-          'add',
-          '-s',
-          'user',
-          'context-vault',
-          '-e',
-          'NODE_OPTIONS=--no-warnings=ExperimentalWarning',
-          '--',
-          process.execPath,
-          ...nodeArgs,
-        ],
-        { stdio: 'pipe', env }
-      );
+    const srvCfg = getServerConfig(vaultDir);
+    const claudeArgs = ['mcp', 'add', '-s', 'user', 'context-vault'];
+    if (srvCfg.env?.NODE_OPTIONS) {
+      claudeArgs.push('-e', `NODE_OPTIONS=${srvCfg.env.NODE_OPTIONS}`);
     }
+    claudeArgs.push('--', srvCfg.command, ...srvCfg.args);
+    execFileSync('claude', claudeArgs, { stdio: 'pipe', env });
   } catch (e) {
     const stderr = e.stderr?.toString().trim();
     throw new Error(stderr || e.message);
@@ -1542,25 +1596,10 @@ async function configureCodex(tool, vaultDir) {
   }
 
   try {
-    if (isNpx()) {
-      const serverArgs = ['-y', 'context-vault', 'serve'];
-      if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
-      execFileSync('codex', ['mcp', 'add', 'context-vault', '--', 'npx', ...serverArgs], {
-        stdio: 'pipe',
-      });
-    } else if (isInstalledPackage()) {
-      const serverArgs = ['serve'];
-      if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
-      execFileSync('codex', ['mcp', 'add', 'context-vault', '--', 'context-vault', ...serverArgs], {
-        stdio: 'pipe',
-      });
-    } else {
-      const nodeArgs = [SERVER_PATH];
-      if (vaultDir) nodeArgs.push('--vault-dir', vaultDir);
-      execFileSync('codex', ['mcp', 'add', 'context-vault', '--', process.execPath, ...nodeArgs], {
-        stdio: 'pipe',
-      });
-    }
+    const srvCfg = getServerConfig(vaultDir);
+    execFileSync('codex', ['mcp', 'add', 'context-vault', '--', srvCfg.command, ...srvCfg.args], {
+      stdio: 'pipe',
+    });
   } catch (e) {
     const stderr = e.stderr?.toString().trim();
     throw new Error(stderr || e.message);
@@ -1664,29 +1703,7 @@ function configureJsonTool(tool, vaultDir) {
   // Clean up old "context-mcp" key
   delete config[tool.configKey]['context-mcp'];
 
-  if (isNpx()) {
-    const serverArgs = vaultDir ? ['--vault-dir', vaultDir] : [];
-    config[tool.configKey]['context-vault'] = {
-      command: 'npx',
-      args: ['-y', 'context-vault', 'serve', ...serverArgs],
-      env: { NODE_OPTIONS: '--no-warnings=ExperimentalWarning' },
-    };
-  } else if (isInstalledPackage()) {
-    const serverArgs = ['serve'];
-    if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
-    config[tool.configKey]['context-vault'] = {
-      command: 'context-vault',
-      args: serverArgs,
-    };
-  } else {
-    const serverArgs = [SERVER_PATH];
-    if (vaultDir) serverArgs.push('--vault-dir', vaultDir);
-    config[tool.configKey]['context-vault'] = {
-      command: process.execPath,
-      args: serverArgs,
-      env: { NODE_OPTIONS: '--no-warnings=ExperimentalWarning' },
-    };
-  }
+  config[tool.configKey]['context-vault'] = getServerConfig(vaultDir);
 
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 }

package/commands/vault-cleanup.md

@@ -0,0 +1,43 @@
+# /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

@@ -0,0 +1,43 @@
+# /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

@@ -0,0 +1,35 @@
+# /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.

package/dist/register-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../src/register-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,YAAY,CAAC;AAmDlE,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAwI9D"}
+{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../src/register-tools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,YAAY,CAAC;AAkFlE,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CA8I9D"}

package/dist/register-tools.js

@@ -38,6 +38,27 @@ const toolModules = [
     publishToTeam,
 ];
 const TOOL_TIMEOUT_MS = 120_000;
+const REINDEX_TIMEOUT_MS = 30_000;
+const TOOL_ANNOTATIONS = {
+    // Read-only tools (4)
+    list_context: { readOnlyHint: true },
+    context_status: { readOnlyHint: true },
+    list_buckets: { readOnlyHint: true },
+    session_start: { readOnlyHint: true },
+    // Read with side-effect counters (2) — update hit_count/recall_count/co-retrievals
+    get_context: { readOnlyHint: false, destructiveHint: false },
+    recall: { readOnlyHint: false, destructiveHint: false },
+    // Additive write tools (3) — create entries, never delete/replace
+    create_snapshot: { readOnlyHint: false, destructiveHint: false },
+    ingest_url: { readOnlyHint: false, destructiveHint: false },
+    ingest_project: { readOnlyHint: false, destructiveHint: false },
+    // Destructive write tools (5) — may update/delete existing data
+    save_context: { readOnlyHint: false, destructiveHint: true },
+    delete_context: { readOnlyHint: false, destructiveHint: true },
+    clear_context: { readOnlyHint: false, destructiveHint: true },
+    session_end: { readOnlyHint: false, destructiveHint: true },
+    publish_to_team: { readOnlyHint: false, destructiveHint: true },
+};
 // Reindex state hoisted to module scope so that in HTTP daemon mode
 // (where registerTools is called once per session), the reindex only
 // runs once for the entire process rather than once per connecting session.
@@ -132,12 +153,15 @@ export function registerTools(server, ctx) {
                 return reindexPromise;
             return; // non-blocking: just ensure it's started
         }
-        const promise = reindex(ctx, { fullSync: true })
+        const promise = Promise.race([
+            reindex(ctx, { fullSync: true, skipEmbeddings: true }),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Reindex timeout (30s). FTS index may be incomplete.')), REINDEX_TIMEOUT_MS)),
+        ])
             .then((stats) => {
             reindexDone = true;
             const total = stats.added + stats.updated + stats.removed;
             if (total > 0) {
-                console.error(`[context-vault] Auto-reindex: +${stats.added} ~${stats.updated} -${stats.removed} (${stats.unchanged} unchanged)`);
+                console.error(`[context-vault] Auto-reindex: +${stats.added} ~${stats.updated} -${stats.removed} (${stats.unchanged} unchanged, embeddings deferred)`);
             }
         })
             .catch((e) => {
@@ -163,7 +187,7 @@ export function registerTools(server, ctx) {
         },
     };
     for (const mod of toolModules) {
-        server.tool(mod.name, mod.description, mod.inputSchema, tracked(((args) => mod.handler(args, ctx, shared)), mod.name));
+        server.tool(mod.name, mod.description, mod.inputSchema, TOOL_ANNOTATIONS[mod.name] ?? { readOnlyHint: false, destructiveHint: true }, tracked(((args) => mod.handler(args, ctx, shared)), mod.name));
     }
     ensureIndexed().catch(() => { });
 }