memory/SKILL.md

name, description, metadata

name	description	metadata
memory	Agent memory with semantic search via pgvector	version vibestack 1.0.0 main requires false 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

# 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

# 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

{
  "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

# Recent memories by type
curl "http://localhost:8081/memory?type=finding&limit=20"

# All recent
curl "http://localhost:8081/memory?limit=50"

Delete

# 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

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:

# "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:

curl "http://localhost:8081/search?q=connection+refused+port+5432&type=finding"

Conversation Context

Recall previous discussions with user:

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:

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