Reasoning Lifecycle

Relevant source files

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

• README.md
• CLAUDE.md
• session_manager.py
• models.py
• memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md
• tests/test_integration.py

The Reasoning Lifecycle governs how a coding agent moves from initial problem analysis to durable conclusions and long-term memory. It manages the transition of information from ephemeral "scratch" thoughts to stable architecture decisions and promoted memories. This lifecycle ensures that large-codebase context remains manageable by applying compaction and promotion rules to machine reasoning.

Sources: README.md:12-19, README.md:90-100

Lifecycle States

The project categorizes information into four distinct lifecycle states based on stability and reuse value.

State	Durability	Description
Scratch Reasoning	Ephemeral	Local, bounded, and disposable logic used during active tasks.
Checkpoint Summaries	Temporary	Recovery artifacts used to restore state at subtask boundaries.
Promoted Conclusions	Persistent	Reusable machine memory gated by evidence and stability.
Canonical Docs	Permanent	Human-maintained "truth" such as design docs, ADRs, and module maps.

Sources: README.md:91-96, CLAUDE.md:37-44

Data Flow and Persistence

The UnifiedSessionManager orchestrates the flow of data through these states. When an agent invokes a tool, the logic flows through a 5-layer stack from the MCP transport down to the domain models and markdown storage.

Reasoning Progression

The reasoning process begins with a Problem Statement and progresses through iterative cycles of thoughts, branching, and memory promotion.

1. Session Initiation

A session starts by defining a problem, success criteria, and constraints. This creates a UnifiedSession object which acts as the aggregate root for all subsequent reasoning artifacts.
Sources: session_manager.py:46-63, tests/test_integration.py:27-35

2. Iterative Thought and Branching

The agent records individual Thought objects. If alternative approaches are needed, the agent creates a Branch.

• Thoughts: Contain specific logic, confidence scores, and package dependencies.
• Branches: Link to a specific from_thought_id, allowing non-linear exploration of a problem space.
  Sources: session_manager.py:168-195, session_manager.py:210-225

3. Memory Promotion

Ephemeral thoughts become durable Memory artifacts when they provide stable value beyond the current task.

• Promotion Gating: Must be backed by evidence, high confidence, and likely future reuse.
• Storage: Memories are embedded in the session markdown and also written as standalone markdown files for cross-session retrieval.
  Sources: README.md:98-103, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:38-42

Token and Context Management

The lifecycle enforces "compaction" to prevent context window saturation. The system monitors token counts and triggers compression at defined thresholds.

• Active Context Ceiling: 64K tokens.
• Compaction Trigger: 45K tokens.
• Method: The system replaces raw transcripts with handoff bundles and summaries when transitioning between subtasks.

Sources: README.md:106-116, CLAUDE.md:52-54

Memory Retrieval Split

Retrieval is split between two systems to prevent overlapping responsibilities.

Tool	Ownership	Target Content
qmd	Canonical Documents	Human-maintained truth, document collections, module maps.
Zvec	Semantic Artifacts	Promoted machine memories, investigation summaries, architecture decisions.

Sources: README.md:65-71, CLAUDE.md:27-31

Conclusion

The Reasoning Lifecycle ensures that ephemeral chain-of-thought logic is distilled into structured, durable artifacts. By separating scratch reasoning from promoted conclusions and canonical documentation, the system maintains a high-signal memory bank that supports long-running agent workflows without exhausting context limits.

Sources: README.md:120-129, CLAUDE.md:46-50