Pgmemory

Persistent semantic memory for OpenClaw agents — PostgreSQL + pgvector

Security Scan

The skill generally matches its stated purpose (Postgres+pgvector memory) but it includes automated workspace injection, stores embedding API keys in a local config by default, and the registry metadata omits declared credentials/deps — these discrepancies warrant caution before installing.

Purpose & Capability

Name/description (persistent semantic memory with PostgreSQL + pgvector) align with included code, SQL migrations, and scripts for write/query/setup. However the package advertises Python deps including numpy but requirements.txt contains only psycopg2-binary (minor mismatch). The skill also performs agent-workspace integration (scaffolding/injecting startup steps into AGENTS.md) which is plausible for a memory system but is a higher-impact capability than a simple library.

Instruction Scope

SKILL.md and the included setup script instruct the agent to modify user workspace files (AGENTS.md injection, 'This is not optional' wording in changelog), configure cron jobs for daily decay, scaffold per-agent namespaces, and optionally run Docker/DB provisioning. These are legitimate for a memory integration but they are broad file-system and workspace changes that go beyond passive library installation and should be approved by the user. The scripts also read/write ~/.openclaw/pgmemory.json and can store embedding API keys there.

Install Mechanism

No remote download/install spec is included (instruction-only plus bundled scripts). All code is present in the bundle and migrations/docs are local. This is lower-risk than remote installers. There is no suspicious external install URL. (Note: setup can install/configure Docker and create cron entries on the host when you run it — actions that require user consent.)

Credentials

Registry metadata declared no required env vars, but the scripts require an embedding provider API key (config supports storing api_key in ~/.openclaw/pgmemory.json or falling back to an env var name configured in the config). The CHANGELOG explicitly added storing API keys directly in the config. Storing secrets in a plaintext config file under the home directory is a security/privacy risk and should be considered proportional only if the user is comfortable with local storage of keys. The number of environment/credential access points is small and relevant to embeddings, but the registry omission of these expectations is inconsistent.

Persistence & Privilege

The skill does not request always:true and does not modify other skills' configs directly, but the setup wizard can modify agent workspace files (AGENTS.md), create cron jobs for decay, and save its own config (~/.openclaw/pgmemory.json). Those are normal for a persistent memory integration but are persistent effects with system-wide visibility across agent workspaces; users should review and approve these changes before running the wizard. The skill can be run non-interactively with --yes which increases risk if executed without review.

What to consider before installing

This skill appears to implement a coherent PostgreSQL+pgvector memory system, but take these precautions before installing/ running the setup wizard: 1) Inspect scripts/setup.py and confirm you are comfortable with it modifying AGENTS.md, writing a config to ~/.openclaw/pgmemory.json, and installing/configuring cron/docker. 2) Decide how to supply embedding API keys: the wizard can store a key in plain JSON under your home directory (CHANGELOG explicitly added this behavior) — consider using a local provider (Ollama) or an env var and restrict file permissions if you allow config storage. 3) Backup AGENTS.md and any agent workspaces before running --sync-agents or the automatic injection. 4) The requirements mention numpy but requirements.txt only lists psycopg2-binary; ensure you install necessary Python deps manually. 5) For least privilege, run the setup in a sandboxed environment (or test agent) first and review network calls (voyage/openai endpoints) if you must avoid sending embedding data externally. If you want, I can point out the exact lines in setup.py that modify AGENTS.md, create cron jobs, or persist the api_key so you can review/patch them.

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)