agent-memory
Use when an agent keeps relearning the same correction, CLAUDE.md has grown unreadable, or you need to trace where a remembered rule came from. Promotes facts through four tiers only on recurrence across sessions and days, with memory_promote.py and a human adopt step.
How do I install this agent skill?
npx skills add https://github.com/alirezarezvani/claude-skills --skill agent-memoryIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a robust, security-conscious memory system that implements a tiered promotion ladder for agent facts. It uses deterministic, rule-based extraction and recurrence gates instead of LLMs or databases, and features built-in PII redaction and human-in-the-loop review for persistent storage. No malicious patterns or risky behaviors were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Agent Memory — promotion is earned, not asserted
Portability: stdlib only. No database, no embeddings, no network, no LLM calls.
The problem
A project's CLAUDE.md is a memory system with one tier and no eviction: every
durable fact and every passing preference land in the same always-loaded file,
until the important lines are diluted by the incidental ones. Facts learned
mid-session vanish at teardown unless someone writes them down.
The fix is not more storage — it is a promotion ladder. A claim earns its way toward always-loaded context by recurring; a human confirms the last step.
The four tiers
Tiers are distinguished by injection policy, not storage format.
| Tier | Holds | Injected | Committed |
|---|---|---|---|
| L0 | raw session transcripts | never | no (already on disk) |
| L1 | candidate atoms | on relevance, at prompt time | no (gitignored) |
| L2 | this project's context | every session start | yes, after adopt |
| L3 | stable cross-project persona | always | yes, after adopt |
The gates
Nothing moves up because it sounded important. It moves up because it recurred.
- L0 → L1 — an explicit marker fires (a directive, a correction, a stated preference, a named lesson, a reproducible failure). Rule-based, high precision, deliberately low recall.
- L1 → L2 — ≥ 3 distinct sessions spanning ≥ 2 distinct calendar days. A claim stated outright needs 2 sessions; the distinct-day rule still applies. A verified claim promotes on one observation and is the only day-exempt path.
- L2 → L3 — held in ≥ 2 distinct projects, aged ≥ 30 days, uncontested.
Two gates refuse rather than guess. A claim whose text was altered by redaction never promotes on evidence alone — the flag firing is evidence the source was sensitive, and a lexical filter finding one secret is not proof it found all of them. A claim with an open contradiction is frozen at L1 until a human resolves it; the incumbent is never silently overwritten.
Use it
# what is remembered, and what is blocking the next promotion
python3 scripts/memory_inspect.py --tier L1
# where did this line come from — sessions, days, transcript, quoted source
python3 scripts/memory_inspect.py --why "PR base branch is dev"
# every claim with an open contradiction, both directions of the join
python3 scripts/memory_inspect.py --contested
# dry-run the promotion pass; writes nothing
python3 scripts/memory_promote.py
Three hooks run the loop unattended: SessionStart injects L2 + L3,
UserPromptSubmit recalls relevant L1 atoms, SessionEnd captures and stages.
Each is disabled independently with AGENT_MEMORY_SESSIONSTART=0,
AGENT_MEMORY_USERPROMPTSUBMIT=0, AGENT_MEMORY_SESSIONEND=0. Every hook fails
open: a broken memory system costs you memory, never a session.
Hard rules
- Redact before writing. Every atom passes the filter before it reaches disk. Anything altered is quarantined from promotion.
- Propose, never apply. Promotions land in
.memory/staged/. Only an explicit/cs-memory adopttouches aCLAUDE.md, and it backs both up first. - Cite, don't invent. Every atom carries a back-pointer to the transcript
line that produced it.
--whyresolving to ambiguous prints nothing rather than guess: a wrong citation is worse than a missing one. - Never surface a contested claim as fact. It is still injected — hiding the conflict is worse — but always tagged.
- The committed tiers carry no paths. Promotion strips the back-pointer prefix, which embeds an OS username.
Forcing questions
Walk these one at a time before trusting the store.
- Which line in your
CLAUDE.mddid you last actually read before acting? - Would you rather the agent forget a true thing, or remember a false one?
- When two remembered rules disagree, who decides — and when?
- What would make you delete
.memory/entirely?
Rationale, open decisions, field schema: ../../DESIGN.md.
More in this skill
Load these only when the task needs them.
-
references/hook_capture_discipline.md — Hook discipline — running on someone else's critical path
-
references/promotion_gate_design.md — Designing the gates — why these thresholds, and what they cost
-
references/tiered_memory_canon.md — Tiered agent memory — the canon, and what this skill takes from it
-
python3 scripts/memory_extract.py --help— L0 -> L1. Rule-based, no LLM -
python3 scripts/validate_examples.py— drift gate for DESIGN.md, memory_schema.json and the worked examples
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/alirezarezvani/claude-skills/agent-memory">View agent-memory on skillZs</a>