scriptoriumadmin/claude-skills
1
0
Fork 0
mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-09-07 08:26:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
claude-skills/engineering/agent-memory/commands/cs-memory.md
Claude a3b6a195cb
feat(agent-memory): implement the four-tier memory ladder 
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
2026-08-24 18:23:01 +00:00

3.9 KiB
Raw Permalink Blame History

description argument-hint
Inspect, trace, and adopt the tiered agent-memory store (status | why | contested | adopt | forget) 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.