Persistent Memory
Use this skill as the single memory system for this repository.
Commands
Use either command style:
python3 .agents/skills/persistent-memory/scripts/memory.py
.agents/skills/persistent-memory/scripts/pmem
Supported commands:
init
sync
(database-only health check)
cleanup-legacy
backfill-embeddings --batch 500
prune --source "" [--older-than ]
search "" --limit 8
add "" --tags "" --source "assistant"
recent --limit 10
stats
Required Workflow
Initialize memory in a fresh workspace:
pmem init
At the start of substantial tasks:
pmem sync
(database-only health check)
pmem search "" --limit 8
When user explicitly says
remember
or when a durable preference/fact is learned:
pmem add "" --tags "" --source "assistant"
Before finalizing memory-sensitive work, verify recall state:
pmem stats
One-Time Migration (If Upgrading From Older Setup)
Remove legacy imported rows:
pmem cleanup-legacy
Generate vectors for existing notes:
pmem backfill-embeddings
Storage Rules
Store durable preferences, long-lived facts, stable workflows, and repeated constraints.
Do not store noisy one-off transient details unless requested.
Keep entries concise and specific.
Prefer tags that improve retrieval quality (
preferences
,
calendar
,
comms
,
product
).
Retrieval Rules
Use targeted search queries instead of broad terms.
Keep default
--limit
low unless deeper recall is needed.
search
automatically reinforces recalled entries by updating
hits
and
last_seen_at
.
hits
are analytics-oriented and not used as a direct ranking boost.
Search uses hybrid retrieval: lexical + semantic.
Semantic search tries
sqlite-vec
first and auto-falls back to Python cosine if needed.
Bootstrapping and Recovery
If
.memory/
is missing, run
pmem init
.
pmem sync
is a lightweight database-only check (no markdown import/export).
If semantic mode degrades, run
pmem stats
to inspect
semantic_backend
and
embedding_coverage
.
For command examples and quick troubleshooting, read
references/usage.md
.