session package

Reviewed against commit 8a2cb42ad on 2026-10-23.

Reference: generated package page orchestrata_ultimate.session (63 modules, 14,958 lines of code); key modules controller, context, graph_store, kg_sync, cli. Sessions, the session CLI and the gateway's session.* methods are explained as part of the whole in the orchestrata overview; the graph it syncs into is described on knowledge_graph, and the plan parser behind goals on planning.

The story

Orchestrata's work does not happen in one sitting. Development unfolds across many discrete sessions — a human or an agent begins work, logs what was done, records decisions and file artifacts, and hands off to whoever picks the project up next. orchestrata_ultimate.session (spec 006, SPEC-023 for goals) exists to make that continuity durable and auditable. It is a fresh implementation of session management built around a dual-storage architecture: Redis holds hot, low-latency session state (RedisSessionStore), the operational graph (orchkg on orchgraph, a Memgraph fork) holds the cold, permanent archive (GraphSessionStore in graph_store.py; it was Neo4jSessionStore until Neo4j was retired on 2026-07-27), and SessionSync flushes the former into the latter. Alongside the databases sits the humble, human-readable layer everyone actually interacts with: a context.md/context.json pair in the project root, owned by ContextFileManager and rendered through Jinja2 templates.

The central actor is SessionController, composed in controller/_core.py from four responsibility mixins — GoalMixin (SPEC-023 goal-driven sessions with exit criteria), GitOpsMixin (commit/push/tag), ChangelogMixin (CHANGELOG.md categorization and splicing), and TestStateMixin (pytest collection and run state). It holds three things: the project root, the resolved ai_model name, and a ContextFileManager (ctx) — with the currently open session guarded behind a threading.Lock. A typical flow starts when a session begins — via the Click CLI (cli/lifecycle.py), an MCP tool call (mcp_tools.py), or automatically through the session_auto_start_hook. As work proceeds, log_work, log_artifact, and log_choice accumulate as Pydantic models (SessionRecord, WorkItem, LogEntry, FileArtifact, TechChoice in models.py) inside ContextData. In parallel, FactEmitter turns session activity into Fact objects, writes them hot in Redis and optionally cold in the graph, and keeps the Prolog engine synchronized as the logical source of truth through PrologSessionInterface and PrologFactBridge. When the session closes, validate_and_end runs checklist validation (raising ChecklistError/SessionStartError on failure) to enforce that tests pass and git is clean, and HandoverManager, WorkCarryoverManager, and SessionArchiver prepare the next session's starting point.

Durability is a first-class concern, because context.json is written by several independent OS processes (the session_cli.py invocations the agent makes, the SessionStart hook, and the in-process SessionEnd hook). ContextFileManager therefore writes atomically (temp file → fsync → os.replace), guards every read-modify-write with a cross-process fcntl.flock on a sidecar .context.lock, and self-heals corrupt reads by salvaging the valid JSON prefix or restoring a .bak — the defense against the recurring "Extra data" corruption. verify_history_integrity and recover_from_git provide a further safety net, reconstructing lost sessions from git tags and history when needed.

Beyond a single session, the package tells the knowledge graph the whole project's story. KnowledgeGraphSyncer (kg_sync/) runs a staged pipeline into orchkg. sync_all runs seven stages (project, directory tree, AST-extracted classes/functions, specs, traces, docs/statistics, file traceability), and nine when it is given a session number (session and session files are added); its docstring still says 8. Meanwhile kg_context.py is the read side, pulling relevant graph nodes back out for context injection. PortfolioController lifts the same model to multi-project coordination. The package collaborates widely with its neighbors: it builds on core (graph/Redis client factories, traceability decorators, the tracing scanner), drives orchestrator's PipelineRunner from the cli/pipeline.py commands (run/resume/approve/reject agent pipelines), wraps the controller in EventEmittingSessionController so lifecycle events reach the kernel's event bus, and exposes the MCP tools of an external integration (fireflies_tools.py). Three Claude Code hooks (hooks/) close the loop with the editing workflow itself: auto-starting sessions, extracting facts from tool calls, and gating session close.

Key responsibilities

• Session lifecycle — begin / log / end / resume a session and validate a close checklist (SessionController + its Goal/GitOps/Changelog/TestState mixins).
• Human-readable context files — durable, atomic, cross-process-locked, self-healing context.md / context.json management with git-based recovery (ContextFileManager).
• Dual storage — hot session state and facts in Redis (RedisSessionStore), cold permanent archive in the orchkg graph (GraphSessionStore), reconciled by SessionSync.
• Fact stream — capture decisions, artifacts, state changes and metrics as typed Facts and fan them out to Redis, the graph and Prolog (FactEmitter, PrologSessionInterface, PrologFactBridge).
• Continuity — build/merge handoffs (HandoverManager), carry deferred work forward (WorkCarryoverManager), archive old sessions (SessionArchiver), and checkpoint/rollback (RecoveryManager).
• Goals (SPEC-023) — persistent goals with measurable exit criteria, tasks and progress (Goal, GoalMixin, cli/goals.py).
• Knowledge-graph sync — 7-stage (9 with a session) project → orchkg pipeline (KnowledgeGraphSyncer) plus the read-side context provider (kg_context.py).
• Multi-project portfolio — coordinate sessions and work across projects (PortfolioController).
• Entrypoints & integrations — Click CLI (cli/), MCP tools (mcp_tools.py), event-emitting wrapper, and Fireflies meeting intelligence (fireflies_tools.py).

Class diagram

Controller and context files

SessionController is the façade: it composes four responsibility mixins and owns a single ContextFileManager for all file I/O.

Facts and dual storage

FactEmitter fans every fact out to three backends; SessionSync reconciles the hot Redis store into the cold graph archive (GraphSessionStore).

Domain models

The persisted shape of a session. ContextData is the root object serialized to context.json; a SessionRecord nests the log, artifacts, choices and handoff for one session.

Continuity, recovery, portfolio and KG sync

The helpers that carry state across sessions and out to the knowledge graph. The three file-based managers each own a ContextFileManager; RecoveryManager checkpoints through Redis; KnowledgeGraphSyncer runs the 8-stage sync into orchkg.

Notes

• Entrypoints. The Click CLI lives under cli/ (lifecycle.py, goals.py, pipeline.py, archive.py, achievements.py, kg.py, tasks.py, and overview.py — the one-shot startup digest session overview, added after the first version of this page — dispatched by cli/main.py; python -m orchestrata_ultimate.session.cli also works). MCP integration is in mcp_tools.py. The pipeline CLI drives orchestrator.PipelineRunner for agent run/resume/approve/reject.
• Interfaces. interfaces.py declares the Protocol surface (ISessionManager, IFactEmitter, IRecoveryManager, ICarryoverManager, IPortfolioManager, SessionHook); types.py holds the Fact, Checkpoint, FactFilter, SessionState and FactType value types.
• Hooks. hooks/ holds the three Claude Code hooks — session_auto_start_hook, session_fact_hook, and the pre-close gate — registered through hook_registry.py.
• Module inventory (8a2cb42ad). 63 modules, 14,958 lines of code: the top-level modules named above plus archive, audio_alarm, carryover, checkpoint, constants, context, exceptions, facts, governance, handover, hook_registry, portfolio, prolog_facts, prolog_interface, recovery, redis_store, graph_store, spec_parser, sync, session and kg_context; the subpackages controller/ (six modules: _core plus the four mixins), cli/ (12 modules), kg_sync/ (9 modules, 1,972 lines: stages 0 to 7 split over _stage_session, _stage_folders, _stage_code, _stage_specs_traces and _stage_docs, on _base, _common and _ast_helpers), hooks/ (the three hooks) and examples/.
• Traceability. Classes are decorated with @traces(spec="006", ...) (and spec 007/023 where relevant); the RTM links these to the requirement IDs.

Class attributes and method signatures above were extracted from the live source via the AST toolkit; all four mermaid blocks are render-verified.

Class map (generated)

Generated from the live source AST by scripts/gen-module-class-diagrams.py — do not hand-edit. Abstract classes have a green border; members listed are those defined on the class itself (inherited members excluded). Solid empty-triangle arrows = in-package inheritance; dashed arrows into dashed boxes = external/stdlib/cross-package bases; filled diamond = composition (constructed in __init__); open diamond = aggregation (annotated/injected reference); diamond edge labels name the owning attribute.