mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-09-07 08:26:02 +00:00
a3b6a195cb
Turns DESIGN.md from a spec into a working plugin. Five stdlib scripts, three
hooks, agent, command, three references, plugin manifests.
The gates are the design:
L1 -> L2 >= 3 distinct sessions spanning >= 2 distinct calendar days
(`stated` = 2 sessions, day rule still applies; `verified` = 1
observation and is the only day-exempt path)
L2 -> L3 >= 2 distinct projects, >= 30 days, uncontested
Two gates refuse rather than guess. `redacted: true` blocks promotion on any
volume of evidence -- a durability-independent barrier, since a secret restated
across five sessions passes every recurrence gate; the flag firing means the
text was altered, a lexical filter finding one secret is not proof it found all
of them, and L2/L3 are committed to git. An open contradiction freezes both
claims, found by reverse join because the newer atom carries no flag.
All three hooks fail open: a broken memory system costs memory, never a session.
SessionEnd stages promotions to .memory/staged/ and never touches a CLAUDE.md;
only an explicit human adopt does, after backing both files up.
Verified, not asserted:
- all three pinned atom ids from DESIGN.md reproduce exactly
- both blocking gates demonstrated on sample input, named in the output
- end-to-end: two transcripts across two calendar days -> merged L1 atom ->
staged L2 promotion with the path prefix stripped
- reverse join blocks the unflagged newer atom
- cross-tier L2/L3 collision marked at injection time
- recall p50 29ms / p95 31ms / max 35ms spawn-to-exit, scoring itself 2-3ms
over 500 atoms -- interpreter cold start is the entire cost
- validate_examples.py 69 checks 0 failures; SKILL.md 6/6 PASS
- derive_counters --check, check_plugin_json --all, check_paths all clean
DESIGN.md 10.1's "+6" tool estimate corrected to +8 -- the delivered surface is
5 scripts + 3 hooks. README.md's deviations list is authoritative for that and
five other divergences from the pre-implementation spec.
Concept from TencentCloud/TencentDB-Agent-Memory (MIT). No upstream code.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EM5xmJ7AmTMg31rq68BCym
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
---
|
|
description: Inspect, trace, and adopt the tiered agent-memory store (status | why | contested | adopt | forget)
|
|
argument-hint: "status | why \"<claim>\" | contested | adopt | forget \"<claim>\""
|
|
---
|
|
|
|
# /cs:memory — curate what the agent remembers
|
|
|
|
Argument: `$ARGUMENTS` (default: `status`)
|
|
|
|
Scripts live at
|
|
`engineering/agent-memory/skills/agent-memory/scripts/`. All are stdlib-only and
|
|
read-only except where stated.
|
|
|
|
---
|
|
|
|
## `status` (default)
|
|
|
|
1. Run `memory_inspect.py --tier L3`, `--tier L2`, `--tier L1`.
|
|
2. Read `.memory/staged/promotions.json` if it exists.
|
|
3. Read the last 7 days of `.memory/errors.log` if it exists — **surface any
|
|
entry**. That file is where silently dropped writes are recorded, and a log
|
|
nobody is pointed at is the same as no log.
|
|
|
|
Report, in this order: what is always loaded (L3), what this project loads (L2),
|
|
how many candidates are waiting and what is blocking each, what is staged for
|
|
adoption, and any dropped writes.
|
|
|
|
**Do not adopt anything here.** `status` is read-only.
|
|
|
|
---
|
|
|
|
## `why "<claim>"`
|
|
|
|
Run `memory_inspect.py --why "<claim>"`.
|
|
|
|
Report the full provenance: observation count, distinct sessions, distinct
|
|
calendar days, first and latest transcript back-pointers, whether each resolves,
|
|
and the quoted source line when exactly one transcript matched.
|
|
|
|
If the resolution status is **`ambiguous`**, say so plainly and print no source
|
|
line. Two projects can hold a transcript of the same basename; guessing attaches
|
|
a real claim to the wrong session, and a wrong citation is worse than none.
|
|
|
|
---
|
|
|
|
## `contested`
|
|
|
|
Run `memory_inspect.py --contested`.
|
|
|
|
For each pair, present both claims with their dates and sources side by side and
|
|
ask the user which governs. **Do not pick.** Do not merge them. Do not mark one
|
|
resolved on your own judgement — resolution is a human decision by design.
|
|
|
|
---
|
|
|
|
## `adopt`
|
|
|
|
The only command in this file that writes. Six steps, in order, no skipping:
|
|
|
|
1. Run `memory_promote.py --stage` to refresh `.memory/staged/promotions.json`.
|
|
2. **Back up both `CLAUDE.md` files** (project and global) with a timestamped
|
|
copy. Do this before writing anything, every time.
|
|
3. Walk the staged list **one atom at a time**. For each, show the claim, the
|
|
evidence (sessions, days, sources), and the target file. Wait for the user.
|
|
4. **Refuse outright** any atom with `redacted: true` — no amount of evidence
|
|
substitutes for the human reading the original. Explain why and move on.
|
|
5. **Refuse** any atom whose citation does not resolve.
|
|
6. Append accepted atoms to the target `CLAUDE.md` under a clearly marked
|
|
`<!-- agent-memory: adopted -->` section, and log each to `.memory/adopted.log`.
|
|
|
|
Never write to a `CLAUDE.md` outside this flow. Never batch-accept.
|
|
|
|
---
|
|
|
|
## `forget "<claim>"`
|
|
|
|
1. Locate the atom with `memory_inspect.py --why "<claim>"`.
|
|
2. Show the user exactly what will be removed, from which tier, and whether it
|
|
was already adopted into a `CLAUDE.md`.
|
|
3. On confirmation, remove it from `.memory/atoms.jsonl` and, if it was adopted,
|
|
remove the corresponding line from the `CLAUDE.md` — after backing that file
|
|
up.
|
|
|
|
Removing an atom does **not** prevent re-learning. If the marker fires again in
|
|
a future session, it returns. That is correct: forgetting is not a permanent
|
|
veto, and saying so avoids a confusing surprise later. To stop it returning,
|
|
change the underlying fact or state the correction — a correction is itself a
|
|
high-confidence observation.
|
|
|
|
---
|
|
|
|
## Refuse and route
|
|
|
|
- No `.memory/` directory yet → say so. It is created on the first session end
|
|
with the hooks installed; nothing is wrong.
|
|
- User asks to lower a promotion threshold so something passes → refuse. Gates
|
|
are changed in the open, in `DESIGN.md`, not per-claim. Offer to record the
|
|
case as evidence the threshold is wrong.
|
|
- User asks to design or price a memory system generally → route to
|
|
`engineering/memory-engineering`. This skill *is* a memory system; that one
|
|
audits any of them, this one included.
|