Agent Memory — promotion is earned, not asserted
Agent Memory implements a four-tier memory store (L0 transcripts, L1 candidates, L2 project context, L3 stable persona) for Claude Code projects, where durable facts are promoted based on recurrence across sessions and days, not single assertions. It uses hooks to capture, recall, and inject memories, and requires human adoption before anything is committed to CLAUDE.md. The skill provides inspection and promotion scripts to manage the memory lifecycle.
✨ What it does
- Four-tier memory store with distinct injection policies: L0 transcripts, L1 candidates, L2 project context, L3 stable pe
- Deterministic promotion gates based on recurrence (e.g., ≥3 sessions across ≥2 days) with no LLM or database.
- Automatic capture via SessionEnd hook, relevance-based recall via UserPromptSubmit, and injection at SessionStart.
- Redaction filter before any atom is written to disk; altered atoms are quarantined from promotion.
- Human adoption required for any change to CLAUDE.md via /cs:memory adopt, with backups.
- Inspection scripts to view tiers, trace provenance, list contested claims, and dry-run promotions.
🎯 When to use it
- When CLAUDE.md has grown too large and you want the agent to learn durable facts from its own sessions instead of relying on a bloated file.
- When the agent keeps re-learning the same correction or forgetting important context between sessions.
- When you need to trace where a remembered rule came from or why a claim is not being promoted.
- When you want to audit or manage the memory store, including viewing contested claims or dry-running promotions.
🚀 How to use
Trigger: /cs:memory
Trigger the skill by asking about memory status, why a claim is remembered, or to manage promotions. Use the provided Python scripts directly or ask the agent to run them. The skill expects optional arguments like a tier name or a quoted claim. Example prompts:
python3 scripts/memory_inspect.py --tier L1
python3 scripts/memory_inspect.py --why "PR base branch is dev"
python3 scripts/memory_promote.py
You can also ask: "What is blocking promotion of that claim?" or "Show me contested memories."
📄 Output: Inspection reports, promotion dry-run results, and staged promotion files in .memory/staged/.
📦 Add this skill to Claude Code
# 1. Get the skills repo
git clone --depth 1 https://github.com/alirezarezvani/claude-skills /tmp/claude-skills
# 2. Copy this skill into your project (or ~/.claude/skills for all projects)
mkdir -p .claude/skills
cp -r /tmp/claude-skills/engineering/agent-memory/skills/agent-memory .claude/skills/agent-memorySkill source: engineering/agent-memory/skills/agent-memory/SKILL.md
⚠️ Good to know
Requires the skill's scripts and hooks to be installed; promotions are never applied automatically and require human adoption via /cs:memory adopt.
❓ FAQ
How does a claim get promoted from L1 to L2?
A claim must appear in at least 3 distinct sessions spanning at least 2 distinct calendar days. If stated outright, 2 sessions suffice, but the distinct-day rule still applies. Verified claims promote on one observation and are exempt from the day rule.
What happens to claims with open contradictions?
They are frozen at L1 until a human resolves the contradiction. They are still injected but always tagged as contested, and the incumbent is never silently overwritten.
Can I disable the hooks?
Yes, each hook can be disabled independently with environment variables: AGENT_MEMORY_SESSIONSTART=0, AGENT_MEMORY_USERPROMPTSUBMIT=0, AGENT_MEMORY_SESSIONEND=0. Hooks fail open, so a broken memory system costs memory but not the session.
🤖 Overview, features, install steps and FAQ were generated from the project's SKILL.md on Sep 4, 2026. Always check the original source before running commands.