clawvault 1.1.0

package/README.md

@@ -0,0 +1,216 @@
+# ClawVault 🐘
+
+**An elephant never forgets.**
+
+Structured memory system for AI agents. Store, search, and link memories across sessions.
+
+## Requirements
+
+- **Node.js 18+**
+- **[qmd](https://github.com/Versatly/qmd)** — Local semantic search (required)
+
+```bash
+# Install qmd first
+bun install -g qmd   # or: npm install -g qmd
+
+# Then install clawvault
+npm install -g clawvault
+```
+
+## Why ClawVault?
+
+AI agents forget things. Context windows overflow, sessions end, important details get lost. ClawVault fixes that:
+
+- **Structured storage** — Organized categories, not random notes
+- **Local search** — qmd provides BM25 + semantic search with local embeddings (no API quotas)
+- **Wiki-links** — `[[connections]]` visible in Obsidian's graph view
+- **Session continuity** — Handoff/recap system for context death
+- **Token efficient** — Search instead of loading entire memory files
+
+## Quick Start
+
+```bash
+# Initialize vault with qmd collection
+clawvault init ~/memory --qmd-collection my-memory
+
+# Store memories
+clawvault remember decision "Use qmd" --content "Local embeddings, no API limits"
+clawvault remember lesson "Context death is survivable" --content "Write it down"
+clawvault capture "Quick note to process later"
+
+# Search (uses qmd)
+clawvault search "decision"           # BM25 keyword search
+clawvault vsearch "what did I decide" # Semantic search
+
+# Session management
+clawvault handoff --working-on "task1" --next "task2"  # Before context death
+clawvault recap                                          # On session start
+```
+
+**Tip:** Set `CLAWVAULT_PATH` environment variable to skip directory walk:
+```bash
+echo 'export CLAWVAULT_PATH="$HOME/memory"' >> ~/.bashrc
+```
+
+## Search: qmd vs memory_search
+
+**Use `qmd` (or `clawvault search`) — not `memory_search`**
+
+| Tool | Backend | Speed | API Limits |
+|------|---------|-------|------------|
+| `qmd search` / `clawvault search` | Local BM25 | Instant | None |
+| `qmd vsearch` / `clawvault vsearch` | Local embeddings | Fast | None |
+| `memory_search` | Gemini API | Variable | **Yes, hits quotas** |
+
+```bash
+# ✅ Use this
+qmd search "query" -c my-memory
+clawvault search "query"
+
+# ❌ Avoid (API quotas)
+memory_search
+```
+
+## Vault Structure
+
+```
+my-memory/
+├── .clawvault.json      # Config (includes qmd collection name)
+├── decisions/           # Choices with reasoning
+├── lessons/             # Things learned
+├── people/              # One file per person
+├── projects/            # Active work
+├── commitments/         # Promises and deadlines
+├── inbox/               # Quick capture (process later)
+└── handoffs/            # Session continuity
+```
+
+## Commands
+
+### Store Memories
+
+```bash
+# With type classification (recommended)
+clawvault remember <type> <title> --content "..."
+# Types: decision, lesson, fact, commitment, project, person
+
+# Quick capture
+clawvault capture "Note to self"
+
+# Manual store
+clawvault store -c decisions -t "Title" --content "..."
+```
+
+**Note:** All write commands auto-update the qmd index. Use `--no-index` to skip.
+
+### Search
+
+```bash
+clawvault search "query"           # BM25 keyword
+clawvault search "query" -c people # Filter by category
+clawvault vsearch "query"          # Semantic (local embeddings)
+```
+
+### Browse
+
+```bash
+clawvault list                # All documents
+clawvault list decisions      # By category
+clawvault get decisions/title # Specific document
+clawvault stats               # Vault overview
+```
+
+### Session Continuity
+
+```bash
+# Before context death (long pause, session end, hitting limits)
+clawvault handoff \
+  --working-on "building CRM, fixing webhook" \
+  --blocked "waiting for API key" \
+  --next "deploy to production" \
+  --decisions "chose Supabase over Firebase" \
+  --feeling "focused"
+
+# On session start
+clawvault recap           # Full markdown recap
+clawvault recap --brief   # Token-efficient version
+clawvault recap --json    # For programmatic use
+
+# Health check
+clawvault doctor
+```
+
+## Agent Setup (AGENTS.md)
+
+Add this to your `AGENTS.md` to ensure proper memory habits:
+
+```markdown
+## Memory
+
+**Write everything down. Memory doesn't survive session restarts.**
+
+### Search (use qmd, not memory_search)
+\`\`\`bash
+qmd search "query" -c your-memory    # Fast keyword
+qmd vsearch "query" -c your-memory   # Semantic
+\`\`\`
+
+### Store
+\`\`\`bash
+clawvault remember decision "Title" --content "..."
+clawvault remember lesson "Title" --content "..."
+\`\`\`
+
+### Session Handoff
+Before context death:
+\`\`\`bash
+clawvault handoff --working-on "..." --next "..."
+\`\`\`
+
+On wake:
+\`\`\`bash
+clawvault recap
+\`\`\`
+
+### Why qmd over memory_search?
+- Local embeddings — no API quotas
+- Always works — no external dependencies
+- Fast — instant BM25, quick semantic
+```
+
+## Templates
+
+ClawVault includes templates for common memory types:
+
+- `decision.md` — Choices with context and reasoning
+- `lesson.md` — Things learned
+- `person.md` — People you work with
+- `project.md` — Active work
+- `handoff.md` — Session state before context death
+- `daily.md` — Daily notes
+
+Use with: `clawvault store -c category -t "Title" -f decision`
+
+## Library Usage
+
+```typescript
+import { ClawVault, createVault, findVault } from 'clawvault';
+
+const vault = await createVault('./memory', { qmdCollection: 'my-memory' });
+
+await vault.store({
+  category: 'decisions',
+  title: 'Use ClawVault',
+  content: 'Decided to use ClawVault for memory.',
+});
+
+const results = await vault.find('memory', { limit: 5 });
+```
+
+## License
+
+MIT
+
+---
+
+*"An elephant never forgets." — Now neither do you.* 🐘