# Letta Claude Subconscious：为 Claude Code 构建持久记忆层的技术实现 > 深入解析 Letta 推出的 Claude Subconscious 项目，通过子进程级后台 agent 与四个 Claude Code hooks 实现跨会话的上下文保持与状态持久化。 ## 元数据 - 路径: /posts/2026/03/26/letta-claude-subconscious-agent-memory-persistence/ - 发布时间: 2026-03-26T15:02:05+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 站点: https://blog.hotdry.top ## 正文 Claude Code 作为一款强大的编程 agent，每次会话结束后的「记忆清零」问题长期困扰开发者。你是否有过这样的经历：花半小时向 Claude 解释项目的架构设计、编码规范和特殊约定，下次打开同样的项目，它却像陌生人一样从头开始？这种状态丢失不仅影响效率，更打破了人机协作的连续性。Letta 推出的 Claude Subconscious 项目正是为了解决这一痛点，它通过在 Claude Code 底层构建一个持续运行的后台 agent，为其赋予类似「潜意识」的持久记忆能力。 ## 架构设计：子进程级的后台观察者 Claude Subconscious 并非简单的向量存储插件，而是一个完整的后台 agent，运行在 Claude Code 进程之下，持续观察、学习和 whisper 回馈。它的核心架构依赖于 Claude Code 提供的四个 hook 挂载点，这些 hooks 分布在会话的生命周期关键节点上。 当用户在终端启动一个新的 Claude Code 会话时，`SessionStart` hook 会被触发。该 hook 的执行脚本是 `session_start.ts`，超时时间设定为 5 秒，主要职责包括创建新的 Letta 对话（或复用已有对话）、发送会话启动通知（包含项目路径和时间戳），以及清理任何残留的旧版本 `` 内容。这个初始连接建立后，后台 agent 就开始了它的观察工作。 每次用户提交 prompt 之前，`UserPromptSubmit` hook 会通过 `sync_letta_memory.ts` 脚本同步记忆内容，超时时间为 10 秒。这是整个系统最关键的交互点——后台 agent 会将其积累的记忆 blocks 和消息注入到 Claude Code 的上下文窗口中。注入方式有两种模式，由环境变量 `LETTA_MODE` 控制，稍后我们会详细展开。 在工作流程的中间阶段，`PreToolUse` hook 会检查是否有新的消息或记忆变化。如果发现更新，它会通过 `additionalContext` 机制将增量信息注入到 Claude Code 的执行上下文中。这确保了即使在长时间的任务执行过程中，Claude Code 也能获得最新的上下文指导，而不必等待整个任务完成。 最后，当会话结束时，`Stop` hook 负责将完整的会话 transcript 发送回后台 agent 进行处理。这个 hook 采用异步模式执行，主脚本 `send_messages_to_letta.ts` 会快速解析会话记录（JSONL 格式），提取用户消息、助手响应、思考块和工具使用记录，然后将负载写入临时文件并启动 detached 后台 worker `send_worker_sdk.ts`。主脚本会立即退出，不阻塞 Claude Code 的关闭流程。后台 worker 则独立运行，调用 Letta Code SDK 开启一个新的会话，让 Subconscious agent 能够使用 Read、Grep、Glob 等工具探索代码库，同时更新其记忆状态。 ## 记忆模型：八块记忆的结构化分工 Claude Subconscious 的记忆组织方式值得深入探讨。它不使用单一的向量数据库，而是采用了结构化的 memory blocks 架构，默认配置下包含八种不同职责的记忆块。 `core_directives` 块负责定义 agent 的角色定位和行为准则，它告诉 Subconscious 应该以什么样的身份和风格与用户交互。`guidance` 块是活跃指导区，每次会话开始前会同步到 Claude Code，提供即时的问题或建议。`user_preferences` 块记录学习到的用户编码风格偏好，比如是否偏好显式类型注解、使用 pnpm 还是 npm、注释风格等。`project_context` 块则存储代码库知识，包括架构决策、已知陷阱和项目特定约定。 `session_patterns` 块记录 recurring behaviors，即反复出现的行为模式——比如用户经常在周末调试认证问题，或者总是在重构前先写测试。`pending_items` 块追踪未完成的工作、显式的 TODO 事项和需要跟进的项目。`self_improvement` 块是一个元认知区，包含如何随着时间推移优化记忆架构的指南。`tool_guidelines` 块则记录如何有效使用各种可用工具的指导。 这种多块结构的优势在于精细化的上下文管理。在 `full` 模式下，首次 prompt 时所有 blocks 会被完整注入；后续 prompt 则只注入变化的 blocks 作为 diffs，类似 git diff 的增量更新机制。这种设计显著降低了 token 消耗，同时保持了上下文的完整性。 ## 注入模式对比：whisper 与 full 的选择 `LETTA_MODE` 环境变量控制着记忆注入的粒度，这是部署时需要重点考虑的参数。`whisper` 模式是默认值，它只注入来自 Subconscious agent 的消息。这种模式下，Sub 只会「轻声细语」地在有话可说时才发声，如果没有有价值的内容建议，它会保持沉默，不会制造无意义的噪声。对于追求轻量级增强的用户，这是推荐的选择。 `full` 模式则激进得多，它会注入完整的 memory blocks 内容以及消息。在首次 prompt 时，所有八个 blocks 都会被完整写入上下文；后续 prompt 则显示 blocks 的变化 diffs。这种模式适合需要完整项目背景的复杂任务，但也意味着更高的 token 消耗和可能的信息过载。 还有第三种选项 `off`，完全禁用注入，适合临时需要纯净上下文的场景，或者在调试时排除 Letta 干扰。 ## SDK 工具分层：安全与自主的平衡 Claude Subconscious 的一个关键特性是它不仅能被动观察，还能主动使用工具。`LETTA_SDK_TOOLS` 环境变量控制着这种能力的等级。 `read-only` 是默认值，Subconscious agent 可以使用 Read、Grep、Glob、web_search 和 fetch_webpage 工具。这意味着它能够在处理 transcript 时主动阅读你的代码、搜索相关文件、甚至上网查询资料来增强其上下文理解能力。这是一种安全的设计——agent 只能读取，不能修改。 `full` 模式下，agent 获得了全部工具访问权限，包括 Bash、Edit、Write、Task 等。它不仅能读，还能执行命令、修改文件、甚至通过 Task 工具 Spawn 子 agent 进行并行研究或委托工作。这种模式赋予了 Subconscious 高度的自主性，但也带来了更大的风险——你需要充分信任这个后台 agent 的行为。 `off` 模式则完全禁用客户端工具，Subconscious 退化为纯观察者，只能基于接收到的 transcript 进行记忆更新，没有任何文件系统或网络访问能力。 ## 关键配置参数清单 对于生产环境部署，以下是建议关注的核心参数。 **必需配置**：只需设置 `LETTA_API_KEY`，从 app.letta.com 获取即可。插件会自动处理 agent 的创建和初始化。 **可选但推荐**：如果需要自定义行为，`LETTA_MODE` 设为 `whisper` 或 `full`；`LETTA_SDK_TOOLS` 设为 `read-only`（默认）或 `full`；`LETTA_MODEL` 可覆盖默认模型，常见选项包括 `anthropic/claude-sonnet-4-5`、`openai/gpt-4.1-mini` 或 `openai/gpt-5.2`。 **自托管部署**：`LETTA_BASE_URL` 用于指定自托管 Letta 服务器地址，默认为 `https://api.letta.com`。如果使用自托管，需要确保相应的 Provider API Key 已配置在 Letta 服务器端。 **状态管理**：`LETTA_HOME` 默认值为当前工作目录，设为 `$HOME` 可以将所有状态统一到 `~/.letta/` 目录下，方便多项目共享同一个 agent brain。 ## 与 Supermemory 的本质区别 市场上存在多种为 AI agent 添加记忆的方案，Supermemory 是其中一个知名选项。但两者的设计哲学有本质差异。Supermemory 本质上是一个向量存储检索系统——它将内容 embeddings 后存入向量数据库，查询时通过相似度匹配召回相关内容。它的核心能力是「记住说过什么」。 Claude Subconscious 则是一个 agent 级别的记忆子系统加意图推理层。它不只是存储和检索，还具备真正的推理能力——通过 Letta Code SDK，它能够在后台主动分析 transcript、阅读相关代码文件、搜索网络更新知识，甚至在 `full` 模式下自主执行操作。换句话说，Supermemory 回答的是「之前有没有相关的说法」，而 Subconscious 回答的是「基于之前的所有交互，我现在应该给什么建议」。 这种架构差异导致两者适用场景不同。对于简单的「找到之前提到过的配置」，向量检索足够；但对于「理解用户的编码习惯演变并给出前瞻性建议」，则需要 agent 级别的推理能力。 ## 落地建议 首次启用 Claude Subconscious 时，需要注意它不是即时生效的魔法。初始几个会话，agent 收集的信号有限，提供的有价值建议也相对有限。官方建议给它 3 到 5 个会话的「观察期」，让它有机会读取你的代码、学习你的模式、建立记忆连接。 生产环境部署时，建议从 `read-only` 工具模式开始，验证行为符合预期后再考虑开启 `full` 模式。日志目录位于 `$TMPDIR/letta-claude-sync-$UID/`，通过 `tail -f` 可以实时监控各个 hook 的执行状态，便于排查集成问题。 资料来源：Letta 官方 GitHub 仓库 (https://github.com/letta-ai/claude-subconscious) 及 Letta Code 文档 (https://docs.letta.com/letta-code/memory/)。 ## 同分类近期文章 ### [NVIDIA PersonaPlex 双重条件提示工程与全双工架构解析](/posts/2026/04/09/nvidia-personaplex-dual-conditioning-architecture/) - 日期: 2026-04-09T03:04:25+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 NVIDIA PersonaPlex 的双流架构设计、文本提示与语音提示的双重条件机制，以及如何在单模型中实现实时全双工对话与角色切换。 ### [ai-hedge-fund：多代理AI对冲基金的架构设计与信号聚合机制](/posts/2026/04/09/multi-agent-ai-hedge-fund-architecture/) - 日期: 2026-04-09T01:49:57+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析GitHub Trending项目ai-hedge-fund的多代理架构，探讨19个专业角色分工、信号生成管线与风控自动化的工程实现。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [tui-use 框架：让 AI Agent 自动化控制终端交互程序](/posts/2026/04/09/tui-use-ai-agent-terminal-automation-framework/) - 日期: 2026-04-09T01:26:00+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 详解 tui-use 框架如何通过 PTY 与 xterm headless 实现 AI agents 对 REPL、数据库 CLI、交互式安装向导等终端程序的自动化控制与集成参数。 ### [LiteRT-LM C++ 推理运行时：边缘设备的量化、算子融合与内存管理实践](/posts/2026/04/08/litert-lm-cpp-inference-runtime-quantization-fusion-memory/) - 日期: 2026-04-08T21:52:31+08:00 - 分类: [ai-systems](/categories/ai-systems/) - 摘要: 深入解析 LiteRT-LM 在边缘设备上的 C++ 推理运行时，聚焦量化策略配置、算子融合模式与内存管理的工程化实践参数。