🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Pgmemory
🦀 ClawHub

Pgmemory

by @jbushman

Persistent semantic memory for OpenClaw agents — PostgreSQL + pgvector

Versionv1.2.0
Downloads1,000
#database#social-media#legal
TERMINAL
clawhub install pgmemory

📖 About This Skill

name: pgmemory version: 1.2.0 description: Persistent semantic memory for OpenClaw agents — PostgreSQL + pgvector author: jbushman tags: [memory, postgresql, pgvector, embeddings, agents]

pgmemory

Gives OpenClaw agents persistent semantic memory backed by PostgreSQL + pgvector.

Agents wake up fresh every session. pgmemory fixes that — decisions, constraints, infrastructure facts, and discoveries persist across sessions and surface automatically when relevant.

Setup

Run once after installing:

python3 ~/.openclaw/skills/pgmemory/scripts/setup.py

The wizard handles everything: Docker/PostgreSQL, migrations, embedding provider, AGENTS.md scaffolding, and decay cron.

When to use this skill

Read this SKILL.md when:

  • Setting up pgmemory for the first time
  • Adding a new OpenClaw agent and want it to have persistent memory
  • Diagnosing memory issues (run --doctor)
  • Switching embedding providers
  • Understanding how memory decay or archiving works

    • Core commands

    Write a memory

    python3 ~/.openclaw/skills/pgmemory/scripts/write_memory.py \
  --key "unique.descriptive.key" \
  --content "What to remember" \
  --category decision \
  --importance 3

    Categories: decision · constraint · infrastructure · vision · preference · context · task

    Importance:

  • 3 = critical — decisions, constraints, infrastructure. Never expires. Always loaded.
  • 2 = important — context, preferences. Expires after 180 days if unused.
  • 1 = transient — low-value notes. Expires after 30 days.

    • Search memories

    # Semantic search
python3 ~/.openclaw/skills/pgmemory/scripts/query_memory.py "database connection"
    Load all critical memories (importance 3)
    
python3 ~/.openclaw/skills/pgmemory/scripts/query_memory.py --importance 3 --limit 20
    Stats
    
python3 ~/.openclaw/skills/pgmemory/scripts/query_memory.py --stats
    List all keys
    
python3 ~/.openclaw/skills/pgmemory/scripts/query_memory.py --list

    Maintenance

    # Full health check
python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --doctor
    Validate config
    
python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --validate
    Run pending migrations
    
python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --migrate
    Sync pgmemory into all OpenClaw agent workspaces
    
python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --sync-agents
    Run decay cycle manually
    
python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --decay

    What to write to memory

    Write immediately when:

  • You make a decision about architecture, tooling, or approach
  • You discover a constraint — something that will bite you if forgotten
  • You complete infrastructure work (migrations, deployments, config changes)
  • You identify a preference or vision that should guide future work
  • A sub-agent completes — harvest its important findings

    • Skip writing for:

  • Casual conversation
  • Things already in MEMORY.md or other workspace files
  • Anything you'd classify as importance 1 unless it's genuinely useful

    • Multi-agent setup

    Each OpenClaw agent gets its own namespace (= agent ID). Run --sync-agents after adding a new agent to scaffold pgmemory automatically:

    openclaw agents add code-writer
python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --sync-agents

    Or add --sync-agents to HEARTBEAT.md for automatic pickup within 30 minutes.

    Harvest from sub-agents

    After a sub-agent completes, pull its important findings into the primary namespace:

    python3 ~/.openclaw/skills/pgmemory/scripts/query_memory.py \
  --harvest shopwalk:subagent:task-label

    Memory decay

    Memories decay based on age and category. Frequently accessed memories stay fresh. Decayed memories move to archive (never deleted). Restored automatically if matched in a future search.

    Decay runs daily via cron (configured during setup). Run manually anytime:

    python3 ~/.openclaw/skills/pgmemory/scripts/setup.py --decay

    Switching embedding providers

    Changing providers after setup requires re-embedding all memories — you cannot mix dimensions in the same database. Run --doctor first to check for mismatches.

    ⚠️ Provider migration (--re-embed) is planned for v1.1. For now: set up a fresh database if you need to switch providers.

    Config reference

    Minimal (all that's required): 

    {
  "db":         { "uri": "postgresql://openclaw@localhost:5432/openclaw" },
  "embeddings": { "provider": "voyage", "api_key_env": "VOYAGE_API_KEY" },
  "agent":      { "name": "main" }
}

    Default config is at ~/.openclaw/pgmemory.json. Override with --config .

    Full config reference: see references/schema.sql and CHANGELOG.md.

    Requirements

  • Python 3.9+
  • PostgreSQL 14+ with pgvector 0.5+
  • psycopg2-binary, numpy — install via pip install -r requirements.txt
  • Embedding provider API key (or Ollama for local)

    • ⚙️ Configuration

    Run once after installing:

    python3 ~/.openclaw/skills/pgmemory/scripts/setup.py

    The wizard handles everything: Docker/PostgreSQL, migrations, embedding provider, AGENTS.md scaffolding, and decay cron.