context-vault 3.18.0 → 3.20.0

package/skills/context-assembly/SKILL.md

@@ -1,308 +0,0 @@
-# Context Assembly — Loading Knowledge at Task Start
-
-Learn how to load context from your vault at the beginning of a session or task. Assemble relevant knowledge efficiently and prime Claude with exactly what you need.
-
-## The Session-Start Protocol
-
-When you start work on a project or task, follow this 3-step protocol:
-
-1. **Scope your context** to the right project (bucket)
-2. **Preload memory** to warm up Claude's context
-3. **Load task-specific context** as needed
-
-This loads relevant knowledge automatically instead of searching every 5 minutes.
-
-## Step 1: Scope Your Context with Buckets
-
-Every entry in your vault has a bucket tag (bucket:projectname) that scopes it to a project.
-
-At session start, **tell Claude to focus on one project**:
-
-```javascript
-clear_context({
-  scope: "autohub",                    // Focus on "autohub" project
-  preload_bucket: "autohub",           // Warm-up cache with autohub entries
-  max_tokens: 4000                     // Budget for context (adjust as needed)
-})
-```
-
-This call:
-- Clears the previous session's context focus
-- Returns recent autohub entries directly in the response (decisions, insights, patterns)
-- Sets scope guidance: the response reminds you to filter to autohub in subsequent calls
-
-**Result:** You get immediate project context in the response. For subsequent `get_context` calls, include `buckets: ["autohub"]` to stay scoped.
-
-## Step 2: Get Task-Specific Context
-
-Once scoped, retrieve context relevant to your specific task:
-
-```javascript
-get_context({
-  query: "what decisions have we made about the authentication flow?",
-  buckets: ["autohub"],                // Optional: already scoped, but be explicit
-  limit: 10,                           // Limit to 10 entries
-  max_tokens: 2000                     // Stay within token budget
-})
-```
-
-This returns:
-- Decisions, insights, and patterns related to auth
-- Only from the autohub bucket
-- Ranked by relevance
-- Fits within your token budget
-
-**Use cases:**
-- "What was our database choice?" → Query for database decisions
-- "How do we handle errors in API calls?" → Query for error-handling patterns
-- "What stakeholders are involved?" → Query for contact entries
-- "What's blocking us on billing?" → Query for blockers or decisions on payments
-
-## Step 3: Build Context Briefs for Complex Topics
-
-When a topic has many scattered entries (5+), don't load them individually. Create a snapshot instead:
-
-```javascript
-create_snapshot({
-  topic: "API authentication",
-  buckets: ["autohub"],
-  kinds: ["decision", "pattern"]       // Optional: only snapshots of these types
-})
-```
-
-The snapshot consolidates all related entries into a single brief. Much more efficient than loading 8 separate entries.
-
-**When to snapshot:**
-- Starting a big new arc (e.g., "API redesign")
-- Onboarding a new team member to the project
-- Before meetings where you need to present project context
-- When assembling context for a complex task (20+ related entries)
-
-## Efficient Context Loading: Skeleton Mode
-
-For large projects with 100+ entries, use **skeleton mode** to keep token use low:
-
-```javascript
-get_context({
-  query: "authentication implementation",
-  buckets: ["autohub"],
-  pivot_count: 3,                      // Full body for top 3 entries, skeletons for rest
-  max_tokens: 2000                     // Strict token budget
-})
-```
-
-**Result:**
-- Top 3 entries: Full content (title + body + context)
-- Remaining entries: Skeleton format (title + tags + first 100 chars)
-- Token-efficient: Skeletons use 10% of the tokens of full entries
-
-**Use skeleton mode when:**
-- You have a tight token budget (< 2000 tokens)
-- You want breadth over depth (see all related entries, not all details)
-- You're exploring a topic (decide which entries deserve deep reading)
-
-## Graph Traversal: Follow Related Entries
-
-Entries can link to each other using `related_to`. Follow these links to find contextually similar entries:
-
-```javascript
-get_context({
-  query: "OAuth implementation",
-  buckets: ["autohub"],
-  follow_links: true                   // Include linked entries
-})
-```
-
-This returns:
-- Matching entries for "OAuth implementation"
-- All entries linked to those entries (related_to links)
-- Both forward links (this entry references X) and backlinks (X references this entry)
-
-**Use when:**
-- You want to understand the full decision tree (see what led to this decision)
-- You want impact analysis (what other decisions depend on this one?)
-- You're tracing a complex topic across multiple entries
-
-## Context Budget: Token Management
-
-Your context budget (`max_tokens`) is precious. Allocate wisely:
-
-```javascript
-// Tight budget: High-level overview only
-get_context({
-  query: "authentication architecture",
-  max_tokens: 1000,          // ~4-5 entries
-  pivot_count: 1             // Only top entry in full
-})
-
-// Medium budget: Decision + supporting context
-get_context({
-  query: "authentication architecture",
-  max_tokens: 3000,          // ~10-12 entries
-  pivot_count: 3             // Top 3 in full, rest as skeletons
-})
-
-// Generous budget: Deep dive with related entries
-get_context({
-  query: "authentication architecture",
-  max_tokens: 5000,          // ~15-20 entries
-  follow_links: true,        // Include related entries
-  pivot_count: 5             // Top 5 in full
-})
-```
-
-**Guidelines:**
-- Reserve 30-50% of your session context for vault entries
-- Use skeleton mode to fit more entries in less tokens
-- Follow_links expands context; use sparingly with strict max_tokens
-- Create snapshots to consolidate large topics into a single entry
-
-## Conflict Detection: Spot Outdated Decisions
-
-When loading context, spot decisions that might be outdated:
-
-```javascript
-get_context({
-  query: "database choice",
-  buckets: ["autohub"],
-  detect_conflicts: true     // Flag superseded or conflicting entries
-})
-```
-
-**Result:**
-- Marked entries that have been superseded (newer version exists)
-- Flagged entries with conflicting information (different decisions on the same topic)
-- Suggests which entries are stale
-
-**Use when:**
-- Loading context from a project you haven't touched in 3+ months
-- Starting a new arc that touches a previously decided area
-- You suspect decisions have changed since last session
-
-## Browsing: When You Don't Know What You're Looking For
-
-Sometimes you want to browse your vault without a specific query:
-
-```javascript
-list_context({
-  tags: ["bucket:autohub"],
-  kind: "decision",          // Only decisions
-  limit: 20                  // Show 20 most recent
-})
-```
-
-Returns a list of entries (title + tags, no full body) so you can browse and decide which to read deeply.
-
-**Use when:**
-- You're onboarding to a project (see what decisions exist)
-- You want to refresh memory before a meeting
-- You're looking for entries by browse, not search
-
-## Common Workflows
-
-### Workflow 1: Start Work on a New Feature
-
-```javascript
-// 1. Scope to project
-clear_context({ preload_bucket: "autohub", max_tokens: 4000 })
-
-// 2. Get architecture decisions
-get_context({
-  query: "overall architecture and tech stack",
-  limit: 5,
-  max_tokens: 1500
-})
-
-// 3. Get feature-specific context
-get_context({
-  query: "user authentication flow",
-  limit: 5,
-  max_tokens: 1500
-})
-
-// 4. Follow related decisions
-get_context({
-  query: "API security",
-  follow_links: true,
-  max_tokens: 1000
-})
-```
-
-Total: ~4500 tokens for a complete project context setup.
-
-### Workflow 2: Onboard New Team Member
-
-```javascript
-// Create a comprehensive snapshot
-create_snapshot({
-  topic: "autohub project overview and key decisions",
-  buckets: ["autohub"],
-  kinds: ["decision", "pattern"]
-})
-
-// Share the snapshot as a brief
-// (They can read it in 30 minutes instead of searching)
-```
-
-### Workflow 3: Deep Dive on Complex Decision
-
-```javascript
-get_context({
-  query: "why did we choose Turso over PostgreSQL?",
-  buckets: ["autohub"],
-  follow_links: true,      // See related decisions (infrastructure, scale, cost)
-  max_tokens: 3000
-})
-```
-
-### Workflow 4: End-of-Session Cleanup
-
-Before ending your session, use the context to inform your captures:
-
-```javascript
-// What decisions did we make today?
-get_context({
-  query: "today's decisions",
-  since: "today",
-  limit: 10
-})
-
-// Do any of today's insights conflict with past entries?
-get_context({
-  query: "authentication implementation",
-  detect_conflicts: true
-})
-
-// Save new decisions without duplicating old ones
-save_context({
-  kind: "decision",
-  title: "Updated auth flow",
-  body: "...",
-  supersedes: ["old-auth-id"]  // Retire old decision
-})
-```
-
-## Preload and Performance
-
-**Preload behavior:**
-- `clear_context({ preload_bucket: "autohub" })` queries the vault and returns matching entries directly in the response text
-- This gives you immediate context without a separate `get_context` call
-- There is no shared cache between tools. Each `get_context` call runs its own query.
-
-**Optimize for speed:**
-- Call `clear_context` with `preload_bucket` at session start to get a project overview in one call
-- Use `max_tokens` to limit response size (fewer entries = smaller responses)
-- Use skeleton mode (`pivot_count`) to reduce token use in `get_context`
-- Create snapshots to consolidate many entries into a single brief
-
-## Token Budget Checklist
-
-Before a `get_context` call, verify:
-
-- [ ] Is max_tokens set to a reasonable value (< 50% of session budget)?
-- [ ] Am I using skeleton mode if I need breadth?
-- [ ] Is follow_links true only if I need to trace decisions?
-- [ ] Did I use a snapshot for large topics?
-- [ ] Did I scope with clear_context at session start?
-
-If you can answer yes to most, your context call will be efficient.

package/skills/knowledge-capture/SKILL.md

@@ -1,303 +0,0 @@
-# Knowledge Capture — Session-End Protocol for Vault
-
-Learn the session-end capture protocol: how to extract and save insights, decisions, and learning before you leave a task or session.
-
-## Why Capture at Session End?
-
-At the end of each session or task, you have fresh context about:
-- What you decided and why
-- What you learned (surprises, aha moments, gotchas)
-- Patterns you discovered
-- What worked well and what didn't
-- Next steps and blockers
-
-**This is the best time to save.** If you don't capture now, this context evaporates. Later, you'll waste time rediscovering it.
-
-Invest 5-10 minutes at session end to save decisions and insights. You'll thank yourself when the next session starts.
-
-## The Session-End Checklist
-
-At the end of your session, ask yourself these questions. For each yes, save an entry:
-
-### Decisions Made
-- Did you choose between options? (tech stack, approach, design)
-- Did you change direction? (pivot, constraint, new information)
-- Did you scope something in or out? (include/exclude features, projects)
-
-**Example entry:**
-```javascript
-save_context({
-  kind: "decision",
-  title: "Chose esbuild over Webpack for bundling",
-  body: `Evaluated Webpack, esbuild, and Turbopack. Chose esbuild because:
-  - 100x faster builds (15s → 0.2s on our codebase)
-  - Simpler config for our use case
-  - Better ESM support
-  Rejected Webpack (too complex for gains), Turbopack (immature).`,
-  tags: ["bucket:frontend-infra", "bundling", "build-tools"],
-  encoding_context: { project: "web-redesign", arc: "perf-optimization", task: "setup-build" },
-  tier: "durable"
-})
-```
-
-### Insights & Discoveries
-- Did you learn how something works? (system behavior, edge case, pattern)
-- Did you encounter a gotcha or surprising behavior?
-- Did you find a best practice or anti-pattern?
-
-**Example entry:**
-```javascript
-save_context({
-  kind: "insight",
-  title: "SQLite ANALYZE required for query planner efficiency",
-  body: `After 1M+ rows, SQLite query planner becomes ineffective without ANALYZE.
-
-  Observed: Queries that took 50ms with 100k rows jumped to 5000ms at 1M rows.
-  Root cause: Query planner using outdated statistics.
-  Solution: Run ANALYZE after bulk inserts. Restores performance to <100ms.
-
-  Lesson: Add ANALYZE to migration and bulk ETL scripts.`,
-  tags: ["bucket:context-vault", "database", "performance", "sqlite"],
-  encoding_context: { project: "context-vault", arc: "scaling", task: "perf-investigation" }
-})
-```
-
-### Patterns Discovered
-- Did you find a repeatable technique or approach?
-- Did you establish a convention the team should know?
-- Did you find a workaround or hack that works consistently?
-
-**Example entry:**
-```javascript
-save_context({
-  kind: "pattern",
-  title: "Always include encoding_context for vault entries",
-  body: `Saves entries without encoding_context have < 5% recall ratio.
-  Entries with encoding_context (project, arc, task) have > 25% recall.
-
-  Pattern: Always include encoding_context structured like:
-  { project: "x", arc: "y", task: "z" }
-
-  This lets Claude find entries months later by context match, not just keywords.`,
-  tags: ["bucket:context-vault", "vault-practice", "metadata"],
-  tier: "durable"
-})
-```
-
-### Lessons Learned
-- What went well? What went poorly?
-- What will you do differently next time?
-- What surprised you? What met expectations?
-
-**Example entry:**
-```javascript
-save_context({
-  kind: "insight",
-  title: "Lesson: Async migration failed due to incomplete cleanup",
-  body: `Migrated from sync to async event handlers. Thought we were careful, but missed:
-  - One old listener still on the window that created a memory leak
-  - Two components that expected synchronous behavior and broke
-  - No rollback path, had to revert by hand
-
-  Lessons:
-  - Add integration tests for async behavior before migrating
-  - Create a feature flag to roll back live if needed
-  - Disable old listeners explicitly before adding new ones`,
-  tags: ["bucket:web", "async", "migration", "gotcha"],
-  encoding_context: { project: "web", arc: "event-system-v2", task: "async-migration" }
-})
-```
-
-### References Worth Keeping
-- Did you find a useful doc, guide, or tool?
-- Did you discover a library or utility worth bookmarking?
-- Did you implement something worth referencing later?
-
-**Example entry:**
-```javascript
-save_context({
-  kind: "reference",
-  title: "PostgreSQL EXPLAIN ANALYZE guide",
-  body: "https://www.postgresql.org/docs/current/sql-explain.html\n\nUse EXPLAIN ANALYZE to see actual vs planned query costs.",
-  tags: ["database", "postgresql", "performance"],
-  source: "postgresql.org"
-})
-```
-
-## Encoding Context: Future-Proof Your Saves
-
-Always include encoding context so Claude finds entries later, even if the topic changes:
-
-```javascript
-encoding_context: {
-  project: "autohub",        // What project?
-  arc: "api-redesign",       // What arc?
-  task: "oauth-flow",        // What task?
-  // Optional:
-  date: "2026-03-31",
-  blockers: ["waiting for API docs from vendor"]
-}
-```
-
-Or as freetext:
-```javascript
-encoding_context: "Was redesigning auth flow for mobile, ran into SQLite scaling limits"
-```
-
-This context lets Claude retrieve your entry months later when starting a new auth project, even if you don't mention the old project name.
-
-## Cross-Reference with Related Entries
-
-If your entry relates to existing vault entries, link them:
-
-```javascript
-save_context({
-  title: "OAuth 2.0 implementation",
-  body: "...",
-  related_to: ["database-choice-id", "auth-architecture-id"],  // Link to other entries
-  tags: ["bucket:autohub", "authentication"]
-})
-```
-
-Then later, Claude can find related decisions by following these links.
-
-## Deduplication: Check Before Saving
-
-Before saving, search for similar entries:
-
-```javascript
-get_context({
-  query: "OAuth implementation",
-  buckets: ["autohub"],
-  kind: "decision"
-})
-```
-
-If you find a very similar entry (score > 0.85), **update it instead of duplicating:**
-
-```javascript
-save_context({
-  id: "existing-oauth-entry-id",  // Reuse the ID
-  body: "Updated implementation notes: ..."
-})
-```
-
-Low-quality deduplication ruins recall ratio. Always check first.
-
-## Bucket Scoping: Keep Entries Organized
-
-Always tag entries with their project bucket:
-
-```javascript
-tags: ["bucket:autohub", "oauth"]    // ✓ Scoped
-tags: ["oauth"]                      // ✗ Hard to find later
-```
-
-When saving: Use bucket:projectname
-When retrieving: Use buckets: ["projectname"]
-
-## Snapshot Creation: Consolidate Scattered Entries
-
-If you discovered 5+ related entries during this session, consolidate them into a snapshot:
-
-```javascript
-create_snapshot({
-  topic: "OAuth 2.0 flow in autohub",
-  buckets: ["autohub"]
-})
-```
-
-This creates a single brief that pulls together decisions, patterns, and lessons across all related entries. Much better for future sessions than searching for 5+ scattered entries.
-
-## Workflow: End-of-Session Template
-
-Use this template at the end of each session:
-
-```markdown
-## Session End Capture
-
-**Project:** [Name]
-**Arc:** [Phase or focus area]
-**Date:** [YYYY-MM-DD]
-
-### Decisions Made
-- [ ] ...
-- [ ] ...
-
-### Insights Discovered
-- [ ] ...
-- [ ] ...
-
-### Patterns Established
-- [ ] ...
-- [ ] ...
-
-### Blockers / Next Steps
-- [ ] ...
-- [ ] ...
-
-### Entries to Save
-1. Decision: [Title]
-2. Insight: [Title]
-3. Pattern: [Title]
-```
-
-For each item, save an entry to the vault using `save_context()`.
-
-## Quick Example: Real Session End
-
-**End of session on OAuth implementation:**
-
-1. **Decisions made:**
-   - Chose Clerk (managed auth) over Auth0 (cost)
-   - Decided to implement PKCE flow for mobile
-
-   → Save 2 decision entries
-
-2. **Insights discovered:**
-   - Learned that PKCE requires custom state parameter handling in mobile SDK
-   - Found that Clerk webhooks are eventually consistent (30s lag)
-
-   → Save 2 insight entries
-
-3. **Blockers:**
-   - Waiting for vendor to whitelist our callback URLs
-
-   → Save to task.md, not vault
-
-4. **Lessons learned:**
-   - Always test OAuth flow end-to-end with real device before production
-
-   → Save 1 lesson entry
-
-5. **References found:**
-   - OAuth 2.0 PKCE spec
-   - Clerk integration guide
-
-   → Save 2 reference entries
-
-**Total:** 8 vault entries saved in 10 minutes. Future sessions will discover these automatically.
-
-## When NOT to Save
-
-Skip the vault for:
-- Temporary debugging notes (save to session notes instead)
-- Task status updates (save to arc.md or task.md)
-- Exploratory dead ends (unless they're interesting gotchas)
-- Bulk raw data (use references or snapshots instead)
-
-The vault is for **persistent knowledge**, not task tracking.
-
-## Tier Selection Guide
-
-When saving, choose a tier:
-
-| Situation | Tier |
-|-----------|------|
-| New decision we'll use for months | `durable` |
-| Current implementation insight | `working` |
-| Temporary session note | `ephemeral` (auto-expires in 30d) |
-| Architecture pattern we'll reference | `durable` |
-| Debugging discovery specific to this bug | `working` (or skip) |
-
-Default to `working` unless it's architecture or a decision you'll use for a long time.