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:

CODEBLOCK0

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

CODEBLOCK1

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

Importance:

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

Search memories

CODEBLOCK2

Maintenance

CODEBLOCK3

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:

CODEBLOCK4

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:

CODEBLOCK5

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:

CODEBLOCK6

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):
CODEBLOCK7

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+
• INLINECODE19, numpy — install via INLINECODE21
• Embedding provider API key (or Ollama for local)