2.5 KiB
SKILL: Org-Mode & AST Manipulation (The Grammar)
Overview
This skill defines the Grammar of the Memex. It is the set of rules that allow the `org-agent` to treat plain text as a structured, hierarchical database. In the Personal Software Foundry (PSF), Org-mode is the **Homoiconic Memory**—it is both the documentation for humans and the abstract syntax tree (AST) for the agent.
The Org Mandate
Following the PSF Mandates, all internal logic, plans, and skills MUST follow these structural rules:
1. Everything is a Node
Every concept or task is represented as an Org headline.
- Headlines: Hierarchical structure using asterisks (`*`, `**`, etc.).
- Metadata: Contained within `:PROPERTIES:` drawers.
- Identity: Every permanent node MUST have a globally unique `:ID:` for robust cross-referencing.
2. Literate Programming
Code is never isolated. It must be wrapped in `#+begin_src` blocks and accompanied by a narrative that explains its architectural intent. This ensures the "Why" is as persistent as the "How."
3. Naming & Paths
The Memex uses a strictly flat, link-heavy structure to prevent "folder silos":
- Daily Captures: `~/memex/daily/YYYY-MM-DD.org`
- Permanent Knowledge: `~/memex/notes/kebab-case-filename.org`
- Project Roots: `~/memex/projects/project-name/`
Binary Integrity (org-attach)
To prevent "broken path rot," all binary files (PDFs, images, data) are managed via the Attachment Protocol.
- Host Node: Binaries are always attached to a specific symbolic node (headline).
- ID-Based Storage: Files are stored in a directory named after the node's UUID.
- Internal Linking: Use `attachment:filename.ext` to ensure links remain valid even if the host file is moved.
Symbolic Implementation
The following logic defines how the agent perceives and manipulates the Org AST.
(defun org-mode-parse-node (id)
"Retrieves the AST of a specific node by its ID."
(let ((notes-dir (expand-file-name "~/memex/notes/")))
(kernel-log "AST - Parsing node: ~a" id)
;; Implementation of org-element-parse-buffer for the targeted node
(org-agent:run-shell-command (format nil "grep -r ':ID: ~a' ~a" id notes-dir))))