claude-subconscious

Claude Subconscious

A subconscious for Claude Code. A Letta agent that watches your sessions, accumulates context, and provides async guidance to "main Claude".

[!IMPORTANT] Claude Subconcious is an experimental way to extend Claude Code (a closed source / black box agent) with the power of Letta's memory system and context engineering.

If you're looking for a coding agent that's memory-first, model agnostic, and fully open source, we recommend using Letta Code.

What Is This?

Claude Code forgets everything between sessions. Claude Subconscious adds a persistent memory layer underneath:

• A Letta agent observes every Claude Code conversation
• Accumulates patterns across sessions, projects, and time
• Provides async guidance, reminders, and context

Letta agents learn from input and can be customized to store specific information, run tool calls, perform background research, or take autonomous actions. Using Letta's Conversations feature, a single agent can serve multiple Claude Code sessions in parallel with shared memory across all of them.

How It Works

Letta does simple management of your CLAUDE.md file, and injects some content into user prompts. Your Claude Code transcript will be send to the subconscious agent each time Claude stops.

┌─────────────┐          ┌─────────────┐
│ Claude Code │◄────────►│ Letta Agent │
└─────────────┘          └─────────────┘
       │                        │
       │   Session Start        │
       ├───────────────────────►│ New session notification
       │                        │
       │   Before each prompt   │
       │◄───────────────────────┤ Memory → CLAUDE.md
       │                        │
       │   After each response  │
       ├───────────────────────►│ Transcript → Agent (async)
       │                        │
       │   Next prompt          │
       │◄───────────────────────┤ Guidance → CLAUDE.md

Installation

Install from GitHub:

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

Updating

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

Install from Source

Clone the repository:

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

Enable the plugin (from inside the cloned directory):

/plugin enable .

Or enable globally for all projects:

/plugin enable --global .

If running from a different directory, use the full path to the cloned repo.

Linux: tmpfs Workaround

If plugin installation fails with EXDEV: cross-device link not permitted, your /tmp is likely on a different filesystem (common on Ubuntu, Fedora, Arch). Set TMPDIR to work around this Claude Code bug:

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

Add to your shell profile (~/.bashrc or ~/.zshrc) to make permanent.

Configuration

Required

export LETTA_API_KEY="your-api-key"

Get your API key from app.letta.com.

Optional

export LETTA_AGENT_ID="agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export LETTA_BASE_URL="http://localhost:8283"  # For self-hosted Letta
export LETTA_MODEL="openai/gpt-4o-mini"        # Model override

• LETTA_AGENT_ID - If not set, the plugin automatically imports a default "Subconscious" agent on first use.
• LETTA_BASE_URL - For self-hosted Letta servers. Defaults to https://api.letta.com.
• LETTA_MODEL - Override the agent's model. Optional - the plugin auto-detects and selects from available models. See Model Configuration below.

Agent Resolution Order

1. Environment variable - LETTA_AGENT_ID if set
2. Saved config - ~/.letta/claude-subconscious/config.json if exists
3. Auto-import - Imports bundled Subconscious.af agent, saves ID for future use

This means zero-config setup: just set LETTA_API_KEY and the plugin handles the rest.

Model Configuration

The plugin automatically detects available models on your Letta server and configures the agent appropriately:

1. Queries available models from your Letta server (GET /v1/models/)
2. Checks if the agent's model is available on that server
3. Auto-selects a fallback if the current model isn't available

Auto-Selection Priority

When the agent's model isn't available, the plugin selects from available models in this order:

1. openai/gpt-4o-mini (recommended - fast and cost-effective)
2. openai/gpt-4o
3. anthropic/claude-3-5-sonnet
4. anthropic/claude-3-haiku
5. google_ai/gemini-2.0-flash
6. First available model on the server

Manual Override