diff --git a/docs/technical-architecture/10-memory-research.md b/docs/technical-architecture/10-memory-research.md
new file mode 100644
index 0000000..72859bd
--- /dev/null
+++ b/docs/technical-architecture/10-memory-research.md
@@ -0,0 +1,478 @@
+# 10. Agent 记忆机制调研与 ZK Data Agent 对比
+
+本文整理主流 Agent / AI 产品的记忆实现方式，并对照 ZK Data Agent 当前实现。目标不是判断哪一种“最好”，而是说明不同记忆机制分别解决什么问题，以及为什么我们当前选择“用户记忆 + Skill 使用记忆 + 异步整理队列 + Markdown 可编辑文件”的路线。
+
+调研时间：2026-05-19。
+
+## 1. 结论摘要
+
+主流记忆实现大致分为六类：
+
+| 类型 | 代表 | 核心做法 | 适合场景 |
+|------|------|----------|----------|
+| 产品级长期记忆 | ChatGPT Memory | 平台自动保存用户偏好和事实，并在后续对话中注入 | 通用个人助手 |
+| 会话状态记忆 | OpenAI Agents SDK Sessions、AutoGen Memory | 自动保存历史消息或把外部记忆注入上下文 | 线程连续对话 |
+| 文件化项目记忆 | Claude Code `CLAUDE.md`、Claw 基座 memory files | 通过项目/用户级 Markdown 文件向 Agent 注入稳定规则 | 工程项目、团队约定 |
+| 图/向量检索记忆 | LangGraph Store、Mem0、Zep/Graphiti | 抽取事实，存入向量库或知识图谱，按语义检索 | 长期、跨会话、海量事实 |
+| Agent 自主管理记忆 | Letta / MemGPT | Agent 有显式 memory blocks 和 archival memory，可读写管理 | 状态型 Agent、长期角色 |
+| 框架内置任务记忆 | CrewAI | 短期、长期、实体、上下文记忆组合 | 多 Agent 任务协作 |
+
+ZK Data Agent 当前更接近：
+
+```text
+文件化项目记忆
+  + 产品级用户记忆
+  + Skill 作用域记忆
+  + 异步记忆整理队列
+```
+
+它没有优先做向量库或知识图谱，而是选择 Markdown 文件作为最终记忆正文。这个取舍适合当前团队场景：记忆内容需要能被用户看到、编辑、删除，并且要按 Skill 作用域精准注入。
+
+## 2. 主流实现机制
+
+### 2.1 ChatGPT Memory：产品级个人长期记忆
+
+ChatGPT Memory 的核心是平台级用户记忆。它会保存用户偏好、事实和历史对话中有持续价值的信息，并在后续对话中使用。用户可以查看、管理、删除保存的记忆，也可以关闭相关能力。
+
+机制特点：
+
+- 记忆作用域是用户账号。
+- 由产品后台判断哪些内容值得保存。
+- 注入方式对用户透明，用户看到的是“助手更了解我”。
+- 适合通用个人助手，不适合表达复杂业务流程结构。
+
+和我们的关系：
+
+ZK Data Agent 的“用户记忆”借鉴了这个方向，但没有把全部记忆做成黑盒。我们把最终正文落到 `user.md`，并在 UI 里允许用户编辑。
+
+### 2.2 OpenAI Agents SDK Sessions：会话状态记忆
+
+OpenAI Agents SDK 的 Sessions 主要解决“同一个会话线程里自动保留历史上下文”。开发者不需要每轮手动传入完整历史，Session 会保存对话项，并在下一轮运行时自动带上。
+
+机制特点：
+
+- 更偏 conversation state，而不是长期个人偏好。
+- 适合多轮会话连续执行。
+- 常见实现是 SQLite / SQLAlchemy / 自定义 session backend。
+- 记忆对象主要是消息历史，不是抽象后的长期知识。
+
+和我们的关系：
+
+ZK Data Agent 也有 session 持久化，但我们把它和“长期记忆”分开：
+
+```text
+session.json
+  保存当前会话消息、工具调用、产物和运行事件。
+
+memory/user.md、memory/skills/*.md
+  保存跨会话长期偏好和 Skill 使用经验。
+```
+
+这个区分很重要：会话历史服务“恢复当前任务”，长期记忆服务“下次任务更懂用户和业务”。
+
+### 2.3 Claude Code / OpenClaw / Claw：文件化项目记忆
+
+Claude Code 使用 `CLAUDE.md` 作为项目或用户级记忆文件，常用于保存仓库规则、构建命令、代码风格、项目约定等。OpenClaw / Claw 类 Code Agent 基座通常也会保留这条路线：从全局或工作目录发现记忆文件，并把内容注入上下文。
+
+在当前仓库里，对应实现主要是：
+
+```text
+src/agent_context.py
+src/session_memory_compact.py
+```
+
+其中 `agent_context.py` 负责发现全局和目录级 memory files，`session_memory_compact.py` 负责会话压缩场景下的 session memory 摘要。
+
+机制特点：
+
+- 记忆是文本文件，天然可读、可版本化。
+- 非常适合工程项目规则和团队约定。
+- 注入通常按目录/项目作用域进行。
+- 记忆更新更多依赖人工维护，而不是完全自动。
+
+和我们的关系：
+
+ZK Data Agent 继承了“文件化、可编辑、可解释”的优点，但把作用域进一步细分：
+
+```text
+user.md
+  用户级偏好和稳定习惯。
+
+skills/<skill-name>.md
+  某个 Skill 的使用经验、踩坑、格式偏好和边界修正。
+```
+
+也就是说，我们不是只有“项目记忆”，而是增加了“Skill 记忆”这一层。
+
+### 2.4 LangGraph：线程状态 + 长期 Memory Store
+
+LangGraph 把 memory 分成 short-term memory 和 long-term memory。短期记忆通常跟 thread 绑定，用来维持一次会话；长期记忆通过 store 按 namespace 保存，可以跨 thread 召回。它还把长期记忆进一步拆成 semantic、episodic、procedural 等类型。
+
+机制特点：
+
+- thread state 解决会话内上下文。
+- store 解决跨会话长期信息。
+- 支持按 user id / namespace 组织记忆。
+- 长期记忆可以由应用逻辑或 Agent 写入、搜索、更新。
+
+和我们的关系：
+
+ZK Data Agent 当前没有引入通用 Store / VectorStore，而是用文件系统和 SQLite 队列实现一个轻量版本：
+
+```text
+namespace = account_id + memory kind + skill_name
+storage = Markdown files + SQLite queue
+retrieval = user memory always considered, skill memory按启用 Skill 精准注入
+```
+
+这比 LangGraph Store 简单，但更直接服务我们当前的 Skill 工作台。
+
+### 2.5 Mem0：独立记忆层
+
+Mem0 更像一个独立 memory layer。典型链路是：从对话中抽取事实，存入记忆系统；后续根据 query 检索相关记忆，再注入给模型。它强调 add / search / update / delete 这类记忆 API，也支持面向用户、Agent、session 等维度组织。
+
+机制特点：
+
+- 记忆层和 Agent 框架解耦。
+- 常见存储后端是向量、图或混合检索。
+- 强调自动抽取、去重、更新和语义召回。
+- 适合大规模个性化 Agent 或跨应用记忆服务。
+
+和我们的关系：
+
+ZK Data Agent 目前没有把记忆做成独立检索服务。原因是我们的高频需求不是“从海量事实里语义搜索”，而是“把少量稳定经验准确注入到对应 Skill”。如果未来 Skill 记忆膨胀，可以在 Markdown 之外增加 Mem0 类似的检索层。
+
+### 2.6 Letta / MemGPT：Agent 自主管理内存
+
+Letta 延续 MemGPT 思路，把 Agent 看成有长期状态的主体。它通常区分 core memory 和 archival memory：core memory 是短小、常驻上下文的重要信息；archival memory 是更大的外部记忆空间，Agent 可以通过工具读写。
+
+机制特点：
+
+- Agent 可以主动管理自己的记忆。
+- core memory 常驻，archival memory 需要检索。
+- 适合长期角色 Agent、个人助理、需要自我状态连续性的 Agent。
+- 复杂度更高，需要更强的记忆写入约束和审计。
+
+和我们的关系：
+
+ZK Data Agent 没有让主 Agent 在执行链路里自由修改记忆。我们把记忆写入放到后台 worker，避免主任务因为记忆整理变慢或出错。这是一个更保守的团队平台取舍。
+
+### 2.7 Zep / Graphiti：时间感知知识图谱记忆
+
+Zep / Graphiti 代表的是 temporal knowledge graph 路线：从对话或事件中抽取实体和关系，形成带时间属性的知识图谱。它解决的问题不是简单偏好记忆，而是“事实如何随时间变化”“实体关系如何演进”。
+
+机制特点：
+
+- 记忆结构是实体、关系、事件、时间。
+- 适合复杂事实网络和时间演化。
+- 检索结果可以包含关系路径和上下文。
+- 实现成本和运维复杂度高于 Markdown 或向量检索。
+
+和我们的关系：
+
+标签边界、业务规则、Skill 使用经验目前更适合文本化规则，不一定需要图谱。但如果未来要做“用户、Skill、数据集、标签、错误类型、修复策略”之间的关系分析，图谱路线会有价值。
+
+### 2.8 CrewAI：多 Agent 任务记忆
+
+CrewAI 的记忆体系主要服务多 Agent 协作，通常包含 short-term memory、long-term memory、entity memory 和 contextual memory。它关注的是任务过程中多个 Agent 如何共享上下文和持续改进。
+
+机制特点：
+
+- 和 Crew / Agent / Task 结构绑定。
+- 强调任务协作过程中的上下文复用。
+- 对实体、任务经验有独立组织方式。
+
+和我们的关系：
+
+ZK Data Agent 当前不是多 Agent 编排优先，而是单个工作台 Agent + Skill 能力包优先。Skill 记忆在某种程度上承担了“任务经验记忆”的角色。
+
+### 2.9 AutoGen：Memory 组件注入上下文
+
+AutoGen 的 AgentChat 提供 Memory 抽象，可以把 list memory、vector memory 等组件挂到 AssistantAgent 上。运行时 Memory 会根据消息更新上下文，或把检索结果添加到模型输入。
+
+机制特点：
+
+- Memory 是 Agent 可插拔组件。
+- 可以使用简单列表，也可以接向量检索。
+- 更偏框架扩展点，而不是产品级记忆管理 UI。
+
+和我们的关系：
+
+ZK Data Agent 的记忆也可以理解为一个可插拔上下文组件，但我们额外做了用户 UI、Skill 作用域和后台队列。
+
+## 3. ZK Data Agent 当前实现
+
+实现入口：
+
+```text
+src/personal_memory.py
+backend/api/server.py
+frontend/app/components/assistant-ui/threadlist-sidebar.tsx
+```
+
+### 3.1 存储结构
+
+每个账号有独立记忆目录：
+
+```text
+.port_sessions/accounts/<account_id>/memory/
+  user.md
+  skills/
+    <skill-name>.md
+  memory.db
+```
+
+其中：
+
+- `user.md`：用户级长期记忆。
+- `skills/<skill>.md`：某个 Skill 的使用记忆。
+- `memory.db`：事件队列、状态和 revision 账本。
+
+### 3.2 注入逻辑
+
+模型调用前，后端调用：
+
+```text
+memory_manager.render_injection(account_id, enabled_skill_names)
+```
+
+注入规则：
+
+```text
+用户记忆
+  账号级，作为长期偏好注入。
+
+Skill 使用记忆
+  只读取当前启用 Skill 对应的 skills/<skill>.md。
+
+冲突优先级
+  用户本轮明确要求 > 个性化记忆。
+```
+
+这避免了一个常见问题：所有记忆都无差别注入导致上下文污染。
+
+### 3.3 生成时机
+
+每次交互结束后，后端调用：
+
+```text
+memory_manager.enqueue_interaction(...)
+```
+
+系统不会每轮同步整理记忆，而是先检测信号：
+
+```text
+显式记忆词：
+记住、以后、下次、默认、总是、不要、应该、固定
+
+纠错词：
+不对、不是这样、格式错、之前说过、还是不行
+
+Skill 经验：
+skill、工具、流程、格式
+
+工具经验：
+模型返回的工具参数不是合法 JSON
+```
+
+命中后写入 SQLite pending 队列。显式记忆优先级更高。
+
+### 3.4 异步整理
+
+后台 worker 每 5 秒扫描账号事件，每次最多处理 8 条 pending event：
+
+```text
+pending -> processing -> done / failed
+```
+
+整理方式：
+
+1. 读取已有 `user.md` 和相关 `skills/<skill>.md`。
+2. 把一批事件交给模型做“整理式合并”。
+3. 模型必须输出 JSON：
+
+```json
+{
+  "user_memory": "完整 Markdown 或空字符串",
+  "skill_memories": {
+    "skill-name": "完整 Markdown"
+  }
+}
+```
+
+4. 如果模型输出不可解析，则走 fallback 规则。
+5. 写入 Markdown 文件，并更新 revision。
+
+### 3.5 用户可编辑
+
+前端左下角“记忆”入口支持：
+
+- 查看用户记忆行数。
+- 查看 Skill 记忆列表。
+- 编辑用户记忆。
+- 编辑某个 Skill 记忆。
+- 查看记忆队列状态。
+
+管理后台只看队列、用量等统计，不展示其他用户具体记忆内容。
+
+## 4. 对比表
+
+| 维度 | ChatGPT | Claude Code / OpenClaw | LangGraph / Mem0 / Zep | Letta | ZK Data Agent |
+|------|---------|--------------------|-------------------------|-------|---------------|
+| 主要目标 | 个人助手个性化 | 项目规则注入 | 长期检索记忆 | 状态型长期 Agent | 团队 Skill 工作台 |
+| 记忆粒度 | 用户 | 用户/项目/目录 | 用户/线程/实体/namespace | Agent memory block | 用户 + Skill |
+| 存储形态 | 平台内部 | Markdown 文件 | Store / 向量 / 图 | Core + archival memory | Markdown + SQLite queue |
+| 生成时机 | 产品后台自动 | 多为人工维护 | 自动抽取 / API 写入 | Agent 主动管理 | 交互结束后异步整理 |
+| 检索方式 | 平台决定 | 直接注入文件 | 语义搜索 / 图检索 | Core 常驻 + archival 检索 | 用户记忆 + 当前 Skill 记忆注入 |
+| 可编辑性 | 用户可管理 | 文件可编辑 | 取决于产品/API | 通常需要工具/API | UI 可编辑 Markdown |
+| 适合业务流程沉淀 | 中 | 中 | 高，但工程复杂 | 高，但复杂 | 高，且轻量 |
+| 风险 | 黑盒、难按业务作用域隔离 | 容易依赖人工维护 | 检索和更新复杂 | 主链路复杂度高 | 暂无语义召回和图谱能力 |
+
+## 5. 为什么当前方案适合我们
+
+### 5.1 我们需要的是 Skill 使用经验，而不只是用户偏好
+
+通用记忆多关注“用户是谁、用户喜欢什么”。我们的高频需求更像：
+
+```text
+product-data 生成数据时，用户偏好什么确认流程？
+标签大师判断时，哪些边界经常被纠正？
+online-mining-v2 查询线上日志时，哪些字段和表更稳定？
+某个 Skill 写文件时，模型容易踩什么坑？
+```
+
+这些经验天然和 Skill 绑定。因此 `skills/<skill>.md` 比单一用户记忆更准确。
+
+### 5.2 我们需要可审计、可编辑，而不是完全黑盒
+
+团队平台里，记忆不能只存在模型或向量库内部。用户需要能看到：
+
+- 记住了什么。
+- 为什么下一次会注入。
+- 哪里可以手动修改。
+- 哪些记忆是用户级，哪些是 Skill 级。
+
+Markdown 文件在这点上比纯向量库更直接。
+
+### 5.3 主链路不能被记忆整理拖慢
+
+数据生成、线上挖掘、标签判断本身就是长任务。记忆整理如果同步放在主链路里，会增加延迟和失败面。
+
+当前设计是：
+
+```text
+主链路：只读取已有记忆 + 入队事件
+后台：异步整理、合并、失败重试/记录
+```
+
+这和团队生产工具的稳定性要求更匹配。
+
+### 5.4 Skill 作用域注入能降低上下文污染
+
+如果所有记忆每次都注入，模型会被无关偏好干扰。当前只注入启用 Skill 的记忆：
+
+```text
+启用 product-data -> 注入 product-data 使用记忆
+启用 label-master -> 注入 label-master 使用记忆
+未启用某 Skill -> 不注入该 Skill 记忆
+```
+
+这使记忆更像“能力使用手册的增量补丁”，而不是一坨全局上下文。
+
+## 6. 当前不足和后续方向
+
+### 6.1 缺少语义召回
+
+当前 Skill 记忆是按 Skill 文件整体注入，不做向量检索。如果某个 Skill 记忆变得很长，可能需要：
+
+- 按章节拆分。
+- 引入轻量 embedding 检索。
+- 只注入和当前 query 相关的片段。
+
+### 6.2 缺少结构化 schema
+
+Markdown 易编辑，但不方便做强约束。后续可以让 Skill 记忆同时存在：
+
+```text
+human.md
+structured.json
+```
+
+其中 Markdown 给人看，JSON 给程序做筛选和校验。
+
+### 6.3 缺少记忆质量评估
+
+目前能看到队列状态，但还没有系统评估：
+
+- 哪些记忆被注入。
+- 注入后是否减少纠错。
+- 哪些记忆过期。
+- 哪些 Skill 记忆导致误导。
+
+后续可以把 memory revision 与 session outcome 关联起来。
+
+### 6.4 缺少跨用户团队记忆
+
+当前是账号级记忆。团队共性经验仍主要沉淀在 Skill 本体里。未来可以区分：
+
+```text
+个人 Skill 记忆
+  某个用户自己的偏好和使用习惯。
+
+团队 Skill 记忆
+  多人使用后沉淀的稳定经验，经 review 后合入 Skill。
+```
+
+这样可以形成从“个人经验”到“团队 Skill 知识”的晋升路径。
+
+## 7. 建议的技术路线
+
+短期保持当前架构：
+
+```text
+Markdown 可编辑记忆
+SQLite 异步队列
+按 Skill 注入
+UI 可查看可修改
+后台可观测队列
+```
+
+中期增强：
+
+```text
+记忆片段化
+记忆注入日志
+过期/冲突检测
+记忆质量指标
+```
+
+长期可选：
+
+```text
+向量检索：解决 Skill 记忆膨胀后的相关片段召回。
+图谱记忆：解决用户、Skill、标签、数据集、错误类型之间的关系分析。
+团队记忆晋升：把多用户共性 Skill 经验 review 后写回 Git Skill。
+```
+
+## 8. 资料来源
+
+- OpenAI Help：ChatGPT Memory FAQ
+  https://help.openai.com/en/articles/8590148-memory-faq
+- OpenAI Agents SDK：Sessions
+  https://openai.github.io/openai-agents-python/sessions/
+- Anthropic Claude Code：Memory
+  https://docs.anthropic.com/en/docs/claude-code/memory
+- LangChain / LangGraph：Memory concepts
+  https://docs.langchain.com/oss/python/concepts/memory
+- Mem0 documentation
+  https://docs.mem0.ai/
+- Letta documentation
+  https://docs.letta.com/
+- Zep / Graphiti documentation
+  https://help.getzep.com/
+- CrewAI Memory concepts
+  https://docs.crewai.com/concepts/memory
+- Microsoft AutoGen AgentChat Memory
+  https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/memory.html
+- ZK Data Agent 当前实现
+  `src/personal_memory.py`、`docs/technical-architecture/05-workspace-memory-observability.md`
diff --git a/docs/technical-architecture/README.md b/docs/technical-architecture/README.md
index a7c3d4d..8e713bd 100644
--- a/docs/technical-architecture/README.md
+++ b/docs/technical-architecture/README.md
@@ -14,6 +14,7 @@
 7. [online-mining-v2 Skill 实现](07-online-mining-v2.md)
 8. [label-master Skill 实现](08-label-master.md)
 9. [外部系统 Skill：ELK、SQL、模型迭代](09-external-skills.md)
+10. [Agent 记忆机制调研与对比](10-memory-research.md)
 
 ## 一句话定位
 
diff --git a/frontend/app/app/doc/[slug]/page.tsx b/frontend/app/app/doc/[slug]/page.tsx
index 8bcd8b3..b660502 100644
--- a/frontend/app/app/doc/[slug]/page.tsx
+++ b/frontend/app/app/doc/[slug]/page.tsx
@@ -51,6 +51,11 @@ const technicalDocs = {
 		file: "09-external-skills.md",
 		image: "/doc-assets/technical/09-external-skills.png",
 	},
+	"10-memory-research": {
+		title: "Agent 记忆机制调研与对比",
+		file: "10-memory-research.md",
+		image: null,
+	},
 } as const;
 
 type TechnicalDocSlug = keyof typeof technicalDocs;
diff --git a/frontend/app/public/doc-assets/technical-docs/10-memory-research.md b/frontend/app/public/doc-assets/technical-docs/10-memory-research.md
new file mode 100644
index 0000000..72859bd
--- /dev/null
+++ b/frontend/app/public/doc-assets/technical-docs/10-memory-research.md
@@ -0,0 +1,478 @@
+# 10. Agent 记忆机制调研与 ZK Data Agent 对比
+
+本文整理主流 Agent / AI 产品的记忆实现方式，并对照 ZK Data Agent 当前实现。目标不是判断哪一种“最好”，而是说明不同记忆机制分别解决什么问题，以及为什么我们当前选择“用户记忆 + Skill 使用记忆 + 异步整理队列 + Markdown 可编辑文件”的路线。
+
+调研时间：2026-05-19。
+
+## 1. 结论摘要
+
+主流记忆实现大致分为六类：
+
+| 类型 | 代表 | 核心做法 | 适合场景 |
+|------|------|----------|----------|
+| 产品级长期记忆 | ChatGPT Memory | 平台自动保存用户偏好和事实，并在后续对话中注入 | 通用个人助手 |
+| 会话状态记忆 | OpenAI Agents SDK Sessions、AutoGen Memory | 自动保存历史消息或把外部记忆注入上下文 | 线程连续对话 |
+| 文件化项目记忆 | Claude Code `CLAUDE.md`、Claw 基座 memory files | 通过项目/用户级 Markdown 文件向 Agent 注入稳定规则 | 工程项目、团队约定 |
+| 图/向量检索记忆 | LangGraph Store、Mem0、Zep/Graphiti | 抽取事实，存入向量库或知识图谱，按语义检索 | 长期、跨会话、海量事实 |
+| Agent 自主管理记忆 | Letta / MemGPT | Agent 有显式 memory blocks 和 archival memory，可读写管理 | 状态型 Agent、长期角色 |
+| 框架内置任务记忆 | CrewAI | 短期、长期、实体、上下文记忆组合 | 多 Agent 任务协作 |
+
+ZK Data Agent 当前更接近：
+
+```text
+文件化项目记忆
+  + 产品级用户记忆
+  + Skill 作用域记忆
+  + 异步记忆整理队列
+```
+
+它没有优先做向量库或知识图谱，而是选择 Markdown 文件作为最终记忆正文。这个取舍适合当前团队场景：记忆内容需要能被用户看到、编辑、删除，并且要按 Skill 作用域精准注入。
+
+## 2. 主流实现机制
+
+### 2.1 ChatGPT Memory：产品级个人长期记忆
+
+ChatGPT Memory 的核心是平台级用户记忆。它会保存用户偏好、事实和历史对话中有持续价值的信息，并在后续对话中使用。用户可以查看、管理、删除保存的记忆，也可以关闭相关能力。
+
+机制特点：
+
+- 记忆作用域是用户账号。
+- 由产品后台判断哪些内容值得保存。
+- 注入方式对用户透明，用户看到的是“助手更了解我”。
+- 适合通用个人助手，不适合表达复杂业务流程结构。
+
+和我们的关系：
+
+ZK Data Agent 的“用户记忆”借鉴了这个方向，但没有把全部记忆做成黑盒。我们把最终正文落到 `user.md`，并在 UI 里允许用户编辑。
+
+### 2.2 OpenAI Agents SDK Sessions：会话状态记忆
+
+OpenAI Agents SDK 的 Sessions 主要解决“同一个会话线程里自动保留历史上下文”。开发者不需要每轮手动传入完整历史，Session 会保存对话项，并在下一轮运行时自动带上。
+
+机制特点：
+
+- 更偏 conversation state，而不是长期个人偏好。
+- 适合多轮会话连续执行。
+- 常见实现是 SQLite / SQLAlchemy / 自定义 session backend。
+- 记忆对象主要是消息历史，不是抽象后的长期知识。
+
+和我们的关系：
+
+ZK Data Agent 也有 session 持久化，但我们把它和“长期记忆”分开：
+
+```text
+session.json
+  保存当前会话消息、工具调用、产物和运行事件。
+
+memory/user.md、memory/skills/*.md
+  保存跨会话长期偏好和 Skill 使用经验。
+```
+
+这个区分很重要：会话历史服务“恢复当前任务”，长期记忆服务“下次任务更懂用户和业务”。
+
+### 2.3 Claude Code / OpenClaw / Claw：文件化项目记忆
+
+Claude Code 使用 `CLAUDE.md` 作为项目或用户级记忆文件，常用于保存仓库规则、构建命令、代码风格、项目约定等。OpenClaw / Claw 类 Code Agent 基座通常也会保留这条路线：从全局或工作目录发现记忆文件，并把内容注入上下文。
+
+在当前仓库里，对应实现主要是：
+
+```text
+src/agent_context.py
+src/session_memory_compact.py
+```
+
+其中 `agent_context.py` 负责发现全局和目录级 memory files，`session_memory_compact.py` 负责会话压缩场景下的 session memory 摘要。
+
+机制特点：
+
+- 记忆是文本文件，天然可读、可版本化。
+- 非常适合工程项目规则和团队约定。
+- 注入通常按目录/项目作用域进行。
+- 记忆更新更多依赖人工维护，而不是完全自动。
+
+和我们的关系：
+
+ZK Data Agent 继承了“文件化、可编辑、可解释”的优点，但把作用域进一步细分：
+
+```text
+user.md
+  用户级偏好和稳定习惯。
+
+skills/<skill-name>.md
+  某个 Skill 的使用经验、踩坑、格式偏好和边界修正。
+```
+
+也就是说，我们不是只有“项目记忆”，而是增加了“Skill 记忆”这一层。
+
+### 2.4 LangGraph：线程状态 + 长期 Memory Store
+
+LangGraph 把 memory 分成 short-term memory 和 long-term memory。短期记忆通常跟 thread 绑定，用来维持一次会话；长期记忆通过 store 按 namespace 保存，可以跨 thread 召回。它还把长期记忆进一步拆成 semantic、episodic、procedural 等类型。
+
+机制特点：
+
+- thread state 解决会话内上下文。
+- store 解决跨会话长期信息。
+- 支持按 user id / namespace 组织记忆。
+- 长期记忆可以由应用逻辑或 Agent 写入、搜索、更新。
+
+和我们的关系：
+
+ZK Data Agent 当前没有引入通用 Store / VectorStore，而是用文件系统和 SQLite 队列实现一个轻量版本：
+
+```text
+namespace = account_id + memory kind + skill_name
+storage = Markdown files + SQLite queue
+retrieval = user memory always considered, skill memory按启用 Skill 精准注入
+```
+
+这比 LangGraph Store 简单，但更直接服务我们当前的 Skill 工作台。
+
+### 2.5 Mem0：独立记忆层
+
+Mem0 更像一个独立 memory layer。典型链路是：从对话中抽取事实，存入记忆系统；后续根据 query 检索相关记忆，再注入给模型。它强调 add / search / update / delete 这类记忆 API，也支持面向用户、Agent、session 等维度组织。
+
+机制特点：
+
+- 记忆层和 Agent 框架解耦。
+- 常见存储后端是向量、图或混合检索。
+- 强调自动抽取、去重、更新和语义召回。
+- 适合大规模个性化 Agent 或跨应用记忆服务。
+
+和我们的关系：
+
+ZK Data Agent 目前没有把记忆做成独立检索服务。原因是我们的高频需求不是“从海量事实里语义搜索”，而是“把少量稳定经验准确注入到对应 Skill”。如果未来 Skill 记忆膨胀，可以在 Markdown 之外增加 Mem0 类似的检索层。
+
+### 2.6 Letta / MemGPT：Agent 自主管理内存
+
+Letta 延续 MemGPT 思路，把 Agent 看成有长期状态的主体。它通常区分 core memory 和 archival memory：core memory 是短小、常驻上下文的重要信息；archival memory 是更大的外部记忆空间，Agent 可以通过工具读写。
+
+机制特点：
+
+- Agent 可以主动管理自己的记忆。
+- core memory 常驻，archival memory 需要检索。
+- 适合长期角色 Agent、个人助理、需要自我状态连续性的 Agent。
+- 复杂度更高，需要更强的记忆写入约束和审计。
+
+和我们的关系：
+
+ZK Data Agent 没有让主 Agent 在执行链路里自由修改记忆。我们把记忆写入放到后台 worker，避免主任务因为记忆整理变慢或出错。这是一个更保守的团队平台取舍。
+
+### 2.7 Zep / Graphiti：时间感知知识图谱记忆
+
+Zep / Graphiti 代表的是 temporal knowledge graph 路线：从对话或事件中抽取实体和关系，形成带时间属性的知识图谱。它解决的问题不是简单偏好记忆，而是“事实如何随时间变化”“实体关系如何演进”。
+
+机制特点：
+
+- 记忆结构是实体、关系、事件、时间。
+- 适合复杂事实网络和时间演化。
+- 检索结果可以包含关系路径和上下文。
+- 实现成本和运维复杂度高于 Markdown 或向量检索。
+
+和我们的关系：
+
+标签边界、业务规则、Skill 使用经验目前更适合文本化规则，不一定需要图谱。但如果未来要做“用户、Skill、数据集、标签、错误类型、修复策略”之间的关系分析，图谱路线会有价值。
+
+### 2.8 CrewAI：多 Agent 任务记忆
+
+CrewAI 的记忆体系主要服务多 Agent 协作，通常包含 short-term memory、long-term memory、entity memory 和 contextual memory。它关注的是任务过程中多个 Agent 如何共享上下文和持续改进。
+
+机制特点：
+
+- 和 Crew / Agent / Task 结构绑定。
+- 强调任务协作过程中的上下文复用。
+- 对实体、任务经验有独立组织方式。
+
+和我们的关系：
+
+ZK Data Agent 当前不是多 Agent 编排优先，而是单个工作台 Agent + Skill 能力包优先。Skill 记忆在某种程度上承担了“任务经验记忆”的角色。
+
+### 2.9 AutoGen：Memory 组件注入上下文
+
+AutoGen 的 AgentChat 提供 Memory 抽象，可以把 list memory、vector memory 等组件挂到 AssistantAgent 上。运行时 Memory 会根据消息更新上下文，或把检索结果添加到模型输入。
+
+机制特点：
+
+- Memory 是 Agent 可插拔组件。
+- 可以使用简单列表，也可以接向量检索。
+- 更偏框架扩展点，而不是产品级记忆管理 UI。
+
+和我们的关系：
+
+ZK Data Agent 的记忆也可以理解为一个可插拔上下文组件，但我们额外做了用户 UI、Skill 作用域和后台队列。
+
+## 3. ZK Data Agent 当前实现
+
+实现入口：
+
+```text
+src/personal_memory.py
+backend/api/server.py
+frontend/app/components/assistant-ui/threadlist-sidebar.tsx
+```
+
+### 3.1 存储结构
+
+每个账号有独立记忆目录：
+
+```text
+.port_sessions/accounts/<account_id>/memory/
+  user.md
+  skills/
+    <skill-name>.md
+  memory.db
+```
+
+其中：
+
+- `user.md`：用户级长期记忆。
+- `skills/<skill>.md`：某个 Skill 的使用记忆。
+- `memory.db`：事件队列、状态和 revision 账本。
+
+### 3.2 注入逻辑
+
+模型调用前，后端调用：
+
+```text
+memory_manager.render_injection(account_id, enabled_skill_names)
+```
+
+注入规则：
+
+```text
+用户记忆
+  账号级，作为长期偏好注入。
+
+Skill 使用记忆
+  只读取当前启用 Skill 对应的 skills/<skill>.md。
+
+冲突优先级
+  用户本轮明确要求 > 个性化记忆。
+```
+
+这避免了一个常见问题：所有记忆都无差别注入导致上下文污染。
+
+### 3.3 生成时机
+
+每次交互结束后，后端调用：
+
+```text
+memory_manager.enqueue_interaction(...)
+```
+
+系统不会每轮同步整理记忆，而是先检测信号：
+
+```text
+显式记忆词：
+记住、以后、下次、默认、总是、不要、应该、固定
+
+纠错词：
+不对、不是这样、格式错、之前说过、还是不行
+
+Skill 经验：
+skill、工具、流程、格式
+
+工具经验：
+模型返回的工具参数不是合法 JSON
+```
+
+命中后写入 SQLite pending 队列。显式记忆优先级更高。
+
+### 3.4 异步整理
+
+后台 worker 每 5 秒扫描账号事件，每次最多处理 8 条 pending event：
+
+```text
+pending -> processing -> done / failed
+```
+
+整理方式：
+
+1. 读取已有 `user.md` 和相关 `skills/<skill>.md`。
+2. 把一批事件交给模型做“整理式合并”。
+3. 模型必须输出 JSON：
+
+```json
+{
+  "user_memory": "完整 Markdown 或空字符串",
+  "skill_memories": {
+    "skill-name": "完整 Markdown"
+  }
+}
+```
+
+4. 如果模型输出不可解析，则走 fallback 规则。
+5. 写入 Markdown 文件，并更新 revision。
+
+### 3.5 用户可编辑
+
+前端左下角“记忆”入口支持：
+
+- 查看用户记忆行数。
+- 查看 Skill 记忆列表。
+- 编辑用户记忆。
+- 编辑某个 Skill 记忆。
+- 查看记忆队列状态。
+
+管理后台只看队列、用量等统计，不展示其他用户具体记忆内容。
+
+## 4. 对比表
+
+| 维度 | ChatGPT | Claude Code / OpenClaw | LangGraph / Mem0 / Zep | Letta | ZK Data Agent |
+|------|---------|--------------------|-------------------------|-------|---------------|
+| 主要目标 | 个人助手个性化 | 项目规则注入 | 长期检索记忆 | 状态型长期 Agent | 团队 Skill 工作台 |
+| 记忆粒度 | 用户 | 用户/项目/目录 | 用户/线程/实体/namespace | Agent memory block | 用户 + Skill |
+| 存储形态 | 平台内部 | Markdown 文件 | Store / 向量 / 图 | Core + archival memory | Markdown + SQLite queue |
+| 生成时机 | 产品后台自动 | 多为人工维护 | 自动抽取 / API 写入 | Agent 主动管理 | 交互结束后异步整理 |
+| 检索方式 | 平台决定 | 直接注入文件 | 语义搜索 / 图检索 | Core 常驻 + archival 检索 | 用户记忆 + 当前 Skill 记忆注入 |
+| 可编辑性 | 用户可管理 | 文件可编辑 | 取决于产品/API | 通常需要工具/API | UI 可编辑 Markdown |
+| 适合业务流程沉淀 | 中 | 中 | 高，但工程复杂 | 高，但复杂 | 高，且轻量 |
+| 风险 | 黑盒、难按业务作用域隔离 | 容易依赖人工维护 | 检索和更新复杂 | 主链路复杂度高 | 暂无语义召回和图谱能力 |
+
+## 5. 为什么当前方案适合我们
+
+### 5.1 我们需要的是 Skill 使用经验，而不只是用户偏好
+
+通用记忆多关注“用户是谁、用户喜欢什么”。我们的高频需求更像：
+
+```text
+product-data 生成数据时，用户偏好什么确认流程？
+标签大师判断时，哪些边界经常被纠正？
+online-mining-v2 查询线上日志时，哪些字段和表更稳定？
+某个 Skill 写文件时，模型容易踩什么坑？
+```
+
+这些经验天然和 Skill 绑定。因此 `skills/<skill>.md` 比单一用户记忆更准确。
+
+### 5.2 我们需要可审计、可编辑，而不是完全黑盒
+
+团队平台里，记忆不能只存在模型或向量库内部。用户需要能看到：
+
+- 记住了什么。
+- 为什么下一次会注入。
+- 哪里可以手动修改。
+- 哪些记忆是用户级，哪些是 Skill 级。
+
+Markdown 文件在这点上比纯向量库更直接。
+
+### 5.3 主链路不能被记忆整理拖慢
+
+数据生成、线上挖掘、标签判断本身就是长任务。记忆整理如果同步放在主链路里，会增加延迟和失败面。
+
+当前设计是：
+
+```text
+主链路：只读取已有记忆 + 入队事件
+后台：异步整理、合并、失败重试/记录
+```
+
+这和团队生产工具的稳定性要求更匹配。
+
+### 5.4 Skill 作用域注入能降低上下文污染
+
+如果所有记忆每次都注入，模型会被无关偏好干扰。当前只注入启用 Skill 的记忆：
+
+```text
+启用 product-data -> 注入 product-data 使用记忆
+启用 label-master -> 注入 label-master 使用记忆
+未启用某 Skill -> 不注入该 Skill 记忆
+```
+
+这使记忆更像“能力使用手册的增量补丁”，而不是一坨全局上下文。
+
+## 6. 当前不足和后续方向
+
+### 6.1 缺少语义召回
+
+当前 Skill 记忆是按 Skill 文件整体注入，不做向量检索。如果某个 Skill 记忆变得很长，可能需要：
+
+- 按章节拆分。
+- 引入轻量 embedding 检索。
+- 只注入和当前 query 相关的片段。
+
+### 6.2 缺少结构化 schema
+
+Markdown 易编辑，但不方便做强约束。后续可以让 Skill 记忆同时存在：
+
+```text
+human.md
+structured.json
+```
+
+其中 Markdown 给人看，JSON 给程序做筛选和校验。
+
+### 6.3 缺少记忆质量评估
+
+目前能看到队列状态，但还没有系统评估：
+
+- 哪些记忆被注入。
+- 注入后是否减少纠错。
+- 哪些记忆过期。
+- 哪些 Skill 记忆导致误导。
+
+后续可以把 memory revision 与 session outcome 关联起来。
+
+### 6.4 缺少跨用户团队记忆
+
+当前是账号级记忆。团队共性经验仍主要沉淀在 Skill 本体里。未来可以区分：
+
+```text
+个人 Skill 记忆
+  某个用户自己的偏好和使用习惯。
+
+团队 Skill 记忆
+  多人使用后沉淀的稳定经验，经 review 后合入 Skill。
+```
+
+这样可以形成从“个人经验”到“团队 Skill 知识”的晋升路径。
+
+## 7. 建议的技术路线
+
+短期保持当前架构：
+
+```text
+Markdown 可编辑记忆
+SQLite 异步队列
+按 Skill 注入
+UI 可查看可修改
+后台可观测队列
+```
+
+中期增强：
+
+```text
+记忆片段化
+记忆注入日志
+过期/冲突检测
+记忆质量指标
+```
+
+长期可选：
+
+```text
+向量检索：解决 Skill 记忆膨胀后的相关片段召回。
+图谱记忆：解决用户、Skill、标签、数据集、错误类型之间的关系分析。
+团队记忆晋升：把多用户共性 Skill 经验 review 后写回 Git Skill。
+```
+
+## 8. 资料来源
+
+- OpenAI Help：ChatGPT Memory FAQ
+  https://help.openai.com/en/articles/8590148-memory-faq
+- OpenAI Agents SDK：Sessions
+  https://openai.github.io/openai-agents-python/sessions/
+- Anthropic Claude Code：Memory
+  https://docs.anthropic.com/en/docs/claude-code/memory
+- LangChain / LangGraph：Memory concepts
+  https://docs.langchain.com/oss/python/concepts/memory
+- Mem0 documentation
+  https://docs.mem0.ai/
+- Letta documentation
+  https://docs.letta.com/
+- Zep / Graphiti documentation
+  https://help.getzep.com/
+- CrewAI Memory concepts
+  https://docs.crewai.com/concepts/memory
+- Microsoft AutoGen AgentChat Memory
+  https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/memory.html
+- ZK Data Agent 当前实现
+  `src/personal_memory.py`、`docs/technical-architecture/05-workspace-memory-observability.md`
diff --git a/frontend/app/public/doc-assets/technical-docs/README.md b/frontend/app/public/doc-assets/technical-docs/README.md
index a7c3d4d..8e713bd 100644
--- a/frontend/app/public/doc-assets/technical-docs/README.md
+++ b/frontend/app/public/doc-assets/technical-docs/README.md
@@ -14,6 +14,7 @@
 7. [online-mining-v2 Skill 实现](07-online-mining-v2.md)
 8. [label-master Skill 实现](08-label-master.md)
 9. [外部系统 Skill：ELK、SQL、模型迭代](09-external-skills.md)
+10. [Agent 记忆机制调研与对比](10-memory-research.md)
 
 ## 一句话定位