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.
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- agent-memory
- 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)" }
- 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]
03 SKILL.md 正文
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.
04 同仓库更多 Skills
youtube-full
Use when the user needs YouTube transcripts, video search, channel browsing, playlist extraction, or content monitoring. Trigger phrases: 'get the transcript for', 'search YouTube for', 'what are the latest videos on', 'list this playlist', 'monitor this channel', or any request involving a YouTube URL, video ID, or @handle. Do NOT use for downloading video or audio files, YouTube engagement data (likes, comments), or private/age-restricted videos.
x-twitter-growth
X/Twitter growth engine for building audience, crafting viral content, and analyzing engagement. Use when the user wants to grow on X/Twitter, write tweets or threads, analyze their X profile, research competitors on X, plan a posting strategy, or optimize engagement. Complements social-content (generic multi-platform) with X-specific depth: algorithm mechanics, thread engineering, reply strategy, profile optimization, and competitive intelligence via web search.
write-a-skill
Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, or author a new skill.
wrap-up
Close out a launched Claude Managed Agent — recap every primitive the founder now owns, regenerate the single-file overview page, and suggest the next 1-2 upgrades. Use when the user says "wrap up", "close this out", "what do I own now", "give me the summary", "recap the agent", or when the orchestrator routes phase=wrap-up. primitives_inventory.py tables everything owned (agent, environment, session, memory, outcome, deployment); overview_page.py regenerates a self-contained ./my-agent/agent-overview.html; upgrade_suggester.py ranks the next moves from recorded deferrals plus standing hardening steps. Companion to run-without-you; the last stop before phase=done.
workflow-builder
Design and write deterministic multi-agent workflow scripts (.js files in .claude/workflows/) for Claude Code's Workflow tool. Use when a user wants to build, create, author, scaffold, or run a custom Claude Code workflow, orchestrate sub-agents (fan-out, pipeline, loop, judge-panel), or automate a repeatable multi-step task across fresh-context agents.
weekly-review
Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says "/cs:weekly-review". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.