| name | supersede |
| description | Mark a memory entry as superseded by a newer entry. Use when a previously-correct learning is replaced (e.g., the API changed, the architecture was refactored, the failed approach is now the right one). The old entry stays in archival_memory for audit but is excluded from default recall (its valid_until is set to NOW()). |
| metadata | {"user-invocable":true} |
Supersede Memory Entry
Phase 1.10 of memory hardening v2 added bi-temporal validity (valid_from,
valid_until) to archival_memory. A "superseded" entry is one whose
valid_until has been set -- it stayed correct until that timestamp, but a
newer entry replaces it. Default recall excludes superseded entries; pass
--include-superseded to see them.
When to Use
Trigger this skill when a stored learning is factually replaced rather
than wrong-from-the-start:
| Use supersede | Don't use supersede |
|---|
| API/library changed and the old pattern no longer works | Old entry was always wrong -> delete or store a correction |
| Architecture refactored, old pattern still works but newer is preferred | Old entry is a duplicate -> let the dedup gate handle it next store |
| User preference changed | The recall already returns the new entry above the old one |
| "Failed approach" turned out to work after a fix | The change is too small to merit a new row |
Supersede preserves audit history. If you need to purge an entry entirely,
delete it directly from the DB.
Quick Invocation
/supersede <old-id> "<new content>" [--reason "<why>"]
The old-id is the UUID printed by recall_learnings.py --json or by the
PostgreSQL archival_memory table. The new content is the replacement
learning text -- a fresh embedding is generated automatically.
Examples
/supersede 613a1764-7c40-450d-86fc-814553c05c15 "Updated: always validate JWT issuer claim AND signature, not just signature" --reason "Discovered token-spoofing CVE; original guidance was incomplete"
/supersede 2ae48c4f-6073-4366-9636-6fd732327710 "Memory pressure: prefer reboot at >85% RAM; surgical kills no longer help on Windows 11 26200" --reason "Earlier guidance was for Windows 10; new build changes Modified/Standby behaviour"
What It Does
- Looks up the entry by id -- errors if it doesn't exist or is already superseded.
- Within a single transaction:
- Sets
valid_until = NOW() on the old entry.
- Inserts a NEW row with
valid_from = NOW(), valid_until = NULL, the new content, a fresh embedding, and metadata including supersedes: <old-id> and supersede_reason: <reason>.
- Inherits session_id, scope, project_id, tags, context, and confidence from the old entry unless overridden.
- Returns JSON with
old_id, new_id, valid_from, valid_until, learning_type, scope, and project_id.
Idempotent: re-running supersede on an already-superseded id errors with the
original valid_until rather than double-marking or inserting a duplicate.
Execution
When this skill is invoked, run:
cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/supersede.py \
<OLD_ID> "<NEW_CONTENT>" --reason "<REASON>"
CLI flags:
| Flag | Purpose |
|---|
--reason "<text>" | Stored in metadata.supersede_reason. Strongly recommended. |
--scope GLOBAL|PROJECT | Override scope of the new entry (defaults to inheriting old). |
--project-dir <path> | Override project_id for the new entry. |
--type <LEARNING_TYPE> | Override learning_type. Inferred from content when omitted. |
--provider local|voyage | Embedding provider (default: local). |
Valid learning types: FAILED_APPROACH, WORKING_SOLUTION, USER_PREFERENCE,
CODEBASE_PATTERN, ARCHITECTURAL_DECISION, ERROR_FIX, OPEN_THREAD.
Output
{
"success": true,
"old_id": "613a1764-7c40-450d-86fc-814553c05c15",
"new_id": "7bfe8f13-8054-4355-8923-55b5086f3e11",
"supersedes": "613a1764-7c40-450d-86fc-814553c05c15",
"valid_from": "2026-05-16T15:08:13.733061+00:00",
"valid_until": "2026-05-16T15:08:18.845321+00:00",
"learning_type": "CODEBASE_PATTERN",
"scope": "PROJECT",
"project_id": null
}
On error:
{
"success": false,
"error": "Entry <id> already superseded at <iso-timestamp>",
"valid_until": "<iso-timestamp>"
}
Exit code is 0 on success, 1 on error.
Verifying
After supersede, run a recall and confirm the old entry is gone from the
default result set:
cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py \
--query "<keyword from old entry>" --json
To see the superseded entry for audit:
cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py \
--query "<keyword>" --include-superseded --json
To query the state at a past point in time (the old entry was valid then):
cd $CLAUDE_OPC_DIR && PYTHONPATH=. uv run python scripts/core/recall_learnings.py \
--query "<keyword>" --valid-at 2026-04-01T00:00:00Z --json
Related
.claude/skills/memory/SKILL.md -- canonical memory reference (recall + store).claude/skills/recall/SKILL.md -- recall slash commandrecall_learnings.py --valid-at -- bi-temporal point-in-time recallrecall_learnings.py --no-decay -- disable exponential decay (debug)
