remember

name	remember
description	Use whenever the user shares (or you discover) something that should survive session boundaries — architectural decisions, recurring user preferences, non-obvious constraints, "always do it this way" rules. Writes a tier-2 topic file in `.claude/memory/topics/`, adds a tier-1 pointer to the index, and snapshots any prior version to the lineage ledger.
when_to_use	Reach for this when the user says "remember that...", when a hard-won insight emerges from debugging, or when a constraint is too subtle to live only in CLAUDE.md. Do NOT use for retrieving a memory — use `/recall` instead; do NOT use for ephemeral session notes — those belong in TaskCreate or progress-log.
disable-model-invocation	true
allowed-tools	["Read","Write","Edit","Glob"]
logical	new topic file written under .claude/memory/topics/<slug>.md and pointer added to .claude/memory/index.md

/remember — Store to Memory

Three-Tier Memory Architecture

Tier	Location	Loaded	Purpose
1	.claude/memory/index.md	Always	One-line pointers — tiny, fast
2	.claude/memory/topics/*.md	On demand	Detailed topic files
3	Session transcripts	Never whole	Raw history, searchable via grep

How to Store

Step 1: Write the topic file

Create .claude/memory/topics/<slug>.md:

# <Topic Title>

Last verified: YYYY-MM-DD
Confidence: high | medium | low   # optional; omit to treat as medium
Version: v1
Previous: (none)

<Content: decisions, patterns, context, rationale>

Keep it scannable. Use bullet points. Include why, not just what.

If the topic already exists (update, not create):

1. Read the current file. Record its Version: value as prev (e.g. v2).

2. Snapshot it: copy the current contents to .claude/lineage/versions/memory/topics/<slug>/v<prev> (create parent directories as needed).

3. Write the new contents with Version: v<prev+1> and Previous: v<prev>.

4. Append to .claude/lineage/ledger.jsonl:

   {"ts":"<UTC>","operator":"commit","resource":"memory/topics/<slug>","version":"v<prev+1>","prev":"v<prev>","trigger":"remember","evidence":".claude/memory/topics/<slug>.md","actor":"memory:/remember"}
   

New topics (Version: v1, no prior snapshot) do not write a ledger entry — there is nothing to reverse. Versioning begins at the first update.

Step 2: Add pointer to index

Append one line to .claude/memory/index.md:

- [<Topic Title>](topics/<slug>.md) — <one-line hook, under 120 chars>

Examples

Example 1: new topic — first capture

Input: user says "remember that we never enable SAML on staging — auth team owns that toggle and we'd be stepping on their tests."

Output:

• .claude/memory/topics/staging-saml-policy.md created with Version: v1, Previous: (none), body explaining the rule + why (auth team test territory).
• .claude/memory/index.md gains - [Staging SAML policy](topics/staging-saml-policy.md) — auth team owns SAML toggle on staging; do not enable.
• No ledger entry (first version has nothing to reverse).

Example 2: existing topic — update with snapshot

Input: user says "update the staging SAML note — the rule is now 'never on staging or preview'."

Output:

• .claude/lineage/versions/memory/topics/staging-saml-policy/v1 snapshot taken.
• .claude/memory/topics/staging-saml-policy.md rewritten with Version: v2, Previous: v1, updated body.
• One JSON line appended to .claude/lineage/ledger.jsonl:

  {"ts":"2026-05-19T10:00:00Z","operator":"commit","resource":"memory/topics/staging-saml-policy","version":"v2","prev":"v1","trigger":"remember","evidence":".claude/memory/topics/staging-saml-policy.md","actor":"memory:/remember"}
  

• Index pointer unchanged (same file).

Rules

• Check if a related topic already exists before creating a new one — update instead
• Include Last verified: date so future sessions know staleness
• Confidence: is optional; when omitted it is treated as medium. Use high | medium | low to reflect how firmly the fact is established — not how recent it is. Recency is tracked separately by Last verified:. (§4.2, Table 1: per-entry confidence as a retrieval-ranking field alongside recency — arXiv:2605.26112)
• Don't store things derivable from code or git history
• Don't store ephemeral task details — those belong in tasks, not memory
• Frame stored knowledge as "Previously noted (may be outdated)" when recalled
• Max 50 lines per topic file. If it's longer, split into subtopics.

What to Store

Good candidates:

• Architectural decisions and their rationale
• User preferences that affect how you work
• Non-obvious project constraints (deadlines, compliance requirements)
• Patterns that took multiple attempts to discover
• External resource locations (dashboards, issue trackers, docs)

Bad candidates:

• Code structure (read the code)
• Git history (use git log)
• Current task progress (use tasks)
• Debugging solutions (the fix is in the code)