3.5 KiB
SKILL: Atomic Notes Retrieval (Universal Literate Note)
Overview
This skill provides the Deep Memory for the agent. it enables Sparse Tree Perception over the Zettelkasten, using semantic search and recursive interlinking to maintain high-signal context without token bloat.
Phase A: Demand (PRD)
1. Purpose
Define the interfaces for knowledge retrieval from the atomic note DAG.
2. User Needs
- Atomicity: Each note represents exactly one concept.
- Sparse Tree Perception: Extract headlines and IDs before deep reading.
- Recursive Deep-Dive: Follow internal links to pull related context.
- Search Efficiency: Optimized searching via `ripgrep`.
3. Success Criteria
TODO Concept Discovery
TODO Link Resolution
TODO Sparse Tree Extraction Verification
Phase B: Blueprint (PROTOCOL)
Phase B: Blueprint (PROTOCOL)
1. Architectural Intent
The core intent is to create a semantic query layer on top of the Zettelkasten. This involves indexing notes for efficient search, creating a sparse representation of the note graph, and providing functions to traverse this graph based on semantic relevance and explicit links. The system will prioritize speed and low memory footprint for interactive use. We'll focus on leveraging existing CLI tools like `ripgrep` and `jq` whenever possible and keeping the Lisp code thin by relying on external indexing and search. We aim for a functional core, minimizing mutable state to ease reasoning and testing.
2. Semantic Interfaces (Lisp Signatures)
Function: `find-atomic-notes`
Finds atomic notes matching a semantic query.
:ARGS ((query string) (options plist)) :RETURNS (list-of note-ids) :DESCRIPTION "Performs a semantic search for notes. Options can control search depth, relevance threshold, and maximum results." :EXAMPLE `(find-atomic-notes "Bayesian Inference" '(:max-results 10 :relevance-threshold 0.7))`
Function: `get-note-content`
Retrieves the content of a specific note.
:ARGS ((note-id string)) :RETURNS (string) :DESCRIPTION "Retrieves the full text content of the note identified by note-id." :EXAMPLE `(get-note-content "skill-atomic-notes")`
Function: `extract-headline-ids`
Extracts headline and ID pairs from a note's content.
:ARGS ((note-content string)) :RETURNS (list-of (cons headline id)) :DESCRIPTION "Parses the note content and returns a list of headline-ID pairs for hierarchical navigation." :EXAMPLE `(extract-headline-ids (get-note-content "skill-atomic-notes"))`
Function: `resolve-internal-links`
Resolves internal links within a note and fetches the linked note IDs.
:ARGS ((note-id string)) :RETURNS (list-of note-ids) :DESCRIPTION "Finds all internal links (e.g., id:some-other-note) in a note and returns a list of the target note IDs." :EXAMPLE `(resolve-internal-links "skill-atomic-notes")`
Function: `expand-note-graph`
Recursively expands the note graph from a starting set of notes to a specified depth.
:ARGS ((seed-note-ids list-of-strings) (depth integer)) :RETURNS (list-of note-ids) :DESCRIPTION "Expands the note graph by recursively following links to a given depth." :EXAMPLE `(expand-note-graph '("skill-atomic-notes" "some-other-note") 2)`