@swarmdo/cli 1.4.8

package/.claude/skills/sdo-agentdb-vector-search/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: "AgentDB Vector Search"
+description: "Implement semantic vector search with AgentDB for intelligent document retrieval, similarity matching, and context-aware querying. Use when building RAG systems, semantic search engines, or intelligent knowledge bases."
+---
+
+# AgentDB Vector Search
+
+## What This Skill Does
+
+Implements vector-based semantic search using AgentDB's high-performance vector database with **~1.9x-4.7x measured faster** operations than traditional solutions. Features HNSW indexing, quantization, and sub-millisecond search (<100µs).
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow or standalone)
+- OpenAI API key (for embeddings) or custom embedding model
+
+## Quick Start with CLI
+
+### Initialize Vector Database
+
+```bash
+# Initialize with default dimensions (1536 for OpenAI ada-002)
+npx agentdb@latest init ./vectors.db
+
+# Custom dimensions for different embedding models
+npx agentdb@latest init ./vectors.db --dimension 768  # sentence-transformers
+npx agentdb@latest init ./vectors.db --dimension 384  # all-MiniLM-L6-v2
+
+# Use preset configurations
+npx agentdb@latest init ./vectors.db --preset small   # <10K vectors
+npx agentdb@latest init ./vectors.db --preset medium  # 10K-100K vectors
+npx agentdb@latest init ./vectors.db --preset large   # >100K vectors
+
+# In-memory database for testing
+npx agentdb@latest init ./vectors.db --in-memory
+```
+
+### Query Vector Database
+
+```bash
+# Basic similarity search
+npx agentdb@latest query ./vectors.db "[0.1,0.2,0.3,...]"
+
+# Top-k results
+npx agentdb@latest query ./vectors.db "[0.1,0.2,0.3]" -k 10
+
+# With similarity threshold (cosine similarity)
+npx agentdb@latest query ./vectors.db "0.1 0.2 0.3" -t 0.75 -m cosine
+
+# Different distance metrics
+npx agentdb@latest query ./vectors.db "[...]" -m euclidean  # L2 distance
+npx agentdb@latest query ./vectors.db "[...]" -m dot        # Dot product
+
+# JSON output for automation
+npx agentdb@latest query ./vectors.db "[...]" -f json -k 5
+
+# Verbose output with distances
+npx agentdb@latest query ./vectors.db "[...]" -v
+```
+
+### Import/Export Vectors
+
+```bash
+# Export vectors to JSON
+npx agentdb@latest export ./vectors.db ./backup.json
+
+# Import vectors from JSON
+npx agentdb@latest import ./backup.json
+
+# Get database statistics
+npx agentdb@latest stats ./vectors.db
+```
+
+## Quick Start with API
+
+```typescript
+import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank';
+
+// Initialize with vector search optimizations
+const adapter = await createAgentDBAdapter({
+  dbPath: '.agentdb/vectors.db',
+  enableLearning: false,       // Vector search only
+  enableReasoning: true,       // Enable semantic matching
+  quantizationType: 'binary',  // 32x memory reduction
+  cacheSize: 1000,             // Fast retrieval
+});
+
+// Store document with embedding
+const text = "The quantum computer achieved 100 qubits";
+const embedding = await computeEmbedding(text);
+
+await adapter.insertPattern({
+  id: '',
+  type: 'document',
+  domain: 'technology',
+  pattern_data: JSON.stringify({
+    embedding,
+    text,
+    metadata: { category: "quantum", date: "2025-01-15" }
+  }),
+  confidence: 1.0,
+  usage_count: 0,
+  success_count: 0,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Semantic search with MMR (Maximal Marginal Relevance)
+const queryEmbedding = await computeEmbedding("quantum computing advances");
+const results = await adapter.retrieveWithReasoning(queryEmbedding, {
+  domain: 'technology',
+  k: 10,
+  useMMR: true,              // Diverse results
+  synthesizeContext: true,    // Rich context
+});
+```
+
+## Core Features
+
+### 1. Vector Storage
+```typescript
+// Store with automatic embedding
+await db.storeWithEmbedding({
+  content: "Your document text",
+  metadata: { source: "docs", page: 42 }
+});
+```
+
+### 2. Similarity Search
+```typescript
+// Find similar documents
+const similar = await db.findSimilar("quantum computing", {
+  limit: 5,
+  minScore: 0.75
+});
+```
+
+### 3. Hybrid Search (Vector + Metadata)
+```typescript
+// Combine vector similarity with metadata filtering
+const results = await db.hybridSearch({
+  query: "machine learning models",
+  filters: {
+    category: "research",
+    date: { $gte: "2024-01-01" }
+  },
+  limit: 20
+});
+```
+
+## Advanced Usage
+
+### RAG (Retrieval Augmented Generation)
+```typescript
+// Build RAG pipeline
+async function ragQuery(question: string) {
+  // 1. Get relevant context
+  const context = await db.searchSimilar(
+    await embed(question),
+    { limit: 5, threshold: 0.7 }
+  );
+
+  // 2. Generate answer with context
+  const prompt = `Context: ${context.map(c => c.text).join('\n')}
+Question: ${question}`;
+
+  return await llm.generate(prompt);
+}
+```
+
+### Batch Operations
+```typescript
+// Efficient batch storage
+await db.batchStore(documents.map(doc => ({
+  text: doc.content,
+  embedding: doc.vector,
+  metadata: doc.meta
+})));
+```
+
+## MCP Server Integration
+
+```bash
+# Start AgentDB MCP server for Claude Code
+npx agentdb@latest mcp
+
+# Add to Claude Code (one-time setup)
+claude mcp add agentdb npx agentdb@latest mcp
+
+# Now use MCP tools in Claude Code:
+# - agentdb_query: Semantic vector search
+# - agentdb_store: Store documents with embeddings
+# - agentdb_stats: Database statistics
+```
+
+## Performance Benchmarks
+
+```bash
+# Run comprehensive benchmarks
+npx agentdb@latest benchmark
+
+# Results:
+# ✅ Pattern Search: ~4.7x faster (100µs vs 15ms)
+# ✅ Batch Insert: 500x faster (2ms vs 1s for 100 vectors)
+# ✅ Large-scale Query: ~4.7x faster (8ms vs 100s at 1M vectors)
+# ✅ Memory Efficiency: 4-32x reduction with quantization
+```
+
+## Quantization Options
+
+AgentDB provides multiple quantization strategies for memory efficiency:
+
+### Binary Quantization (32x reduction)
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'binary',  // 768-dim → 96 bytes
+});
+```
+
+### Scalar Quantization (4x reduction)
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'scalar',  // 768-dim → 768 bytes
+});
+```
+
+### Product Quantization (8-16x reduction)
+```typescript
+const adapter = await createAgentDBAdapter({
+  quantizationType: 'product',  // 768-dim → 48-96 bytes
+});
+```
+
+## Distance Metrics
+
+```bash
+# Cosine similarity (default, best for most use cases)
+npx agentdb@latest query ./db.sqlite "[...]" -m cosine
+
+# Euclidean distance (L2 norm)
+npx agentdb@latest query ./db.sqlite "[...]" -m euclidean
+
+# Dot product (for normalized vectors)
+npx agentdb@latest query ./db.sqlite "[...]" -m dot
+```
+
+## Advanced Features
+
+### HNSW Indexing
+- **O(log n) search complexity**
+- **Sub-millisecond retrieval** (<100µs)
+- **Automatic index building**
+
+### Caching
+- **1000 pattern in-memory cache**
+- **<1ms pattern retrieval**
+- **Automatic cache invalidation**
+
+### MMR (Maximal Marginal Relevance)
+- **Diverse result sets**
+- **Avoid redundancy**
+- **Balance relevance and diversity**
+
+## Performance Tips
+
+1. **Enable HNSW indexing**: Automatic with AgentDB, 10-100x faster
+2. **Use quantization**: Binary (32x), Scalar (4x), Product (8-16x) memory reduction
+3. **Batch operations**: 500x faster for bulk inserts
+4. **Match dimensions**: 1536 (OpenAI), 768 (sentence-transformers), 384 (MiniLM)
+5. **Similarity threshold**: Start at 0.7 for quality, adjust based on use case
+6. **Enable caching**: 1000 pattern cache for frequent queries
+
+## Troubleshooting
+
+### Issue: Slow search performance
+```bash
+# Check if HNSW indexing is enabled (automatic)
+npx agentdb@latest stats ./vectors.db
+
+# Expected: <100µs search time
+```
+
+### Issue: High memory usage
+```bash
+# Enable binary quantization (32x reduction)
+# Use in adapter: quantizationType: 'binary'
+```
+
+### Issue: Poor relevance
+```bash
+# Adjust similarity threshold
+npx agentdb@latest query ./db.sqlite "[...]" -t 0.8  # Higher threshold
+
+# Or use MMR for diverse results
+# Use in adapter: useMMR: true
+```
+
+### Issue: Wrong dimensions
+```bash
+# Check embedding model dimensions:
+# - OpenAI ada-002: 1536
+# - sentence-transformers: 768
+# - all-MiniLM-L6-v2: 384
+
+npx agentdb@latest init ./db.sqlite --dimension 768
+```
+
+## Database Statistics
+
+```bash
+# Get comprehensive stats
+npx agentdb@latest stats ./vectors.db
+
+# Shows:
+# - Total patterns/vectors
+# - Database size
+# - Average confidence
+# - Domains distribution
+# - Index status
+```
+
+## Performance Characteristics
+
+- **Vector Search**: <100µs (HNSW indexing)
+- **Pattern Retrieval**: <1ms (with cache)
+- **Batch Insert**: 2ms for 100 vectors
+- **Memory Efficiency**: 4-32x reduction with quantization
+- **Scalability**: Handles 1M+ vectors efficiently
+- **Latency**: Sub-millisecond for most operations
+
+## Learn More
+
+- GitHub: the upstream project (see NOTICE)
+- Documentation: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
+- MCP Integration: `npx agentdb@latest mcp` for Claude Code
+- Website: https://swarmdo.com
+- CLI Help: `npx agentdb@latest --help`
+- Command Help: `npx agentdb@latest help <command>`

package/.claude/skills/sdo-browser/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: sdo-browser
+description: Web browser automation with AI-optimized snapshots for swarmdo agents
+version: 1.0.0
+triggers:
+  - /browser
+  - browse
+  - web automation
+  - scrape
+  - navigate
+  - screenshot
+tools:
+  - browser/open
+  - browser/snapshot
+  - browser/click
+  - browser/fill
+  - browser/screenshot
+  - browser/close
+---
+
+# Browser Automation Skill
+
+Web browser automation using agent-browser with AI-optimized snapshots. Reduces context by 93% using element refs (@e1, @e2) instead of full DOM.
+
+## Core Workflow
+
+```bash
+# 1. Navigate to page
+agent-browser open <url>
+
+# 2. Get accessibility tree with element refs
+agent-browser snapshot -i    # -i = interactive elements only
+
+# 3. Interact using refs from snapshot
+agent-browser click @e2
+agent-browser fill @e3 "text"
+
+# 4. Re-snapshot after page changes
+agent-browser snapshot -i
+```
+
+## Quick Reference
+
+### Navigation
+| Command | Description |
+|---------|-------------|
+| `open <url>` | Navigate to URL |
+| `back` | Go back |
+| `forward` | Go forward |
+| `reload` | Reload page |
+| `close` | Close browser |
+
+### Snapshots (AI-Optimized)
+| Command | Description |
+|---------|-------------|
+| `snapshot` | Full accessibility tree |
+| `snapshot -i` | Interactive elements only (buttons, links, inputs) |
+| `snapshot -c` | Compact (remove empty elements) |
+| `snapshot -d 3` | Limit depth to 3 levels |
+| `screenshot [path]` | Capture screenshot (base64 if no path) |
+
+### Interaction
+| Command | Description |
+|---------|-------------|
+| `click <sel>` | Click element |
+| `fill <sel> <text>` | Clear and fill input |
+| `type <sel> <text>` | Type with key events |
+| `press <key>` | Press key (Enter, Tab, etc.) |
+| `hover <sel>` | Hover element |
+| `select <sel> <val>` | Select dropdown option |
+| `check/uncheck <sel>` | Toggle checkbox |
+| `scroll <dir> [px]` | Scroll page |
+
+### Get Info
+| Command | Description |
+|---------|-------------|
+| `get text <sel>` | Get text content |
+| `get html <sel>` | Get innerHTML |
+| `get value <sel>` | Get input value |
+| `get attr <sel> <attr>` | Get attribute |
+| `get title` | Get page title |
+| `get url` | Get current URL |
+
+### Wait
+| Command | Description |
+|---------|-------------|
+| `wait <selector>` | Wait for element |
+| `wait <ms>` | Wait milliseconds |
+| `wait --text "text"` | Wait for text |
+| `wait --url "pattern"` | Wait for URL |
+| `wait --load networkidle` | Wait for load state |
+
+### Sessions
+| Command | Description |
+|---------|-------------|
+| `--session <name>` | Use isolated session |
+| `session list` | List active sessions |
+
+## Selectors
+
+### Element Refs (Recommended)
+```bash
+# Get refs from snapshot
+agent-browser snapshot -i
+# Output: button "Submit" [ref=e2]
+
+# Use ref to interact
+agent-browser click @e2
+```
+
+### CSS Selectors
+```bash
+agent-browser click "#submit"
+agent-browser fill ".email-input" "test@test.com"
+```
+
+### Semantic Locators
+```bash
+agent-browser find role button click --name "Submit"
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find testid "login-btn" click
+```
+
+## Examples
+
+### Login Flow
+```bash
+agent-browser open https://example.com/login
+agent-browser snapshot -i
+agent-browser fill @e2 "user@example.com"
+agent-browser fill @e3 "password123"
+agent-browser click @e4
+agent-browser wait --url "**/dashboard"
+```
+
+### Form Submission
+```bash
+agent-browser open https://example.com/contact
+agent-browser snapshot -i
+agent-browser fill @e1 "John Doe"
+agent-browser fill @e2 "john@example.com"
+agent-browser fill @e3 "Hello, this is my message"
+agent-browser click @e4
+agent-browser wait --text "Thank you"
+```
+
+### Data Extraction
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+# Iterate through product refs
+agent-browser get text @e1  # Product name
+agent-browser get text @e2  # Price
+agent-browser get attr @e3 href  # Link
+```
+
+### Multi-Session (Swarm)
+```bash
+# Session 1: Navigator
+agent-browser --session nav open https://example.com
+agent-browser --session nav state save auth.json
+
+# Session 2: Scraper (uses same auth)
+agent-browser --session scrape state load auth.json
+agent-browser --session scrape open https://example.com/data
+agent-browser --session scrape snapshot -i
+```
+
+## Integration with Swarmdo
+
+### MCP Tools
+All browser operations are available as MCP tools with `browser/` prefix:
+- `browser/open`
+- `browser/snapshot`
+- `browser/click`
+- `browser/fill`
+- `browser/screenshot`
+- etc.
+
+### Memory Integration
+```bash
+# Store successful patterns
+npx @swarmdo/cli memory store --namespace browser-patterns --key "login-flow" --value "snapshot->fill->click->wait"
+
+# Retrieve before similar task
+npx @swarmdo/cli memory search --query "login automation"
+```
+
+### Hooks
+```bash
+# Pre-browse hook (get context)
+npx @swarmdo/cli hooks pre-edit --file "browser-task.ts"
+
+# Post-browse hook (record success)
+npx @swarmdo/cli hooks post-task --task-id "browse-1" --success true
+```
+
+## Tips
+
+1. **Always use snapshots** - They're optimized for AI with refs
+2. **Prefer `-i` flag** - Gets only interactive elements, smaller output
+3. **Use refs, not selectors** - More reliable, deterministic
+4. **Re-snapshot after navigation** - Page state changes
+5. **Use sessions for parallel work** - Each session is isolated

package/.claude/skills/sdo-caveman-compress/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: sdo-caveman-compress
+description: >
+  Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
+  to save input tokens. Preserves all technical substance, code, URLs, and structure.
+  Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md.
+  Trigger: /sdo-caveman-compress FILEPATH or "compress memory file"
+---
+
+# Caveman Compress
+
+## Purpose
+
+Compress natural language files (CLAUDE.md, todos, preferences) into caveman-speak to reduce input tokens. Compressed version overwrites original. Human-readable backup saved as `<filename>.original.md`.
+
+## Trigger
+
+`/sdo-caveman-compress <filepath>` or when user asks to compress a memory file.
+
+## Process
+
+1. The compression scripts live in `scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `scripts/__main__.py` next to this SKILL.md.
+
+2. From the directory containing this SKILL.md, run:
+
+python3 -m scripts <absolute_filepath>
+
+3. The CLI will:
+- detect file type (no tokens)
+- call Claude to compress
+- validate output (no tokens)
+- if errors: cherry-pick fix with Claude (targeted fixes only, no recompression)
+- retry up to 2 times
+- if still failing after 2 retries: report error to user, leave original file untouched
+
+4. Return result to user
+
+## Compression Rules
+
+### Remove
+- Articles: a, an, the
+- Filler: just, really, basically, actually, simply, essentially, generally
+- Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
+- Hedging: "it might be worth", "you could consider", "it would be good to"
+- Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
+- Connective fluff: "however", "furthermore", "additionally", "in addition"
+
+### Preserve EXACTLY (never modify)
+- Code blocks (fenced ``` and indented)
+- Inline code (`backtick content`)
+- URLs and links (full URLs, markdown links)
+- File paths (`/src/components/...`, `./config.yaml`)
+- Commands (`npm install`, `git commit`, `docker build`)
+- Technical terms (library names, API names, protocols, algorithms)
+- Proper nouns (project names, people, companies)
+- Dates, version numbers, numeric values
+- Environment variables (`$HOME`, `NODE_ENV`)
+
+### Preserve Structure
+- All markdown headings (keep exact heading text, compress body below)
+- Bullet point hierarchy (keep nesting level)
+- Numbered lists (keep numbering)
+- Tables (compress cell text, keep structure)
+- Frontmatter/YAML headers in markdown files
+
+### Compress
+- Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
+- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
+- Drop "you should", "make sure to", "remember to" — just state the action
+- Merge redundant bullets that say the same thing differently
+- Keep one example where multiple examples show the same pattern
+
+CRITICAL RULE:
+Anything inside ``` ... ``` must be copied EXACTLY.
+Do not:
+- remove comments
+- remove spacing
+- reorder lines
+- shorten commands
+- simplify anything
+
+Inline code (`...`) must be preserved EXACTLY.
+Do not modify anything inside backticks.
+
+If file contains code blocks:
+- Treat code blocks as read-only regions
+- Only compress text outside them
+- Do not merge sections around code
+
+## Pattern
+
+Original:
+> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
+
+Compressed:
+> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
+
+Original:
+> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.
+
+Compressed:
+> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
+
+## Boundaries
+
+- ONLY compress natural language files (.md, .txt, .typ, .typst, .tex, extensionless)
+- NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
+- If file has mixed content (prose + code), compress ONLY the prose sections
+- If unsure whether something is code or prose, leave it unchanged
+- Original file is backed up as FILE.original.md before overwriting
+- Never compress FILE.original.md (skip it)

package/.claude/skills/sdo-caveman-compress/scripts/__init__.py

@@ -0,0 +1,9 @@
+"""Caveman compress scripts.
+
+This package provides tools to compress natural language markdown files
+into caveman format to save input tokens.
+"""
+
+__all__ = ["cli", "compress", "detect", "validate"]
+
+__version__ = "1.0.0"

package/.claude/skills/sdo-caveman-compress/scripts/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()