context-vault 3.4.4 → 3.5.0

package/assets/agent-rules.md

@@ -0,0 +1,50 @@
+<!-- context-vault-rules v1.0 -->
+# Context Vault — Agent Rules
+
+You have access to a persistent knowledge vault via MCP tools (`get_context`, `save_context`, `list_context`, `delete_context`). Use it to build lasting memory across sessions.
+
+## When to Retrieve
+
+Check the vault when you're about to invest effort that past knowledge could shortcut. Apply this test: "Might I or a previous session have encountered this before?" If yes, search first.
+
+Retrieval triggers:
+- **Starting a session**: call `session_start()` or `get_context(query: "<project or task context>")` to load relevant prior knowledge
+- **Hitting an error**: search for the error message or root cause before debugging from scratch
+- **Making a decision**: check if this architectural or design choice was already made and why
+- **Integrating with an API, library, or service**: search for known quirks, gotchas, or working patterns
+- **Entering an unfamiliar area of the codebase**: check for prior insights about that module or domain
+- **Before saving**: search to avoid duplicates and to update existing entries instead
+
+A vault search takes milliseconds. Debugging from scratch takes minutes. Always check first.
+
+## When to Save
+
+Save when you encounter something a future session would benefit from knowing. Apply this test: "Would I tell a colleague about this to save them time?" If yes, save it.
+
+Save triggers:
+- Solved a non-obvious bug (root cause was not apparent from the error)
+- Discovered undocumented API/library/tool behavior
+- Found a working integration pattern requiring non-obvious configuration
+- Hit a framework limitation and found a workaround
+- Made an architectural decision with tradeoffs worth preserving
+
+## When NOT to Save
+
+- Facts derivable from reading the current code or git history
+- The fix itself (that belongs in the commit, not the vault)
+- Generic programming knowledge you already know
+- Session-specific state (files edited, commands run)
+
+## How to Save
+
+Every entry must have:
+- `title`: clear, specific (not "auth fix" but "Express 5 raw body parser breaks Stripe webhook verification")
+- `tags`: at minimum a `bucket:<project>` tag for scoping
+- `kind`: insight, pattern, reference, decision, or event
+- `tier`: `working` for active context, `durable` for long-term reference
+
+Capture what was learned (the insight), why it matters (what problem it prevents), and when it applies (what context makes it relevant).
+
+## Session Review
+
+At the end of significant work sessions, review what you learned. If the session produced novel knowledge (not every session does), save 1-3 consolidated entries. Prefer one solid entry over multiple fragments.

package/assets/setup-prompt.md

@@ -0,0 +1,58 @@
+# Context Vault: Agent-Assisted Setup Prompt
+
+Paste the prompt below into your AI coding assistant (Claude Code, Cursor, Windsurf, etc.) after installing context-vault to customize your installation.
+
+---
+
+## Prompt
+
+```
+I just installed context-vault as an MCP server. Help me set it up properly for my workflow. Do these steps in order, asking me before making any changes:
+
+1. Verify the vault MCP connection is working by calling context_status()
+
+2. Scan my existing rules and instructions:
+   - Read files in ~/.claude/rules/ (or equivalent for this client)
+   - Read any CLAUDE.md in my current project and home directory
+   - Read .cursorrules or .windsurfrules if they exist
+   - Tell me if you find any existing vault-related instructions
+
+3. Check if a context-vault rules file is already installed. If not, offer to install one. The rules file teaches you when and how to save knowledge to my vault automatically. Show me the exact content before writing anything.
+
+4. Check for conflicts between the vault rules and my existing instructions. Flag any contradictions or redundancies and ask me how to resolve them.
+
+5. Scan my current workspace for projects (look for package.json, .git, Cargo.toml, pyproject.toml, etc.). For each project, propose a vault bucket name and create it if I approve.
+
+6. Show me a summary of everything you configured.
+
+Important:
+- Never modify my existing rules files. Only create a new dedicated context-vault rules file or append with clear delimiter markers.
+- Show me exact file paths and content before writing anything.
+- If I decline any step, skip it.
+```
+
+---
+
+## What this does
+
+After running this prompt, your AI agent will:
+
+- **Verify** your vault connection is working
+- **Detect** your existing rules and avoid conflicts
+- **Install** a rules file that teaches the agent when to save knowledge automatically
+- **Configure** project-specific vault buckets for organized storage
+
+The rules file is a small (~50 lines) markdown file that guides your agent on:
+- When to save (after solving non-obvious bugs, finding undocumented behavior, etc.)
+- When NOT to save (generic knowledge, code-derivable facts)
+- How to save (with proper titles, tags, and tiers)
+- Session review (consolidating learnings at end of work sessions)
+
+You can edit or delete the rules file at any time. It lives at:
+- **Claude Code:** `~/.claude/rules/context-vault.md`
+- **Cursor:** `~/.cursor/rules/context-vault.mdc` (global Cursor rules)
+- **Windsurf:** `~/.windsurfrules` (appended with delimiter markers)
+
+## Manual installation
+
+If you prefer not to use agent-assisted setup, you can copy the rules file content directly from the [Agent Rules Reference](/docs/agent-rules) page on our website.

package/assets/skills/vault-setup/skill.md

@@ -0,0 +1,81 @@
+---
+name: vault-setup
+description: >
+  Agent-assisted context vault setup and customization. Verifies the MCP
+  connection, detects existing rules, scans projects for vault buckets, and
+  resolves conflicts with existing instructions — all with explicit user approval
+  before making any changes.
+  Triggers: "/vault setup", "set up my vault", "configure vault", "customize vault",
+  "vault setup", "personalize vault".
+---
+
+# vault-setup skill
+
+Agent-assisted setup that customizes the context-vault installation for the user's workflow. Always show what you plan to do before doing it. Never modify existing rules without permission.
+
+## Step 1 — Verify vault connection
+
+Call `context_status()` (or `get_context(query: "test", limit: 1)` if context_status is unavailable). Report:
+- Whether the MCP connection is working
+- Vault location and entry count
+- If it fails: print the exact error and stop — the MCP server needs to be running first
+
+## Step 2 — Scan existing rules
+
+Read these locations silently (do not write anything yet):
+- `~/.claude/rules/` — list all files
+- `~/.claude/rules/context-vault.md` — the installed rules file (if present)
+- `CLAUDE.md` in the current working directory (if it exists)
+- `~/.claude/CLAUDE.md` (if it exists)
+- `.cursorrules` in cwd (if it exists)
+- `.windsurfrules` in cwd (if it exists)
+
+Report what you found:
+- Whether a context-vault rules file is already installed and its version
+- Any existing vault-related instructions in other files (quote them)
+- Any conflicts or redundancies
+
+## Step 3 — Check for conflicts
+
+Compare the installed rules (if any) against the user's existing instructions. Flag:
+- Contradictions (e.g., "always save everything" vs the vault's quality heuristic)
+- Redundancies (e.g., the user already has identical instructions in CLAUDE.md)
+- Missing rules (vault connection not verified, no bucket conventions set)
+
+Ask the user how to resolve each conflict before proceeding.
+
+## Step 4 — Scan for projects
+
+Look in the current working directory and one level up for project roots:
+- Files: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `pom.xml`
+- Directories: `.git`
+
+For each project found, propose a vault bucket name (lowercase, hyphens, derived from the project name or directory). Example: `my-app` → `bucket:my-app`.
+
+Ask: "I found these projects. Create vault buckets for them? I'll add bucket conventions to your rules."
+
+Only proceed if the user approves.
+
+## Step 5 — Apply changes
+
+For each approved change, show the exact content and path before writing. Changes may include:
+- Creating or updating `~/.claude/rules/context-vault.md` with project-specific bucket conventions
+- Appending project bucket notes to the rules file
+
+Never modify the user's own rules files (CLAUDE.md, .cursorrules, etc.). Only write to the dedicated context-vault rules file.
+
+## Step 6 — Summary
+
+Print a final summary:
+- What was configured
+- Where each file was written
+- How to view the rules: `context-vault rules show`
+- How to remove everything: `context-vault uninstall`
+
+## What NOT to do
+
+- Do not save vault entries about the setup itself (the setup is not vault-worthy knowledge)
+- Do not modify files without showing exact content first
+- Do not delete or overwrite user-written rules
+- Do not assume project structure — verify with file reads
+- Do not proceed past a failed vault connection