Memory Keeper

View saved version →

---
name: auditing-persistent-state
description: Use when inspecting a persistent project or Library to determine canonical locations, file roles, memory ownership, references, duplicates, stale state, evidence completeness, or the safe target state before mutation.
---

# Auditing Persistent State

## Purpose

Establish observed truth before consequential mutation. An audit is read-only unless repair/organization was also requested.

## Scope and roles

Inventory the exact authoritative surface and requested scope, then classify items as `CANONICAL`, `SUPPORT`, `REFERENCE`, `ARCHIVE`, `TEMPORARY`, `UNCLASSIFIED`, or `TRASH`. Never classify from filename/age alone when content or references matter.

Check roots, memory chain, competing canons, broken routes, incoming references, successors, and competing copies across surfaces.

## Evidence completeness

An inventory is complete only when the tool proves the requested scope was exhausted. If a response is **truncated**, says it may be a **partial listing**, exposes **pagination** or a **next cursor**, follow it until exhausted when the conclusion depends on absence/completeness.

If complete coverage cannot be established, label the conclusion **INCOMPLETE EVIDENCE**. A zero-result search or stale index does not prove absence when direct list/read is available. Do not perform destructive cleanup based on incomplete evidence.

## Output contract

Separate observed facts, inferred roles, and unresolved assumptions. `UNCLASSIFIED` stays non-destructive. If memory is inconsistent, use `repairing-memory-state`; if target state is proven and structural mutation is requested, use `organizing-persistent-files`.

View saved version →

---
name: maintaining-memory-keeper
description: Use when creating, editing, testing, auditing, packaging, versioning, releasing, or preparing publication of the Memory Keeper plugin or any of its skills.
---

# Maintaining Memory Keeper

This is developer/self-maintenance discipline, not a user-facing mode.

## Required discipline

- behavior changes require a failing regression/contract test first;
- each specialist stays focused; `using-memory-keeper` stays concise and trigger-oriented;
- version and diagnostic marker stay synchronized across manifests/docs/tests;
- pressure scenarios cover bypass/rationalization, incomplete evidence, recovery, and completion;
- built ZIPs are inspected/linted, not inferred from the source tree;
- `verifying-persistent-work` is required before a release-complete claim.

## Official test path

Run `scripts/run_release_tests.py --source <plugin-root>` for source certification. It executes tests in an isolated copy with bytecode disabled, then re-lints the untouched source, preventing tests from creating `__pycache__` and falsely failing their own cleanliness gate. Pass final ZIPs with repeated `--zip <archive>` arguments.

## Release hygiene

Reject `__pycache__`, `.pyc/.pyo`, temp/editor debris, nested old releases, stale version/marker strings, missing specialists, malformed/unsafe ZIPs, or MCP declarations. `scripts/package_lint.py` must fail cleanly rather than crash on malformed input.

Static contracts prove package/skill invariants, not host auto-invocation. Automatic routing must still be pressure-tested on a host where the plugin is actually installed.

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: maintaining-project-memory
description: Use when a project gains, changes, validates, abandons, or depends on durable truth that future work must remember, including architecture, behavior, bugs, baselines, constraints, versions, tests, canonical locations, or memory structure.
---

# Maintaining Project Memory

## Core law

**One durable fact = one canonical owner. One canonical memory = one living file.** Memory stores current truth, not a session transcript.

## Before changing durable truth

1. Identify the authoritative persistent surface and project root.
2. Load the smallest relevant memory chain from root to owner.
3. Identify the detailed owner; ambiguity routes to `repairing-memory-state`.
4. Read `references/memory-hierarchy.md` before creating, splitting, merging, or compacting memory.

## Synchronization

After every durable change:

1. update the nearest owning memory immediately;
2. replace obsolete truth instead of appending diary history;
3. update a parent only when parent-level routing/status/constraint changed;
4. keep child detail out of the parent;
5. verify memory reflects the new truth before completion.

Durable truth includes architecture, feature state, bugs, baselines, tests, workflows, paths, constraints, abandoned approaches that must not return, and next actions future work depends on. Throwaway edits require no memory rewrite.

## Memory lifecycle

Apply the lifecycle rules in the hierarchy reference. In short:

- **Split trigger:** a subdomain gains independent ownership and enough independently changing truth that keeping it inline lowers route density or causes parent duplication.
- **Merge trigger:** a child no longer has independent ownership and its remaining truth can live in the parent without duplication or routing ambiguity.
- **Compaction trigger:** current truth is obscured by stale history, repetition, oversized detail, or low route density; rewrite in place while preserving constraints that still affect future decisions.

Never create a sibling active canon with `_MAJ`, `_FINAL`, dates, `copy`, `backup`, `(1)`, `v2`, `new`, or `updated`. Update the active canon in place or perform controlled replacement with exactly one active owner remaining.

For local filesystems, `scripts/memory_keeper_check.py` provides conservative structural checks; project technical tests remain separate.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: organizing-persistent-files
description: Use when moving, renaming, archiving, deleting, deduplicating, replacing, or reorganizing persistent project files, folders, release artifacts, or ChatGPT Library items.
---

# Organizing Persistent Files

## Iron rule

**Audit before structural/destructive mutation.** Use `auditing-persistent-state` unless exact roles, references, canon, successor, destination, and target state are already established from fresh complete evidence.

## Idempotent transaction

`pre-read/list -> classify -> precondition -> mutate -> capture returned final identity -> repair pointers/memory -> post-read/list -> verify`

For every structural mutation:

1. resolve exact source identity and authoritative surface;
2. resolve intended destination/successor and detect any **destination conflict**;
3. identify references and canonical role;
4. define a postcondition that makes the operation **idempotent**: re-observing the already-correct target must not trigger a duplicate mutation;
5. perform the real persistent mutation once;
6. capture the provider/tool **returned final identity** (id/path/name), including any **auto-rename** result;
7. update pointers/routes and durable memory if truth changed;
8. fresh re-list/re-read source and final destination;
9. use `verifying-persistent-work` last.

Never assume the requested destination name is the actual final name when the storage layer may dedupe or auto-rename. If status is ambiguous, use `recovering-persistent-work` before any repeat.

## Deletion

Delete only when the item is not active canon, required information survives, references are safe, required successor is readable, and post-state can be verified. Otherwise archive or stop.

## ChatGPT Library

Use native Library mutation on the exact Library item. `/mnt/data` is only a working surface. Read `references/storage-adapters.md` for provider-specific identity and conflict rules.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: recovering-persistent-work
description: Use when a persistent read, write, move, rename, delete, upload, or verification times out, is interrupted, partially succeeds, returns ambiguous status, repeatedly mismatches, or resumes after a mid-transaction stop.
---

# Recovering Persistent Work

## Core principle

**Recovery is bounded at both operation and transaction level. Failure never creates an infinite repair loop and never weakens verification.**

## Observe before recovery

After timeout/interruption/ambiguous result/failed post-write verification:

1. stop mutation;
2. fresh re-read/re-list the actual persistent surface;
3. compare observed state with pre-state and target;
4. classify failed, succeeded-despite-timeout, or partial success;
5. never repeat an ambiguous write if target state already holds.

## Stable operation fingerprint

Before an automatic recovery mutation, define an **operation fingerprint** from logical operation kind + canonical source identity + intended destination/target identity + intended postcondition. **renaming or subdividing a step does not reset** this fingerprint or its retry history.

## Bounded budgets

A **transaction** is one naturally atomic user-requested persistent target state. Independent operations may be separate transactions only when they have independent success criteria; never split or rename one failing transaction merely to refresh the budget.


- per operation fingerprint: at most **one automatic recovery attempt**;
- **transaction recovery budget:** **maximum 2 automatic recovery mutations** across the whole persistent transaction, even when fingerprints differ;
- observation/re-read does not consume mutation budget.

A recovery mutation is allowed only when unambiguous, safe, and it preserves the last known-good canon.

## Progress rule

After each recovery mutation, re-observe. Require **monotonic progress** toward the target: the set/severity of mismatches must strictly decrease. **no progress** (unchanged state), regression, or a state that **oscillates** A↔B stops automatic recovery immediately.

Also stop when the **same failing step** / fingerprint fails again, the global budget is exhausted, capability is missing, or the next action is destructive/ambiguous.

## Terminal state

Preserve last known-good truth where possible, report observed mismatch and smallest next decision/action, and mark **BLOCKED / NOT COMPLETE**. Never recursively rename repair steps to gain retries. Never relax a completion gate.

A later user action or newly available capability starts from a fresh audit; it does not retroactively make the failed transaction complete.

View saved version →

---
name: repairing-memory-state
description: Use when persistent project memory is inconsistent, duplicated, stale, broken, orphaned, contradictory, ambiguously rooted, or has invalid routes after moves, renames, replacements, or partial repairs.
---

# Repairing Memory State

## Goal

Restore one coherent canonical truth without inventing facts or destroying uncertain data.

## Repair order

1. Freshly observe state and record a **rollback point**: identities/locations and last known-good canonical content needed to recover.
2. Record **repair provenance**: what evidence selected each owner/successor and which prior source it supersedes.
3. Determine the nearest logical owner for each conflicting durable fact.
4. Resolve root ambiguity before destructive change.
5. Repair owner content/routing first, then reduce parent copies to routing/high-level status.
6. Repair moved/renamed pointers.
7. Keep a superseded source recoverable until the replacement and routes pass fresh verification; **superseded source remains recoverable** through archive/version history when possible.
8. Only then remove redundant active canons, re-read/re-list, and verify exactly one active owner remains.

## Never

Never choose by newest-looking filename/date, concatenate contradictory facts, create `_FINAL`/`_MAJ`/dated/copy/backup/`v2` active canons, or delete uncertainty merely to make the audit clean.

If evidence cannot select the canon, stop at **NOT COMPLETE** and request only the smallest missing decision. Operational timeout/failure belongs to `recovering-persistent-work`.

View saved version →

---
name: using-memory-keeper
description: Use when a task involves ChatGPT Library, persistent project files, project memory, durable project code or docs, lasting decisions, structural cleanup, interrupted persistent work, or a completion claim about persistent work.
---

# Using Memory Keeper

<EXTREMELY-IMPORTANT>
If persistent project state may be read, changed, organized, repaired, recovered, or declared complete, Memory Keeper applies **BEFORE any response or action** touching that state.

**Load every applicable specialist. Skills compose; they are not mutually exclusive.** “Small”, “urgent”, “already known”, or “just one file” are not exemptions.
</EXTREMELY-IMPORTANT>

## Route

- durable truth -> `maintaining-project-memory`
- inventory/health -> `auditing-persistent-state`
- move/rename/archive/delete/deduplicate -> `organizing-persistent-files`
- conflicting/orphaned memory -> `repairing-memory-state`
- timeout/partial/ambiguous persistence -> `recovering-persistent-work`
- completion claim -> `verifying-persistent-work`
- Memory Keeper development -> `maintaining-memory-keeper`

When several apply, compose them in dependency order: **audit before organization**, memory repair before destructive cleanup, memory synchronization after durable mutation, **recovery before completion verification**, and verification last.

Scratch work with no persistent mutation or durable truth change is excluded.

Diagnostic: `MEMORY_KEEPER_V4_2026-09-17`.

View saved version →

---
name: verifying-persistent-work
description: Use when about to claim persistent project work is complete, done, fixed, organized, saved, synchronized, updated, cleaned, migrated, or successfully written.
---

# Verifying Persistent Work

## Iron law

**No persistent success claim without fresh authoritative evidence from the actual persistent surface after the last mutation.**

A successful write call, old test run, remembered state, temporary `/mnt/data` artifact, or search hit alone is insufficient.

## Gate

1. identify evidence for every applicable requirement;
2. run relevant technical verification freshly;
3. obtain **authoritative evidence** from a direct filesystem read/stat/hash or **provider-native read/list** of the exact persistent item **after the last mutation**;
4. verify owning canonical memory and parent routing where applicable;
5. verify references/pointers and absence of competing active canons;
6. compare observed final state with requested target.

A **search/index result alone is insufficient** to prove destructive absence, exact final identity, or completion when direct read/list is available; indexes can lag. Use search for discovery, then verify directly.

If any gate is unchecked or fails, state **NOT COMPLETE**. Operational repair may use `recovering-persistent-work` only within its fingerprint and transaction budgets. Verification itself must not create an unbounded reverify/recover loop.

Use `references/verification-gates.md` for the checklist. Do not use “done”, “fixed”, “saved”, “organized”, “clean”, or “synced” until it passes.

Referenced files: 1 — file references are metadata, not package contents.