PALEE CLI

Personal Active Learning & Evaluation Engine
A deterministic, Spaced-Repetition (SM-2) & Directed Acyclic Graph (DAG) study engine for Obsidian vaults.

Documentation

Complete interactive documentation with architecture guides, interactive Mermaid diagrams, and CLI command references is available at https://kuldeep2822k.github.io/cli/.

Overview

PALEE helps you learn efficiently by:

• Recommending what to study next based on dependencies and SM-2 scheduling
• Tracking mastery across conceptual, practical, debug, and teaching dimensions
• Scheduling reviews using scientifically-proven spaced repetition
• Integrating natively with Obsidian notes
• Providing AI-powered Feynman testing
• Remembering learning context between sessions through durable session logs and a compact hot-memory file

Quick Start

Installation

npm install -g @kuldeep2822k/palee

Connect to Your Obsidian Vault

palee config set-vault ~/Documents/Obsidian/Learning

Configure Free AI (Optional)

palee config set-provider opencode
palee config set-base-url https://opencode.ai/zen/v1
printf '%s' "$OPENCODE_API_KEY" | palee config set-api-key
palee config set-model nemotron-3-ultra-free
palee config test-connection

set-api-key takes the key on stdin, via --from-env <VAR>, or as an interactive prompt — never as an argument, because argv is readable by every other process. palee config show never prints it; the key is stored in the config file, written 0600 on POSIX. On Windows that mode is ignored, so set-api-key instead refuses to store the key when the config directory is outside your user profile (see Windows Notes). PALEE_API_KEY in the environment outranks the stored key, for anyone who would rather never write it to disk.

test-connection sends one short prompt and reports the URL it called, which key source won, how long the reply took and how many tokens it cost. It is the only command that reaches the network, and nothing in palee next, plan, review, validate, adopt, roadmap --from or migrate can do the same — test/ai-network-boundary.test.ts fails if a second socket site appears. It refuses plain HTTP to any host that is not loopback, refuses endpoints in reserved address space (link-local and the cloud metadata address, the unspecified and multicast ranges, IPv4-mapped literals, and .internal names), refuses redirects rather than re-sending the credential to a host nobody approved, reads no more than 256 KiB of a response before giving up on it, and exits 2 on a bad endpoint, 3 on a reply that broke the output contract, 5 when the provider could not be reached.

Start Learning

# See what to study next
palee next

# Build a study session
palee plan

# Track your progress
palee progress

Key Features

Smart Recommendations

• Dependency-aware: Never study topics before prerequisites
• Spaced repetition: Reviews scheduled using SM-2 algorithm
• Unlock-based scoring: Topics scored by how many they unlock

Obsidian Integration

• Native vault support: Works directly with your existing notes
• Frontmatter metadata: Study data stored in note frontmatter
• Zero duplication: Vault IS the data store

AI-Powered Testing (Phase 2 — not yet available)

• Feynman method: AI tests your ability to explain concepts
• Multi-dimensional grading: Conceptual, practical, debug, teaching scores
• Tool-constrained: AI receives read-only validated context tools; PALEE owns confirmed writes

Neither palee test nor palee tutor is implemented yet, so the commands below do not run. The four-pillar scores they would write are already stored and read by palee assess and palee review today.

Progress Tracking

• Mastery visualization: Track mastery across all topics
• Review scheduling: Never miss a review
• Track analytics: See your learning patterns

Session Continuity

• Durable session logs: Every confirmed session is saved as a searchable Obsidian note
• Hot memory: The next session starts with a concise summary of the current learning position
• Stable references: Topics, sessions, and durable decisions use immutable IDs

Example Workflow

# 1. Adopt your existing notes
palee adopt "Docker Fundamentals.md"

# 2. See what to learn next
palee next
# → Learn: Pod Lifecycle in Kubernetes

# 3. Record a review after studying it
palee review T-pod-lifecycle-k8s --quality 4
# → SM-2 reschedules the next review date

# 4. Track progress
palee progress
# → 23.45% overall mastery

Commands

Command	Description
palee next	Show next recommended action
palee plan	Build study session plan
palee progress	View mastery statistics
palee review <topic> --quality N	Record review result (0-5)
palee session start	Resume learning from hot memory; starts AI tutor if provider is configured
palee session end	Save a confirmed session summary and refresh hot memory
palee migrate	Upgrade versioned PALEE data safely
palee adopt <note>	Adopt Obsidian note into PALEE
palee roadmap --from <file>	Validate and import a user-provided roadmap (no AI, no network)
palee dashboard	Show system status
palee validate	Check data integrity
palee config set-vault <path>	Set the Obsidian vault path
palee config set-provider <name>	Name the AI provider
palee config set-base-url <url>	Set the OpenAI-compatible endpoint (http / https only)
palee config set-api-key	Store the provider key from stdin, --from-env <VAR>, or a prompt
palee config unset-api-key	Remove the stored key
palee config set-model <model>	Set the model identifier
palee config test-connection	Send one short prompt to verify the provider (the only command that reaches the network)
palee config show	Display current config — vault path, provider, endpoint, model; the key prints as ••••••••

Phase 2 will add palee test and palee tutor, and a palee roadmap interview mode. None of the three is implemented: palee test and palee tutor are not registered commands, and palee roadmap without --from exits 2 rather than starting an interview.

Configuration

Provider Setup

palee config set-provider opencode
palee config set-base-url https://opencode.ai/zen/v1
palee config set-api-key --from-env OPENCODE_API_KEY
# Supports any OpenAI-compatible endpoint
# Recommended free option: OpenCode Zen

The key is kept in the config file, stored as plaintext at rest under a 0600 mode on POSIX, and no command prints it. On Windows the file mode does not apply, so the key's privacy rests on the config directory's ACL; see Windows Notes for how set-api-key guards that. palee roadmap and every offline command work without any of this.

Vault Connection

palee config set-vault /path/to/obsidian/vault
# PALEE will scan for notes with frontmatter

Data Model

Each topic note stores flat YAML frontmatter directly inside your Obsidian vault:

---
palee_schema: 1
palee_id: T-docker-volumes
title: Docker Volumes
difficulty: beginner
depends_on:
  - T-docker-basics
topic_mastery: 0.725
conceptual: 0.85
practical: 0.70
debug: 0.60
feynman: 0.75
assessed_at: 2026-01-15
ease_factor: 2.36
interval_days: 6
repetition: 1
lapses: 0
last_quality: 4
last_reviewed_at: 2026-01-15
due_at: 2026-01-21
---

Frontmatter stores flat keys directly for clean Obsidian parsing and fast atomic updates. Programmatic TypeScript interfaces (Topic) map these fields into structured conceptual and review metrics.

topic_mastery is derived from assessment scores ((conceptual + practical + debug + 2*feynman) / 5), independent from SM-2 recall scheduling. Newly adopted notes begin with topic_mastery: 0.0 and null review fields.

Session memory is stored inside the connected vault:

.palee/
├── hot.md
├── sessions/
└── index.md

hot.md is capped at 250 words and points to the latest full session. Full session notes preserve the learning history without forcing every future AI prompt to load the entire log.

See memory_design.md for the session-memory format, lifecycle, stable IDs, and recovery rules.

See storage_design.md for frontmatter preservation, atomic writes, vault traversal, validation, and cache behavior.

See invariants.md for the acceptance-test blueprint that must pass before Phase 1 is considered complete.

See roadmap_design.md for the imported-roadmap and guided personalized-roadmap contracts.

Philosophy

PALEE is built on three principles:

1. Deterministic core: Reliable SM-2 scheduling and dependency tracking
2. AI augmentation: Intelligent tutoring constrained to validated actions
3. Human oversight: You confirm all consequential actions

Exit Codes

PALEE uses standard exit codes to facilitate scripting:

• 0: Success
• 1: Partial failure (e.g., batch roadmap import where some topics failed)
• 2: Usage error (e.g., missing argument, unconfigured vault)
• 3: Validation error (e.g., malformed roadmap, invalid dependency)
• 4: Optimistic concurrency conflict (file was modified by another process)
• 5: Unexpected error (e.g., Node.js exception)

Windows Notes

• Path Normalization: PALEE natively handles both forward slashes (/) and backslashes (\) for vault configuration and file references.
• Lock Timeouts: On Windows, file locks become stale after 60 seconds (vs 120s on Unix) to accommodate aggressive process termination without finally blocks executing.
• Config Storage: The config file on Windows is stored in %LOCALAPPDATA%\palee\config.json.
• API key privacy: Because Windows ignores the POSIX 0600 file mode and resolves access through the directory's inherited ACL, palee config set-api-key refuses to write the key when the config directory resolves outside your user profile (%USERPROFILE% / %LOCALAPPDATA%) — a share or synced folder can grant other principals read access. The refusal names the directory. To proceed anyway, pass the key at runtime via the PALEE_API_KEY environment variable (never written to disk), move PALEE_CONFIG_DIR under your profile, or set PALEE_ALLOW_INSECURE_CONFIG_DIR=1 if you have secured the directory by other means.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Detailed contribution guidelines will be added with the implementation source.

License

MIT (see LICENSE).