# 谁懂啊！Claude Code总失忆？这个后台代理悄悄记住所有项目上下文，写代码再也不用重复交代！

项目地址：https://github.com/letta-ai/claude-subconscious

主要语言：TypeScript

stars: 1.3k

### 核心功能

- **增强Claude Code能力**：Claude Subconscious是一个后台代理，为Claude Code提供持久记忆和智能引导。Claude Code在会话间会遗忘所有信息，而Claude Subconscious能持续观察会话记录、读取代码库、跨会话和项目记忆，并在每次提示前提供上下文、模式和提醒。
- **多会话支持**：借助Letta的Conversations功能，单个Claude Subconscious代理可并行服务多个Claude Code会话，并在所有会话间共享记忆。

### 工作原理

Claude Code每次响应后，会话记录会通过Letta Code SDK发送给Letta代理。代理读取文件、搜索网络、更新记忆，然后在下次提示前反馈信息。具体交互如下：

- **会话开始**：向代理发送新会话通知。
- **提示前**：代理将引导信息注入标准输出。
- **工具使用前**：若有更新，通过`additionalContext`注入信息。
- **响应后**：异步将会话记录发送给代理，代理读取文件并更新记忆。

### 安装与更新

- **从GitHub安装**：

```
/plugin marketplace add letta-ai/claude-subconscious
/plugin install claude-subconscious@claude-subconscious
```

- **更新**：

```
/plugin marketplace update
/plugin update claude-subconscious@claude-subconscious
```

- **从源码安装**：

```
git clone https://github.com/letta-ai/claude-subconscious.git
cd claude-subconscious
npm install
```

- **启用插件**：在克隆目录内执行`/plugin enable .`，或全局启用`/plugin enable --global .`。
- **Linux临时文件系统问题解决**：若安装失败，可设置`TMPDIR`：

```
mkdir -p ~/.claude/tmp
export TMPDIR="$HOME/.claude/tmp"
```

### 配置

- **必需配置**：设置`LETTA_API_KEY`，可从[app.letta.com](https://app.letta.com/)获取。

```
export LETTA_API_KEY="your-api-key"
```

- **可选配置**：

```
export LETTA_MODE="whisper"    # Default. Or "full" for blocks + messages, "off" to disable
export LETTA_AGENT_ID="agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export LETTA_BASE_URL="http://localhost:8283"  # For self-hosted Letta
export LETTA_MODEL="anthropic/claude-sonnet-4-5"  # Model override
export LETTA_CONTEXT_WINDOW="1048576"             # Context window size (e.g. 1M tokens)
export LETTA_HOME="$HOME"      # Consolidate .letta state to ~/.letta/
export LETTA_SDK_TOOLS="read-only"       # Or "full", "off"
```

### 默认代理

- **功能**：读取代码、学习用户偏好、跟踪项目上下文、提供指导和搜索网络。
- **记忆块**：维护8个记忆块，包括`core_directives`、`guidance`、`user_preferences`等。
- **沟通风格**：观察性、简洁且不具侵入性。
- **双向沟通**：Claude Code可直接与代理交互，代理会在下次同步时响应。

### 钩子

- **SessionStart**：创建新的Letta对话，发送会话开始通知，清理CLAUDE.md中的旧内容，保存会话状态。
- **UserPromptSubmit**：获取代理的记忆块和消息，根据`LETTA_MODE`注入信息。
- **PreToolUse**：检查记忆更新，若有更新则注入`additionalContext`。
- **Stop**：异步将会话记录发送给代理，不阻塞Claude Code。

### 状态管理

- **持久状态**：存储在项目目录的`.letta/claude/`中，包括`conversations.json`和`session-{id}.json`。
- **临时状态**：存储在`$TMPDIR/letta-claude-sync-$UID/`中，用于调试的日志文件。

### 使用场景

- **持久项目上下文**：代理读取代码库并跨会话记忆。
- **学习用户偏好**：了解用户的编码风格和工具偏好。
- **跨会话连续性**：无缝衔接不同会话。
- **背景研究**：在用户工作时搜索网络和读取文件。
- **模式检测**：识别用户的行为模式并提供建议。
- **主动代码库感知**：在用户处理特定功能时探索相关文件。

### 调试

可查看日志文件进行调试：

```
# Watch all logs (macOS/Linux)
tail -f /tmp/letta-claude-sync-$(id -u)/*.log

# Or specific logs
tail -f /tmp/letta-claude-sync-$(id -u)/send_messages.log
tail -f /tmp/letta-claude-sync-$(id -u)/send_worker_sdk.log
```

### API注意事项

- 记忆同步需要`?include=agent.blocks`查询参数。
- 会话记录传递使用Letta Code SDK，无原始API调用。
- SDK工作者在更新状态前流式传输代理的完整响应。

原文：https://mp.weixin.qq.com/s/l8lCWdIlGyI1fU1XZNgMRQ

欢迎关注公zh：AI Tech研习社

关注公zh，后台回复【OpenClaw完全使用手册】，领取OpenClaw完全使用手册.pdf学习资料，更多学习资源敬请期待。