Pgmemory

Persistent semantic memory for OpenClaw agents — PostgreSQL + pgvector

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 <path>.

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)