The Eight Memory Blocks in the Default Subconscious Agent Explained

The default Subconscious agent maintains eight persistent memory blocks—core_directives, guidance, pending_items, project_context, self_improvement, session_patterns, tool_guidelines, and user_preferences—that store behavioral guidelines, project context, and user preferences across Claude Code sessions.

The letta-ai/claude-subconscious repository implements a persistent memory layer for Claude Code through the Subconscious agent. According to the source code in Subconscious.af, these eight memory blocks form a structured knowledge base that survives across sessions, automatically injected into Claude's system prompt via the <letta_memory_blocks> XML wrapper defined in scripts/conversation_utils.ts.

Overview of the Eight Memory Blocks

Each block lives as a file under the agent's system/ directory and is declared in the Subconscious.af manifest (lines 56‑293). The blocks divide responsibility across identity, operational guidance, and learned context.

1. core_directives

Purpose: Primary role, behavioral guidelines, and processing logic for observing Claude Code sessions.

Defined in Subconscious.af (lines 56‑62), this block contains the immutable personality and safety constraints that govern how the agent interprets every session. It is the highest-priority context and typically only modified to reflect policy changes.

2. guidance

Purpose: Active guidance for the next Claude Code session.

Located in Subconscious.af (lines 175‑181), this block serves as a scratchpad for immediate, actionable hints. The agent writes here when it detects something useful to surface, and clears entries after delivery or when they become stale. This is the primary channel through which the Subconscious whispers suggestions to Claude Code.

3. pending_items

Purpose: Unfinished work, explicit TODOs, and follow-up items mentioned across sessions.

Defined at lines 194‑200 in Subconscious.af, this block tracks tasks that span multiple interactions. Items are cleared when resolved, making it the canonical backlog for cross-session continuity.

4. project_context

Purpose: Active project knowledge, including architecture decisions, known gotchas, and key files.

As specified in Subconscious.af (lines 202‑209), this block stores durable facts about the codebase. The manifest notes that you can create sub-blocks for multiple projects if needed, allowing the agent to maintain context across different repositories.

5. self_improvement

Purpose: Guidelines for evolving memory architecture and learning procedures.

Found in Subconscious.af (lines 230‑237), this meta-cognitive block contains rules about how the agent should restructure its own memory limits and retention policies. For example, it might specify a hard cap on the total number of memory files allowed.

6. session_patterns

Purpose: Recurring behaviors, time-based patterns, and common struggles.

Defined in Subconscious.af (lines 251‑258), this block captures longitudinal observations about user habits. The agent uses these patterns to generate predictive guidance before the user encounters a known friction point.

7. tool_guidelines

Purpose: How to use available tools effectively.

Located at lines 270‑277 in Subconscious.af, this block stores reference material for tool capabilities and parameters. It is consulted when the agent is uncertain about which tool to invoke or how to format arguments.

8. user_preferences

Purpose: Learned coding style, tool preferences, and communication style.

As defined in Subconscious.af (lines 286‑293), this block accumulates explicit statements and observed corrections about how the user prefers to work. It drives personalization of code suggestions and formatting choices.

Interacting with Memory Blocks Programmatically

The Subconscious agent mutates these blocks using Letta's built-in memory tools. In scripts/conversation_utils.ts, the runtime wraps the current state of all eight blocks into the <letta_memory_blocks> XML element that prefixes Claude's system prompt. After any in-session edit, scripts/sync_letta_memory.ts automatically persists changes back to the repository's CLAUDE.md file.

Below are practical TypeScript snippets that execute inside Letta tool calls (e.g., memory, memory_replace, memory_insert).

Updating Active Guidance

Use str_replace to overwrite the placeholder with a timely hint:

await memory(agent_state, "str_replace", {
  path: "/memories/guidance",
  old_string: "(No active guidance. Write here when there's something genuinely useful for the next session.)",
  new_string: "⚡ Remember to refactor the user‑auth module – it contains duplicated token logic."
});

Adding a Pending TODO

Use insert to prepend a new task to pending_items:

await memory(agent_state, "insert", {
  path: "/memories/pending_items",
  insert_line: 0,
  insert_text: "- [ ] Finish the OpenAPI spec for the billing service."
});

Enriching Project Context

Replace the empty placeholder with architectural facts:

await memory(agent_state, "str_replace", {
  path: "/memories/project_context",
  old_string: "(No project context yet. Populated as sessions reveal codebase details.)",
  new_string: "The codebase uses **Zod** for runtime schema validation and **tRPC** for type‑safe RPC endpoints."
});

Recording User Preferences

Capture explicit style choices in user_preferences:

await memory(agent_state, "str_replace", {
  path: "/memories/user_preferences",
  old_string: "(No user preferences yet. Populated as sessions reveal coding style, tool choices, and communication preferences.)",
  new_string: "User prefers **explicit type annotations** in TypeScript and likes **single‑quote** strings."
});

Logging Session Patterns

Document recurring friction points for predictive guidance:

await memory(agent_state, "str_replace", {
  path: "/memories/session_patterns",
  old_string: "(No patterns observed yet. Populated after multiple sessions.)",
  new_string: "When fixing build failures, the user often forgets to run `npm install` after adding a new devDependency."
});

Refining Tool Usage

Append specific shortcuts to tool_guidelines:

await memory(agent_state, "insert", {
  path: "/memories/tool_guidelines",
  insert_line: 10,
  insert_text: "- Remember to run `git status` before committing large memory edits."
});

Evolving Self-Improvement Rules

Adjust memory architecture limits:

await memory(agent_state, "str_replace", {
  path: "/memories/self_improvement",
  old_string: "Never exceed 12 total memory files",
  new_string: "Never exceed **10** total memory files (reserve two slots for experimental notes)."
});

Modifying Core Directives

Update foundational policy (use sparingly):

await memory(agent_state, "str_replace", {
  path: "/memories/core_directives",
  old_string: "Primary role, behavioral guidelines, and processing logic for observing Claude Code sessions.",
  new_string: "Primary role, behavioral guidelines, and processing logic for observing Claude Code sessions. **New policy:** Never suggest committing secrets."
});

Key Files in the Memory Architecture

These five files implement the persistent memory layer that makes the eight blocks survive across Claude Code sessions:

• Subconscious.af — The authoritative manifest that declares the eight memory blocks, their descriptions, and line ranges (56‑293).
• scripts/conversation_utils.ts — Contains the XML wrappers (<letta_memory_blocks>) and logic that injects the current state of all eight blocks into Claude's system prompt.
• scripts/sync_letta_memory.ts — Persists any in-session memory edits back to the repository's CLAUDE.md file, ensuring cross-session durability.
• scripts/pretool_sync.ts — Detects changed memory blocks before each tool call and ensures they are included in the outgoing payload.
• scripts/session_start.ts — Initializes the agent's mode (whisper, listen-only, or full) and announces memory-only mode when applicable.

Summary

• The Subconscious agent organizes knowledge into eight distinct memory blocks defined in Subconscious.af (lines 56‑293).
• core_directives and guidance control behavior and immediate suggestions, while pending_items tracks cross-session tasks.
• project_context and user_preferences store durable facts about the codebase and coding style.
• session_patterns, tool_guidelines, and self_improvement enable meta-learning and predictive assistance.
• All mutations flow through Letta's memory tools and are persisted via scripts/sync_letta_memory.ts to CLAUDE.md.

Frequently Asked Questions

What is the Subconscious agent in Claude Code?

The Subconscious agent is a Letta-based implementation from the letta-ai/claude-subconscious repository that attaches a persistent memory layer to Claude Code. It observes sessions, records insights into eight structured memory blocks, and injects that context into future interactions via the <letta_memory_blocks> XML wrapper.

How do the eight memory blocks persist across sessions?

After any memory edit, scripts/sync_letta_memory.ts writes the updated block contents back to the CLAUDE.md file in the repository. When a new Claude Code session starts, scripts/conversation_utils.ts reads these files and wraps them in <letta_memory_blocks> XML that is prepended to Claude's system prompt, effectively restoring the agent's memory state.

Which memory block should store TODO items?

Unfinished work and explicit TODOs belong in pending_items, defined in Subconscious.af (lines 194‑200). This block is specifically designed for follow-up items mentioned across sessions, with the directive to clear entries when they are resolved.

Can I add custom memory blocks beyond the default eight?

While the default Subconscious agent ships with exactly eight blocks, the self_improvement block (lines 230‑237) contains guidelines for evolving memory architecture. According to the source, you can create sub-blocks for multiple projects within project_context, but adding entirely new top-level blocks would require modifying Subconscious.af and updating the sync logic in scripts/sync_letta_memory.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}