memory/SKILL.md

---
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}'
```