context-vault 3.18.0 → 3.20.0

package/skills/memory-management/SKILL.md

@@ -1,237 +0,0 @@
-# Memory Management — Using the Vault for Persistent Memory
-
-Learn when to save information to your vault, how to organize it, and how to keep the vault healthy and retrievable.
-
-## Core Principle: Save Decisions and Insights, Skip Transient Data
-
-The vault is for **persistent knowledge** that will be useful across future sessions and projects. It is not a chat history or temporary scratchpad.
-
-**Always Save:**
-- Decisions (why you chose X over Y, constraints that matter, trade-offs)
-- Insights (discoveries, patterns, "aha" moments)
-- Architectures and design rationales
-- Lessons learned (what worked, what didn't)
-- Project context (goals, stakeholders, constraints)
-
-**Skip:**
-- Exploratory work (debugging steps, failed hypotheses)
-- Task status (use task.md files instead)
-- Temporary notes (use your session notes, not vault)
-- Bulk data (use references or snapshots instead)
-
-## Entry Kinds: Choosing the Right Category
-
-Always pick one kind when saving. The kind affects how Claude will discover and use the entry:
-
-| Kind | When to use | Example |
-|------|-------------|---------|
-| **insight** | Discoveries and aha moments. How something works, why something happened, what you learned. | "SQLite ANALYZE needed after 1M+ row inserts to keep query planner efficient" |
-| **decision** | Choices you made, their rationales, constraints considered, alternatives rejected. This is your decision journal. | "Chose Turso (managed SQLite) over self-hosted PostgreSQL for cost + edge compatibility" |
-| **pattern** | Repeated approaches, best practices, conventions, tactics. Reusable playbooks. | "Always include encoding_context in saves so entries are discoverable 6 months later" |
-| **reference** | External sources, URLs, docs, commands, templates. Pointers to information outside the vault. | "PostgreSQL EXPLAIN ANALYZE guide: https://..." |
-| **contact** | People: their roles, expertise, how to reach them. Requires identity_key (their email or ID). | Contact: Alice Chen, Product Lead, alice@acme.com |
-| **source** | Books, articles, papers, tools. Requires identity_key (unique name). | "The Mythical Man-Month" by Fred Brooks |
-
-## Tag Hygiene: Organizing for Discoverability
-
-Tags are how Claude finds your entries. Use these patterns:
-
-**Project/Bucket Tags (required):** Use the `bucket:` prefix to scope entries to projects:
-```
-bucket:autohub           # For autohub project
-bucket:context-vault     # For context-vault project
-bucket:platform          # For platform infrastructure
-```
-
-When saving: `tags: ["bucket:autohub", "authentication", "oauth"]`
-
-When retrieving: `get_context(buckets: ["autohub"])` to load only autohub entries.
-
-**Topic Tags (optional, lowercase):** Use lowercase, single-word tags for topics:
-```
-tags: ["database", "caching", "performance"]  ✓
-tags: ["Database Design", "User Cache"]       ✗ (avoid capitals, multi-word)
-```
-
-**Tiers (set via `tier` parameter, not tags):**
-- `working` (default): Active context, available always
-- `durable`: Long-term reference (decisions, architecture)
-- `ephemeral`: Auto-expires (session notes, temporary captures)
-
-## Identity Keys: Deduplicating Entities
-
-For entity kinds (contact, source, project), always provide an `identity_key`. This is the unique identifier that prevents duplicates:
-
-**Contact example:**
-```
-kind: contact
-identity_key: alice@acme.com
-title: Alice Chen
-meta: { role: "Product Lead", team: "Backend" }
-```
-
-If you save another contact with the same `identity_key`, it updates the existing entry instead of creating a duplicate.
-
-**Source example:**
-```
-kind: source
-identity_key: mythical-man-month
-title: The Mythical Man-Month
-meta: { author: "Fred Brooks", year: 1975 }
-```
-
-## Encoding Context: Making Entries Discoverable Later
-
-**Encoding context** captures the situation when you saved an entry, so Claude can find it later even if you don't remember the exact topic.
-
-Always include when saving:
-```
-encoding_context: {
-  project: "autohub",
-  arc: "api-redesign",
-  task: "implementing oauth2 flow"
-}
-```
-
-Or as free text:
-```
-encoding_context: "Was designing auth flow for mobile client in Q1 2026"
-```
-
-**Why it matters:** Six months later, when starting a new auth project, Claude loads your old decision by context match, not just keyword search.
-
-## Recall Ratio: Measuring Vault Health
-
-The **recall ratio** shows what fraction of your entries are actually retrieved in real usage.
-
-- Target: 0.30 (30% of entries recalled per month)
-- Typical: 0.07 (7% of entries recalled)
-- If < 0.10: Your entries are not well-organized. Use buckets, encoding_context, and snapshots to improve discoverability.
-
-**Improve recall:**
-1. Use consistent bucket tags across sessions
-2. Always include encoding_context (project, arc, task)
-3. Create snapshots to consolidate scattered entries on the same topic
-4. Use supersedes to retire old, replaced entries
-
-## Superseding: Retiring Old Entries
-
-When you replace an entry (e.g., update a decision), don't delete the old one. Instead, save the new one with `supersedes`:
-
-```javascript
-save_context({
-  title: "OAuth 2.0 implementation — updated Q2",
-  kind: "decision",
-  body: "... new decision rationale ...",
-  supersedes: ["old-oauth-entry-id"]
-})
-```
-
-The old entry stays but is marked as superseded and hidden from future searches. This keeps your decision history intact.
-
-## Deduplication: Checking Before You Save
-
-Before saving, always check if the entry already exists:
-
-```javascript
-get_context({
-  query: "OAuth 2.0 flow",
-  kind: "decision",
-  buckets: ["autohub"]
-})
-```
-
-If you find a very similar entry (score > 0.85), update it instead of creating a new one:
-
-```javascript
-save_context({
-  id: "existing-entry-id",  // Reuse the ID
-  body: "... updated content ..."
-})
-```
-
-## Tier System: Lifecycle Management
-
-Entries have three tiers that affect retention:
-
-| Tier | Lifetime | Use for |
-|------|----------|---------|
-| **ephemeral** | 7-30 days | Session notes, temporary captures, exploration |
-| **working** (default) | Indefinite | Active decisions, current insights, patterns in use |
-| **durable** | Indefinite + archive | Architecture decisions, lessons learned, core reference |
-
-Set tier when saving:
-```javascript
-save_context({
-  body: "...",
-  tier: "durable"  // Will be archived, never deleted
-})
-```
-
-Ephemeral entries auto-expire. Set expiry with `expires_at: "2026-04-30"`.
-
-## Data Categories: What Gets Stored Where
-
-The vault organizes entries into three categories, each with different handling:
-
-| Category | Scope | Use | Example |
-|----------|-------|-----|---------|
-| **knowledge** | Personal or team vault | Decisions, insights, patterns, references | "SQLite + embeddings architecture for RAG" |
-| **entity** | Team vault only | People, projects, tools, vendors | "Alice Chen, alice@acme.com" |
-| **event** | Cold storage | Session logs, metrics, audit trail | "Deprecated API endpoint X on 2026-03-30" |
-
-- Knowledge and entity entries are indexed for semantic search
-- Events are kept separate (no search by default, access via category filter)
-- Only visible to the vault you saved to (personal or team)
-
-## Workflow: Save → Search → Update → Retire
-
-**Save:**
-```javascript
-save_context({
-  kind: "decision",
-  title: "Use Turso for database",
-  body: "Chose Turso over PostgreSQL because...",
-  tags: ["bucket:autohub", "database", "infrastructure"],
-  encoding_context: { project: "autohub", arc: "backend-v2" },
-  tier: "durable"
-})
-```
-
-**Search (later):**
-```javascript
-get_context({
-  query: "database choice for autohub",
-  buckets: ["autohub"]
-})
-```
-
-**Update (when context changes):**
-```javascript
-save_context({
-  id: "turso-decision-id",
-  body: "Still using Turso, but now with edge replication for..."
-})
-```
-
-**Retire (when no longer relevant):**
-```javascript
-save_context({
-  title: "MySQL migration plan — SUPERSEDED",
-  kind: "decision",
-  body: "No longer pursuing this. Staying with Turso.",
-  supersedes: ["mysql-migration-id"]
-})
-```
-
-## Quick Checklist
-
-Before saving, verify:
-- [ ] Is this a decision, insight, pattern, or reference? (Pick one kind)
-- [ ] Does it have a bucket:project tag?
-- [ ] Does it include encoding_context for future retrieval?
-- [ ] Did I check for duplicates first (get_context)?
-- [ ] Is the title clear and searchable?
-- [ ] Will I actually need this in a future session or project?
-
-If you can't answer yes to most of these, save as ephemeral or skip entirely.