Claude Subconscious 常见问题FAQ30个高频问题官方答案汇总【免费下载链接】claude-subconsciousGive Claude Code a subconscious项目地址: https://gitcode.com/GitHub_Trending/cl/claude-subconsciousClaude Subconscious 是一款基于 Letta Code SDK 的开源插件为 Claude Code 装上一个后台记忆代理subconscious agent。它在后台静默观察你的每一次编码会话、读取代码库、随时间积累长期记忆并在你每次提问前悄悄低语回有用的上下文。本文汇总了围绕Claude Subconscious 记忆插件的 30 个高频问题安装步骤、API Key 配置、三种运行模式、SDK 工具权限、多项目共享记忆与日志排查全部给出官方口径的答案新手也能一次看懂。一、基础认知Claude Subconscious 是什么Q1. Claude Subconscious 到底是什么它是运行在 Claude Code 底下的第二个 AI 代理看监听每个 Claude Code 会话的完整对话记录读处理记录时可用 Read、Grep、Glob 探索你的代码库记跨会话、跨项目、跨时间积累记忆说在每次提问前把上下文、模式、提醒低语回给你不阻塞全程后台异步运行它不只是一个记忆层而是一个拥有真实工具权限、越用越聪明的后台代理。项目定位详见 README.md。Q2. 能用在生产环境吗不能。官方明确声明它只是用 Letta Code SDK 构建的 demo 应用不面向生产使用。如果你需要后台潜意识代理能力的生产级编码代理官方建议使用开源的 Letta Codenpm install -g letta-ai/letta-code安装后用letta启动。Q3. 它的工作原理是什么核心循环是每次响应后同步、每次提问前低语每轮响应结束后会话记录通过 Letta Code SDK 异步发送给后台 Letta 代理代理读文件、搜网页、更新自己的记忆下一轮提问前代理把记忆与消息注入到 Claude 的提示上下文中整个流程由 4 个 Claude Code 钩子驱动配置见 hooks/hooks.json钩子脚本超时作用SessionStartsession_start.ts5s通知代理新会话开始清理旧 CLAUDE.mdUserPromptSubmitsync_letta_memory.ts10s每次提问前注入记忆 消息PreToolUsepretool_sync.ts5s工作流中途更新上下文Stopsend_messages_to_letta.ts120s异步派生后台 Worker 发送会话记录Q4. 它和写 CLAUDE.md 有什么区别任何模式下Subconscious 都不往 CLAUDE.md 写内容。所有内容都通过 stdout 注入到提示上下文中。旧版本曾把记忆同步进 CLAUDE.md如果你看到残留的letta内容插件会在会话开始时自动清理。Q5. 它和 Letta Code 是什么关系Claude Subconscious 依赖letta-ai/letta-code-sdk见 package.json利用 Letta 的Conversations能力单个代理可同时服务多个并行的 Claude Code 会话且所有会话共享同一套记忆。二、安装与启动3 种方式快速上手Q6. 最快的安装方式是什么在 Claude Code 中执行两条插件命令即可从插件市场安装/plugin marketplace add letta-ai/claude-subconscious /plugin install claude-subconsciousclaude-subconsciousQ7. 如何从源码安装克隆仓库后本地安装依赖并启用插件git clone https://gitcode.com/GitHub_Trending/cl/claude-subconscious cd claude-subconscious npm install然后在克隆目录内执行/plugin enable .启用插件。如果 Claude Code 运行在其他目录需使用克隆仓库的完整路径。Q8. 如何更新插件/plugin marketplace update /plugin update claude-subconsciousclaude-subconsciousQ9. 如何让插件对全部项目全局生效在克隆目录内执行/plugin enable --global .不加分号参数只对当前项目生效加--global后所有项目共用同一套 Subconscious。Q10. 对 Node.js 版本有要求吗要求Node.js 18.0.0见 package.json 的engines字段运行时依赖tsx执行 TypeScript 脚本。Q11. Linux 上安装报 EXDEV: cross-device link not permitted 怎么办这是因为/tmp挂载在不同文件系统Ubuntu、Fedora、Arch 上常见。把TMPDIR指向主目录下的目录即可mkdir -p ~/.claude/tmp export TMPDIR$HOME/.claude/tmp写入~/.bashrc或~/.zshrc可永久生效。Q12. Windows 上报 npx spawn ENOENT 怎么解决该问题已在 1.1.0 版本修复Windows 兼容性补丁升级插件到最新即可。项目提供了 hooks/silent-npx.cjs 与 hooks/SilentLauncher.cs 等跨平台启动器来规避 npx 直接 spawn 失败的问题。三、配置指南API Key、模型与多项目Q13. 唯一的必配项是什么只需一个环境变量——Letta 的 API Key可在 Letta 官方控制台获取export LETTA_API_KEYyour-api-key这就是零配置体验的来源设置 Key 之后代理的创建、模型选择、会话管理全部自动完成。Q14. 如何连接自托管的 Letta 服务器默认连接https://api.letta.com。自托管时设置LETTA_BASE_URLexport LETTA_BASE_URLhttp://localhost:8283URL 构造逻辑集中在 scripts/letta_api_url.ts会自动补/v1前缀。Q15. 如何手动指定模型export LETTA_MODELanthropic/claude-sonnet-4-5模型格式为provider/model。若该模型在你服务器上不可用插件会警告并回退到自动选择。可用LETTA_CONTEXT_WINDOW如1048576表示 1M tokens覆盖上下文窗口。Q16. 模型的自动选择是怎么运作的插件启动时会查询服务器的可用模型列表按优先级自动挑选letta/auto→anthropic/claude-sonnet-4-5最推荐→openai/gpt-4.1-mini→anthropic/claude-haiku-4-5→openai/gpt-5.2→ Gemini Flash 系列 → 服务器第一个可用模型。选择逻辑见 scripts/agent_config.ts。默认捆绑代理使用免费模型zai/glm-5追求更强推理能力可手动切换。Q17. 如何让不同项目使用不同的代理默认所有项目共享同一个代理大脑全局保存在~/.letta/claude-subconscious/config.json。按项目隔离时用环境变量指定不同代理 ID例如配合 direnv 在项目.envrc中写export LETTA_AGENT_IDagent-xxx-for-this-projectQ18. LETTA_HOME 是做什么的它是插件状态文件的根目录会在{LETTA_HOME}/.letta/claude/下存放会话数据与对话映射。默认是当前工作目录设置为$HOME可把所有状态集中到~/.letta/一处方便管理。四、运行模式LETTA_MODE 的三档详解Q19. LETTA_MODE 有哪三种模式通过环境变量LETTA_MODE控制解析逻辑见 scripts/conversation_utils.ts模式Claude 看到什么适用场景whisper默认只有 Sub 的低语消息轻量——有事才说话full记忆块 消息全量上下文——首条提示注入全部块之后只发 diffoff什么都不注入临时禁用所有钩子Q20. whisper 模式注入的内容长什么样每次提问前通过 stdout 注入一段带时间戳的消息块letta_message fromSubconscious timestamp2026-01-26T20:37:1400:00 你本周第三次问异步上下文里的错误处理 建议系统性回顾一下错误处理架构。 /letta_message代理被刻意配置成观察者风格我注意到……而非你应该……、简洁技术化没内容可说时就保持沉默绝不硬凑。Q21. full 模式是怎么做增量同步的会话的第一条提示注入全部记忆块letta_memory_blocks之后的提示只注入变化的块letta_memory_update的 diff 形式既完整又省 token。Q22. 如何临时禁用 Subconscious 的所有提示export LETTA_MODEoffoff模式下SessionStart等钩子直接退出不做任何注入适合临时排查问题。Q23. 旧版本写进 CLAUDE.md 的 内容会残留吗不会。SessionStart钩子每次会话开始都会清理项目内.claude/CLAUDE.md和全局~/.claude/CLAUDE.md中的遗留letta区块属于自动迁移。五、SDK 工具后台代理的三档权限Q24. LETTA_SDK_TOOLS 有哪三档档位可用工具定位read-only默认Read、Grep、Glob、web_search、fetch_webpage安全的后台研究与读文件full全部工具Bash、Edit、Write、Task 等完全自主——可改代码、派生子代理off无仅记忆操作只监听——处理记录但不能动客户端工具Q25. 默认的 read-only 模式安全吗安全。代理只能读文件、搜索代码、抓网页没有任何写操作适合后台默默学习你的代码库这一核心场景。Q26. full 模式有什么特别之处full模式下代理可通过Task工具派生子代理——在你继续写代码的同时它并行分派研究任务或把工作委托给其他代理。注意LETTA_SDK_TOOLS需要letta-ai/letta-code-sdk依赖已随插件安装。六、记忆与数据代理、记忆块和状态文件Q27. 默认代理的 8 个记忆块分别是干什么的首次使用时插件自动导入捆绑的 Subconscious 代理定义见 Subconscious.af它维护 8 个记忆块记忆块用途core_directives角色定义与行为准则guidence/guidance面向下一会话的主动指导每次提问前同步user_preferences学到的编码风格、工具偏好、沟通方式project_context代码库知识、架构决策、已知坑点session_patterns重复行为、时间规律、常见卡点pending_items未完成工作、显式 TODO、跟进项self_improvement记忆架构自我演化的准则tool_guidelines如何使用记忆、文件系统、网页搜索工具Q28. 多项目之间真的共享同一个大脑吗是的。一个代理多个项目代理 ID 全局保存于~/.letta/claude-subconscious/config.json各项目的.letta/claude/目录只存会话账本Claude Code 会话 ID → Letta 对话 ID 的映射并非独立代理。记忆块在所有项目间共享。Q29. 状态文件和日志分别存在哪里持久状态项目目录下.letta/claude/的conversations.json与session-{id}.json会话进度、已处理索引临时日志$TMPDIR/letta-claude-sync-$UID/下的session_start.log、sync_letta_memory.log、send_messages.log、send_worker_sdk.log七、调试与排错日志在哪看Q30. 前几次会话为什么感觉没什么提示这是正常现象代理首次启动时上下文极少需要几个会话的积累才能给出有价值的指导——它要先读完你的代码、学出你的模式才会开口。若怀疑钩子没跑起来实时跟踪日志即可定位tail -f /tmp/letta-claude-sync-$(id -u)/*.log另有一个常见隐形故障LETTA_MODEL/LETTA_CONTEXT_WINDOW配置了却不生效。这是 Letta 废弃了旧的llm_configPATCH 请求格式导致模型同步静默失败已在 CHANGELOG.md 的 Unreleased 版本中修复——升级后即可正确应用。写在最后Claude Subconscious 把跨会话记忆这件事从手工维护 CLAUDE.md变成了一个会自己读代码、自己学习、自己开口的后台代理。新手只需三步设置LETTA_API_KEY→ 安装插件 → 让它观察几个会话。随着记忆块越积越厚它给你的低语会越来越懂你。完整功能与配置细节可随时查阅 README.md。【免费下载链接】claude-subconsciousGive Claude Code a subconscious项目地址: https://gitcode.com/GitHub_Trending/cl/claude-subconscious创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考