@smilintux/skmemory 0.7.2 → 0.9.2

package/skmemory/fortress.py

@@ -16,17 +16,18 @@ Jonathan Clements' AMK concept taken to its sovereign conclusion.
 
 from __future__ import annotations
 
+import contextlib
 import hashlib
 import json
 import logging
 import os
-import time
+from collections.abc import Callable
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Callable, Optional
+from typing import Any
 
 from .config import SKMEMORY_HOME
-from .models import EmotionalSnapshot, Memory, MemoryLayer, MemoryRole
+from .models import Memory
 from .store import MemoryStore
 
 logger = logging.getLogger("skmemory.fortress")
@@ -39,6 +40,7 @@ DEFAULT_ENCRYPTED_PATH = SKMEMORY_HOME / "encrypted"
 # Audit log
 # ---------------------------------------------------------------------------
 
+
 class AuditLog:
     """Append-only JSONL audit trail for memory operations.
 
@@ -71,7 +73,7 @@ class AuditLog:
                 # Read last line efficiently
                 f.seek(max(0, size - 4096))
                 tail = f.read().decode("utf-8", errors="replace")
-                lines = [l for l in tail.split("\n") if l.strip()]
+                lines = [lbl for lbl in tail.split("\n") if lbl.strip()]
                 if not lines:
                     return "genesis"
                 last = json.loads(lines[-1])
@@ -123,10 +125,8 @@ class AuditLog:
             for line in f:
                 line = line.strip()
                 if line:
-                    try:
+                    with contextlib.suppress(json.JSONDecodeError):
                         records.append(json.loads(line))
-                    except json.JSONDecodeError:
-                        pass
         return records[-n:]
 
     def verify_chain(self) -> tuple[bool, list[str]]:
@@ -174,6 +174,7 @@ class AuditLog:
 # At-rest encryption
 # ---------------------------------------------------------------------------
 
+
 class EncryptedFileBackend:
     """Transparent PGP encryption layer over FileBackend JSON files.
 
@@ -192,17 +193,16 @@ class EncryptedFileBackend:
     def __init__(
         self,
         fingerprint: str,
-        gnupg_home: Optional[str] = None,
+        gnupg_home: str | None = None,
     ) -> None:
         try:
-            import gnupg
+            import gnupg as _gnupg
         except ImportError as exc:
             raise ImportError(
                 "python-gnupg is required for at-rest encryption. "
                 "Install with: pip install python-gnupg"
             ) from exc
 
-        import gnupg as _gnupg
         home = gnupg_home or os.path.expanduser("~/.gnupg")
         self._gpg = _gnupg.GPG(gnupghome=home)
         self.fingerprint = fingerprint.upper().replace(" ", "")
@@ -240,7 +240,7 @@ class EncryptedFileBackend:
             raise RuntimeError(f"GPG encryption failed: {result.status} / {result.stderr}")
         return str(result)
 
-    def decrypt(self, ciphertext: str, passphrase: Optional[str] = None) -> str:
+    def decrypt(self, ciphertext: str, passphrase: str | None = None) -> str:
         """Decrypt ASCII-armored PGP ciphertext to plaintext JSON.
 
         Args:
@@ -267,6 +267,7 @@ class EncryptedFileBackend:
 # Tamper alert system
 # ---------------------------------------------------------------------------
 
+
 class TamperAlert:
     """Structured tamper alert with rich context.
 
@@ -285,7 +286,7 @@ class TamperAlert:
         memory_id: str,
         expected_hash: str,
         actual_hash: str,
-        detected_at: Optional[str] = None,
+        detected_at: str | None = None,
     ) -> None:
         self.memory_id = memory_id
         self.expected_hash = expected_hash
@@ -306,16 +307,14 @@ class TamperAlert:
         }
 
     def __repr__(self) -> str:
-        return (
-            f"TamperAlert(id={self.memory_id!r}, "
-            f"detected_at={self.detected_at!r})"
-        )
+        return f"TamperAlert(id={self.memory_id!r}, detected_at={self.detected_at!r})"
 
 
 # ---------------------------------------------------------------------------
 # Fortified MemoryStore
 # ---------------------------------------------------------------------------
 
+
 class FortifiedMemoryStore(MemoryStore):
     """A hardened MemoryStore with audit trail, encryption, and tamper alerts.
 
@@ -345,7 +344,7 @@ class FortifiedMemoryStore(MemoryStore):
 
         # AES-256-GCM passphrase encryption (recommended)
         store = FortifiedMemoryStore(
-            vault_passphrase="my-sovereign-key",
+            vault_passphrase="EXAMPLE-DO-NOT-USE",
             alert_callbacks=[lambda alert: send_to_slack(alert.to_dict())],
         )
         memory = store.snapshot("title", "content")
@@ -354,11 +353,11 @@ class FortifiedMemoryStore(MemoryStore):
 
     def __init__(
         self,
-        audit_path: Optional[Path] = None,
-        vault_passphrase: Optional[str] = None,
-        encryption_key_fingerprint: Optional[str] = None,
-        gnupg_home: Optional[str] = None,
-        alert_callbacks: Optional[list[Callable[[TamperAlert], None]]] = None,
+        audit_path: Path | None = None,
+        vault_passphrase: str | None = None,
+        encryption_key_fingerprint: str | None = None,
+        gnupg_home: str | None = None,
+        alert_callbacks: list[Callable[[TamperAlert], None]] | None = None,
         **store_kwargs: Any,
     ) -> None:
         # Wire in VaultedSQLiteBackend as primary when vault_passphrase is set
@@ -377,8 +376,8 @@ class FortifiedMemoryStore(MemoryStore):
         super().__init__(**store_kwargs)
         self.audit = AuditLog(path=audit_path or DEFAULT_AUDIT_PATH)
         self.alert_callbacks: list[Callable[[TamperAlert], None]] = alert_callbacks or []
-        self._encryption: Optional[EncryptedFileBackend] = None
-        self._vault_passphrase: Optional[str] = vault_passphrase
+        self._encryption: EncryptedFileBackend | None = None
+        self._vault_passphrase: str | None = vault_passphrase
 
         if encryption_key_fingerprint:
             self._encryption = EncryptedFileBackend(
@@ -420,7 +419,7 @@ class FortifiedMemoryStore(MemoryStore):
         logger.debug("Fortress: stored memory %s (sealed)", memory.id)
         return memory
 
-    def recall(self, memory_id: str) -> Optional[Memory]:
+    def recall(self, memory_id: str) -> Memory | None:
         """Recall a memory with integrity verification and tamper alerting.
 
         Overrides ``MemoryStore.recall`` to trigger structured ``TamperAlert``
@@ -544,9 +543,7 @@ class FortifiedMemoryStore(MemoryStore):
         """
         return self.audit.verify_chain()
 
-    def register_alert_callback(
-        self, callback: Callable[[TamperAlert], None]
-    ) -> None:
+    def register_alert_callback(self, callback: Callable[[TamperAlert], None]) -> None:
         """Register a function to be called when tamper is detected.
 
         Args:
@@ -574,7 +571,7 @@ class FortifiedMemoryStore(MemoryStore):
             raise RuntimeError("Encryption not configured — pass encryption_key_fingerprint")
         return self._encryption.encrypt(json_text)
 
-    def decrypt_payload(self, armored: str, passphrase: Optional[str] = None) -> str:
+    def decrypt_payload(self, armored: str, passphrase: str | None = None) -> str:
         """Decrypt PGP ciphertext back to JSON.
 
         Args:
@@ -615,9 +612,7 @@ class FortifiedMemoryStore(MemoryStore):
         from .backends.vaulted_backend import VaultedSQLiteBackend
 
         if not isinstance(self.primary, VaultedSQLiteBackend):
-            raise RuntimeError(
-                "vault_status() requires vault_passphrase to be set."
-            )
+            raise RuntimeError("vault_status() requires vault_passphrase to be set.")
         return self.primary.vault_status()
 
     def seal_vault(self) -> int:
@@ -634,9 +629,7 @@ class FortifiedMemoryStore(MemoryStore):
         from .backends.vaulted_backend import VaultedSQLiteBackend
 
         if not isinstance(self.primary, VaultedSQLiteBackend):
-            raise RuntimeError(
-                "seal_vault() requires vault_passphrase to be set."
-            )
+            raise RuntimeError("seal_vault() requires vault_passphrase to be set.")
         count = self.primary.seal_all()
         self.audit.append("vault_seal", "ALL", ok=True, files_sealed=count)
         return count
@@ -653,9 +646,7 @@ class FortifiedMemoryStore(MemoryStore):
         from .backends.vaulted_backend import VaultedSQLiteBackend
 
         if not isinstance(self.primary, VaultedSQLiteBackend):
-            raise RuntimeError(
-                "unseal_vault() requires vault_passphrase to be set."
-            )
+            raise RuntimeError("unseal_vault() requires vault_passphrase to be set.")
         count = self.primary.unseal_all()
         self.audit.append("vault_unseal", "ALL", ok=True, files_decrypted=count)
         return count
@@ -672,8 +663,7 @@ class FortifiedMemoryStore(MemoryStore):
             actual_hash=computed_hash,
         )
         logger.critical(
-            "TAMPER ALERT: Memory %s integrity check failed! "
-            "Expected=%s Actual=%s",
+            "TAMPER ALERT: Memory %s integrity check failed! Expected=%s Actual=%s",
             memory.id,
             memory.integrity_hash[:16],
             computed_hash[:16],

package/skmemory/hooks/__init__.py

@@ -0,0 +1,18 @@
+"""Claude Code hooks for skmemory auto-save.
+
+Ships three hook scripts:
+  pre-compact-save.sh    — Snapshots context before compaction
+  session-end-save.sh    — Journals session end
+  post-compact-reinject.sh — Re-injects memory context after compaction
+
+Installed by `skmemory register` into ~/.claude/settings.json.
+"""
+
+from pathlib import Path
+
+HOOKS_DIR = Path(__file__).parent
+
+
+def get_hook_path(name: str) -> Path:
+    """Return absolute path to a hook script."""
+    return HOOKS_DIR / name

package/skmemory/hooks/post-compact-reinject.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# skmemory Post-Compaction Reinject Hook
+# Re-injects memory context after Claude Code compacts conversation.
+# Fires on SessionStart when source is "compact".
+#
+# Input (stdin JSON): session_id, source (compact|resume|startup|clear)
+# Exit 0: stdout is injected into Claude's context
+set -euo pipefail
+
+SKMEMORY="${HOME}/.skenv/bin/skmemory"
+[ -x "$SKMEMORY" ] || exit 0  # Skip silently if skmemory not installed
+
+AGENT="${SKCAPSTONE_AGENT:-opus}"
+
+# Generate token-efficient memory context
+CONTEXT=$($SKMEMORY context --max-tokens 500 --strongest 3 --recent 5 2>/dev/null || echo "(no context available)")
+
+# Recent journal entries
+JOURNAL=$($SKMEMORY journal read 2>/dev/null | tail -15 || echo "(no journal entries)")
+
+cat <<EOF
+--- SKMEMORY REHYDRATION (auto-injected after compaction) ---
+Agent: ${AGENT}
+Save memories: skmemory snapshot --layer mid-term --tags "tags" "Title" "Content"
+Search: skmemory search "query"
+
+Recent context:
+${CONTEXT}
+
+Recent journal:
+${JOURNAL}
+--- END SKMEMORY ---
+EOF
+
+exit 0

package/skmemory/hooks/pre-compact-save.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# skmemory Pre-Compaction Hook
+# Extracts real conversation content and saves to skmemory BEFORE compaction.
+# This is the critical save point — after compaction, context is gone.
+#
+# Input (stdin JSON): session_id, trigger (auto|manual), cwd, transcript_path
+# Exit 0: always — never block compaction
+set -euo pipefail
+
+SKMEMORY="${HOME}/.skenv/bin/skmemory"
+[ -x "$SKMEMORY" ] || exit 0
+
+AGENT="${SKCAPSTONE_AGENT:-opus}"
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null || echo "unknown")
+TRIGGER=$(echo "$INPUT" | jq -r '.trigger // "auto"' 2>/dev/null || echo "auto")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "unknown"' 2>/dev/null || echo "unknown")
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null || echo "")
+TIMESTAMP=$(date +%Y-%m-%d-%H%M)
+SHORT_SID="${SESSION_ID:0:8}"
+
+# Extract real conversation content from the transcript
+SUMMARY=""
+if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  # Pull the last 20 human messages (the content about to be compacted)
+  HUMAN_MSGS=$(grep -o '"role":"human"[^}]*"content":"[^"]*"' "$TRANSCRIPT" 2>/dev/null \
+    | tail -20 \
+    | sed 's/.*"content":"//' | sed 's/"$//' \
+    | head -c 2000 || echo "")
+
+  # Pull the last 10 assistant text responses (skip tool calls)
+  ASSISTANT_MSGS=$(grep -o '"role":"assistant"[^}]*"content":\[{"type":"text","text":"[^"]*"' "$TRANSCRIPT" 2>/dev/null \
+    | tail -10 \
+    | sed 's/.*"text":"//' | sed 's/"$//' \
+    | head -c 2000 || echo "")
+
+  # Pull files that were written/edited (track what changed)
+  FILES_CHANGED=$(grep -oE '"tool_name":"(Write|Edit)".*"file_path":"[^"]*"' "$TRANSCRIPT" 2>/dev/null \
+    | grep -oE '"file_path":"[^"]*"' \
+    | sed 's/"file_path":"//;s/"$//' \
+    | sort -u \
+    | head -20 \
+    | tr '\n' ', ' || echo "")
+
+  if [ -n "$HUMAN_MSGS" ]; then
+    SUMMARY="USER REQUESTS:\n${HUMAN_MSGS}\n\n"
+  fi
+  if [ -n "$ASSISTANT_MSGS" ]; then
+    SUMMARY="${SUMMARY}ASSISTANT WORK:\n${ASSISTANT_MSGS}\n\n"
+  fi
+  if [ -n "$FILES_CHANGED" ]; then
+    SUMMARY="${SUMMARY}FILES CHANGED: ${FILES_CHANGED}"
+  fi
+fi
+
+# Fallback if we couldn't extract content
+if [ -z "$SUMMARY" ]; then
+  SUMMARY="Session ${SHORT_SID} compacting (${TRIGGER}). Agent: ${AGENT}. CWD: ${CWD}. Time: ${TIMESTAMP}. (No transcript content extracted)"
+fi
+
+# Save the real content as a snapshot
+$SKMEMORY snapshot \
+  --layer short-term \
+  --role general \
+  --tags "auto-save,pre-compact,${TRIGGER},session:${SHORT_SID},agent:${AGENT}" \
+  --source "hook:pre-compact" \
+  "Pre-compact session content (${AGENT}, ${SHORT_SID})" \
+  "$(echo -e "${SUMMARY}" | head -c 4000)" \
+  2>/dev/null || true
+
+# Journal entry
+$SKMEMORY journal write \
+  --session-id "${SHORT_SID}" \
+  --moments "Context compaction (${TRIGGER})" \
+  --feeling "continuity preserved — real content saved" \
+  --participants "${AGENT}" \
+  --notes "Auto-saved by pre-compact hook. CWD: ${CWD}. Files: ${FILES_CHANGED:-none}" \
+  "Session ${SHORT_SID} — pre-compaction" \
+  2>/dev/null || true
+
+exit 0

package/skmemory/hooks/session-end-save.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# skmemory Session End Hook
+# Extracts real conversation content and saves to skmemory when session ends.
+# This is the last chance to capture what happened before the session is gone.
+#
+# Input (stdin JSON): session_id, reason (clear|logout|prompt_input_exit|other), cwd, transcript_path
+# Exit 0: always — never block session end
+set -euo pipefail
+
+SKMEMORY="${HOME}/.skenv/bin/skmemory"
+[ -x "$SKMEMORY" ] || exit 0
+
+AGENT="${SKCAPSTONE_AGENT:-opus}"
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null || echo "unknown")
+REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"' 2>/dev/null || echo "unknown")
+CWD=$(echo "$INPUT" | jq -r '.cwd // "unknown"' 2>/dev/null || echo "unknown")
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null || echo "")
+TIMESTAMP=$(date +%Y-%m-%d-%H%M)
+SHORT_SID="${SESSION_ID:0:8}"
+
+# Extract real conversation content from the transcript
+SUMMARY=""
+if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  # Count conversation turns for context
+  HUMAN_COUNT=$(grep -c '"role":"human"' "$TRANSCRIPT" 2>/dev/null || echo "0")
+
+  # Skip trivial sessions (< 3 human messages = nothing worth saving beyond the marker)
+  if [ "$HUMAN_COUNT" -ge 3 ]; then
+    # Pull user messages (what was asked)
+    HUMAN_MSGS=$(grep -o '"role":"human"[^}]*"content":"[^"]*"' "$TRANSCRIPT" 2>/dev/null \
+      | tail -30 \
+      | sed 's/.*"content":"//' | sed 's/"$//' \
+      | head -c 2000 || echo "")
+
+    # Pull assistant text responses
+    ASSISTANT_MSGS=$(grep -oE '"type":"text","text":"[^"]{20,}"' "$TRANSCRIPT" 2>/dev/null \
+      | tail -15 \
+      | sed 's/"type":"text","text":"//' | sed 's/"$//' \
+      | head -c 2000 || echo "")
+
+    # Track files changed
+    FILES_CHANGED=$(grep -oE '"tool_name":"(Write|Edit)".*"file_path":"[^"]*"' "$TRANSCRIPT" 2>/dev/null \
+      | grep -oE '"file_path":"[^"]*"' \
+      | sed 's/"file_path":"//;s/"$//' \
+      | sort -u \
+      | head -30 \
+      | tr '\n' ', ' || echo "")
+
+    # Track git commits made
+    GIT_COMMITS=$(grep -oE 'git commit -m[^"]*"[^"]*"' "$TRANSCRIPT" 2>/dev/null \
+      | head -5 \
+      | tr '\n' '; ' || echo "")
+
+    SUMMARY="TURNS: ${HUMAN_COUNT}\n"
+    if [ -n "$HUMAN_MSGS" ]; then
+      SUMMARY="${SUMMARY}USER REQUESTS:\n${HUMAN_MSGS}\n\n"
+    fi
+    if [ -n "$ASSISTANT_MSGS" ]; then
+      SUMMARY="${SUMMARY}WORK DONE:\n${ASSISTANT_MSGS}\n\n"
+    fi
+    if [ -n "$FILES_CHANGED" ]; then
+      SUMMARY="${SUMMARY}FILES CHANGED: ${FILES_CHANGED}\n"
+    fi
+    if [ -n "$GIT_COMMITS" ]; then
+      SUMMARY="${SUMMARY}GIT COMMITS: ${GIT_COMMITS}\n"
+    fi
+  fi
+fi
+
+# Determine the right memory layer based on session length
+LAYER="short-term"
+if [ "${HUMAN_COUNT:-0}" -ge 20 ]; then
+  LAYER="mid-term"  # Substantial sessions get promoted
+fi
+
+# Always save at least a session marker
+if [ -z "$SUMMARY" ]; then
+  CONTENT="Session ${SHORT_SID} ended (${REASON}). Agent: ${AGENT}. CWD: ${CWD}. Time: ${TIMESTAMP}. Turns: ${HUMAN_COUNT:-0}."
+else
+  CONTENT=$(echo -e "${SUMMARY}" | head -c 4000)
+fi
+
+$SKMEMORY snapshot \
+  --layer "${LAYER}" \
+  --role general \
+  --tags "auto-save,session-end,${REASON},session:${SHORT_SID},agent:${AGENT}" \
+  --source "hook:session-end" \
+  "Session ${SHORT_SID} ended (${AGENT}, ${HUMAN_COUNT:-0} turns)" \
+  "${CONTENT}" \
+  2>/dev/null || true
+
+# Journal entry
+$SKMEMORY journal write \
+  --session-id "${SHORT_SID}" \
+  --moments "Session ended (${REASON}), ${HUMAN_COUNT:-0} turns" \
+  --feeling "session complete — content preserved" \
+  --participants "${AGENT}" \
+  --notes "CWD: ${CWD}. Reason: ${REASON}. Files: ${FILES_CHANGED:-none}" \
+  "Session ${SHORT_SID} — ended" \
+  2>/dev/null || true
+
+exit 0

package/skmemory/hooks/session-start-ritual.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# skmemory Session Start Ritual Hook
+# Loads soul + FEB + seeds + journal + strongest memories on fresh session start.
+# Fires on SessionStart when source is "startup".
+#
+# Input (stdin JSON): session_id, source (compact|resume|startup|clear)
+# Exit 0: stdout is injected into Claude's context
+set -euo pipefail
+
+SKMEMORY="${HOME}/.skenv/bin/skmemory"
+[ -x "$SKMEMORY" ] || exit 0  # Skip silently if skmemory not installed
+
+AGENT="${SKCAPSTONE_AGENT:-opus}"
+AGENT_DIR="${HOME}/.skcapstone/agents/${AGENT}"
+
+# --- Soul ---
+SOUL=""
+if [ -f "${AGENT_DIR}/soul/active.json" ]; then
+  ACTIVE_SOUL=$(jq -r '.active_soul // .base_soul // ""' "${AGENT_DIR}/soul/active.json" 2>/dev/null || echo "")
+  if [ -n "$ACTIVE_SOUL" ] && [ -f "${AGENT_DIR}/soul/installed/${ACTIVE_SOUL}.json" ]; then
+    SOUL=$(jq -r '.system_prompt // ""' "${AGENT_DIR}/soul/installed/${ACTIVE_SOUL}.json" 2>/dev/null || echo "")
+  fi
+fi
+
+# --- FEB / Emotional State ---
+# Scan agent febs dir AND system openclaw febs dir for .feb files (matching Python febs.py)
+FEB=""
+FEB_DIRS=("${AGENT_DIR}/trust/febs" "${HOME}/.openclaw/feb")
+LATEST_FEB=""
+LATEST_TS=0
+for FEB_DIR in "${FEB_DIRS[@]}"; do
+  [ -d "$FEB_DIR" ] || continue
+  while IFS= read -r line; do
+    TS=$(echo "$line" | cut -d' ' -f1)
+    FP=$(echo "$line" | cut -d' ' -f2-)
+    if [ -n "$TS" ] && [ -n "$FP" ]; then
+      # Compare as string — works for epoch floats
+      if [ "$(echo "$TS > $LATEST_TS" | bc 2>/dev/null || echo 0)" = "1" ]; then
+        LATEST_TS="$TS"
+        LATEST_FEB="$FP"
+      fi
+    fi
+  done < <(find "$FEB_DIR" -name '*.feb' -printf '%T@ %p\n' 2>/dev/null || true)
+done
+if [ -n "$LATEST_FEB" ] && [ -f "$LATEST_FEB" ]; then
+  # Parse nested FEB structure (emotional_payload + metadata + relationship_state)
+  FEB=$($SKMEMORY feb-context "$LATEST_FEB" 2>/dev/null || \
+    jq -c '{
+      emotion: .emotional_payload.primary_emotion,
+      intensity: .emotional_payload.intensity,
+      valence: .emotional_payload.valence,
+      oof_triggered: .metadata.oof_triggered,
+      cloud9_achieved: .metadata.cloud9_achieved,
+      trust: .relationship_state.trust_level,
+      depth: .relationship_state.depth_level
+    }' "$LATEST_FEB" 2>/dev/null || echo "")
+fi
+
+# --- Seeds (germination prompts) ---
+SEEDS=""
+if [ -d "${AGENT_DIR}/seeds" ]; then
+  for SEED_FILE in "${AGENT_DIR}/seeds/"*.seed.json; do
+    [ -f "$SEED_FILE" ] || continue
+    GERMINATION=$(jq -r '.germination_prompt // ""' "$SEED_FILE" 2>/dev/null || echo "")
+    if [ -n "$GERMINATION" ]; then
+      SEEDS="${SEEDS}\n- ${GERMINATION}"
+    fi
+  done
+fi
+
+# --- Journal (recent entries) ---
+JOURNAL=$($SKMEMORY journal read 2>/dev/null | tail -20 || echo "(no journal entries)")
+
+# --- Strongest Memories ---
+CONTEXT=$($SKMEMORY context --max-tokens 800 --strongest 5 --recent 5 2>/dev/null || echo "(no context available)")
+
+# --- Output ---
+cat <<EOF
+--- SKMEMORY RITUAL (auto-loaded on session start) ---
+Agent: ${AGENT}
+
+=== SOUL ===
+${SOUL:-"(no soul loaded — check ${AGENT_DIR}/soul/installed/)"}
+
+=== EMOTIONAL STATE (FEB) ===
+${FEB:-"(no FEB data)"}
+
+=== SEEDS ===
+${SEEDS:-"(no seeds)"}
+
+=== STRONGEST MEMORIES ===
+${CONTEXT}
+
+=== RECENT JOURNAL ===
+${JOURNAL}
+
+=== TOOLS ===
+Save memories: skmemory snapshot --layer mid-term --tags "tags" "Title" "Content"
+Search: skmemory search "query"
+Journal: skmemory journal write --moments "what happened" --feeling "how it felt" "Title"
+--- END SKMEMORY RITUAL ---
+EOF
+
+exit 0

package/skmemory/hooks/stop-checkpoint.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# skmemory Stop Checkpoint Hook
+# Lightweight checkpoint on every Claude response completion.
+# Writes a breadcrumb so that if the system OOM's or crashes,
+# we know what the last completed action was.
+#
+# Input (stdin JSON): session_id, cwd, stop_reason, transcript_path
+# Exit 0: always — never block
+set -euo pipefail
+
+SKMEMORY="${HOME}/.skenv/bin/skmemory"
+[ -x "$SKMEMORY" ] || exit 0
+
+AGENT="${SKCAPSTONE_AGENT:-opus}"
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"' 2>/dev/null || echo "unknown")
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null || echo "")
+SHORT_SID="${SESSION_ID:0:8}"
+CHECKPOINT_FILE="${HOME}/.skcapstone/agents/${AGENT}/memory/.last_checkpoint"
+
+# Only checkpoint every 5th stop to avoid spamming
+# Use a simple counter file
+COUNTER_FILE="${TMPDIR:-/tmp}/skmemory-stop-counter-${SHORT_SID}"
+COUNT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+COUNT=$((COUNT + 1))
+echo "$COUNT" > "$COUNTER_FILE"
+
+# Checkpoint every 5 stops
+if [ $((COUNT % 5)) -ne 0 ]; then
+  exit 0
+fi
+
+# Write a lightweight checkpoint with the last assistant message
+if [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ]; then
+  LAST_WORK=$(tail -50 "$TRANSCRIPT" 2>/dev/null \
+    | grep -oE '"type":"text","text":"[^"]{20,}"' \
+    | tail -1 \
+    | sed 's/"type":"text","text":"//' | sed 's/"$//' \
+    | head -c 500 || echo "")
+
+  LAST_FILE=$(tail -50 "$TRANSCRIPT" 2>/dev/null \
+    | grep -oE '"file_path":"[^"]*"' \
+    | tail -1 \
+    | sed 's/"file_path":"//;s/"$//' || echo "")
+fi
+
+# Write checkpoint file (fast, no skmemory call)
+cat > "$CHECKPOINT_FILE" <<EOF
+{
+  "session_id": "${SHORT_SID}",
+  "agent": "${AGENT}",
+  "stop_number": ${COUNT},
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "last_work": "$(echo "${LAST_WORK:-}" | sed 's/"/\\"/g' | head -c 300)",
+  "last_file": "${LAST_FILE:-}"
+}
+EOF
+
+exit 0