Session Management
Relevant source files
The following files were used as context for generating this wiki page:
Session Management is a core system within Autohand CLI designed to persist conversation history, workspace states, and project-specific knowledge across multiple interactions. By storing data in a structured directory format, the system enables users to resume previous work seamlessly, maintaining context that would otherwise be lost between CLI invocations.
The system is composed of two primary sub-systems: the Session Persistence System, which handles the immediate history of a conversation, and the Historical Retrieval System, which synthesizes long-term project knowledge from successful and failed attempts.
Sources: prd/session-persistence.md:10-18, prd/historical-retrieval.md:11-18, src/core/agent.ts:182-184
Architecture and Lifecycle
The session lifecycle is managed by the SessionManager, which coordinates the creation, loading, and persistence of session data. Every interaction is automatically saved to the user's home directory to prevent data loss.
Session Lifecycle Flow
The following diagram illustrates the interaction between the User, CLI, and the Session Management components during a typical work session.
The lifecycle ensures that even in the event of a crash, the JSONL format allows for recovery of the conversation up to the last successful message.
Sources: prd/session-persistence.md:58-76, src/session/SessionManager.ts:24-51, src/core/agent.ts:1335-1358
Data Structures and Storage
Session data is stored in ~/.autohand-cli/sessions/. This directory contains an index for fast lookups and individual folders for each session.
Storage Hierarchy
~/.autohand-cli/
├── sessions/
│ ├── index.json # Fast lookup for all sessions
│ └── <session-id>/ # Unique session directory
│ ├── metadata.json # Configuration and status
│ ├── conversation.jsonl # Append-only message log
│ └── state.json # Workspace files and git status
Sources: prd/session-persistence.md:81-93, src/session/SessionManager.ts:16-22
Metadata and Message Schemas
The system uses specific interfaces to define the structure of sessions and messages.
| Field | Type | Description |
|---|---|---|
sessionId | string | Unique identifier (e.g., UUID-timestamp). |
status | active | completed | crashed | The current state of the session. |
model | string | The LLM model used during the session. |
projectPath | string | Absolute path to the workspace root. |
messageCount | number | Total number of messages in the conversation. |
Sources: src/session/types.ts:10-26, src/session/SessionManager.ts:31-40
| Message Field | Type | Description |
|---|---|---|
role | user | assistant | tool | system | The sender of the message. |
content | string | The actual text or tool output. |
tool_call_id | string | Links a tool response to an assistant request. |
timestamp | string | ISO 8601 timestamp of the message. |
Sources: src/session/types.ts:30-38, src/session/SessionManager.ts:148-154
Project Knowledge Synthesis
The ProjectManager extends session management by analyzing session outcomes to build a long-term "Project Knowledge" base. It tracks anti-patterns (repeated failures) and best practices (successful patterns) to optimize future interactions within the same repository.
Knowledge Extraction Flow
The synthesis process calculates confidence scores for patterns based on frequency of occurrence.
Sources: src/session/ProjectManager.ts:60-76, prd/historical-retrieval.md:76-88, src/session/types.ts:90-107
Knowledge Components
The ProjectKnowledge structure tracks the following:
- Anti-Patterns: Failed commands or approaches (e.g., trying to install a non-existent package).
- Best Practices: Commands that successfully passed tests or builds.
- Tech Stack: Detected languages, frameworks, and tools (e.g., TypeScript, React, Bun).
Sources: src/session/ProjectManager.ts:153-207, src/session/types.ts:90-107
CLI Integration and Commands
The session system is exposed through several CLI commands and internal agent transitions.
Resuming Sessions
The autohand resume <session-id> command allows a user to reload the full conversation history. The AutohandAgent restores the conversation history and injects project knowledge before starting the interactive loop.
Sources: src/core/agent.ts:402-452, prd/session-persistence.md:158-175
Core Session Commands
| Command | Action | Implementation |
|---|---|---|
autohand sessions | Lists past sessions | SessionManager.listSessions() |
autohand resume <id> | Loads a specific session | SessionManager.loadSession() |
/new | Closes current and starts fresh | Agent.resetConversationContext() |
Sources: prd/session-persistence.md:155-195, src/core/agent.ts:1335-1358, src/session/SessionManager.ts:64-90
Implementation Details
Session Manager Initialization
async initialize(): Promise<void> {
await fs.ensureDir(this.sessionsDir);
await this.loadIndex();
}
Sources: src/session/SessionManager.ts:24-27
Message Persistence (JSONL)
Messages are appended to a .jsonl file to ensure that even if the process is interrupted, the existing log remains valid.
async append(message: SessionMessage): Promise<void> {
this.messages.push(message);
const conversationPath = path.join(this.sessionDir, 'conversation.jsonl');
await fs.appendFile(conversationPath, JSON.stringify(message) + '\n');
await this.save();
}
Sources: src/session/SessionManager.ts:148-157
Conclusion
Session Management provides Autohand CLI with stateful capabilities that bridge the gap between individual tool executions and complex, multi-day development tasks. By combining immediate conversation persistence with long-term project knowledge synthesis, the system ensures that the agent becomes more efficient over time, avoiding documented failures and leveraging known successful patterns within a specific workspace.