:PROPERTIES:
:ID:       414dc691-351d-4b36-9ff6-25d060a5d261
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Atomic Notes Retrieval (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :knowledge:retrieval:zettelkasten:psf:

* 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.

** The Memex Linking Rule
While referring to any other file or concept in the Memex, you MUST always use the =org-id= for reference (e.g., =[[id:uuid-here][Link Text]]=). 
- *Why:* This ensures the structural integrity of the Skill Graph and Zettelkasten even if files are renamed or moved across the PARA structure.
- *Web Browsers vs. Agents:* Note that while =id:= links do not natively resolve to clickable links in standard web browsers (like the Gitea UI), they are required for the agent and Emacs to natively resolve the graph. Structural integrity supersedes browser convenience.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 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)
:PROPERTIES:
:STATUS: SIGNED
:END:


* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:

** 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)`