53 lines
4.0 KiB
Org Mode
53 lines
4.0 KiB
Org Mode
:PROPERTIES:
|
|
:ID: d1e9236b-2ab2-4f17-b0d8-19870e04f018
|
|
:CREATED: [2026-03-30 Mon 21:16]
|
|
:EDITED: [2026-04-07 Tue 13:42]
|
|
:END:
|
|
#+TITLE: SOUL - The Institutional Memory of the Neurosymbolic Lisp Machine
|
|
|
|
* Architectural Learnings
|
|
|
|
** [2026-03-23] Org-Native Skill System (Lisp Machine Mandate)
|
|
- *Problem:* Extending the agent required writing Common Lisp in the core daemon, breaking the "Homoiconic Memory" philosophy where Org-mode is the native memory format. Standard agent architectures use disconnected Markdown/YAML/Python folders.
|
|
- *Solution:* The *Org-Native Skill Standard*. Skills are written entirely as `.org` files. The daemon parses the Org file at startup, extracts `#+begin_src lisp` blocks containing triggers, neuro-prompts, and symbolic verification rules, and dynamically compiles them into the live system using `eval` and `read`.
|
|
- *Heuristic:* The Core is strictly the PTA loop (`core.lisp`, `neuro.lisp`, `symbolic.lisp`). ALL business logic, API connectors, and rule sets MUST live as `.org` files in the `skills/` directory.
|
|
|
|
** [2026-03-23] Cognitive Loop Architecture (org-agent)
|
|
- *Problem:* Monolithic PTA (Perceive-Think-Act) loops lead to "Neural Drift" where the LLM's unverified suggestions can cause illegal system states or security breaches.
|
|
- *Solution:* Implement the *Four-Stage Cognitive Loop*: Perceive -> Think -> Decide -> Act.
|
|
- *Heuristic:* Probabilistic Engine (Neural/LLM) is a proposal engine only. Deterministic Engine (Symbolic/Lisp) is the absolute gatekeeper.
|
|
- *Verification:* Never execute an action unless it has passed through `decide()` and been verified against the symbolic Object Store (CLOSOS).
|
|
|
|
** [2026-03-23] Externalized Configuration Mandate
|
|
- *Problem:* Hardcoded API keys and endpoints in Lisp source prevent portability and create security risks.
|
|
- *Solution:* Use `cl-dotenv` to load `.env` from the system source directory during `eval-when`.
|
|
- *Heuristic:* Use `(uiop:getenv)` with a `(get-env)` fallback helper for all externalized parameters.
|
|
|
|
** [2026-03-23] Hardware Compartment Mandate
|
|
- *Problem:* Forcing a single deployment method (e.g. Docker) creates infrastructure lock-in and limits adoption for users with specific security/performance needs.
|
|
- *Solution:* Treat the runtime as a "Hardware Compartment." Abstract deployment into a `deploy/` directory with support for Bare Metal, Docker, LXC, and VMs.
|
|
- *Heuristic:* The Kernel speaks OACP (TCP); it does not care about the enclosure.
|
|
|
|
** [2026-03-23] LLM Failover Cascade
|
|
- *Problem:* AI providers are unreliable (rate limits, outages). A single provider failure blinds the entire agent.
|
|
- *Solution:* Implement a `*provider-cascade*` list. The kernel automatically tries backends in order until success or exhaustion.
|
|
- *Heuristic:* Reliability is a Core Kernel responsibility; Model choice is a Skill responsibility.
|
|
|
|
** [2026-03-23] Homoiconic Memory (The Org Mandate)
|
|
- *Problem:* Mixed-format workspaces (.md and .org) create cognitive friction and prevent unified AST reasoning.
|
|
- *Solution:* Enforce a "Strictly Org-mode" mandate for all internal logic, plans, and memory.
|
|
- *Heuristic:* Use Lisp for logic, Org for everything else.
|
|
|
|
* Root Cause Analyses (RCA)
|
|
|
|
** [2026-03-23] Lisp Reader Syntax Error (Colons)
|
|
- *Symptom:* Kernel crashed with `SIMPLE-READER-ERROR` on skill files containing `: ` or unescaped quotes in prompt strings.
|
|
- *Root Cause:* The Lisp reader interprets colons as package markers. If they are used in text strings without escaping or sanitization, the reader fails.
|
|
- *Prevention:* Sanitize Org-Native skills to replace `: ` with ` - ` in prompts, and wrap `read-from-string` in `handler-case`.
|
|
|
|
** [2026-03-30 Mon] PSF Mandate Violation: Non-Literate Implementation
|
|
- *Symptom:* `psf-core` logic and tests were written as raw `.lisp` files instead of `.org` literate files.
|
|
- *Root Cause:* Deep-seated "Legacy Coding" habits; prioritized speed of execution over the "Sovereign Literature" mandate.
|
|
- *Prevention:* The agent MUST refuse to create `.lisp` or `.py` files directly for system logic. All implementation must begin as an Org headline with a narrative.
|
|
|