agent-memory
/agent-memory
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.
- Author
- alirezarezvani ↗
- Repository
- claude-skills ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 5
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 5 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/memory_core.py, scripts/memory_extract.py, scripts/memory_inspect.py, scripts/memory_promote.py, scripts/validate_examples.py
What it does and when to use 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.
Arguments
/agent-memory [optional: status | why \"<claim>\" | a tier name]
Original author description
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.
How it works
- The problem
- The four tiers
- The gates
- Use it
- Hard rules
- Forcing questions
SKILL.md preview
--- name: agent-memory description: 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. argument-hint: "[optional: status | why \"<claim>\" | a tier name]" license: MIT metadata: version: 1.0.0 build_pattern: "Tencent TencentDB-Agent-Memory's tiering concept rebuilt natively on Claude Code hooks; deterministic recurrence gates, no LLM, no database" distinct_from: "llm-wiki (a vault you write on purpose; this writes itself from sessions); skillopt-sleep (replays tasks to improve a skill; this extracts facts to remember); memory-engineering (audits and prices any memory system; this IS one, and is a legitimate subject of that audit)" --- # 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 ```bash # 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 1. **Redact before writing.** Every atom passes the filter before it reaches disk. Anything altered is quarantined from promotion. 2. **Propose, never apply.** Promotions land in `.memory/staged/`. Only an explicit `/cs-memory adopt` touches a `CLAUDE.md`, and it backs both up first. 3. **Cite, don't invent.** Every atom carries a back-pointer to the transcript line that produced it. `--why` resolving to *ambiguous* prints nothing rather than guess: a wrong citation is worse than a missing one. 4. **Never surface a contested claim as fact.** It is still injected — hiding the conflict is worse — but always tagged. 5. **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. 1. Which line in your `CLAUDE.md` did you last actually read before acting? 2. Would you rather the agent forget a true thing, or remember a false one? 3. When two remembered rules disagree, who decides — and when? 4. What would make you delete `.memory/` entirely? Rationale, open decisions, field schema: [`../../DESIGN.md`](../../DESIGN.md).
Files in this package (10)
- SKILL.md 5 KB
- assets/memory_schema.json 15 KB
- references/hook_capture_discipline.md 7 KB
- references/promotion_gate_design.md 7 KB
- references/tiered_memory_canon.md 7 KB
- scripts/memory_core.py 15 KB
- scripts/memory_extract.py 8 KB
- scripts/memory_inspect.py 11 KB
- scripts/memory_promote.py 10 KB
- scripts/validate_examples.py 22 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · alirezarezvani/claude-skills | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| komluk/scaffolding | 100 | MIT |
| nirholas/three.ws | 100 | Apache-2.0 |
| nimadorostkar/Claude-Skills-collection | 100 | MIT |
| norifumi3/cc-marketplace | 100 | MIT |
| OpenHands/extensions | 92 | MIT |
| HelixDevelopment/agent | 92 | MIT |
| VoDaiLocz/kilo-kit-mcp | 90 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version 2cac21df0f16 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90project-memory
Use when working in a repository that keeps durable project context, cross-session memory, incident history, decisions, or agent state across Claude, Codex, and later sessions. - 100memory-review
Review the file-based memory store via the Agent Monitor Config Explorer API: the user and project CLAUDE.md plus per-project auto-memory files under ~/.claude/projects/<slug>/memory/*.md. Groups by project, shows the index (MEMORY.md) vs per-fact files, and flags stale or… - 100audit-memory
Audit this repo's agent rules and memory files (CLAUDE.md, AGENTS.md, Cursor rules, the agent's memory folder) for lines that are wrong, out of date, in conflict, or no longer followed by the code. Use when the user asks to audit, check or clean up CLAUDE.md, AGENTS.md, rules or… - 100memory-tool
Give Claude agents persistent memory across conversations with the Claude API memory tool — a client-side file store under /memories that Claude reads and writes through commands your application executes. Covers setup, the six commands, SDK helpers, path-traversal protection,… - 100memory
Triage context-memory candidates mined from past AI coding sessions. Use when the user says "triage memory", "review memory", "mine memory", "/memory", or asks what durable facts their session history contains. Runs the mine, clusters paraphrased candidates, judges which facts… - 84memory
Store and retrieve durable agent memory — remember decisions, preferences, and session outcomes with calibrated salience; recall prior context before acting or resuming a project. Use whenever you store a memory, search memory, retrieve prior context, or check what was learned in past sessions.