48 lines
2.5 KiB
Org Mode
48 lines
2.5 KiB
Org Mode
#+TITLE: SKILL: Org-Mode & AST Manipulation (The Grammar)
|
|
#+ID: skill-org-mode
|
|
#+STARTUP: content
|
|
#+FILETAGS: :org-mode:ast:homoiconic:
|
|
|
|
* 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 [[file:personal-software-foundry.org][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**.
|
|
1. **Host Node:** Binaries are always attached to a specific symbolic node (headline).
|
|
2. **ID-Based Storage:** Files are stored in a directory named after the node's UUID.
|
|
3. **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.
|
|
|
|
#+begin_src lisp
|
|
(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))))
|
|
#+end_src
|
|
|
|
* See Also
|
|
- [[file:personal-software-foundry.org][Personal Software Foundry Mandates]]
|
|
- [[file:org-skill-scribe.org][Scribe Agent (The Archivist)]]
|