Future: AI Module and Phase 2 Design

Relevant Source Files

• agent.md
• planning/palee_cli_spec.md
• planning/PHASE_2_GAPS.md
• planning/ai_module_design.md
• planning/roadmap_design.md

This page outlines the planned evolution of PALEE (Personal Active Learning & Evaluation Engine) beyond its core deterministic features. It details the AI tutoring architecture, the transition to guided learning flows, and the resolution of architectural gaps identified during Phase 1.

AI Module Architecture

The AI module is designed as an intelligent layer above the Engine Core. It utilizes Large Language Models (LLMs) to facilitate Feynman-style testing and interactive tutoring while maintaining strict separation between AI-generated proposals and the deterministic vault state planning/ai_module_design.md

Interaction Flow

The system employs a tool-calling loop where the LLM can request context but cannot directly mutate the vault. All changes proposed by the AI must pass through a validation and user-confirmation gate planning/ai_module_design.md

AI Interaction Diagram

Sources:planning/ai_module_design.mdplanning/ai_module_design.md

---

AI Configuration and Session Continuity

Provider Configuration

AI capabilities require a configured provider. Credentials and endpoints are stored in platform-specific configuration directories planning/ai_module_design.md:

• Unix/macOS: ~/.config/palee/ai_provider.json
• Windows: %LOCALAPPDATA%\palee\ai_provider.json

The configuration includes base_url, api_key, and modelplanning/ai_module_design.md

Session Memory (hot.md)

To maintain continuity without exceeding LLM context limits, PALEE uses hot.md as a working memory buffer.

• Initial Context: The AI receives hot.md (active topic, last session ID, unresolved confusion) planning/ai_module_design.md
• History Retrieval: Full session records from .palee/sessions/S-*.md are only fetched via the get_session tool when explicitly required planning/ai_module_design.md
• Context Bounding: Dialogue turns exceeding a count of four are summarized to prevent unbounded token growth planning/ai_module_design.md

Sources:planning/ai_module_design.mdsrc/storage/memory.ts

---

Feynman-Style Testing (palee test)

The palee test <topic> command (Phase 2) implements the Feynman technique:

1. Context Loading: The engine reads the target topic note as the primary study material planning/PHASE_2_GAPS.md
2. Interactive Dialogue: The AI asks conceptual questions; the user explains in their own words planning/PHASE_2_GAPS.md
3. Multi-Dimensional Grading: The AI produces an assessment_proposal object containing scores for conceptual, practical, debug, and feynman pillars planning/ai_module_design.md
4. Persistence: Scores are written to the topic's frontmatter (assessment), updating topic_mastery. Spaced-repetition recall scheduling (due_at) remains independently driven by user review records planning/palee_cli_spec.md

Sources:planning/PHASE_2_GAPS.mdplanning/ai_module_design.md

---

Guided Roadmap Generation

While Phase 1 supports deterministic YAML/Markdown roadmap imports, Phase 2 introduces a guided interview mode via palee roadmapplanning/roadmap_design.md

The Interview Flow

If no --from source is provided, the CLI initiates a 6-question interview covering planning/roadmap_design.md:

• Learning goals and current level.
• Availability (hours/week) and target dates.
• Preferred practice styles and technology constraints.

Proposal Validation

The AI-generated roadmap must adhere to the roadmap_proposal schema, including roadmap_id, a unique topic_id list, and estimated effort planning/roadmap_design.md The engine validates this for cycles and dangling dependencies before the user is asked to confirm the import planning/roadmap_design.md

Roadmap Data Flow

Sources:planning/roadmap_design.mdsrc/engine/dependency.ts

---

Phase 2 Gaps and Refinements

Based on PHASE_2_GAPS.md, the remaining CLI and AI enhancements are scheduled as follows:

Feature	Status	Description	Target Component
Markdown Roadmaps	Completed	Support roadmap definitions inside .md files using frontmatter or YAML fences src/storage/roadmap-parser.ts	roadmap.ts
Batch Adopt	Completed	palee adopt --all (plus --include, --exclude, --tag) to scan and adopt untracked notes src/cli/adopt.ts	adopt.ts
Auto-ID Generation	Planned	Generate T- prefixed IDs from filenames (e.g., Docker.md -> T-docker) planning/PHASE_2_GAPS.md	src/types.ts
Topic Resolution	Planned	Advanced matching: exact ID → title → slug → token distance planning/invariants.md	src/engine/index.ts
Transactional Fixes	Partially delivered	Three repairs ship: derived-view rebuild, mastery recompute, and review-field reset. Broader fix classes (broken dependencies, missing fields) remain planned via fixable metadata; see ADR-0035.	validate.ts

Sources:planning/PHASE_2_GAPS.mddocs/adr/0008-validation-framework-decisions.md