Memory Promotion

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• README.md
• models.py
• session_manager.py
• mcp_tools.py
• memory-bank/memories/1eba30a1-6283-44a2-a372-82e9fe92460d.md

Memory Promotion defines the transition of ephemeral reasoning into durable machine memory within the Sequential Thinking MCP architecture. It ensures that only validated, high-confidence conclusions persist for long-term semantic retrieval, preventing the accumulation of raw chain-of-thought data in the permanent record.

In the project's target architecture, promoted memories move from local, bounded scratchpads to a structured retrieval layer. This process distinguishes between "canonical human truth" (markdown documents) and "promoted machine memory" (semantic artifacts).

Sources: CLAUDE.md:34-40, README.md:60-70

The Reasoning Lifecycle

The system manages memory through a specific lifecycle that separates temporary exploration from permanent storage. This prevents token context overflow and maintains high signal-to-noise ratios for future retrieval.

1. Scratch Reasoning: Ephemeral, bounded, and disposable thoughts generated during active problem-solving.
2. Checkpoint Summaries: Compact recovery artifacts that allow an agent to resume work at subtask boundaries.
3. Promoted Conclusions: Durable machine memory created only after passing promotion gates.
4. Canonical Docs: Official human-maintained truth, such as design documents or runbooks.

Sources: CLAUDE.md:34-39, README.md:62-65

Promotion Flow

This diagram illustrates the lifecycle of a thought from creation to promotion.

The diagram shows how thoughts are filtered by confidence and evidence before reaching the durable memory state.
Sources: CLAUDE.md:34-40, README.md:43-50

Architecture and Retrieval Layers

The system divides retrieval responsibilities to prevent overlapping systems from conflicting.

• Zvec Layer: Owns the retrieval for promoted memory artifacts and non-document semantic artifacts like investigation summaries and architecture decisions.
• Metadata Store: Manages the lifecycle state of promoted items, including confidence scores and promotion status.
• qmd Layer: Handles retrieval for canonical documentation and collections.

Sources: CLAUDE.md:24-30, README.md:52-58

Metadata Requirements

Promoted artifacts must include specific metadata to manage their lifecycle.

Field	Description	Source
confidence	Numeric value (0-1) indicating certainty.	models.py:84
evidence	Supporting data or reasoning that justifies the memory.	CLAUDE.md:29
promotion_status	Current state in the durability lifecycle.	CLAUDE.md:29
scope	The task or project context where the memory is valid.	CLAUDE.md:29
staleness	Indicators of whether the memory requires update or removal.	CLAUDE.md:29
sync_state	Status of synchronization between local and cloud layers.	CLAUDE.md:30

Promotion Gating Logic

The system gates promotion to maintain the quality of long-term memory. An artifact becomes durable only if it meets specific criteria:

• Evidence: The conclusion must be backed by data or successful execution.
• Stability: The information remains valid beyond the current immediate task.
• Reuse Value: The memory provides likely value for future sessions or different agents.
• Confidence Ceiling: Raw thoughts are filtered based on their confidence score, typically requiring a value within the 0.0 to 1.0 range.

Sources: CLAUDE.md:39-40, README.md:66-70, session_manager.py:166

Implementation of Gated Storage

The UnifiedSessionManager currently facilitates the storage of memories that serve as the foundation for promotion.

# session_manager.py:255-274
def store_memory(
    self,
    content: str,
    confidence: float = 0.8,
    code_snippet: str = "",
    language: str = "",
    tags: str = "",
) -> str:
    if not self.current_session:
        raise ValueError("No active session")
    memory = Memory(
        session_id=self.current_session.id,
        content=content,
        confidence=confidence,
        code_snippet=code_snippet,
        language=language,
        tags=tags.split(",") if tags else [],
    )
    self.current_session.memories.append(memory)
    self._save_memory_to_file(memory)
    self._save_session_to_file(self.current_session)
    return memory.id

Sources: session_manager.py:255-274, mcp_tools.py:91-110

MCP Integration Surface

Memory promotion is exposed through standard MCP tools. These tools allow agents to interact with the durable memory layer without directly accessing the underlying storage.

Tool Name	Action	Parameters
promote_memory	Transitions a thought or conclusion to durable storage.	thought_id, evidence, tags
store_memory	Creates a persistent memory record in the current session.	content, confidence, code_snippet, tags
query_memories	Retrieves promoted memories based on tags or content.	tags, content_contains
summarize_session	Compresses session context into a promoted summary.	session_id

Sources: README.md:88-95, mcp_tools.py:91-137

Sequence of Promotion Call

This sequence diagram shows how an agent promotes a thought to a durable memory.

The sequence highlights the validation and indexing steps required for durable persistence.
Sources: session_manager.py:276-299, mcp_tools.py:176-218

Memory Promotion effectively bridges ephemeral reasoning and long-term project knowledge, ensuring the MCP server provides stable, contextually relevant information across disparate sessions.