Skip to content
Skills Library
AI & agents · Building & coding

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.

Licence
MIT
Last repository change
23.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
5
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. The problem
  2. The four tiers
  3. The gates
  4. Use it
  5. Hard rules
  6. Forcing questions
Original SKILL.md headings · 91 lines, 635 words
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

RepositoryScoreLicence
This page · alirezarezvani/claude-skills100MIT
TerminalSkills/skills100Apache-2.0
komluk/scaffolding100MIT
nirholas/three.ws100Apache-2.0
nimadorostkar/Claude-Skills-collection100MIT
norifumi3/cc-marketplace100MIT
OpenHands/extensions92MIT
HelixDevelopment/agent92MIT
VoDaiLocz/kilo-kit-mcp90Apache-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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.