Initial memory skill - agent memory with pgvector semantic search

SKILL.md

@@ -0,0 +1,186 @@
+---
+name: memory
+description: Agent memory with semantic search via pgvector
+metadata:
+  version: "1.0.0"
+  vibestack:
+    main: false
+    requires:
+      - postgres
+---
+
+# Memory Skill
+
+Lightweight agent memory with semantic search using PostgreSQL + pgvector.
+
+## What Gets Stored
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **conversation** | Chat messages with context | User questions, agent responses |
+| **execution** | Task runs and outcomes | Commands run, success/failure, duration |
+| **finding** | Discoveries and solutions | "Port 8080 was blocked by firewall" |
+| **memory** | Persistent agent knowledge | Preferences, learned patterns |
+
+## Features
+
+- Semantic search across all memory types
+- Automatic embedding on insert
+- Configurable retention policies
+- Simple REST API for CRUD + search
+- Lightweight local embeddings (~90MB model)
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEMORY_PORT` | `8081` | API port |
+| `MEMORY_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformers model |
+| `MEMORY_RETENTION_DAYS` | `30` | Auto-delete after N days (0 = forever) |
+| `MEMORY_MAX_RESULTS` | `10` | Default search results limit |
+
+## API
+
+### Store Memory
+
+```bash
+# Store a finding
+curl -X POST http://localhost:8081/memory \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "finding",
+    "content": "Redis was OOM - increased REDIS_MAXMEMORY to 256mb",
+    "metadata": {"skill": "redis", "severity": "resolved"}
+  }'
+
+# Store conversation
+curl -X POST http://localhost:8081/memory \
+  -d '{
+    "type": "conversation",
+    "content": "User asked how to check disk space. Showed df -h command.",
+    "metadata": {"session_id": "abc123"}
+  }'
+```
+
+### Search Memory
+
+```bash
+# Semantic search
+curl "http://localhost:8081/search?q=redis+memory+issue&limit=5"
+
+# Filter by type
+curl "http://localhost:8081/search?q=disk+space&type=conversation"
+
+# Filter by metadata
+curl "http://localhost:8081/search?q=error&metadata.skill=postgres"
+```
+
+### Response Format
+
+```json
+{
+  "results": [
+    {
+      "id": "01HQXYZ...",
+      "type": "finding",
+      "content": "Redis was OOM - increased REDIS_MAXMEMORY to 256mb",
+      "metadata": {"skill": "redis"},
+      "similarity": 0.87,
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+### List Recent
+
+```bash
+# Recent memories by type
+curl "http://localhost:8081/memory?type=finding&limit=20"
+
+# All recent
+curl "http://localhost:8081/memory?limit=50"
+```
+
+### Delete
+
+```bash
+# Delete specific memory
+curl -X DELETE "http://localhost:8081/memory/01HQXYZ..."
+
+# Bulk delete by type older than N days
+curl -X DELETE "http://localhost:8081/memory?type=execution&older_than=7d"
+```
+
+## Database Schema
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE memories (
+    id TEXT PRIMARY KEY,
+    type TEXT NOT NULL,
+    content TEXT NOT NULL,
+    embedding vector(384),
+    metadata JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_memories_type ON memories(type);
+CREATE INDEX idx_memories_created ON memories(created_at);
+CREATE INDEX idx_memories_embedding ON memories USING ivfflat (embedding vector_cosine_ops);
+```
+
+## Usage Patterns
+
+### Agent Self-Reflection
+
+Before starting a task, search for relevant past experiences:
+
+```bash
+# "Have I done something like this before?"
+curl "http://localhost:8081/search?q=deploy+nodejs+application"
+```
+
+### Error Resolution
+
+When encountering an error, check if it's been seen before:
+
+```bash
+curl "http://localhost:8081/search?q=connection+refused+port+5432&type=finding"
+```
+
+### Conversation Context
+
+Recall previous discussions with user:
+
+```bash
+curl "http://localhost:8081/search?q=user+preferences+formatting&type=conversation"
+```
+
+## Embedding Model
+
+Uses `all-MiniLM-L6-v2` from sentence-transformers:
+- 384 dimensions
+- ~90MB download
+- Fast inference (~5ms per embedding)
+- Good quality for short texts
+
+For even smaller footprint, set `MEMORY_MODEL=all-MiniLM-L3-v2` (~60MB, slightly lower quality).
+
+## Integration
+
+Other skills can store memories by POSTing to the API:
+
+```bash
+# In any skill's script
+store_memory() {
+    curl -s -X POST http://localhost:8081/memory \
+        -H "Content-Type: application/json" \
+        -d "{\"type\":\"$1\",\"content\":\"$2\",\"metadata\":$3}"
+}
+
+store_memory "execution" "Backup completed successfully" '{"skill":"backup","duration":45}'
+```