Overview

Relevant Source Files

• README.md
• bin/palee.ts
• package.json
• planning/palee_cli_spec.md
• src/index.ts

The Personal Active Learning & Evaluation Engine (PALEE) is a smart, AI-powered study tracker designed to optimize learning through a deterministic core of spaced repetition and dependency-aware recommendations. It integrates natively with Obsidian vaults, treating Markdown files as the canonical source of truth for both learning content and progress metadata.

PALEE bridges the gap between static notes and active learning by providing a structured engine that calculates what you should study next, while offering an optional AI layer for interactive tutoring and Feynman-style testing.

Core Philosophy

PALEE is built on three architectural pillars README.md#184-189:

1. Deterministic Core: Reliable scheduling using the SM-2 algorithm and strict dependency graph tracking.
2. AI Augmentation: Intelligent tutoring and assessment constrained to validated, read-only context tools.
3. Human Oversight: A "Human Confirm Gate" ensures that no consequential state changes (like updating mastery scores) occur without explicit user approval planning/palee_cli_spec.md#107-112

System Architecture

The system is organized into three distinct layers to ensure data integrity and separation of concerns planning/palee_cli_spec.md#23-64

1. Storage Layer (The Vault)

The Obsidian vault is the single source of truth. PALEE stores metadata in YAML frontmatter within individual topic notes and manages session history in a hidden .palee/ directory README.md#164-171

• Topic Notes: Contain palee_id, mastery scores, and SM-2 state README.md#136-158
• Session Memory: Includes hot.md (a 250-word working memory cap) and durable session logs README.md#164-173

2. Engine Core

A pure-function library responsible for the logic of learning. It handles:

• SM-2 Algorithm: Calculating review intervals and ease factors planning/palee_cli_spec.md#41
• Dependency Graph: Managing prerequisites and detecting cycles planning/palee_cli_spec.md#42
• Mastery Calculation: Deriving overall mastery from conceptual, practical, debug, and Feynman scores README.md#162

3. Interface Layer (CLI & Tools)

The command-line interface provides the primary way to interact with the engine. It includes commands for adoption, planning, reviewing, and session management bin/palee.ts#12-22

System Component Mapping

The following diagram illustrates how Natural Language concepts map to specific code entities and storage structures.

Entity Relationship Diagram: Logic to Code Mapping

Sources: src/types.ts#1-100README.md#136-173planning/palee_cli_spec.md#25-37

Navigation and Learning Paths

To explore the PALEE codebase and documentation, follow these paths:

Setup and Usage

• Getting Started: Learn how to install the @kuldeep2822k/palee package via NPM package.json#2-3 configure your vault path using palee config set-vaultREADME.md#24 and set up AI providers README.md#29

Technical Deep Dives

• Architecture Overview: A detailed look at the three-layer architecture, the file-safety contract (atomic writes and locking), and the "Obsidian-Native" storage strategy planning/palee_cli_spec.md#18-37
• CLI Commands: Comprehensive reference for commands like palee nextbin/palee.ts#48palee planbin/palee.ts#55 and palee sessionbin/palee.ts#101

Implementation Details

The system's behavior is governed by specific modules:

• Scheduling: Logic residing in the SM-2 engine.
• Validation: Vault integrity checks handled by the validate command bin/palee.ts#79
• Safety: Atomic write operations and optimistic concurrency control (OCC) planning/palee_cli_spec.md#32-34

Data Flow: Command to Storage

Sources: bin/palee.ts#69-75planning/palee_cli_spec.md#50-57README.md#190-197