Persistent Memory

Persistent Memory

Capture, recall, consolidate, and forget memories scoped to a user-chosen topic (e.g. parenting, work, relationship-anna) as plain markdown files, so any future conversation can pick up where the last one left off.

This SKILL.md is a thin index. Operation pipelines, taxonomy, privacy rules, integration patterns, and scaling guidance live in rules/*.md and load on demand. Literal artefact templates live in templates/*.md. Worked examples and citations live in references/*.md. Read only what the current operation asks for.

Mode Detection

Parse $ARGUMENTS (first token) and detect the operation:

State the detected operation and resolved scope in one line before continuing. Example:

Operation: write
Scope: parenting
Storage tier: home (~/.agent-memory/parenting/)

If no scope is provided, ask once (single batched message) — never guess.

Required Reading by Operation

Load on demand — do not preload.

Storage Layout (one-line summary; full rules in rules/storage-layout.md)

Three tiers; the user picks per invocation, or accepts the default.

Per-scope directory layout (identical across tiers):

<storage-root>/<scope>/
├── INDEX.md          # Curated, ≤ 200 lines; always loaded by `read`
├── entries/          # Individual memory entries; loaded on demand
│   └── <yyyy-mm-dd>-<slug>.md
├── archive/          # Consolidated / superseded entries (audit trail)
└── AUDIT.log         # Append-only ledger of write / consolidate / forget

Core Workflow

Every operation is gated. Do not proceed to the next phase until the prior phase's gate passes.

write (default)

read

consolidate

forget

list

Walk every storage tier the user has enabled, print every scope with entry counts and last-updated timestamps. No writes.

Integration With Other Skills

This skill is model-invocable (disable-model-invocation: false) so host workflows can call it programmatically. Two ways to invoke it:

1. Explicit — the user types /persistent-memory write parenting or /persistent-memory read parenting.
2. Runtime, from a host skill — the host skill's SKILL.md contains a one-line pointer block that calls Skill("persistent-memory", "read <scope>") when the host runs.

The second form is the canonical integration. Runtime Skill() calls require disable-model-invocation: false — without it the Skill tool refuses the call at the harness layer (you'd see Skill X cannot be used with Skill tool due to disable-model-invocation). See rules/integration-with-skills.md for the full contract and the literal snippet at templates/pointer-snippet.md.

For the parenting example: add one block to parenting/SKILL.md:

> **Persistent memory:** Before responding, run
> `Skill("persistent-memory", "read parenting")` to load accumulated
> context for this scope.

Scaling Tiers (full guidance in rules/scaling-tiers.md)

Graduate one tier at a time. The skill ships a migration recipe in rules/scaling-tiers.md for moving from markdown to SQLite, and from SQLite to a vector DB, without losing entries.

Core Principles

1. Plain text, local-first. Memory is markdown the user can read, edit, grep, and delete with standard tools. No proprietary format.
2. Progressive disclosure. INDEX is small and always loaded; detail entries load on demand. Modeled on Claude Code's MEMORY.md.
3. Two-phase write. Extract candidates first, then resolve each against existing entries with ADD / UPDATE / DELETE / NOOP. Modeled on Mem0's extraction + update pipeline.
4. Consent before persistence. Every write shows the user a diff preview unless --auto is passed; secrets and PII on the never-store list are refused outright.
5. Forgetting is a feature. A clear forget operation is part of the surface, not an afterthought. Required for privacy and for pruning entrenched mistakes (see Reflexion entrenchment warning).
6. One scope, one purpose. Resist mega-scopes ("life"). Split into parenting, health, work etc. so the INDEX stays under 200 lines.
7. Markdown until it hurts. Stay on Tier 1 until a concrete signal (search latency, INDEX bloat, multi-user) forces a graduation.

Anti-patterns (one-liner — full list in rules/anti-patterns.md)

• Writing to memory without showing the user the diff first.
• Storing secrets, credentials, or government IDs (refuse outright).
• Mega-scopes that swell the INDEX past 200 lines.
• Letting the model auto-write without scope confirmation.
• Re-recording the same fact instead of UPDATE-ing the existing entry.
• Deleting an entry without an AUDIT.log line.
• Skipping consolidation forever — the INDEX rots and recall degrades.
• Committing ~/.agent-memory/ to a public repo.

Definition of Done

A write run is done when:

• Scope and storage tier explicitly resolved (no defaults assumed silently).
• Privacy pre-flight passed (no never-store items in candidates).
• Candidate list shown to the user with ADD / UPDATE / DELETE / NOOP tags.
• User approved (or --auto flag was explicit).
• Entry files written; INDEX updated; AUDIT.log line appended.
• One-line summary delivered: "Saved N memories to ()."

A read run is done when:

• Scope resolved; if no INDEX exists, user is told the scope is empty.
• INDEX content is now in the conversation context.
• Detail entries are fetched only when the INDEX references them.

A consolidate run is done when:

• Before / after summary shown (entry count delta, INDEX line delta).
• User explicitly approved.
• AUDIT.log line appended with operation, timestamp, and counts.

A forget run is done when:

• Target entries shown verbatim before deletion.
• User confirmed (typed "yes" or --confirm flag).
• Entries removed (or redacted); INDEX updated; AUDIT.log line appended.