Persistent Memory
Give your coding agent durable local memory—recall context at task start, honor “remember” requests, and search prior facts without re-explaining the repo every session.
Overview
Persistent Memory is a journey-wide agent skill that runs a local init/sync/search/add CLI so solo builders recall durable repo context whenever they start work or ask the agent to remember something.
Install
npx skills add https://github.com/ropl-btc/agent-skills --skill persistent-memoryWhat is this skill?
- Single workflow for init, sync, semantic search, add, recent, and stats via `memory.py` or `pmem`
- Required ritual: sync + search (limit 8) at the start of substantial tasks
- Explicit `remember` and durable preferences routed through `add` with tags and source
- Maintenance commands: cleanup-legacy, backfill-embeddings (batch 500), prune by source and age
- Pre-finalize check with `stats` on memory-sensitive deliverables
- Default search and recent limits of 8 and 10 respectively in the documented CLI examples
- backfill-embeddings supports batch size 500
- Six core command families: init, sync, search, add, recent, stats
Adoption & trust: 752 installs on skills.sh; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You lose thread-to-thread context and re-explain preferences, stack choices, and prior decisions because the agent has no owned persistent memory workflow in the repo.
Who is it for?
Solo builders standardizing one local memory CLI across all agent sessions in a long-lived repository.
Skip if: Teams that forbid local DB/files under `.agents` or want cloud-only memory without a repo-local workflow.
When should I use this skill?
ALWAYS USE when handling persistent memory in this workspace, including task-start recall, explicit remember instructions, storing durable preferences/facts, and retrieving prior context.
What do I get? / Deliverables
The workspace keeps searchable, tagged memories with a verified stats state before memory-sensitive work finishes.
- Initialized local memory store via `pmem init`
- Tagged memory rows from `add` with optional source labels
- Verified recall state from `stats` before sensitive finalization
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Search prior API auth decisions before implementing a new endpoint so the agent does not contradict established patterns.
Recall documented review conventions stored after the last release before running a pre-ship pass.
Add a durable note about incident root cause after a hotfix so the next on-call thread finds it via search.
Retrieve remembered scope boundaries and non-goals before expanding an MVP spec.
How it compares
Use as a procedural in-repo memory layer, not as a one-off note in chat or an external SaaS bookmark.
Common Questions / FAQ
Who is persistent-memory for?
Indie and solo developers who want one documented CLI ritual for recall, explicit remembers, and stats checks across Claude Code, Cursor, Codex, or similar agents in a single workspace.
When should I use persistent-memory?
At the start of substantial build, ship, or operate tasks (sync + search), whenever the user says remember, when storing durable preferences, and before finalizing work that depends on prior context—plus `init` on fresh clones.
Is persistent-memory safe to install?
It writes and reads local memory stores via bundled scripts; review the Security Audits panel on this Prism page and inspect `.agents/skills/persistent-memory` before running init or prune in production repos.
SKILL.md
READMESKILL.md - Persistent Memory
# 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 <command>` - `.agents/skills/persistent-memory/scripts/pmem <command>` Supported commands: - `init` - `sync` (database-only health check) - `cleanup-legacy` - `backfill-embeddings --batch 500` - `prune --source "<label>" [--older-than <days>]` - `search "<query>" --limit 8` - `add "<memory text>" --tags "<comma,tags>" --source "assistant"` - `recent --limit 10` - `stats` ## Required Workflow 1. Initialize memory in a fresh workspace: - `pmem init` 2. At the start of substantial tasks: - `pmem sync` (database-only health check) - `pmem search "<topic keywords>" --limit 8` 3. When user explicitly says `remember` or when a durable preference/fact is learned: - `pmem add "<memory text>" --tags "<tags>" --source "assistant"` 4. Before finalizing memory-sensitive work, verify recall state: - `pmem stats` ## One-Time Migration (If Upgrading From Older Setup) 1. Remove legacy imported rows: - `pmem cleanup-legacy` 2. 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`. # Persistent Memory Usage ## Quick Start ```bash .agents/skills/persistent-memory/scripts/pmem init .agents/skills/persistent-memory/scripts/pmem sync .agents/skills/persistent-memory/scripts/pmem backfill-embeddings .agents/skills/persistent-memory/scripts/pmem search "investor update" --limit 8 ``` ## One-Time Legacy Cleanup ```bash .agents/skills/persistent-memory/scripts/pmem cleanup-legacy .agents/skills/persistent-memory/scripts/pmem backfill-embeddings ``` ## Prune by Source ```bash # prune all notes from a source .agents/skills/persistent-memory/scripts/pmem prune --source "smoke-test" # prune only old notes from a source .agents/skills/persistent-memory/scripts/pmem prune --source "temp-import" --older-than 30 ``` ## Store Durable Memory ```bash .agents/skills/persistent-memory/scripts/pmem add "Always convert times to CET" --tags "timezone,calendar" --source "assistant" ``` ## Inspect and Verify ```bash .agents/skills/persistent-memory/scripts/pmem recent --limit 10 .agents/skills/persistent-memory/scripts/pmem stats ``` ## Notes - `search` updates `hits` and `last_seen_at` for returned rows. - `hits` are analytics-oriented (not a direct ranking boost). - `search` combines lexical + semantic retrieval. - semantic backend prefers `sqlite-vec` and auto-falls back to Python cosine. - `sync` is a database-only health check and prints embedding