:PROPERTIES:
:ID:       e8b500e2-3f26-4c8e-8558-528061e178ca
:CREATED:  [2026-03-31 Tue 18:28]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Object Store Persistence (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :memory:persistence:closos:psf:

* Overview
The *Object Store Persistence* skill ensures that the agent's perceptual memory (the `*object-store*`) is durable. It provides the mechanism to "dump" the in-RAM knowledge graph to a Lisp-native image file and "reload" it upon boot, eliminating the need to re-parse the entire Memex on every restart.

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

** 1. Purpose
Define automated behaviors for knowledge graph serialization and restoration.

** 2. User Needs
- *Instant Recall:* Rapid loading of the Object Store from a persistent image.
- *High-Fidelity Serialization:* Recursive dumping of `org-object` structs and their relations.
- *Atomic Persistence:* Save the entire graph state to a single `.el` or `.lisp` file.
- *Background Synchronization:* Periodically dump the image during heartbeats.

** 3. Success Criteria
*** TODO Image Dump logic verification (File exists and is readable)
*** TODO Image Load logic verification (Object count matches RAM state)
*** TODO Performance audit (Loading image must be >10x faster than parsing)

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

** 1. Architectural Intent
Interfaces for state dumping and restoration. Source of truth is the RAM-resident `*object-store*` and the `system/state/memory-image.lisp` file.

** 2. Semantic Interfaces
#+begin_src lisp
(defun memory-dump-image ()
  "Serializes the current *object-store* to disk.")

(defun memory-load-image ()
  "Restores the *object-store* from the persistent image file.")
#+end_src

* Phase D: Build (Implementation)

** Image Serialization
We serialize the `*history-store*` (immutable objects) and the current `*object-store*` root pointers.

#+begin_src lisp
(defun memory-dump-image ()
  "Serializes the entire history store and current pointers to a Lisp image."
  (let* ((state-dir (or (uiop:getenv "SYSTEM_DIR") "system/"))
         (image-file (merge-pathnames "state/memory-image.lisp" state-dir)))
    (ensure-directories-exist image-file)
    (org-agent:kernel-log "MEMORY - Dumping Merkle-Tree history to ~a..." (uiop:native-namestring image-file))
    (with-open-file (out image-file :direction :output :if-exists :supersede)
      (format out "(in-package :org-agent)~%")
      ;; 1. Dump all immutable objects in the history store
      (maphash (lambda (hash obj)
                 (print `(setf (gethash ,hash *history-store*) ,obj) out))
               org-agent:*history-store*)
      ;; 2. Dump the current active pointers (the object store)
      (maphash (lambda (id obj)
                 (print `(setf (gethash ,id *object-store*) (gethash ,(org-agent:org-object-hash obj) *history-store*)) out))
               org-agent:*object-store*))
    '(:target :system :payload (:action :message :text "Merkle-Tree image dumped."))))

(defun memory-load-image ()
  "Loads the memory image from disk."
  (let* ((state-dir (or (uiop:getenv "SYSTEM_DIR") "system/"))
         (image-file (merge-pathnames "state/memory-image.lisp" state-dir)))
    (if (uiop:file-exists-p image-file)
        (progn
          (org-agent:kernel-log "MEMORY - Loading knowledge graph image...")
          (load image-file)
          t)
        (progn
          (org-agent:kernel-log "MEMORY ERROR - Image file not found.")
          nil))))
#+end_src

** Cognitive Tools
#+begin_src lisp
(org-agent:def-cognitive-tool :persist-memory "Saves the current state of the Memex (Object Store + History) to disk."
  :parameters nil
  :body (lambda (args)
          (declare (ignore args))
          (memory-dump-image)
          "MEMORY PERSISTED SUCCESSFUL."))

(org-agent:def-cognitive-tool :rollback-memory "Reverts the in-memory state to a previous snapshot."
  :parameters ((:index :type :integer :description "The snapshot index to roll back to (0 is most recent)"))
  :body (lambda (args)
          (org-agent:rollback-object-store (getf args :index))
          "ROLLBACK COMPLETE."))
#+end_src

** Registration
#+begin_src lisp
(org-agent:defskill :skill-object-store-persistence
  :priority 100
  :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :heartbeat))
  :neuro (lambda (context) nil)
  :symbolic (lambda (action context) (memory-dump-image)))
#+end_src