Memory Operation Primitives

As a Senior Data Engineer, you already know CRUD operations on databases. Today, we map that familiar concept onto AI Agent memory — but with a twist: memory here is not just static data; it’s the agent’s evolving understanding of the user, the task, and the world.

作为一名资深数据工程师，你已经熟悉数据库的 CRUD 操作。今天，我们将把这个熟悉的概念映射到 AI Agent 的记忆上——但这里有一个不同之处：这里的记忆不仅仅是静态数据，而是 Agent 对用户、任务和世界不断演化的理解。

What is “Memory Operation Primitives”?

In technical terms, these are four primitivesm. They are the minimum set of operations any agent memory system must implement. They define how an agent maintains state across interactions, enabling long-running tasks, personalization, and context coherence.

Store, Recall, Update and Forget.

CN: 用技术术语说，四种原语是 任何 Agent 记忆系统必须实现的最小操作集。它们定义了 Agent 如何在多次交互中维持状态，从而实现长时间运行的任务、个性化以及上下文连贯性。

Store = you write down a new fact the boss tells you.
Recall = you flip through the notebook to find that fact when needed.
Update = you cross out an old fact and write the corrected version.
Forget = you tear out pages that are no longer relevant to save space.

CN: 想象你是一位私人助理（即 Agent），手里有一个笔记本。

Store（保存） = 你把老板告诉你的新事实写下来。
Recall（回忆/检索） = 你需要时翻阅笔记本找到那条事实。
Update（更新） = 你划掉旧事实并写上修正后的版本。
Forget（遗忘/删除） = 你把不再相关的页撕掉，以节省空间。

Without these four operations, your agent is stateless — every conversation starts from zero. That’s fine for a simple Q&A bot, but useless for a real AI/LLM Engineer’s agent that needs to:

Remember user preferences across sessions (e.g., “always use Databricks SQL warehouse”).
Recall previous task results to avoid recomputation.
Update its understanding as new data arrives.
Forget outdated information to prevent hallucination and context overflow.

CN: 没有这四个操作，你的 Agent 就是无状态的——每次对话都从零开始。这对于简单的问答机器人还行，但对于一个真正的 AI/LLM 工程师的 Agent 来说毫无用处，因为它需要：

跨会话记住用户偏好（例如“始终使用 Databricks SQL warehouse”）。
回忆先前任务结果以避免重复计算。
随着新数据到达而更新其理解。
遗忘过时信息以防止幻觉和上下文溢出。

More importantly, these primitives are the building blocks for Short-term Memory (conversation state), Long-term Memory (user preferences), Episodic Memory (historical tasks), and Semantic Memory (knowledge base) — all of which appear later in your plan.

CN: 更重要的是，这些原语是短期记忆（对话状态）、长期记忆（用户偏好）、情景记忆（历史任务）和语义记忆（知识库）的构建块——这些都会在你后续的学习计划中出现。

What does each primitive contain?

1. Store (保存)

Aspect	EN	CN
Definition	Persist a new memory item into the memory system.	将一条新的记忆条目持久化到记忆系统中。
Input	Key (or ID), Content (text/structured data), Metadata (timestamp, type, importance), optionally a TTL (time-to-live).	Key（或ID）、内容（文本/结构化数据）、元数据（时间戳、类型、重要性）、可选 TTL（生存时间）。
Output	Confirmation of storage, or the generated ID.	存储确认，或生成的ID。
Example	Store: `user_preference` → `"preferred_cluster = 'large'"`	保存：`user_preference` → `"preferred_cluster = 'large'"`

2. Recall (回忆/检索)

Aspect	EN	CN
Definition	Retrieve a memory item by key, or perform a query (semantic/keyword) to find relevant memories.	通过 key 检索一条记忆条目，或执行查询（语义/关键词）以找到相关记忆。
Input	Key (exact lookup) or Query string + optional filters (type, date range).	Key（精确查找）或查询字符串 + 可选过滤器（类型、日期范围）。
Output	The memory item(s) or None.	记忆条目或 None。
Example	Recall `user_preference` → returns `"preferred_cluster = 'large'"`	回忆 `user_preference` → 返回 `"preferred_cluster = 'large'"`

3. Update (更新)

Aspect	EN	CN
Definition	Modify an existing memory item — either full replacement or partial merge.	修改已有的记忆条目——可以是完全替换或部分合并。
Input	Key, new content, merge strategy (overwrite vs. merge).	Key、新内容、合并策略（覆盖 vs. 合并）。
Output	Updated item or status.	更新后的条目或状态。
Example	Update `user_preference` → `"preferred_cluster = 'medium'"`	更新 `user_preference` → `"preferred_cluster = 'medium'"`

4. Forget (遗忘/删除)

Aspect	EN	CN
Definition	Remove a memory item, either hard-delete or soft-delete (mark expired).	移除一条记忆条目，可以是硬删除或软删除（标记过期）。
Input	Key or a condition (e.g., forget all memories older than 7 days).	Key 或一个条件（例如，遗忘所有超过7天的记忆）。
Output	Status (success/failure).	状态（成功/失败）。
Example	Forget `user_preference` → removes it.	遗忘 `user_preference` → 移除它。

Key Takeaways

要点 (Aspect)	EN (English)	CN (中文)
Four Primitives	Store, Recall, Update, Forget are the minimum CRUD operations for agent memory.	Store、Recall、Update、Forget 是 Agent 记忆的最小 CRUD 操作集。
Store	Persists a new memory with optional TTL and metadata.	持久化一条新记忆，可带 TTL 和元数据。
Recall	Retrieves by key, automatically checking expiration.	按 key 检索，自动检查过期。
Update	Supports both full replacement and partial merge (for dict content).	支持完全替换和部分合并（针对 dict 内容）。
Forget	Hard-delete or soft-delete; we implemented hard-delete.	硬删除或软删除；我们实现了硬删除。
TTL (Time-to-Live)	Expired items are automatically forgotten on recall, preventing context bloat.	过期的条目在 recall 时自动遗忘，防止上下文膨胀。
Backend Abstraction	Separate interface from implementation for easy swapping (in-memory vs SQLite).	将接口与实现分离，便于切换（内存 vs SQLite）。
Metadata	Always attach metadata (type, importance, source) to enable advanced filtering later.	始终附加元数据（类型、重要性、来源），以便以后实现高级过滤。
Async Consideration	For production, use async database drivers (e.g., aiosqlite, asyncpg). We’ll cover async in A17.	生产环境中使用异步数据库驱动（如 aiosqlite, asyncpg）。我们将在 A17 中讨论异步。
Why It Matters	These primitives form the foundation for all four memory types (Short, Long, Episodic, Semantic) in your plan.	这些原语构成了你计划中所有四种记忆类型（短期、长期、情景、语义）的基础。