Glossary

Relevant Source Files

• package.json
• planning/memory_design.md
• planning/storage_design.md
• src/cli/adopt.ts
• src/cli/dashboard.ts
• src/cli/session.ts
• src/engine/dependency.ts
• src/engine/sm2.ts
• src/storage/lock.ts
• src/types.ts
• test/session-cli.test.ts
• test/storage-lock.test.ts
• test/types-difficulty.test.ts

This page defines the codebase-specific terms, abbreviations, and domain concepts used throughout the PALEE system. It serves as a technical reference for engineers to map conceptual terminology to specific implementation details in the source code.

Core Domain Concepts

Spaced Repetition (SRS)

The learning methodology used to optimize long-term retention. PALEE implements the SM-2 (SuperMemo-2) algorithm to calculate the optimal interval for reviewing topics.

• Ease Factor (EF): A multiplier (default 2.5) that determines how quickly the interval between reviews grows. It is updated based on the quality of the user's performance src/engine/sm2.ts The minimum allowed value is 1.3src/engine/sm2.ts
• Interval: The number of days until the next review. Initial intervals are 1 and 6 days for the first two successful repetitions src/engine/sm2.ts
• Quality (0–5): A rating provided by the user or AI to assess performance. Ratings < 3 are considered lapses and reset the repetition count src/engine/sm2.ts

Topic

The fundamental unit of learning in PALEE. A topic is a Markdown file within the user's Obsidian vault that has been "adopted" by injecting specific YAML frontmatter src/cli/adopt.ts

• Mastery: A numerical value (0.0 to 1.0) representing the learner's proficiency. A topic is considered "mastered" at a threshold of 0.7src/engine/mastery.ts
• Difficulty: A categorical classification (beginner, intermediate, advanced). The system provides a normalization utility to convert various inputs (numeric or string) into these canonical types src/types.ts

Dependency Graph

A Directed Acyclic Graph (DAG) where nodes are Topics and edges are depends_on relationships.

• Ready Topic: A topic that has not yet been mastered but whose dependencies all meet the mastery threshold src/engine/dependency.ts
• Cycle Detection: An SCC-based check (iterative Tarjan plus optional Johnson enumeration) to ensure no circular dependencies exist, which would prevent a topic from ever becoming "ready" src/engine/dependency.ts
• Edge Provenance (depends_on_source): The label recording who authored a note's depends_on list — numbered from the hygiene chain's order (numeric prefixes, and structural rank such as a directory's leading README or deep-dive → lab → exam), tie from a filename collation at equal rank, toc from a listing document's enumeration order, or declared from a list the learner wrote, whether preserved frontmatter or ## Prerequisites links. toc and tie are advisory: they rank the topic and take part in cycle detection but never gate it; numbered, declared, and an absent or unrecognized label all gate fail-closed src/types.ts

Entity Mapping: Natural Language to Code

Sources: src/types.tssrc/engine/sm2.tssrc/engine/dependency.tssrc/cli/adopt.ts

---

Storage & Persistence

Atomic Write

A file-writing strategy that prevents data corruption by writing to a temporary file first and then renaming it to the target destination. This is combined with Optimistic Concurrency Control (OCC) using SHA-256 fingerprints src/cli/adopt.ts

File Locking

A mechanism to prevent multiple processes from modifying the same vault file simultaneously. PALEE uses directory-based locking (.lockdir) which is atomic across platforms src/storage/lock.ts

• Heartbeat: A background process that updates the lock file's mtime every 15 seconds to signal the process is still alive src/storage/lock.ts
• Stale Lock: A lock whose heartbeat has not been updated for a timeout period (60s on Windows, 120s elsewhere). Stale locks can be "taken over" by new processes src/storage/lock.ts

Vault Walker

A utility that recursively traverses the filesystem to find Markdown files, while respecting exclusion rules for hidden directories (e.g., .git, .obsidian) src/cli/dashboard.ts

Data Flow: Persistence and Locking

Sources: src/storage/lock.tssrc/storage/lock.tssrc/cli/adopt.ts

---

Session Management

Hot Memory (hot.md)

A compact file (.palee/hot.md) representing the active working memory for the current or next session. It is limited to a 250-word body to keep LLM context windows small planning/memory_design.md

Session Record

A durable Markdown file stored in .palee/sessions/ that logs the start/end times and topics covered in a specific learning interval src/types.ts

Draft Checkpoint

An unconfirmed session record (prefixed with DRAFT-S-) created during an active session. If the CLI crashes, these are used for recovery src/cli/session.ts

Recovery Actions

When an unconfirmed draft is detected at session start, the user can choose:

• Resume: Continue the session from the draft state.
• Save: Finalize the draft as a completed session.
• Discard: Delete the draft.
• Ignore: Leave the draft for later resolution src/cli/session.ts

Entity Relationship: Session Storage

Sources: src/types.tssrc/cli/session.tsplanning/memory_design.md

dependencies is a storage-input alias. normalizeDependencies in src/storage/dependencies.ts unions it into depends_on at the storage boundary; the engine reads only depends_on.

---

Technical Abbreviations

Abbreviation	Full Term	Context
OCC	Optimistic Concurrency Control	Used in atomicWrite to prevent overwriting manual edits src/cli/adopt.ts
TOCTOU	Time-of-check to time-of-use	A race condition PALEE avoids by using atomic mkdir for locking src/storage/lock.ts
CST	Concrete Syntax Tree	Used by the yaml library to preserve comments and formatting during frontmatter updates src/storage/frontmatter.ts
DFS	Depth-First Search	Traversal strategy inside the iterative Tarjan SCC pass and Johnson enumeration; the outer cycle detector is SCC-based src/engine/dependency.ts

Sources: src/storage/lock.tssrc/engine/dependency.ts