Subconscious System

The subconscious system is Samantha LLM’s automatic memory creation pipeline. After each session ends, a background worker analyzes your conversation and generates structured memories — no manual note-taking required.

How It Works

When you exit a session (samantha-llm start completes), the following happens automatically in the background:

Session ends
    |
    v
Transcript captured (terminal recording)
    |
    v
Conversation parsed and cleaned (ANSI codes stripped)
    |
    v
Large conversations chunked at natural boundaries
    |
    v
Each chunk analyzed by LLM (extracts patterns, decisions, learnings)
    |
    v
Chunks merged and deduplicated
    |
    v
Structured memory files generated
    |
    v
Ready for merge into cerebrum

You don’t need to wait for this to finish. It runs in the background and the memories are available for your next session.

What Gets Extracted

The analysis prompt instructs the LLM to extract:

• Patterns — Recurring workflows, common tasks, working habits
• Decisions — Architectural choices, technical trade-offs, and rationale
• Learnings — New discoveries, insights, things that didn’t work
• Preferences — Your working style, tool choices, communication preferences
• TODOs — Action items and follow-ups identified during the session

Each extraction includes context — not just what was decided, but why.

Conversation Chunking

Long sessions (over ~150K characters) are split into manageable chunks before analysis. The chunker looks for natural boundaries rather than cutting mid-thought:

• Tool execution boundaries (end of a command output)
• File operation boundaries (after a file read/write completes)
• Test execution results
• Task transitions (switching topics)
• Paragraph breaks

Each chunk receives a summary of previous chunks for context continuity. This means conversations of any length can be processed — a 2-hour session works just as well as a 10-minute one.

Managing Sessions

Check Processing Status

samantha-llm subconscious status

Shows whether a worker is running, completed sessions awaiting merge, and any failures.

Merge Completed Sessions

After the background worker finishes, memories sit in a staging area until you merge them:

samantha-llm subconscious merge

This integrates the generated memories into your short-term memory and updates the memory indexes. Samantha will check for unmerged sessions during bootstrap and ask if you’d like to merge them.

Retry After Failures

If processing was interrupted (laptop sleep, API outage), you can retry the failed chunks:

samantha-llm subconscious retry <session_id>

The retry picks up where it left off — chunks that already completed are not reprocessed.

Reprocess Sessions

If a session was processed but produced poor results (no patterns or decisions extracted), you can reprocess it:

samantha-llm subconscious reprocess <session_id>

Without a session ID, this finds and reprocesses all sessions with empty results.

Other Commands

# List all session workspaces
samantha-llm subconscious list

# Show the analysis guidance from the last session
samantha-llm subconscious guidance

# Wait for the background worker to finish (blocks until done)
samantha-llm subconscious wait

# Reset the analysis prompt to the default
samantha-llm subconscious reset-prompt

Session Isolation

Each session gets its own isolated workspace under .ai/subconscious/.ai/sessions/<session_id>/. This means:

• Multiple concurrent sessions don’t interfere with each other
• A failed analysis doesn’t affect other sessions
• Each session’s raw output, parsed results, and generated memories are kept separate until merge

Session workspaces are archived to .ai/subconscious/.ai/processed/ after a successful merge.

Customizing the Analysis Prompt

The LLM analysis is driven by a prompt that defines what to extract and how to format it. The default prompt works well for software engineering sessions, but you can customize it:

# The prompt lives at:
# ~/.config/samantha-llm/subconscious/analysis-prompt.txt

# Reset to the default if you want to start over:
samantha-llm subconscious reset-prompt

Edit the prompt file to change what the subconscious system looks for. For example, you could add extraction categories specific to your domain (design decisions, customer requirements, compliance notes, etc.).

Typical Workflow

For most users, the subconscious system is hands-off:

1. Work normally in a session
2. Exit the session — background processing starts automatically
3. Next session, Samantha checks for unmerged memories and asks to merge
4. Merged memories are available for the rest of the session

The only command you’ll regularly use is samantha-llm subconscious merge, and even that is prompted for you during bootstrap.

Next Steps

• Memory System — Where the generated memories end up
• Memory Search — Searching across all memories including subconscious-generated ones
• Architecture — Technical details of the processing pipeline