Loading
Use when a project's CLAUDE.md has grown past what anyone reads and you want the agent to learn durable facts from its own sessions instead — or when asking why the agent keeps re-learning the same co
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add alirezarezvani/claude-skills --skill agent-memory -a cursor -y
Use when a project's CLAUDE.md has grown past what anyone reads and you want the agent to learn durable facts from its own sessions instead — or when asking why the agent keeps re-learning the same correction, why a remembered rule is wrong, or where a memory line came from. Implements a four-tier store (L0 transcripts / L1 candidates / L2 project context / L3 stable persona) where promotion is earned by recurrence across sessions and days, never by one confident statement, and nothing reaches a committed file without a human adopting it.
Use when a project's CLAUDE.md has grown past what anyone reads and you want the agent to learn durable facts from its own sessions instead — or when asking why the agent keeps re-learning the same correction, why a remembered rule is wrong, or where a memory line came from. Implements a four-tier store (L0 transcripts / L1 candidates / L2 project context / L3 stable persona) where promotion is earned by recurrence across sessions and days, never by one confident statement, and nothing reaches a committed file without a human adopting it.
Portability: stdlib only. No database, no embeddings, no network, no LLM calls.
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.
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 |
Nothing moves up because it sounded important. It moves up because it recurred.
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.
# 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.
.memory/staged/. Only an
explicit /cs:memory adopt touches a CLAUDE.md, and it backs both up first.--why resolving to ambiguous prints nothing rather
than guess: a wrong citation is worse than a missing one.Walk these one at a time before trusting the store.
CLAUDE.md did you last actually read before acting?.memory/ entirely?Rationale, open decisions, field schema: ../../DESIGN.md.