Skip to content
Skills Library
AI & agents · Automation

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".

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
17
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

remember thissave to memorywhat do you remember aboutforget that

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

  1. Mode Detection
  2. Required Reading by Operation
  3. Storage Layout (one-line summary; full rules in [rules/storage-layout.md](./rules/storage-
  4. Core Workflow
  5. Integration With Other Skills
  6. Scaling Tiers (full guidance in [rules/scaling-tiers.md](./rules/scaling-tiers.md))
  7. Core Principles
  8. Anti-patterns (one-liner — full list in [rules/anti-patterns.md](./rules/anti-patterns.md)
  9. Definition of Done
Original SKILL.md headings · 244 lines, 1,631 words
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

RepositoryScoreLicence
This page · mthines/agent-skills100MIT
aws-solutions/konductor100Apache-2.0
r84577-crypto/arena-skills100MIT
yantrikos/yantrikdb-mcp100MIT

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,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.