跨会话持久化上下文系统：Agent记忆捕获、AI压缩与向量化检索注入

问题本质：会话边界导致的认知断层

AI 编码助手每开启一个新会话，上下文窗口即被重置。这意味着开发者花费四十分钟向 Claude 解释项目认证架构、数据库迁移策略和竞态条件位置后，关闭终端再打开，AI 又变成了 "陌生人"。CLAUDE.md 虽能承载静态约定，却无法捕获会话中动态产生的知识 —— 调试过程中的发现、代码审查形成的微约定、反复查询形成的模式偏好。

跨会话持久化上下文系统的核心目标，是构建一条从 "捕获→压缩→检索→注入" 的自动化流水线，让 Agent 在多会话协作中保持认知连续性。

五阶段生命周期捕获机制

claude-mem 通过 Claude Code 插件系统的五个生命周期钩子实现无侵入式捕获：

钩子阶段	捕获内容	处理逻辑
SessionStart	历史会话索引	注入最近 10 个会话的压缩上下文
UserPromptSubmit	用户查询文本	用于识别重复查询模式
PostToolUse	工具执行观测	记录文件读写、命令执行、代码编辑等行为
Stop	响应完成信号	触发会话摘要生成
SessionEnd	会话终止事件	最终清理与持久化

所有钩子采用非阻塞设计，将计算密集型任务（压缩、摘要生成）丢给后台 Worker 队列处理，确保 IDE 响应不受影响。

AI 压缩：从原始观测到语义摘要

原始会话日志包含大量冗余 —— 完整的文件内容、冗长的命令输出、重复的观测记录。直接注入将迅速耗尽上下文窗口。

claude-mem 的压缩策略分为两层：

第一层：实时观测去重。PostToolUse 阶段捕获的原始数据经过去重和截断后进入 SQLite 暂存，保留关键元数据（文件路径、操作类型、时间戳、结果状态）。

第二层：会话级语义摘要。SessionEnd 时，后台 Worker 调用 Claude Agent SDK 对整会话的观测流进行语义抽取，生成结构化的 "学习点"（learnings）—— 包括架构决策、Bug 根因、编码约定、待办事项等。原始 1000 条观测可能压缩为 10-20 条高信号摘要。

这种压缩是有损的，nuanced 上下文可能丢失。因此关键知识仍需显式写入 CLAUDE.md，而非完全依赖自动记忆。

三层渐进式检索架构

直接注入完整历史将淹没当前任务的相关信息。claude-mem 采用渐进式披露（progressive disclosure）策略，按相关性分层检索：

Layer 1: Index（索引层）

内容：观测 ID、标题、类型、时间戳的紧凑列表
Token 消耗：50-100 tokens / 条
作用：让 Agent 快速扫描历史脉络，定位潜在相关记录

Layer 2: Timeline（时间线层）

内容：特定观测周边的时序上下文
作用：提供 "发生了什么" 的叙事流，无需完整细节

Layer 3: Full Details（详情层）

内容：完整的观测数据（原始文件内容、命令输出、Agent 推理过程）
Token 消耗：500-1000 tokens / 条
触发条件：Agent 明确请求特定 ID 的详情时按需加载

相比 "全量注入 upfront" 的朴素方案，三层架构可节省约 10 倍 token 消耗，同时保留按需深入的能力。

混合搜索：FTS5 + 向量检索

记忆系统的检索质量取决于搜索能力。claude-mem 采用混合搜索策略：

SQLite FTS5处理精确匹配场景 —— 文件名、函数名、特定错误码的查找。FTS5 的倒排索引在关键词搜索上延迟极低。

Chroma 向量数据库处理语义匹配场景 ——"之前处理过的那个认证 Bug"、"类似的数据库迁移问题"。通过嵌入模型将查询和历史观测映射到同一向量空间，实现基于含义的模糊检索。

MCP 工具层暴露两个核心 API 供 Agent 调用：

// 第一步：语义搜索索引
search(query: "authentication bug", type: "bugfix", limit: 10)
// 返回: [{id: 123, title: "...", relevance: 0.92}, ...]

// 第二步：按需获取详情
get_observations(ids: [123, 456])
// 返回: 完整观测数据，注入当前上下文

Agent 可主动查询历史，而非被动依赖 SessionStart 注入的上下文。

工程化配置与部署参数

安装命令（Claude Code 插件市场）：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

系统依赖：

Node.js ≥ 20.0.0
Bun ≥ 1.0（自动安装）
uv（Python 包管理器，自动安装）

核心配置路径：~/.claude-mem/settings.json

关键可调参数：

配置项	默认值	说明
workerPort	37777	HTTP 服务端口，公式：37700 + (uid % 100)
contextWindowLimit	动态计算	注入上下文的最大 token 数
compressionModel	claude-3-5-sonnet	生成摘要的模型
enableVectorSearch	true	是否启用 Chroma 语义搜索
dataDirectory	~/.claude-mem/data	SQLite 和向量数据存储路径

隐私控制：使用<private>标签包裹敏感内容，该区块将被排除在存储之外：

<private>
这里包含API密钥或内部域名，不会被持久化
</private>

监控入口：Web Viewer UI 运行于http://localhost:37777，提供实时记忆流可视化和无限滚动浏览。

与静态知识层的协同关系

持久化记忆并非取代现有配置，而是补充第三维度：

层级	来源	内容特性	持久化方式
SKILL.md	人工编写或市场获取	可复用流程、领域专业知识	静态、可共享
CLAUDE.md	人工编写	项目约定、架构决策	静态、版本控制
claude-mem	自动生成	会话观测、学习模式、Bug 历史	动态、AI 压缩

三者竞争同一份上下文窗口预算。SKILL.md 提供跨项目复用能力，CLAUDE.md 保证关键知识不丢失，claude-mem 捕获实际工作中涌现的隐性知识。合理分层可避免 "上下文淹没"—— 即注入过多低信号内容导致推理能力下降。

局限性与风险清单

压缩损失：语义摘要会丢弃细节，关键决策应显式文档化
本地存储限制：记忆数据库绑定单机，多机协作需手动同步~/.claude-mem/data目录
依赖链复杂度：Bun + uv + Python + SQLite + Chroma 的组合增加故障面
隐私主动管理：<private>标签需开发者自觉使用，建议定期审查 Web Viewer 中的存储内容
Token 成本：即使采用渐进式披露，注入历史上下文仍会消耗当前任务的推理预算

可落地的检查清单

安装后验证 Worker 服务：curl http://localhost:37777/health
配置settings.json中的compressionModel以匹配你的 API 配额
在涉及敏感数据的查询中包裹<private>标签
每周审查 Web Viewer，删除过时或敏感的记忆条目
对于跨会话必须保留的关键知识，同时维护 CLAUDE.md 条目作为 "硬备份"
监控 token 使用量，评估三层检索的实际节省效果

资料来源

claude-mem 官方文档: https://docs.claude-mem.ai/introduction
Termdock 技术分析: https://www.termdock.com/blog/claude-mem-persistent-memory-claude-code

ai-systems

内容声明：本文无广告投放、无付费植入。

如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。