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 对话（或复用已有对话）、发送会话启动通知（包含项目路径和时间戳），以及清理任何残留的旧版本 <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/)。