Data and State Management
Relevant source files
The following files were used as context for generating this wiki page:- packages/coding-agent/src/session-manager.ts
- packages/coding-agent/src/settings-manager.ts
- packages/web-ui/src/storage/app-storage.ts
- packages/web-ui/src/storage/backends/indexeddb-storage-backend.ts
- packages/mom/src/agent.ts
- packages/coding-agent/src/main.ts
- packages/mom/README.md
- packages/web-ui/README.md
Data and state management in the pi-mono project is handled differently across its packages, tailored to the specific environment of each tool. The coding-agent and mom (Slack bot) packages utilize a file-system-based approach for persistence, storing session history, logs, and memory in local directories. This allows for direct inspection, manipulation, and version control of the agent's state.
In contrast, the web-ui package employs a browser-based storage architecture using a pluggable backend system. This system defaults to IndexedDB for robust client-side storage of sessions, settings, and API keys, ensuring data persistence within the user's browser without relying on a server. This documentation outlines the architecture and implementation of these distinct but related data management strategies.
coding-agent: File-Based Session & Settings
The coding-agent CLI tool manages its state through two primary mechanisms: a SessionManager for conversation history and a SettingsManager for user preferences. Both create files within a dedicated agent directory, typically ~/.config/pi/agent/.
Sources: packages/coding-agent/src/main.ts:50-51, packages/coding-agent/src/main.ts:401-402
SessionManager
The SessionManager is responsible for persisting the conversation state, including user messages, assistant responses, tool calls, and other significant events. It ensures that conversations can be continued across multiple invocations of the CLI tool.
Sources: packages/coding-agent/src/session-manager.ts
Session File (session.jsonl)
Each session is stored in a session.jsonl file within a unique, timestamped directory. The file uses a JSON Lines format, where each line is a distinct JSON object representing an event. This format is efficient for append-only operations.
Sources: packages/coding-agent/src/session-manager.ts:13-14, packages/coding-agent/src/session-manager.ts:111-113
The diagram below shows the flow of how a new session is created and how events are saved.
Session Event Types
The session.jsonl file logs several types of events to reconstruct the agent's state.
| Event Type | Description |
|---|---|
session | Contains metadata about the session, such as its ID, timestamp, and the initial system prompt. |
message | Logs a complete message object (user, assistant, tool result, or custom bashExecution). |
model_change | Records when the user switches the AI model. |
thinking_level_change | Records when the user changes the agent's thinking level. |
compaction | Logs an event when the conversation history is compacted, including a summary. |
Sources: packages/coding-agent/src/session-manager.ts:122-171
SettingsManager
The SettingsManager handles user-specific configurations that persist across all sessions. It uses a simple JSON file, settings.json, stored in the agent's root configuration directory.
Sources: packages/coding-agent/src/settings-manager.ts:13-21
Managed Settings
| Setting | Type | Description | Default |
|---|---|---|---|
theme | string | The name of the color theme for the TUI. | "dark" |
defaultProvider | string | The default AI provider to use. | undefined |
defaultModel | string | The default model ID to use. | undefined |
defaultThinkingLevel | ThinkingLevel | The default reasoning level for the agent. | "off" |
lastChangelogVersion | string | The last version for which the changelog was displayed. | undefined |
collapseChangelog | boolean | Whether to show a condensed changelog on startup. | false |
hideThinkingBlock | boolean | Whether to hide the "thinking" blocks in the UI. | false |
queueMode | QueueMode | The message queueing behavior ("none", "user", "all"). | "user" |
compaction | object | Settings for automatic context compaction. | { enabled: true, ... } |
Sources: packages/coding-agent/src/settings-manager.ts:32-118
mom: Workspace & Memory Files
The mom Slack bot uses a directory-based approach to manage its state, memory, and logs. This "data directory" serves as its persistent workspace.
Sources: packages/mom/README.md:120-136
The structure is organized by Slack channels, with shared global files at the root.
This diagram illustrates the hierarchical structure of the mom bot's data directory.
Sources: packages/mom/README.md:120-136
Working Memory (MEMORY.md)
A key feature of mom is its use of MEMORY.md files for persistent context. The agent is instructed to read these files to load context and update them to remember important information.
- Global Memory (
./data/MEMORY.md): Shared across all channels. Used for storing information about global skills, user preferences, and project-wide information. - Channel-Specific Memory (
./data/<channel_id>/MEMORY.md): Contains context relevant only to a specific channel, such as ongoing tasks or decisions made in that channel.
The getMemory function reads both the global and channel-specific memory files and combines them to form part of the system prompt.
Sources: packages/mom/src/agent.ts:197-230, packages/mom/README.md:138-146
Conversation History (log.jsonl)
Similar to coding-agent, mom logs all channel activity to a log.jsonl file. This includes user messages, bot responses, and the details of every tool call and its result. The getRecentMessages function reads this log, intelligently groups messages into "turns" (a user message or a sequence of bot messages), and formats the last 50 turns to be included in the prompt context. This turn-based retrieval prevents a long series of tool calls from pushing important conversation history out of the context window.
Sources: packages/mom/src/agent.ts:68-141, packages/mom/README.md:175-186
web-ui: Browser-Based Storage
The web-ui package implements a flexible storage system designed for the browser environment, abstracting away the underlying storage mechanism (e.g., localStorage, IndexedDB).
Sources: packages/web-ui/README.md:111-118
AppStorage and Backends
The core of this system is the AppStorage class, which is configured with various storage backends for different types of data. The SessionIndexedDBBackend is a specialized backend for storing session data.
The following class diagram shows the relationship between AppStorage and its backends.
SessionIndexedDBBackend
This backend uses IndexedDB to store session data, which is ideal for the potentially large size of conversation histories. It creates an IndexedDB database named pi-web-ui-sessions with an object store called sessions. Each session is stored as an object with an id, timestamp, title, screenshot, and the full state.
Sources: packages/web-ui/src/storage/backends/indexeddb-storage-backend.ts:22-39
The sequence diagram below illustrates how a session is saved using this backend.
Conclusion
The pi-mono project employs a pragmatic and context-aware approach to data and state management. For CLI and bot applications (coding-agent, mom), it leverages the local file system, providing transparency and easy access to session logs and configuration files in human-readable formats like JSONL and Markdown. For the web-ui, it uses a robust, browser-native solution with IndexedDB, abstracted through a clean interface to ensure data persistence and security on the client side. This separation of concerns allows each package to use the most appropriate storage strategy for its target environment.