# The Eight Memory Blocks in the Default Subconscious Agent Explained

> Explore the eight memory blocks in the default Subconscious agent: core directives, guidance, pending items, project context, self improvement, session patterns, tool guidelines, and user preferences. Understand their functions...

- Repository: [Letta/claude-subconscious](https://github.com/letta-ai/claude-subconscious)
- Tags: deep-dive
- Published: 2026-03-26

---

**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`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts) automatically persists changes back to the repository's [`CLAUDE.md`](https://github.com/letta-ai/claude-subconscious/blob/main/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:

```typescript
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`:

```typescript
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:

```typescript
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`:

```typescript
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:

```typescript
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`:

```typescript
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:

```typescript
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):

```typescript
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`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts)** — Persists any in-session memory edits back to the repository's [`CLAUDE.md`](https://github.com/letta-ai/claude-subconscious/blob/main/CLAUDE.md) file, ensuring cross-session durability.
- **[`scripts/pretool_sync.ts`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts) to [`CLAUDE.md`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts) writes the updated block contents back to the [`CLAUDE.md`](https://github.com/letta-ai/claude-subconscious/blob/main/CLAUDE.md) file in the repository. When a new Claude Code session starts, [`scripts/conversation_utils.ts`](https://github.com/letta-ai/claude-subconscious/blob/main/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`](https://github.com/letta-ai/claude-subconscious/blob/main/scripts/sync_letta_memory.ts).