Session Management

How pi-tree manages reading sessions — the bridge between users, sources, and AI agent conversations.

Core Concept

Each user can have multiple independent sessions per source. A session is a complete conversation tree backed by a Pi SDK JSONL file. Different sessions can represent different approaches to the same source — guided reading, Q&A, deep dives, and more.

User ──┬── Book A ──┬── Session 1 (Interactive Reading)
       │            ├── Session 2 (Freeform Q&A)
       │            └── Session 3 (Chapter 5 Deep Dive)
       │
       └── Book B ──┬── Session 1 (Interactive Reading)
                    └── Session 2 (Study Group Notes)

Architecture

The session system spans the client, server, and core packages. For a high-level view of the full stack, see the Architecture Overview.

Data Model

Database: `user_sessions`

Column	Type	Description
`id`	INTEGER PK	Session identifier (auto-increment)
`user_id`	TEXT FK	References `users.id`
`source_id`	TEXT	Source identifier
`title`	TEXT	Human-readable session name
`context`	TEXT (JSON)	`SessionContext` blob — session configuration
`session_file`	TEXT	Absolute path to Pi SDK JSONL file
`is_active`	INTEGER	1 = active, 0 = soft-deleted
`created_at`	TEXT	ISO 8601 timestamp
`last_active_at`	TEXT	Updated on each message

SessionContext

typescript

interface SessionContext {
  mode: 'reading' | 'analysis' | 'news' | 'custom';
  systemPrompt?: string;   // Optional prompt override
  skills?: string[];        // Optional skill filter
  model?: string;           // Optional model override
}

The context column captures the intent of the session at creation time. This enables per-session behavior configuration.

Session Profiles

Session behavior is driven by session profiles — declarative mappings of (sourceType, mode) → skills, extensions, model. The server resolves profiles via resolveProfile(sourceType, mode, sessionContext) in the agent registry. SessionContext.skills and SessionContext.model stored in the DB override the profile defaults. See Context Binding for details.

Session Lifecycle

The lifecycle has four key steps:

Create — POST /api/sessions/:userId/:sourceId creates a DB row with a title and context. No JSONL file exists yet.
First load — TreeManager.loadOrCreate(userId, sourceId, sessionId) triggers the Pi SDK to create the JSONL file. The path is stored back in session_file.
Resume — Subsequent loads find the session_file from the database and pass it to SessionManager.open().
Delete — Soft-delete sets is_active = 0. JSONL files are preserved for potential recovery.

In-Memory Session Cache

SessionStore keeps active TreeManager instances in memory to avoid re-creating Pi SDK sessions on every HTTP request.

Key: "userId:sourceId:sessionId" → TreeManager instance

Only one TreeManager exists per unique session. When a session is closed or deleted, it's evicted from the cache.

Context Binding

A session's AI behavior is shaped by session profiles — declarative mappings resolved at session creation time. The server resolves the profile via resolveProfile(sourceType, mode, sessionContext) in the agent registry.

Layer	What	How It Works
Skills	SKILL.md instruction bundles	Profile selects skills per `(sourceType, mode)`. `SessionContext.skills` overrides the profile.
Extensions	Tool bundles (TypeScript, runtime-loaded)	Profile selects extensions (e.g., `[news]` for news mode, `[library]` for router).
System prompt	Deferred context injected on first message	Override via `context.systemPrompt`.
Model	LLM provider + model ID	Profile may set a default model. `SessionContext.model` overrides it.

Profile Resolution

Resolution order: ${sourceType}.${mode} → ${sourceType} → _default.

Built-in profile examples:

Profile Key	Skills	Extensions
`book.reading`	`[interactive-reading]`	—
`book.analysis`	`[book-analysis, book-outline]`	—
`news.news`	`[news-reading]`	`[news]`
`paper.reading`	`[paper-reading]`	—
`youtube.watching`	`[youtube-watching]`	—
`router`	`[session-router]`	`[library]`

Custom profiles can be added at $DATA_PATH/profiles/*.yml with an optional source_type field to scope them to specific source types.

How It Works

Each session gets its configuration from the resolved profile, with SessionContext overrides applied:

PiSession.create(config, resolvedProfile)   // @pi-tree/core
  ├── configureModelRegistry()
  │
  ├── Skills and extensions resolved by profile:
  │   ├── Plugin: packages/plugin-*/skills/      (plugin-bundled)
  │   ├── Plugin: packages/plugin-*/             (plugin tools)
  │   ├── Server: packages/server/agents/skills/ (core routing)
  │   ├── User: DATA_PATH/skills/                (overrides on name collision)
  │   └── User: DATA_PATH/extensions/            (custom Pi extensions)
  │
  ├── createAgentSession() with:
  │   ├── model: context.model ?? profile.model ?? config.readingModel
  │   ├── tools: profile.extensions + excludeTools filtering
  │   └── resourceLoader: profile.skills (filtered)
  │
  └── pendingContext = context.systemPrompt ?? defaultSourceContext

API Reference