passepartout/skills/org-skill-gardener.org

SKILL: Autonomous Gardener (Memex Maintenance)

• Overview
  • Architectural Intent: Graph Integrity
• Implementation
  • Package Initialization
  • State: Maintenance Cycle
• The Audit Engine
  • Link Verification (gardener-find-broken-links)
  • Orphan Detection (gardener-find-orphans)
• Metabolic Integration
  • Main Audit Gate (gardener-deterministic-gate)
  • Skill Registration

Overview

The Autonomous Gardener is the metabolic immune system of the Memex. It autonomously audits the knowledge graph for structural decay—broken links, orphaned nodes, and missing metadata—ensuring that the system remains coherent and navigatable over long horizons.

Architectural Intent: Graph Integrity

In a self-evolving Memex, structural decay is inevitable. Links break as notes are renamed, and nodes become orphaned as projects are abandoned. The Gardener ensures that the "Vibe" of the Memex remains healthy by:

1. Auditing: Identifying broken `id:` links.
2. Analysis: Flagging nodes with zero inbound or outbound connections (Orphans).
3. Reporting: Logging structural issues for user review or future autonomous repair.

Implementation

Package Initialization

(in-package :cl-user)
(defpackage :opencortex.skills.org-skill-gardener
  (:use :cl :opencortex))
(in-package :opencortex.skills.org-skill-gardener)

State: Maintenance Cycle

To minimize system overhead, the Gardener only performs a full audit pass periodically.

(defvar *gardener-last-audit* 0
  "The universal-time of the last full Memex audit.")

The Audit Engine

Link Verification (gardener-find-broken-links)

This function performs deep packet inspection of the Memory graph. It utilizes regular expressions to find Org-mode ID links and verifies their targets against the live object registry.

(defun gardener-find-broken-links ()
  "Scans all objects in memory for broken internal ID links."
  (let ((broken nil))
    (maphash (lambda (id obj)
               (let ((content (org-object-content obj)))
                 (when content
                   (cl-ppcre:do-register-groups (target-id) ("id:([A-Za-z0-9-]+)" content)
                     (unless (lookup-object target-id)
                       (push (list :source id :broken-target target-id) broken))))))
             *memory*)
    broken))

Orphan Detection (gardener-find-orphans)

Structural isolation limits the effectiveness of semantic reasoning. This function maps the entire graph topology to identify nodes that have effectively "fallen off" the Memex.

(defun gardener-find-orphans ()
  "Identifies nodes with zero connectivity in the knowledge graph."
  (let ((inbound (make-hash-table :test 'equal))
        (outbound (make-hash-table :test 'equal))
        (orphans nil))
    ;; 1. Map all connections
    (maphash (lambda (id obj)
               (let ((content (org-object-content obj)))
                 (when content
                   (cl-ppcre:do-register-groups (target-id) ("id:([A-Za-z0-9-]+)" content)
                     (setf (gethash id outbound) t)
                     (setf (gethash target-id inbound) t)))))
             *memory*)
    ;; 2. Identify nodes with zero connections
    (maphash (lambda (id obj)
               (declare (ignore obj))
               (unless (or (gethash id inbound) (gethash id outbound))
                 (push id orphans)))
             *memory*)
    orphans))

Metabolic Integration

Main Audit Gate (gardener-deterministic-gate)

The primary execution hook. It performs the audit and translates technical findings into human-readable logs for the harness.

(defun gardener-deterministic-gate (action context)
  "Main gate for the Gardener skill. Audits graph integrity and logs reports."
  (declare (ignore action context))
  (let ((broken (gardener-find-broken-links))
        (orphans (gardener-find-orphans)))
    
    (when (or broken orphans)
      (harness-log "GARDENER: Audit found ~a broken links and ~a orphans." 
                   (length broken) (length orphans))
      
      (dolist (link broken)
        (harness-log "  [BROKEN LINK] Node ~a -> ~a" (getf link :source) (getf link :broken-target)))
      
      (dolist (orphan orphans)
        (harness-log "  [ORPHAN] Node ~a is isolated." orphan)))
    
    (setf *gardener-last-audit* (get-universal-time))
    ;; Stop the pipeline by returning a Log event.
    (list :type :LOG :payload (list :text "Gardener audit pass complete."))))

Skill Registration

(defskill :skill-gardener
  :priority 40
  :trigger (lambda (ctx)
             (let* ((payload (getf ctx :payload))
                    (sensor (getf payload :sensor)))
               (and (eq sensor :heartbeat)
                    ;; Optimization: Only audit once every 24 hours
                    (> (- (get-universal-time) *gardener-last-audit*) 86400))))
  :probabilistic nil
  :deterministic #'gardener-deterministic-gate)