memory-system

Memory and Personalization Architecture (Memory System)

R — Original Text (Reading)

Claude Web: userMemories injection + memory_user_edits tool + selective application rules + silent attribution + boundary examples Claude Code: File-based persistent memory with typed memories (user, feedback, project, reference) + MEMORY.md index Claude Opus 4.7: "NEVER reference sensitive memories in unrelated contexts" + bad example (proactively mentioning deceased pet) GPT-4o/GPT-4.5: bio tool for persistence + sensitive data prohibition FlintK12: Pedagogical memory (interests, preferences, grade level) + mandatory create_memory call Gemini CLI: save_memory tool + GEMINI.md files for project context

I — Methodological Skeleton (Interpretation)

The core design patterns of memory systems unfold around two axes: "lifecycle management" and "boundary control":

Memory Lifecycle (CRUL Model):

1. Create: Decide when to create a memory. FlintK12 adopts a "mandatory creation" strategy (mandatory create_memory call) to ensure key pedagogical information is not missed. Claude Web adopts "selective creation"—only creating when the user explicitly expresses a preference.
2. Retrieve: At the start of each conversation turn, inject relevant memories into the context window. The key design decision is "how much to inject" and "what to inject"—injecting everything consumes the context window, while selective injection requires relevance judgment.
3. Apply: Silently apply memory content to adjust replies, without explicitly referencing it in the reply. The counterexample from Claude Opus 4.7 is extremely important: if the user once mentioned a pet's death, the AI should not proactively bring it up in unrelated conversations.
4. Update: Allow users to edit or delete stored memories. Claude Web's memory_user_edits tool and Claude Code's typed memory system both support this capability.

Typed Memory: Claude Code divides memories into four categories: user (user preferences), feedback (interaction feedback), project (project context), reference (reference documents). Different types have different storage strategies, retrieval priorities, and application rules.

Boundary Control: The biggest risk of a memory system is not "failing to remember," but "remembering when it should not" or "referencing when it should not."

A1 — Case Analysis (Past Application)

Case 1: Claude Web's Silent Memory Application

• Problem: How can AI leverage user memories without making the conversation awkward or violating privacy?
• Use of the Design Pattern: Claude Web implements a "silent attribution" strategy—after memories are injected into the context, the AI should not reveal expressions such as "according to my memory" or "I remember you said" in its replies. Combined with boundary examples (such as "do not mention the user's deceased pet in unrelated contexts"), this ensures memory application is both effective and unobtrusive.
• Conclusion: The user experience quality of a memory system depends on "implicit application" rather than "explicit mention".

Case 2: Claude Code's file-based persistent memory

• Problem: How can a coding agent maintain context coherence across long projects?
• Use of the design pattern: Adopt file-based persistent memory, storing memory as typed files (user/feedback/project/reference), and use MEMORY.md as the index file. At the start of each session, restore the project context by reading MEMORY.md. This approach is more transparent, more editable, and easier to version-control than database storage.
• Conclusion: In professional tool scenarios, the transparency and editability of memory matter more than the degree of automation.

Case 3: FlintK12's mandatory teaching memory creation

• Problem: How can AI accumulate enough of a student profile within a limited number of conversation turns to achieve personalized teaching?
• Use of the design pattern: Implement a mandatory create_memory call—in every teaching interaction, the AI must call the memory creation tool to record the student's interests, comprehension level, and learning preferences. Pedagogical memory stores information such as interests, preferences, and grade level, for use in personalizing subsequent teaching content.
• Conclusion: In high-value scenarios (where educational outcomes depend directly on the degree of personalization), mandatory memory creation is better than waiting for an explicit trigger.

A2 — Trigger Scenarios (Future Trigger) ★

In what situations will users need this skill?

1. AI needs to remember user preferences, history, or context across sessions
2. The product needs a "personalized" experience but is unsure how to implement the memory architecture
3. Memory content may contain sensitive information and requires designing access control
4. AI exposed memory content in a reply that should not have been exposed
5. Need to decide on the memory storage method (files, database, vector store)

Language signals

• "AI needs to remember the user's preferences"
• "Maintain context across sessions"
• "How should we handle it when the user says 'remember this'"
• "The memory contains sensitive information"
• "How to design personalized recommendations"

Distinction from adjacent skills

• Difference from persona-design : persona-design defines "who the AI is" (static identity), while memory-system defines "what the AI knows about the user" (dynamic information). Identity does not change; memory keeps accumulating.
• Difference from safety-guardrails : safety-guardrails constrain the boundaries of AI behavior. In memory-system, the handling of sensitive memory requires the support of safety-guardrails, but the memory system itself is data management rather than behavior constraint.
• Difference from personality-system : personality-system defines switchable style overlay layers, while memory-system stores the user's style preferences (such as "the user likes concise replies"); these preferences can trigger the selection of a specific persona variant.

E — Executable Steps (Execution)

1. Step 1: Define the memory type system

   • Identify the categories of information the product needs to remember: user preferences, interaction history, project context, domain knowledge, etc.
   • Define creation trigger conditions, storage format, and expiration policy for each category
   • Completion criteria: Each memory type has a clear boundary definition, and different types do not overlap

2. Step 2: Design the creation mechanism

   • Determine the creation policy: mandatory creation (FlintK12 mode, suitable for high-value scenarios) or selective creation (Claude Web mode, suitable for general scenarios)
   • Define creation triggers: explicit triggers ("remember this") + implicit triggers (detecting expressions of preference)
   • Completion criteria: The creation mechanism can correctly determine whether a memory needs to be created in 95% of cases

3. Step 3: Implement silent application rules

   • Write the core application rules: Memory content should implicitly influence replies and should not be explicitly referenced
   • Write counterexamples: List behaviors that should not appear in replies (such as "according to my memory" and "I remember you said before")
   • Completion criteria: Users do not feel the discomfort of "being remembered" during conversation, but can experience the convenience of personalization

4. Step 4: Design boundary controls

   • Define sensitive memory categories (health, finances, family emergencies, etc.) and formulate special handling rules
   • Implement cross-context isolation: Claude Opus 4.7's rule "never reference sensitive memories in unrelated contexts"
   • Design a memory editing/deletion mechanism that allows users to view and manage stored memories
   • Completion criteria: Sensitive memories are not incorrectly referenced, and users have full control over their memories

5. Step 5: Choose a storage strategy

   • File-based storage (Claude Code's MEMORY.md): suitable for professional tools, transparent and editable
   • Structured storage (Claude Web's userMemories): suitable for consumer products, high-performance retrieval
   • Vector storage: suitable for large-scale knowledge and semantic retrieval scenarios
   • Completion criteria: The storage strategy is consistent with the product's memory scale, retrieval needs, and user expectations

B — Boundary (Boundary) ★

Do not use this skill in the following situations

• The AI product does not need any cross-session persistence (pure one-off conversations)
• The memory need can actually be solved through simple system prompt configuration (such as "always reply in Chinese")
• Attempting to use a memory system to replace a knowledge base or RAG (memory is user-related personalized data, not general knowledge)
• Launching a memory feature without designing a memory deletion/editing mechanism (this will seriously damage user trust)

Common failure modes

• Over-referencing memories: The AI frequently uses expressions such as "according to my memory" in replies, making users feel surveilled. Silent application rules should be strictly enforced.
• Sensitive memory leakage: Proactively mentioning the user's sensitive information in unrelated conversations. Claude Opus 4.7 clearly points out that this is a serious error—if the user mentions that a pet has died, the AI should not say "considering your pet just passed away..." in a subsequent conversation about "weekend plans".
• Memory bloat: Creating too many low-value memories (such as "the user used an exclamation mark"), causing memory storage to bloat and retrieval efficiency to decline. Strict creation thresholds should be set.
• Memory conflicts: Contradictory memories are stored (such as the user expressing different preferences at different times), and no conflict resolution strategy has been designed. A "most recent takes priority" or "explicit override" strategy should be adopted.
• Ignoring memory transparency: Users do not know what the AI has remembered and cannot view or delete memories. A memory management interface should be provided.