Local Markdown Storage System
Relevant source files
The following files were used as context for generating this wiki page:
The Local Markdown Storage System is the persistence layer for PlanQueue, responsible for managing session notes, prompt queues, and configuration. It stores data as plain Markdown files on the local filesystem, organized by repository and branch context. This system ensures that prompt plans are persisted across sessions and provides an append-only history for data recovery and auditability.
Sources: README.md:91-101, src/main.ts:1-12
Directory Structure and Path Resolution
PlanQueue utilizes a hierarchical directory structure under the user's home directory to isolate notes based on the project environment. The primary root for storage is ~/.planqueue/.
Storage Hierarchy
Files are organized according to the following pattern:
~/.planqueue/{repo}/{branch}/{session-id}.md
If a session is started outside of a Git repository, the system defaults the directory name to the current directory name and uses no-branch as the branch identifier.
Sources: README.md:91-95, src/main.ts:311-325
Path Resolution Logic
The system resolves locations by querying the local environment for Git metadata.
The diagram shows how the system identifies the correct filesystem paths based on the current working directory and Git state.
Sources: src/main.ts:311-325, tests/core-integration.test.ts:10-21
Data Models and File Types
The storage system manages three primary types of files: Active Notes, History Files, and Global Configuration.
| File Type | Path Pattern | Description |
|---|---|---|
| Active Note | .../{session-id}.md | Current state of the prompt queue and session notes. |
| History | .../{session-id}.history.md | Append-only log of every change made to the note. |
| Configuration | ~/.planqueue/config.json | Global settings for shortcuts and behavior. |
Sources: README.md:91-101, src/main.ts:322-325, CHANGELOG.md:27-33
Note Normalization
When a note is saved, the system performs "auto-normalization." Plain text lines or bullet points (e.g., - task) are automatically converted into Markdown task syntax (- [ ] task). Headings (#) and blockquotes (>) are preserved as prose and ignored by the queue processor.
Sources: README.md:46-51, src/main.ts:241-244
Persistence Mechanism
The system employs a debounced saving strategy to balance responsiveness with filesystem performance.
Debounced Saver
A DebouncedSaver is created for every session. When content changes in the editor or via an agent tool, the save operation is scheduled rather than executed immediately. This prevents excessive disk I/O during rapid editing.
The diagram illustrates the flow of data from the application into persistent storage, including the parallel update to history logs.
Sources: src/main.ts:333-335, src/main.ts:340-353
History Tracking
Every changed save, including discarded drafts, is appended to a sibling .history.md file. This ensures that even if a user explicitly chooses to discard changes in the editor, the typed work remains available in the history file with a timestamp and "discarded" metadata.
Sources: README.md:95-97, src/main.ts:232-239, CHANGELOG.md:31-31
Legacy Support and Migration
PlanQueue maintains backward compatibility for users migrating from earlier versions (e.g., free-text or omp-free-text).
- Read-Only Fallback: The system searches legacy roots (
~/.free-text/and~/.omp-free-text/) if a note is not found in the new~/.planqueue/location. - Write Direction: While the system can read from legacy paths, all new writes are strictly directed to the
~/.planqueue/directory. - Merging: The cross-session browser (
/planqueue) merges notes from current and legacy roots, prioritizing the newest root if duplicates exist.
Sources: README.md:98-101, src/main.ts:89-106, SECURITY.md:29-32
Security and Constraints
The storage system is designed with a limited security surface to protect user data:
- Path Isolation: Local I/O is restricted to the
~/.planqueue/tree and specific legacy roots. It cannot read or write arbitrary paths on the system. - Agent Access: LLM tools like
note_addandmake_notecan only mutate the current session's note buffer; they have no direct filesystem access. - No Network Activity: The storage system makes no network calls and collects no telemetry; data remains strictly local.
Sources: SECURITY.md:25-42
Summary
The Local Markdown Storage System provides a robust, context-aware persistence layer that leverages standard Markdown for interoperability. By organizing notes by Git context and maintaining an append-only history, it ensures that prompt queues are both persistent and recoverable, while its debounced saving mechanism ensures performance within the OMP environment.