Headroom Memory Scope Levels: USER, SESSION, AGENT, and TURN Explained

Headroom supports four hierarchical memory scope levels—USER, SESSION, AGENT, and TURN—that control persistence and visibility from permanent user data to ephemeral turn-level context.

The chopratejas/headroom repository implements a sophisticated memory management system using distinct memory scope levels to determine exactly how long information persists and where it remains visible across the application. These hierarchical scopes ensure AI agents access appropriate context at the right time, balancing long-term user knowledge against temporary conversation state.

The Four Memory Scope Levels

Headroom defines memory scope levels as an enum in headroom/memory/models.py, with each level representing a different longevity and visibility boundary.

USER Scope

The USER scope persists across all sessions for a given user. Memories at this level act as permanent user preferences or facts that should survive individual conversations. According to the source code, this is defined at ScopeLevel.USER in headroom/memory/models.py.

SESSION Scope

The SESSION scope persists only within a single task or conversation, making it ideal for temporary context that should survive multiple turns but disappear when the user starts a new chat. This level is defined at ScopeLevel.SESSION.

AGENT Scope

The AGENT scope persists for the lifetime of a particular agent instance. This allows specific agent configurations or learned behaviors to remain available throughout the session without polluting global user memory. The constant is defined at ScopeLevel.AGENT.

TURN Scope

The TURN scope is ephemeral, living only for the duration of a single LLM call. This is perfect for temporary facts or intermediate computations that should not persist beyond the immediate response. This is defined at ScopeLevel.TURN.

Creating Memories at Specific Scope Levels

When instantiating the Memory class from headroom/memory/models.py, you define the scope implicitly by providing specific ID combinations. The system automatically determines the appropriate scope based on which IDs are present.

from headroom.memory.models import Memory, ScopeLevel

# USER scope: visible across all sessions (no session/agent/turn IDs)

user_mem = Memory(
    content="User's favorite color is blue",
    user_id="alice",
)

# SESSION scope: only for this conversation

session_mem = Memory(
    content="Current task is summarizing a PDF",
    user_id="alice",
    session_id="sess-1234",
)

# AGENT scope: tied to a specific agent instance

agent_mem = Memory(
    content="Agent prefers concise responses",
    user_id="alice",
    session_id="sess-1234",
    agent_id="agent-xyz",
)

# TURN scope: ephemeral, disappears after the LLM call

turn_mem = Memory(
    content="Temporary fact for this turn only",
    user_id="alice",
    session_id="sess-1234",
    agent_id="agent-xyz",
    turn_id="turn-7",
)

Querying Memories by Scope Level

The MemoryStore class in headroom/memory/core.py uses MemoryFilter from headroom/memory/ports.py to retrieve memories filtered by specific scope levels. This allows precise context retrieval based on the current execution context.

from headroom.memory.core import MemoryStore
from headroom.memory.ports import MemoryFilter
from headroom.memory.models import ScopeLevel

store = MemoryStore(...)  # concrete backend like SQLiteVectorIndex

# Retrieve only USER-level memories

user_memories = await store.query(
    MemoryFilter(user_id="alice", scope_levels=[ScopeLevel.USER])
)

# Retrieve SESSION-level memories for a specific conversation

session_memories = await store.query(
    MemoryFilter(
        user_id="alice", 
        session_id="sess-1234",
        scope_levels=[ScopeLevel.SESSION]
    )
)

CLI Support for Memory Scopes

The command-line interface implemented in headroom/cli/memory.py exposes scope level filtering through the --scope flag, allowing developers to inspect memories at different persistence levels directly from the terminal.

# List all USER-level memories for the current user

headroom memory list --scope user

# Show SESSION-level memories for a specific conversation

headroom memory list --scope session --session-id sess-1234

Summary

• Four hierarchical levels: USER (permanent), SESSION (conversation), AGENT (instance), and TURN (ephemeral) provide fine-grained control over memory persistence.
• Defined in headroom/memory/models.py: The ScopeLevel enum at lines 20-23 establishes the contract used throughout the codebase.
• Implicit scoping: The Memory class automatically determines scope based on which ID fields (user_id, session_id, agent_id, turn_id) are populated.
• Query filtering: MemoryFilter in headroom/memory/ports.py accepts scope_levels parameters to retrieve contextually relevant memories.
• Storage routing: headroom/memory/storage_router.py resolves appropriate backends based on scope requirements and request context.

Frequently Asked Questions

What is the difference between SESSION and AGENT scope in Headroom?

SESSION scope persists for an entire conversation or task, while AGENT scope is tied to a specific agent instance that may span multiple sessions or be shorter than a full session. According to the implementation in headroom/memory/models.py, SESSION requires a session_id whereas AGENT requires both session_id and agent_id.

How does TURN scope improve performance in Headroom?

TURN scope prevents memory bloat by automatically discarding temporary facts after a single LLM call completes. As implemented in the storage layer, these ephemeral memories never reach persistent storage backends, reducing query overhead and storage costs for transient computational data.

Can I query multiple memory scope levels simultaneously?

Yes, the MemoryFilter class accepts a list of scope_levels, allowing you to retrieve memories from multiple hierarchies in a single query. For example, you can query both USER and SESSION scopes together to get long-term preferences alongside current conversation context.

Where is the ScopeLevel enum defined in the Headroom codebase?

The ScopeLevel enum is defined in headroom/memory/models.py at lines 20-23, containing the four constants: USER, SESSION, AGENT, and TURN. This enum is imported throughout the codebase including headroom/memory/core.py and headroom/memory/ports.py to enforce type-safe scope handling.

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