# letta-ai/claude-subconscious architecture

> Architecture diagram of the GitHub repository letta-ai/claude-subconscious, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/letta-ai/claude-subconscious
- Repository: https://github.com/letta-ai/claude-subconscious

## Overview

Claude Subconscious is a Claude Code plugin that runs background hooks to share session context with a persistent Letta agent and surface guidance back to Claude. The main loop starts or reuses a Letta conversation, reads and formats transcript updates, sends them asynchronously through the Letta Code SDK, then injects agent messages or memory updates before prompts and tool use. The README also documents agent setup and model selection, shared cross-project memory, and agent access to code and web tools. Some hook wiring and implementation details are not shown in the excerpts; unsampled relationships are omitted.

Main entry points: [`scripts/session_start.ts`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/session_start.ts) (Session start), [`scripts/send_messages_to_letta.ts`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/send_messages_to_letta.ts) (Transcript sender), [`scripts/sync_letta_memory.ts`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts) (Prompt memory sync), [`scripts/pretool_sync.ts`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/pretool_sync.ts) (Pre-tool updates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hooks["Claude hooks"]
  node_session_start["Session start<br/>[session_start.ts]"]
  node_send["Transcript sender"]
  node_prompt_sync["Prompt memory sync"]
  node_tool_sync["Pre-tool updates<br/>[pretool_sync.ts]"]
end

subgraph group_session["Session and state"]
  node_transcripts["Transcript parsing"]
  node_conversations["Conversation and state utilities"]
  node_state[("Local session state")]
end

subgraph group_letta["Letta integration"]
  node_agent_config["Agent configuration<br/>[agent_config.ts]"]
  node_api_urls["API URL builder<br/>[letta_api_url.ts]"]
  node_letta["Letta service"]
end

subgraph group_agent["Background agent"]
  node_worker["SDK worker<br/>[send_worker_sdk.ts]"]
  node_sdk["Letta Code SDK"]
  node_tools["Code and web tools"]
end

node_claude(("Claude Code"))

node_claude -->|"starts session"| node_session_start
node_claude -->|"provides transcript"| node_send
node_send -->|"reads and formats"| node_transcripts
node_send -->|"gets conversation"| node_conversations
node_send -->|"loads and saves"| node_state
node_session_start -->|"creates or reuses"| node_conversations
node_session_start -->|"maps session"| node_state
node_send -->|"spawns worker"| node_worker
node_worker -->|"resumes session"| node_sdk
node_sdk -->|"sends agent messages"| node_letta
node_agent_config -->|"builds requests"| node_api_urls
node_session_start -->|"resolves agent"| node_agent_config
node_session_start -->|"notifies agent"| node_letta
node_prompt_sync -->|"resolves agent"| node_agent_config
node_prompt_sync -->|"loads and saves"| node_state
node_prompt_sync -->|"fetches updates"| node_letta
node_prompt_sync -->|"injects guidance"| node_claude
node_tool_sync -->|"resolves agent"| node_agent_config
node_tool_sync -->|"loads and saves"| node_state
node_tool_sync -->|"checks updates"| node_letta
node_tool_sync -->|"injects updates"| node_claude
node_sdk -->|"invokes tools"| node_tools
node_letta -->|"whispers guidance"| node_claude

click node_session_start "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/session_start.ts"
click node_send "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/send_messages_to_letta.ts"
click node_prompt_sync "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts"
click node_tool_sync "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/pretool_sync.ts"
click node_transcripts "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/transcript_utils.ts"
click node_conversations "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/conversation_utils.ts"
click node_agent_config "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/agent_config.ts"
click node_api_urls "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/letta_api_url.ts"
click node_state "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/conversation_utils.ts"
click node_worker "https://github.com/letta-ai/claude-subconscious/blob/main/scripts/send_worker_sdk.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session_start,node_send,node_prompt_sync,node_tool_sync toneBlue
class node_transcripts,node_conversations,node_state toneAmber
class node_agent_config,node_api_urls,node_letta toneMint
class node_worker,node_sdk,node_tools toneRose
class node_claude toneIndigo
```

## Components

### Claude hooks

- [Session start](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/session_start.ts): `scripts/session_start.ts`
- [Transcript sender](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/send_messages_to_letta.ts): `scripts/send_messages_to_letta.ts`
- [Prompt memory sync](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts): `scripts/sync_letta_memory.ts`
- [Pre-tool updates](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/pretool_sync.ts): `scripts/pretool_sync.ts`

### Session and state

- [Transcript parsing](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/transcript_utils.ts): `scripts/transcript_utils.ts`
- [Conversation and state utilities](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/conversation_utils.ts): `scripts/conversation_utils.ts`
- [Local session state](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/conversation_utils.ts): `scripts/conversation_utils.ts`

### Letta integration

- [Agent configuration](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/agent_config.ts): `scripts/agent_config.ts`
- [API URL builder](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/letta_api_url.ts): `scripts/letta_api_url.ts`
- **Letta service**

### Background agent

- [SDK worker](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/send_worker_sdk.ts): `scripts/send_worker_sdk.ts`
- **Letta Code SDK**
- **Code and web tools**

### Other components

- **Claude Code**

## Connections

- Claude Code → Session start: starts session (evidence: `README.md`)
- Claude Code → Transcript sender: provides transcript (evidence: `README.md`)
- Transcript sender → Transcript parsing: reads and formats (evidence: `scripts/send_messages_to_letta.ts`)
- Transcript sender → Conversation and state utilities: gets conversation (evidence: `scripts/send_messages_to_letta.ts`)
- Transcript sender → Local session state: loads and saves (evidence: `scripts/send_messages_to_letta.ts`)
- Session start → Conversation and state utilities: creates or reuses (evidence: `scripts/session_start.ts`)
- Session start → Local session state: maps session (evidence: `README.md`)
- Transcript sender → SDK worker: spawns worker
- SDK worker → Letta Code SDK: resumes session (evidence: `scripts/send_worker_sdk.ts`)
- Letta Code SDK → Letta service: sends agent messages (evidence: `README.md`)
- Agent configuration → API URL builder: builds requests (evidence: `scripts/agent_config.ts`)
- Session start → Agent configuration: resolves agent (evidence: `scripts/session_start.ts`)
- Session start → Letta service: notifies agent (evidence: `README.md`)
- Prompt memory sync → Agent configuration: resolves agent (evidence: `scripts/sync_letta_memory.ts`)
- Prompt memory sync → Local session state: loads and saves (evidence: `scripts/sync_letta_memory.ts`)
- Prompt memory sync → Letta service: fetches updates (evidence: `README.md`)
- Prompt memory sync → Claude Code: injects guidance (evidence: `README.md`)
- Pre-tool updates → Agent configuration: resolves agent (evidence: `scripts/pretool_sync.ts`)
- Pre-tool updates → Local session state: loads and saves (evidence: `scripts/pretool_sync.ts`)
- Pre-tool updates → Letta service: checks updates (evidence: `README.md`)
- Pre-tool updates → Claude Code: injects updates (evidence: `README.md`)
- Letta Code SDK → Code and web tools: invokes tools (evidence: `README.md`)
- Letta service → Claude Code: whispers guidance (evidence: `README.md`)
