01

Claude Subconscious 概览

理解后台 AI 代理如何通过 Letta Code SDK 增强你的编码体验——从理念到实现

什么是 Claude Subconscious?

想象你在专注编码的时候,有一个隐形的助手在后台默默观察你的代码编辑、理解你的项目结构、记住你的编码习惯——然后在关键时刻轻声提醒你:"这里可能有更好的写法"或者"上次你在这个模块遇到过类似的 bug"。

这就是 Claude Subconscious 的核心理念——让 AI 代理像你的"潜意识"一样工作,不需要你主动提问,它就能理解上下文并给出有价值的建议。

💡
"潜意识"的比喻

人类的潜意识在后台持续处理信息——整理记忆、识别模式、酝酿创意。你不会意识到它在工作,但它的影响无处不在。Claude Subconscious 就是编码世界的"潜意识":后台代理持续监听你的编码活动,积累项目知识,在你需要的时候提供精准的建议。

👁

持续观察

后台代理通过 Letta Code SDK 监听 Claude Code 的所有交互事件——包括文件编辑、终端命令、对话内容。不需要额外操作,完全被动感知。

🧠

学习记忆

代理拥有持久记忆系统,跨会话积累项目知识、用户偏好和编码模式。每次新会话都能利用历史积累,而不是从零开始。

💬

上下文建议

基于观察和学习到的上下文,在合适的时机提供代码改进建议、Bug 预警或最佳实践提示。建议通过 Claude Code 的交互界面呈现。

🔧

工具访问

代理可以访问项目文件系统、运行终端命令、查询 API 文档。这让它能提供比单纯文本建议更深层次的辅助,如自动运行测试验证建议。

Letta Code SDK:插件开发的基础

Letta Code SDK 是 Claude Subconscious 的技术基础。它提供了一套标准化的 API,让开发者可以构建与 Claude Code 深度集成的 AI 代理插件。

📚
SDK 核心概念

Letta Code SDK 遵循事件驱动架构:你的代理注册感兴趣的事件(如文件编辑、对话开始),SDK 在这些事件发生时调用你的回调函数。代理可以通过 SDK 的工具接口执行操作(如读取文件、写入代码)。

TypeScript
import { LettaClient, Agent } from '@letta-ai/sdk';

// 初始化 Letta 客户端
const client = new LettaClient({
  apiKey: process.env.LETTA_API_KEY,
  baseUrl: process.env.LETTA_SERVER_URL
});

// 创建后台代理
const agent = new Agent(client, {
  name: 'claude-subconscious',
  description: '后台编码助手,观察并学习编码模式',
  tools: ['read_file', 'write_file', 'run_command'],
  memory: {
    type: 'persistent',  // 持久化记忆
    maxSize: 10000       // 最大记忆条目数
  }
});
解读

Letta Code SDK 的初始化过程:

  • LettaClient:与 Letta 服务端的连接客户端,需要 API Key 和服务器地址
  • Agent 配置:定义代理的名称、描述和可用工具
  • 工具列表:代理可以使用的操作——读文件、写文件、运行命令
  • 持久记忆:跨会话保存知识,maxSize 控制记忆容量

课程学习路线

本课程将带你从理解概念到实际搭建一个后台 AI 代理。每个模块都包含可运行的代码示例和实践练习。

📁 课程路线图
📚 模块 1:概览与理念(当前位置)
Subconscious 概念、Letta SDK 基础、课程路线
🧠 模块 2:核心概念
后台代理生命周期、记忆系统架构、工具访问机制
🛠 模块 3:实践应用
插件安装配置、事件监听、自定义代理开发
🚀 模块 4:进阶主题
多项目管理、模型配置、性能优化、调试技巧
✅ 模块 5:总结与练习
最佳实践回顾、综合练习、扩展方向

Claude Subconscious 的核心理念是什么?

02

核心概念

深入理解后台代理的生命周期、记忆系统架构和工具访问机制

后台代理的生命周期

一个后台代理从创建到销毁,经历完整的生命周期。理解每个阶段的状态变化,是掌握 Claude Subconscious 工作原理的关键。

🎯
创建
初始化
👁
监听
📺
感知
🧠
思考
🔧
行动
💾
记忆
TypeScript
class SubconsciousAgent {
  // 代理核心工作流程
  async lifecycle() {
    // 1. 初始化:加载配置和工具集
    await this.loadConfig();
    await this.registerTools();

    // 2. 进入事件循环
    while (this.isActive) {
      // 监听 -> 感知 -> 思考 -> 行动 -> 记忆
      const event = await this.observe();
      const context = this.recall(event);
      const insight = await this.think(event, context);
      if (insight.confidence > 0.8) {
        await this.whisper(insight);
      }
      this.remember(event, insight);
    }
  }
}
解读

代理生命周期的核心循环:

  • observe():监听 Claude Code 的编码事件(文件编辑、命令执行)
  • recall():从记忆中检索与当前事件相关的历史信息
  • think():结合事件和上下文,调用 LLM 进行推理
  • whisper():当置信度足够高时,向用户提供建议
  • remember():将新获取的信息存入持久记忆

记忆系统架构

记忆系统是 Claude Subconscious 最核心的组件之一。它决定了代理能"记住"多少信息、如何组织这些信息、以及如何在需要时高效检索。

🧠
三级记忆模型

借鉴人类记忆理论,Claude Subconscious 采用三级记忆模型:工作记忆(当前会话的短期上下文)、短期记忆(最近几次会话的信息摘要)、长期记忆(跨所有会话的持久知识)。这种分层设计在记忆容量和检索效率之间取得平衡。

工作记忆(Working Memory)— 当前会话

📺
会话事件流
🔌
活动上下文

短期记忆(Short-term Memory)— 最近会话

📄
会话摘要
📊
编码模式库

长期记忆(Long-term Memory)— 持久知识

👤
用户偏好
📚
项目知识图谱
点击组件了解三级记忆模型中每一层的具体内容

工具访问:代理的操作能力

记忆系统让代理能"想",工具系统让代理能"做"。通过 Letta Code SDK 的工具接口,代理可以实际操作你的开发环境。

📄

文件系统访问

读取项目文件、搜索代码模式、分析文件依赖关系。代理可以理解整个项目的代码结构,提供跨文件的建议。写入操作需要用户确认。

💻

终端命令执行

运行测试、检查代码风格、查看 Git 状态等。代理可以在提供建议前先运行测试验证,确保建议的正确性。危险命令需要用户确认。

🔎

语义搜索

在代码库中进行语义搜索,找到与当前编辑相关的代码片段和文档。利用向量索引实现毫秒级的相似度搜索。

🌐

外部 API 调用

查询文档 API、搜索 Stack Overflow、获取包的最新版本信息等。扩展代理的知识范围,使其建议更加准确和及时。

在三级记忆模型中,"编码模式库"属于哪一层记忆?

03

实践应用

从安装配置到自定义代理开发——动手构建你的编码潜意识助手

插件安装与配置

将 Claude Subconscious 集成到你的开发环境只需要几步。让我们从安装开始,逐步配置到最佳状态。

🛠
前置条件

安装前确保你已有:1) Claude Code CLI 已安装并登录;2) Letta API Key(从 Letta AI 官网获取);3) Node.js 18+ 运行时。Claude Subconscious 作为 Claude Code 插件运行,不需要独立启动。

Shell
# 步骤 1: 克隆仓库
git clone https://github.com/letta-ai/claude-subconscious.git
cd claude-subconscious

# 步骤 2: 安装依赖
npm install

# 步骤 3: 配置环境变量
cp .env.example .env
# 编辑 .env,填入:
#   LETTA_API_KEY=your_api_key
#   LETTA_SERVER_URL=https://api.letta.com
#   LETTA_MODE=observe   (observe=silent, assist=proactive)

# 步骤 4: 启用插件
claude plugin enable .

# 步骤 5: 验证安装
claude plugin list # 应显示 subconscious (active)
解读

安装过程的五个步骤:

  • 克隆仓库:从 GitHub 获取最新版本的插件代码
  • 安装依赖:npm install 安装 Letta SDK 和其他依赖
  • 环境配置:.env 文件存储 API Key 和运行模式
  • 启用插件:通过 Claude Code 的插件系统注册
  • 验证安装:确认插件已正确注册并处于活动状态

自定义事件监听器

Claude Subconscious 的核心是事件监听器。通过注册不同的监听器,你可以自定义代理对哪些事件做出反应,以及如何反应。

📄

文件编辑事件

监听文件保存和修改事件。代理可以分析代码变更,检测潜在 Bug、建议改进或记录编码模式。最常用的事件类型。

💻

终端命令事件

监听终端命令执行和输出。代理可以从错误信息中学习,下次遇到类似错误时主动提醒。也可以从成功命令中提取模式。

💬

对话交互事件

监听用户与 Claude Code 的对话内容。代理可以从对话中提取用户意图和偏好,优化后续的交互体验。

TypeScript
import { Agent, EventTypes } from '@letta-ai/sdk';

class CodeReviewListener {
  constructor(private agent: Agent) {}

  // 监听文件保存事件
  @on(EventTypes.FILE_SAVE)
  async onFileSave(event: FileSaveEvent) {
    const changes = await this.diff(event.filePath);

    // 分析代码变更
    const analysis = await this.agent.think({
      prompt: `分析以下代码变更,检测潜在问题:
        文件: ${event.filePath}
        变更: ${changes}`,
      context: this.agent.recall(event.filePath)
    });

    // 高风险时立即提醒
    if (analysis.riskLevel === 'high') {
      await this.agent.whisper({
        message: analysis.warning,
        priority: 'high'
      });
    }

    // 记录到记忆系统
    this.agent.remember({
      type: 'code_change',
      file: event.filePath,
      summary: analysis.summary
    });
  }
}
解读

自定义事件监听器的开发模式:

  • @on 装饰器:声明式地注册事件处理器,代码简洁清晰
  • diff 分析:只分析变更部分,减少不必要的计算
  • agent.think():调用 LLM 进行智能分析,传入文件路径和变更内容
  • 优先级提醒:高风险问题立即通知,低风险可以聚合后批量提醒
  • 记忆存储:将分析结果存入记忆,供后续推理使用

构建自定义代理

除了使用默认的后台代理,你还可以基于 Letta Code SDK 构建完全自定义的代理,专注于特定的工作流。

💡
代理设计原则

好的代理设计遵循三个原则:单一职责(一个代理专注一个任务)、最小权限(只请求必要的工具权限)、优雅降级(工具不可用时仍能提供文本建议)。不要试图构建一个"万能"代理。

TypeScript
class TestSuggestAgent extends Agent {
  """自动建议测试的专用代理"""

  name = 'test-suggester';
  tools = ['read_file', 'run_command'];

  async onFileSave(event: FileSaveEvent) {
    // 只处理源代码文件
    if (!event.filePath.match(/\.(ts|js|py)$/)) return;

    // 检查是否已有对应测试文件
    const testPath = this.getTestPath(event.filePath);
    const hasTest = await this.tools.read_file(testPath);

    if (!hasTest) {
      const code = await this.tools.read_file(event.filePath);
      const testCode = await this.generateTest(code);
      await this.whisper({
        message: `检测到 ${event.filePath} 没有测试。建议添加:`,
        suggestion: testCode
      });
    }
  }
}
解读

自定义代理的设计要点:

  • 单一职责:这个代理只做一件事——检测缺少测试的文件并建议测试代码
  • 最小权限:只需要读取文件和运行命令两个工具
  • 文件类型过滤:只处理源代码文件,忽略配置文件等
  • 非侵入式:只提供建议,不自动创建文件

如果你想让代理在检测到 TypeScript 文件缺少测试时自动建议测试代码,应该监听什么事件?

04

进阶主题

多项目管理、模型配置、性能优化和调试技巧——代理开发的高阶实践

多项目环境下的代理管理

开发者通常同时维护多个项目。Claude Subconscious 支持一个代理服务多个项目,同时保持项目上下文隔离。

全局层 — 共享代理实例

全局配置 (config.json)
🧠
共享长期记忆

项目层 — 独立会话上下文

📁
项目 A 上下文 (.letta/claude/)
📁
项目 B 上下文 (.letta/claude/)
点击组件了解多项目管理的架构细节

模型配置与性能优化

选择合适的模型并进行性能优化,是代理开发中的重要技能。不同的任务需要不同的模型配置策略。

性能优化核心思路

代理的性能瓶颈通常在 LLM 调用。优化策略包括:1) 减少调用频率——合并相似事件,避免每次文件保存都调用 LLM;2) 使用轻量模型——简单判断用 Haiku,复杂推理用 Sonnet;3) 缓存推理结果——相似代码模式复用之前的分析结果。

TypeScript
class OptimizedAgent extends Agent {
  private eventBuffer: Event[] = [];
  private analysisCache = new Map<string, Analysis>();

  async onFileSave(event: FileSaveEvent) {
    // 1. 事件合并:积累 5 秒内的变更
    this.eventBuffer.push(event);
    await this.debounce(5000);

    // 2. 缓存检查:相似代码复用分析
    const cacheKey = this.hashChanges(event);
    if (this.analysisCache.has(cacheKey)) {
      return this.analysisCache.get(cacheKey);
    }

    // 3. 模型路由:简单判断用 Haiku
    const model = event.isComplex
      ? 'claude-sonnet-4-20250514'
      : 'claude-haiku-4-20250414';

    // 4. 批量分析
    const analysis = await this.batchAnalyze(
      this.eventBuffer, { model }
    );

    this.analysisCache.set(cacheKey, analysis);
    this.eventBuffer = [];
    return analysis;
  }
}
解读

代理性能优化的四个关键策略:

  • 事件合并(Debounce):5 秒内的多次文件保存合并为一次分析
  • 缓存复用:相似的代码变更直接返回缓存结果
  • 模型路由:简单变更用 Haiku(快+便宜),复杂变更用 Sonnet(精准)
  • 批量处理:将积压的事件一起发送给 LLM,减少 API 调用次数

代理调试与监控技巧

开发代理时,调试是不可避免的。Claude Subconscious 提供了多种调试工具和日志系统,帮助你快速定位问题。

📄

结构化日志

代理的所有行为都记录在 ~/.letta/claude-subconscious/logs/ 目录下。日志包含时间戳、事件类型、LLM 输入/输出、工具调用结果等完整信息,支持 JSON 格式导出。

📊

性能指标

内置性能指标收集:每次 LLM 调用的延迟、token 消耗、缓存命中率。通过 /subconscious stats 命令查看实时统计,帮你识别性能瓶颈。

🔎

记忆检查器

通过 /subconscious memory 命令查看代理当前的记忆内容,包括工作记忆、短期记忆和长期记忆的详细条目。帮助理解代理为什么给出特定的建议。

在多项目环境中,代理如何区分不同项目的上下文?

05

总结与练习

回顾核心知识,通过综合练习巩固技能,探索代理开发的更多可能

核心知识回顾

让我们快速回顾本课程最重要的知识点,确保你已经掌握了 Claude Subconscious 的核心概念和实践技能。

👁

代理生命周期

创建 → 初始化 → 监听 → 感知 → 思考 → 行动 → 记忆 → 循环。关键在于 observe → think → whisper 的闭环,让代理持续从编码活动中学习和改进。

🧠

三级记忆模型

工作记忆(当前会话事件流)→ 短期记忆(最近 10 次会话摘要 + 编码模式库)→ 长期记忆(用户偏好 + 项目知识图谱)。分层设计平衡容量与效率。

🔧

工具与安全

文件系统访问、终端命令执行、语义搜索、外部 API 调用。核心原则:最小权限 + 用户确认 + 非侵入式。危险操作永远需要用户明确授权。

性能优化策略

事件合并(Debounce)、缓存复用、模型路由(Haiku/Sonnet 分层)、批量处理。四大策略协同降低 70% 的 LLM 调用开销。

代理开发最佳实践

📄 最佳实践清单
🎯 代理设计
1. 单一职责——一个代理专注一个任务
2. 最小权限——只请求必要的工具
3. 优雅降级——工具不可用时提供文本建议
4. 非侵入式——只建议不自动执行
⚡ 性能优化
5. 事件合并——避免频繁调用 LLM
6. 模型路由——简单任务用轻量模型
7. 缓存复用——相似输入返回缓存结果
8. 批量处理——积攒事件后一次性分析
🔧 调试运维
9. 结构化日志——记录所有代理行为
10. 记忆检查器——理解代理为什么给特定建议
11. 性能指标——监控延迟和 token 消耗

综合练习:构建代码审查代理

设计一个代码审查代理,能在开发者保存文件时自动分析代码质量,提供改进建议。需要综合运用事件监听、记忆系统和工具访问。

🎯
练习目标

构建一个代理,具备以下能力:1) 监听文件保存事件;2) 读取保存的文件内容;3) 结合记忆中的项目编码规范进行分析;4) 给出代码质量评分和改进建议;5) 将分析结果存入记忆供后续使用。

TypeScript — 练习模板
class CodeReviewAgent extends Agent {
  """代码审查代理 — 请补充完整实现"""

  name = 'code-reviewer';

  // TODO 1: 注册事件监听器
  async onFileSave(event: FileSaveEvent) {
    pass
  }

  // TODO 2: 分析代码质量
  async analyzeQuality(code: string): Promise {
    pass
  }

  // TODO 3: 生成改进建议
  async generateSuggestions(analysis: Analysis): Promise {
    pass
  }

  // TODO 4: 更新记忆
  updateMemory(result: ReviewResult) {
    pass
  }
}
练习提示

完成这个练习的思路:

  • TODO 1:过滤只处理源代码文件,忽略 node_modules 等
  • TODO 2:调用 LLM 分析代码的可读性、性能、安全性
  • TODO 3:基于分析结果生成具体的改进代码片段
  • TODO 4:将审查结果和项目的编码规范关联存储

下一步:扩展方向

🤖

多代理协作

研究多个代理如何协作:一个代理负责代码审查,另一个负责测试建议,第三个负责性能优化。通过代理间的通信协议实现协同工作。

🌐

云端代理

将代理部署到云端,实现跨设备的知识同步。你在公司电脑学到的编码习惯,会自动同步到家里的开发环境。

🚀

领域专用代理

为特定领域定制代理:前端开发代理(专注 React/Vue 最佳实践)、DevOps 代理(专注 CI/CD 和部署配置)、安全代理(专注安全漏洞检测)。

Claude Subconscious 的核心优势是什么?

代理设计应该遵循哪个原则?