persistent-memory
/persistent-memory
Persists topic-scoped context across conversations as plain markdown with write, read, consolidate, and forget operations, a never-store list for secrets, and a consent preview before every write. Triggers on "remember this", "save to memory", "what do you remember about", "forget that", "/persistent-memory".
- Author
- mthines ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 17
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Persists topic-scoped context across conversations as plain markdown with write, read, consolidate, and forget operations, a never-store list for secrets, and a consent preview before every write. Triggers on "remember this", "save to memory", "what do you remember about", "forget that", "/persistent-memory".
Triggers from the description
Arguments
/persistent-memory [write|read|consolidate|forget] <scope> [--tier home|project-local|project-shared]
Original author description
Persists topic-scoped context across conversations as plain markdown with write, read, consolidate, and forget operations, a never-store list for secrets, and a consent preview before every write. Triggers on "remember this", "save to memory", "what do you remember about", "forget that", "/persistent-memory".
How it works
- Mode Detection
- Required Reading by Operation
- Storage Layout (one-line summary; full rules in [rules/storage-layout.md](./rules/storage-
- Core Workflow
- Integration With Other Skills
- Scaling Tiers (full guidance in [rules/scaling-tiers.md](./rules/scaling-tiers.md))
- Core Principles
- Anti-patterns (one-liner — full list in [rules/anti-patterns.md](./rules/anti-patterns.md)
- Definition of Done
SKILL.md preview
---
name: persistent-memory
description: >
Persists topic-scoped context across conversations as plain markdown with
write, read, consolidate, and forget operations, a never-store list for
secrets, and a consent preview before every write. Triggers on "remember
this", "save to memory", "what do you remember about", "forget that",
"/persistent-memory".
disable-model-invocation: false
argument-hint: '[write|read|consolidate|forget] <scope> [--tier home|project-local|project-shared]'
license: MIT
metadata:
author: mthines
version: '1.2.0'
workflow_type: applied
tags:
- memory
- persistent-memory
- long-term-memory
- agent-memory
- scope
- markdown
- progressive-disclosure
- privacy
- consent
- consolidation
---
# 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:
| Operation | Default | Trigger phrases |
| ------------- | ------- | ------------------------------------------------------------------------ |
| `write` | **yes** | "remember", "save to memory", "add to memory", `$0 == "write"` |
| `read` | | "recall", "load memory", "what do you remember about", `$0 == "read"` |
| `consolidate` | | "consolidate memory", "compress memory", `$0 == "consolidate"` |
| `forget` | | "forget that", "delete memory", "redact", `$0 == "forget"` |
| `list` | | "list memory", "what scopes do I have", `$0 == "list"` |
State the detected operation and resolved scope in one line before
continuing. Example:
```text
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.
| Operation | Files |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `write` | [`rules/storage-layout.md`](./rules/storage-layout.md), [`rules/write-pipeline.md`](./rules/write-pipeline.md), [`rules/memory-taxonomy.md`](./rules/memory-taxonomy.md), [`rules/privacy-and-consent.md`](./rules/privacy-and-consent.md) |
| `read` | [`rules/storage-layout.md`](./rules/storage-layout.md), [`rules/read-pipeline.md`](./rules/read-pipeline.md) |
| `consolidate` | [`rules/consolidate-pipeline.md`](./rules/consolidate-pipeline.md), [`rules/memory-taxonomy.md`](./rules/memory-taxonomy.md) |
| `forget` | [`rules/forget-pipeline.md`](./rules/forget-pipeline.md), [`rules/privacy-and-consent.md`](./rules/privacy-and-consent.md) |
| `list` | [`rules/storage-layout.md`](./rules/storage-layout.md) |
| integration | [`rules/integration-with-skills.md`](./rules/integration-with-skills.md) |
| scaling | [`rules/scaling-tiers.md`](./rules/scaling-tiers.md) |
| pre-flight | [`rules/quality-checklist.md`](./rules/quality-checklist.md), [`rules/anti-patterns.md`](./rules/anti-patterns.md) |
---
## Storage Layout (one-line summary; full rules in [`rules/storage-layout.md`](./rules/storage-layout.md))
Three tiers; the user picks per invocation, or accepts the default.
| Tier | Path | Committed? | Default for |
| ----------------- | --------------------------------- | ---------- | -------------------------------------- |
| `home` (default) | `~/.agent-memory/<scope>/` | No | Personal scopes (parenting, work) |
| `project-local` | `<repo>/.agent/memory/<scope>/` | No (gitignore) | Per-project private notes |
| `project-shared` | `<repo>/memory/<scope>/` | Yes | Team-shared project knowledge |
Per-scope directory layout (identical across tiers):
```text
<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)
| Phase | Name | Rule | Gate |
| ----- | --------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
| 0 | Resolve scope + tier | [`rules/storage-layout.md`](./rules/storage-layout.md) | Scope name + storage tier confirmed; directory created |
| 1 | Privacy pre-flight | [`rules/privacy-and-consent.md`](./rules/privacy-and-consent.md) | No secrets / PII on the never-store list slip through |
| 2 | Extract candidates | [`rules/write-pipeline.md`](./rules/write-pipeline.md) | Candidate list produced with type, confidence, source per item |
| 3 | Compare to existing | [`rules/write-pipeline.md`](./rules/write-pipeline.md) | Each candidate tagged ADD / UPDATE / DELETE / NOOP |
| 4 | Consent preview | [`rules/privacy-and-consent.md`](./rules/privacy-and-consent.md) | User saw the diff and approved (unless `--auto` flag) |
| 5 | Write + audit | [`rules/write-pipeline.md`](./rules/write-pipeline.md) | INDEX updated, entry files written, AUDIT.log line appended |
### `read`
| Phase | Name | Rule | Gate |
| ----- | ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------- |
| 0 | Resolve scope | [`rules/storage-layout.md`](./rules/storage-layout.md) | Scope directory exists; INDEX.md present (or report empty) |
| 1 | Load INDEX | [`rules/read-pipeline.md`](./rules/read-pipeline.md) | INDEX content surfaced to current conversation |
| 2 | On-demand fetch | [`rules/read-pipeline.md`](./rules/read-pipeline.md) | Detail entries fetched only when INDEX points to them |
### `consolidate`
| Phase | Name | Rule | Gate |
| ----- | ---------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------- |
| 0 | Snapshot | [`rules/consolidate-pipeline.md`](./rules/consolidate-pipeline.md) | Pre-consolidation state captured (path + file count) |
| 1 | Group + merge | [`rules/consolidate-pipeline.md`](./rules/consolidate-pipeline.md) | Semantically similar entries grouped; merge plan drafted |
| 2 | Prune stale | [`rules/consolidate-pipeline.md`](./rules/consolidate-pipeline.md) | Entries past staleness cutoff flagged for archive |
| 3 | Preview + apply | [`rules/consolidate-pipeline.md`](./rules/consolidate-pipeline.md) | User saw before / after summary and approved |
| 4 | Rewrite INDEX | [`rules/consolidate-pipeline.md`](./rules/consolidate-pipeline.md) | INDEX reflects new state; AUDIT.log appended |
### `forget`
| Phase | Name | Rule | Gate |
| ----- | ---------------- | ---------------------------------------------------------- | ------------------------------------------------------------- |
| 0 | Resolve target | [`rules/forget-pipeline.md`](./rules/forget-pipeline.md) | Memory id, slug, or query resolves to exactly one entry set |
| 1 | Show + confirm | [`rules/forget-pipeline.md`](./rules/forget-pipeline.md) | User saw the entries and explicitly confirmed |
| 2 | Delete or redact | [`rules/forget-pipeline.md`](./rules/forget-pipeline.md) | Entries removed (or redacted); INDEX + AUDIT.log updated |
### `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`](./rules/integration-with-skills.md)
for the full contract and the literal snippet at
[`templates/pointer-snippet.md`](./templates/pointer-snippet.md).
| Pattern | Token cost | Magic | Best for |
| --------------- | ------------------------- | ----- | ---------------------------------------------- |
| **Pointer** | INDEX only, on skill load | None | The default. Explicit, debuggable, no hook. |
| **Hook** | INDEX every session | High | Always-on scopes (e.g. a personal assistant). |
For the parenting example: add one block to `parenting/SKILL.md`:
```markdown
> **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`](./rules/scaling-tiers.md))
| Tier | Backend | Use when |
| ---- | ---------------------------------------------- | ------------------------------------------------------------------------ |
| 1 | Plain markdown (this skill, default) | ≤ ~500 entries per scope, single user, no semantic search needed |
| 2 | Markdown + SQLite FTS index (this skill, opt-in) | Up to ~5k entries per scope, keyword search beats full-INDEX scan |
| 3 | Markdown blobs + local vector DB (Chroma, Qdrant) | Semantic recall ("what did we discuss about X") matters |
| 4 | Managed memory layer (Mem0, Letta, Zep) | Multi-user, multi-tenant, > 10k entries, graph relationships, hosted SLA |
Graduate one tier at a time. The skill ships a migration recipe in
[`rules/scaling-tiers.md`](./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`](./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 <scope> (<tier>)."
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.
Files in this package (17)
- SKILL.md 15 KB
- references/research-sources.md 5 KB
- rules/anti-patterns.md 4 KB
- rules/consolidate-pipeline.md 6 KB
- rules/forget-pipeline.md 5 KB
- rules/integration-with-skills.md 9 KB
- rules/memory-taxonomy.md 4 KB
- rules/privacy-and-consent.md 7 KB
- rules/quality-checklist.md 3 KB
- rules/read-pipeline.md 4 KB
- rules/scaling-tiers.md 15 KB
- rules/storage-layout.md 6 KB
- rules/write-pipeline.md 14 KB
- templates/INDEX.md 1 KB
- templates/lesson-entry.md 1 KB
- templates/memory-entry.md 1 KB
- templates/pointer-snippet.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mthines/agent-skills | 100 | MIT |
| aws-solutions/konductor | 100 | Apache-2.0 |
| r84577-crypto/arena-skills | 100 | MIT |
| yantrikos/yantrikdb-mcp | 100 | MIT |
Database snapshot: 13.11.2026 · package version 12aa363859b7 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100memory-and-context
Store, retrieve, search, and manage persistent memory across sessions. Triggers on: store memory, save this, retrieve, forget, manage memory, context, pattern. - 100shodh-memory
Persistent memory system for AI agents. Use this skill to remember context across conversations, recall relevant information, and build long-term knowledge. Activate when you need to store decisions, learnings, errors, or context that should persist beyond the current session. - 82memory
Save, change or forget a durable fact when the user says remember, note that, commit to memory or forget - 100memory-gardener
Decide what an AI agent should remember, forget, and bring back into a new session. Use when an agent with long-term memory (a memory file, a notes folder, a vector store, CLAUDE.md-style notes) is about to save something, starts a new session and needs context, picks up… - 100memory
Use when the user says 'remember this' or 'log this', asks 'what did you learn yesterday', or whenever you discover something worth keeping across sessions. Per-role persistent memory — durable facts, preferences, decisions, and a daily log, as plain markdown. - 95honcho-memory
Gives AI agents persistent memory across conversations using Honcho. Automatically saves and retrieves user context so the AI remembers preferences, history, and facts between sessions. Use when you need the AI to remember past conversations, recall what a user has told it,…