What Should Claude‑mem Remember? Practical Guidelines for Effective Long‑Term Memory

Long‑Term Memory Is Not Chat History

Claude Code operates with short‑term sessions, so a long‑term memory plugin (claude‑mem) is needed to retain useful context across projects. The goal is not to archive every conversation but to surface high signal‑to‑noise context for decision making.

Storing every dialog, tool output, or log creates a “garbage‑filled” memory that does not help Claude Code. Valuable memory must convey the root cause, excluded paths, and future considerations rather than a raw sequence of actions.

查看了 auth.ts、session.ts、middleware.ts。
运行 pnpm test 失败。
修改了 session refresh 逻辑。
又运行了一次测试。
最后通过。

The above log is a history record but lacks actionable insight. A better memory entry would be:

"The login timeout root cause is that session refresh does not sync cookie maxAge. Future authentication changes must check session TTL, cookie maxAge, and front‑end refresh strategy."

Six Types of Information Worth Remembering

Determine whether an item will influence future decisions. If it will, it belongs in claude‑mem; otherwise, it should not occupy long‑term space.

Architecture decisions : rationale for module boundaries, middleware choices, legacy parameter retention, or service dependencies. Example: the permission module avoids a direct dependency on the organization service to prevent remote calls; future permission logic should reference the cached organization snapshot.

Historical bugs : real defects that indicate risk. Example: the order‑cancellation API previously suffered duplicate inventory release due to missing idempotency; future changes must cover repeated, concurrent, and re‑canceled orders.

Failed attempts : approaches that proved infeasible. Example: a payment callback tried timestamp deduplication, but gateway retry delays made timestamps unreliable; continue using callback_id + order_id as the idempotency key.

Test strategies : essential test scenarios, regression scope, mock rules, data constraints, and high‑risk paths. Example: after modifying coupon calculations, regressions must cover five scenarios: full‑reduction, discount, member price, refund recompute, and activity stacking.

Team conventions : stable rules go into CLAUDE.md; evolving experiential conventions belong in claude‑mem. Example: external payment gateways must be mocked locally; real calls previously polluted callback status.

Long‑term constraints : compatibility, performance thresholds, security requirements, external dependency limits, or gradual rollout restrictions. Example: the order‑detail API must retain the legacy status field for older mobile clients even after the front‑end stops using it.

All six share the common trait of influencing future tasks, which is the judging criterion.

Content to Avoid Storing

Temporary logs : full test output, one‑off error messages, or build stack traces that are only useful for the current session.

Large tool outputs : raw grep results, file snippets, or command returns. Preserve the conclusion, not the raw data.

Unresolved explorations : investigations without a clear outcome add uncertainty.

Expired solutions : architectures, interfaces, or test strategies that have been superseded.

Sensitive information : keys, tokens, connection strings, production accounts, or user privacy data must never be persisted.

Incorrect intermediate judgments : early mis‑diagnoses (e.g., suspecting Redis before discovering a session‑refresh issue) should be recorded as exclusions, not as facts.

For example, instead of storing "Login timeout caused by Redis TTL," store "Login timeout initially suspected Redis TTL but was excluded; actual root cause is missing cookie maxAge sync after session refresh." This retains the exclusion while avoiding false facts.

How to Write a Good Memory Entry

A high‑quality entry includes four elements: background, conclusion, impact, and follow‑up recommendation.

Example: "The order‑cancellation API historically caused duplicate inventory release because the cancel operation lacked idempotency protection. Impact: any future order‑status flow may corrupt inventory consistency. Recommendation: cover repeated, concurrent, and re‑canceled orders and verify inventory releases only once."

Compact natural‑language form: "Order‑cancellation API historically suffered duplicate inventory release; root cause is missing idempotency. Future changes must handle repeated, concurrent, and re‑canceled orders, ensuring inventory releases once."

For test development, use the "risk + scenario + validation point" pattern, e.g., "Coupon module’s main historical risk is incorrect amount calculation when activities overlap. When modifying price logic, cover full‑reduction, discount, member price, refund recompute, and activity stacking; verify final payment amount, discount details, and refund amount consistency."

Avoid three poor styles: (1) pure logs, (2) vague summaries, (3) overly broad rules without boundaries. Good memories are specific, searchable, and actionable.

Regular Memory Cleanup

Long‑term memory degrades over time; periodic pruning is essential.

Remove obsolete architecture solutions (e.g., old session logic after migrating to token).

Delete expired interface constraints (e.g., legacy field compatibility after old client deprecation).

Discard temporary workarounds that were only meant for a short period.

Eliminate duplicate entries that cause redundancy.

Resolve conflicting memories (e.g., contradictory idempotency advice about Redis).

After major refactors, explicitly ask Claude Code to clear outdated memories, e.g., "Mark all session‑refresh related memories as deprecated and adopt token‑refresh conclusions instead."

Organize cleanup by module: summarize current memories related to order cancellation, identify repeats, expirations, or conflicts, and propose removal actions.

Memory quality depends on both accurate writes and diligent deletions; without proper management Claude Code will either forget critical context or make wrong judgments.

Core takeaway: claude‑mem should retain only experience that continues to provide decision value, not every historical artifact.