Session & Learning Ledger
Relevant source files
The following files were used as context for generating this wiki page:
The Session & Learning Ledger system is a core architectural component of M31A designed to manage the lifecycle of AI-driven coding tasks, ensure persistence across restarts, and facilitate cross-session intelligence. While individual sessions track the immediate progress of a specific goal, the Learning Ledger acts as a long-term memory store, recording outcomes, patterns, and failures to improve future performance.
This system ensures that M31A "owns the loop" by documenting every phase of the workflow—from initialization to shipping—and providing a mechanism for the agent to learn from historical data. It combines structured JSON/Markdown persistence with a "Memory" system that rotates to prevent unbounded growth while maintaining relevant context for the LLM.
Sources: README.md:95-101, internal/engine/workflow/ship.go:167-178
Session Management Architecture
The Session Manager handles the persistence of a session's state, goals, and tasks within the planning/ directory of a project. It utilizes several Markdown-backed files to maintain a human-readable and machine-parsable audit trail.
Key Persistence Files
| File | Purpose | Data Structure |
|---|---|---|
PROJECT.md | Stores high-level goal, project type, and framework info. | Key-value pairs and Q&A lists. |
TASKS.md | Tracks the execution status of the topological task list. | Markdown Table. |
STATE.md | Current workflow phase, progress, and last action. | Formatted properties. |
plan.md | The rich implementation plan generated by the LLM. | Versioned Markdown. |
MEMORY.md | Cross-session patterns, failures, and learnings. | Appended Narrative. |
Sources: internal/engine/session/planning.go:17-250, internal/engine/workflow/ship.go:197-210
Workflow State Synchronization
The following diagram illustrates how the Manager synchronizes the in-memory engine state with the filesystem during the transition between phases.
The Manager uses atomic writes to ensure that session files are never left in a corrupted state during crashes or interruptions.
Sources: internal/engine/session/planning.go:11-20, internal/engine/session/planning.go:146-160
The Learning Ledger & Memory System
The Learning Ledger records metrics for every completed session, while the MEMORY.md file provides the LLM with a context-aware history of previous successes and failures.
Cross-Session Learning
During the Ship phase, the engine appends a summary of the session to MEMORY.md. This includes:
- Goal and Success Rate: Tasks completed vs. total.
- Failure Analysis: Root causes for failed tasks and the number of "heals" attempted.
- Pattern Recognition: File extensions and patterns discovered (e.g.,
.go(12),.ts(5)). - Performance Metrics: Total session duration.
Sources: internal/engine/workflow/ship.go:197-230
Memory Rotation Logic
To prevent context window overflow, M31A implements a rotation mechanism for the memory store. When MEMORY.md exceeds 512KB, the system rotates the file to retain only the last 20 session blocks.
The Ship Phase: Finalizing the Ledger
The Ship phase is the final stage where the session is archived and the ledger is updated. It performs a "Ship Preflight" and generates a walkthrough for the user.
Shipping Workflow
- Checklist: Runs
runShipPreflightto ensure no blocking issues remain. - Git Finalization: Commits all files touched by the workflow using a configured prefix (e.g.,
chore). - Metrics Collection: Calculates duration and collects
diffstatistics (insertions/deletions). - Demonstration: Uses the LLM to generate a
DEMONSTRATION.mdwalkthrough. - Ledger Update: Appends the final entry to the global ledger.
Sources: internal/engine/workflow/ship.go:35-150, internal/engine/workflow/ship.go:290-320
Diff Statistics Logic
M31A uses git diff --numstat to accurately classify file changes for the ledger, distinguishing between additions, deletions, and modifications.
Conclusion
The Session & Learning Ledger system ensures that M31A is not just a stateless code generator but an autonomous agent capable of persistence and self-improvement. By maintaining a structured history of project goals, implementation plans, and execution metrics, the system provides both a reliable rollback chain for developers and a rich experience base for the underlying AI models.
Sources: README.md:120-130, internal/engine/workflow/ship.go:465-475