Session Memory Storage

Relevant Source Files

• planning/memory_design.md
• src/cli/session.ts
• src/storage/cache.ts
• src/storage/memory.ts
• test/session-cli.test.ts
• test/storage-memory.test.ts

The Session Memory Storage system manages the persistence of learning sessions, working memory, and draft recovery within the .palee/ directory of an Obsidian vault. It ensures learning continuity by providing the AI with a concise "hot" context while maintaining a durable, human-readable history of all sessions.

Storage Layout and Schema

All session-related data is stored in a hidden .palee/ directory at the vault root. This directory contains canonical session records and derived views.

File/Directory	Role	Description
hot.md	Working Memory	A derived view containing the most recent context, capped at 250 words.
sessions/	Canonical History	Directory containing durable Markdown notes for every completed session.
index.md	Session Index	A derived list of all sessions for human browsing and internal navigation.

ID Generation

The system uses unique, immutable identifiers for sessions and drafts to prevent collisions and ensure stable references.

• **Session ID (S-*)**: Generated using generateSessionIdwith the formatS-YYYYMMDDTHHMMSS-xxxx(wherexxxx` is a 2-byte hex random suffix) src/storage/memory.ts
• **Draft ID (DRAFT-S-*)**: Generated using generateDraftIdwith the formatDRAFT-S-xxxxxxxx(wherexxxxxxxx` is a 4-byte hex random suffix) src/storage/memory.ts

Hot Memory Contract & Duration Tracking

hot.md acts as a singleton (H-active) that summarizes the current state of learning planning/memory_design.md:

• Word Cap: The human-readable body is strictly capped at 250 words via truncateWords to keep AI prompts efficient src/storage/memory.ts.
• Frontmatter: Includes palee_schema: 1, memory_id: "H-active", active_topic, started_at (ISO timestamp of active study initiation), last_session, and updated_at (date only: YYYY-MM-DD) src/storage/memory.ts.
• Safe Reset (resetHotMemory): Safely unlinks hot.md during reinitialization or corrupt state recovery src/storage/memory.ts.

Sources: src/storage/memory.tsplanning/memory_design.md

---

Data Flow: Session Lifecycle

The following diagram maps the CLI actions to the underlying storage implementation functions.

Session State Transitions

Sources: src/cli/session.tssrc/storage/memory.ts

---

Implementation Details

Derived View Regeneration

rebuildHotAndIndex is the primary maintenance function. It scans the sessions/ directory, identifies the most recent completed session, and triggers a refresh of both hot.md and index.md src/storage/memory.ts:

1. Scanning: Reads all S-*.md files in .palee/sessions/.
2. Validation: Skips zero-byte files and safely parses frontmatter to ensure session integrity.
3. Sorting: Sessions are sorted newest-first based on started_at.
4. Indexing: regenerateIndex creates a Markdown list with Obsidian-style links (e.g., [[S-20260808T180000-a1b2c3d4]] - Topic: T-01 (2026-08-08)).

Draft Checkpoints & Storage Boundary Functions

During a session, the system captures progress using writeDraftCheckpoint src/storage/memory.ts. The storage layer provides dedicated helpers:

• getTopicDrafts(vaultPath, topicId): Returns array of matching active drafts with their paths, started_at timestamps, and body text.
• deleteTopicDrafts(vaultPath, topicId): Discovers and deletes all drafts matching a given topic.
• deleteSessionNote(vaultPath, targetPath): Safely deletes a session or draft note with strict directory boundary validation preventing unlinks outside .palee/sessions/.

The recoverDraft function handles four distinct actions src/storage/memory.ts:

Action	Logic
resume	Retains the draft checkpoint note for continued study.
save	Converts the draft into a completed session note via writeSessionNote, computes elapsed duration_minutes, deletes the draft via deleteSessionNote, and refreshes views via rebuildHotAndIndex.
discard	Permanently and safely deletes the draft file via deleteSessionNote.
ignore	Leaves the draft file in place without taking action.

Sources: src/storage/memory.ts · src/cli/session.ts

---

Topic Resolution Logic

When starting or ending a session, the system must determine the active_topic. The resolveSessionTopic function follows a specific precedence src/cli/session.ts#91-150:

1. Explicit Flag: If --topic <id> is provided, it is used immediately src/cli/session.ts#96-121
2. Hot Memory: If no flag is provided, the system parses .palee/hot.md and looks for the active_topic key in the frontmatter src/cli/session.ts#123-126
3. None: If the value is (none) or missing, nothing resolves — start, draft, and end each refuse with exit code 2 instead of proceeding, and a refused start creates no new active session and prints no success banner (#546) src/cli/session.ts#123-129

Natural Language to Code Mapping

Sources: src/cli/session.tssrc/storage/memory.ts