@smilintux/skmemory 0.5.0 → 0.9.2

package/skmemory/graph_queries.py

@@ -0,0 +1,238 @@
+"""
+Cypher query templates for SKGraph (FalkorDB) graph operations.
+
+All graph queries are defined here as constants for maintainability
+and testability. The SKGraphBackend imports from this module so
+query strings never live inline in business logic.
+
+FalkorDB uses a Cypher dialect compatible with RedisGraph and Neo4j.
+MERGE is idempotent: safe to call repeatedly, creates if not present.
+"""
+
+# ═══════════════════════════════════════════════════════════
+# Node creation / upsert
+# ═══════════════════════════════════════════════════════════
+
+#: Create or update a Memory node with key properties.
+UPSERT_MEMORY = """
+MERGE (m:Memory {id: $id})
+SET m.title = $title,
+    m.layer = $layer,
+    m.source = $source,
+    m.source_ref = $source_ref,
+    m.intensity = $intensity,
+    m.valence = $valence,
+    m.created_at = $created_at,
+    m.updated_at = $updated_at
+"""
+
+#: Create or update a Tag node.
+UPSERT_TAG = """
+MERGE (t:Tag {name: $name})
+SET t.name = $name
+"""
+
+#: Create or update a Source node (mcp, cli, seed, session, etc.).
+UPSERT_SOURCE = """
+MERGE (s:Source {name: $name})
+SET s.name = $name
+"""
+
+#: Create or update an AI node for seed creators.
+UPSERT_AI = """
+MERGE (a:AI {name: $name})
+SET a.name = $name
+"""
+
+# ═══════════════════════════════════════════════════════════
+# Relationship creation
+# ═══════════════════════════════════════════════════════════
+
+#: Connect Memory to Tag with a TAGGED edge.
+CREATE_TAGGED = """
+MATCH (m:Memory {id: $mem_id})
+MERGE (t:Tag {name: $tag})
+MERGE (m)-[:TAGGED]->(t)
+"""
+
+#: Connect Memory to Source with a FROM_SOURCE edge.
+CREATE_FROM_SOURCE = """
+MATCH (m:Memory {id: $mem_id})
+MERGE (s:Source {name: $source})
+MERGE (m)-[:FROM_SOURCE]->(s)
+"""
+
+#: Connect two memories with a directional RELATED_TO edge.
+CREATE_RELATED_TO = """
+MATCH (a:Memory {id: $a_id})
+MERGE (b:Memory {id: $b_id})
+MERGE (a)-[:RELATED_TO]->(b)
+"""
+
+#: Connect a promoted memory back to its origin with a PROMOTED_FROM edge.
+CREATE_PROMOTED_FROM = """
+MATCH (child:Memory {id: $child_id})
+MERGE (parent:Memory {id: $parent_id})
+MERGE (child)-[:PROMOTED_FROM]->(parent)
+"""
+
+#: Connect memories from the same source that share 2+ tags with RELATED_TO.
+#: Used by index_memory() to auto-wire shared-tag neighbours.
+CREATE_SHARED_TAG_RELATED = """
+MATCH (a:Memory {id: $a_id})-[:TAGGED]->(t:Tag)<-[:TAGGED]-(b:Memory)
+WHERE b.id <> $a_id
+WITH a, b, count(DISTINCT t) AS overlap
+WHERE overlap >= 2
+MERGE (a)-[:RELATED_TO]->(b)
+"""
+
+#: Connect two sequential memories from the same source with PRECEDED_BY.
+CREATE_PRECEDED_BY = """
+MATCH (later:Memory {id: $later_id})
+MATCH (earlier:Memory {id: $earlier_id})
+MERGE (later)-[:PRECEDED_BY]->(earlier)
+"""
+
+#: Connect AI creator to its planted seed memory.
+CREATE_PLANTED = """
+MATCH (m:Memory {id: $mem_id})
+MERGE (a:AI {name: $creator})
+MERGE (a)-[:PLANTED]->(m)
+"""
+
+# ═══════════════════════════════════════════════════════════
+# Traversal queries
+# ═══════════════════════════════════════════════════════════
+
+#: Traverse all edges up to N hops from a starting memory.
+#: Depth is interpolated at call time (not a parameter) because
+#: FalkorDB does not support parameterised variable-length path lengths.
+TRAVERSE_RELATED = """
+MATCH (start:Memory {{id: $id}})
+MATCH path = (start)-[*1..{depth}]-(related:Memory)
+WHERE related.id <> $id
+RETURN DISTINCT related.id AS id,
+       related.title AS title,
+       related.layer AS layer,
+       related.intensity AS intensity,
+       length(path) AS distance
+ORDER BY distance ASC, related.intensity DESC
+LIMIT 20
+"""
+
+#: Walk PROMOTED_FROM chain upward to find ancestor memories.
+TRAVERSE_LINEAGE = """
+MATCH (start:Memory {id: $id})
+MATCH path = (start)-[:PROMOTED_FROM*1..10]->(ancestor:Memory)
+RETURN ancestor.id AS id,
+       ancestor.title AS title,
+       ancestor.layer AS layer,
+       length(path) AS depth
+ORDER BY depth ASC
+"""
+
+# ═══════════════════════════════════════════════════════════
+# Cluster / community queries
+# ═══════════════════════════════════════════════════════════
+
+#: Find memories that are cluster hubs (many direct neighbours).
+FIND_CLUSTER_HUBS = """
+MATCH (m:Memory)-[r]-(connected:Memory)
+WITH m, count(DISTINCT connected) AS connections
+WHERE connections >= $min_connections
+RETURN m.id AS id,
+       m.title AS title,
+       m.layer AS layer,
+       connections
+ORDER BY connections DESC
+LIMIT 20
+"""
+
+#: Retrieve all memories reachable from a hub (for cluster membership).
+GET_CLUSTER_MEMBERS = """
+MATCH (hub:Memory {id: $hub_id})-[*1..2]-(member:Memory)
+WHERE member.id <> $hub_id
+RETURN DISTINCT member.id AS id,
+       member.title AS title,
+       member.layer AS layer,
+       member.intensity AS intensity
+"""
+
+# ═══════════════════════════════════════════════════════════
+# Search queries
+# ═══════════════════════════════════════════════════════════
+
+#: Full-text search across Memory titles using CONTAINS.
+SEARCH_BY_TITLE = """
+MATCH (m:Memory)
+WHERE toLower(m.title) CONTAINS toLower($query)
+RETURN m.id AS id,
+       m.title AS title,
+       m.layer AS layer,
+       m.intensity AS intensity,
+       m.created_at AS created_at
+ORDER BY m.intensity DESC
+LIMIT $limit
+"""
+
+#: Find memories that share any of the given tags (OR logic).
+SEARCH_BY_TAGS = """
+MATCH (m:Memory)-[:TAGGED]->(t:Tag)
+WHERE t.name IN $tags
+WITH m, collect(DISTINCT t.name) AS matched_tags
+RETURN m.id AS id,
+       m.title AS title,
+       m.layer AS layer,
+       m.intensity AS intensity,
+       matched_tags,
+       size(matched_tags) AS tag_overlap
+ORDER BY tag_overlap DESC, m.intensity DESC
+LIMIT $limit
+"""
+
+#: Find the most recent memory from the same source (for PRECEDED_BY wiring).
+FIND_PREVIOUS_FROM_SOURCE = """
+MATCH (m:Memory)-[:FROM_SOURCE]->(s:Source {name: $source})
+WHERE m.id <> $exclude_id
+RETURN m.id AS id, m.created_at AS created_at
+ORDER BY m.created_at DESC
+LIMIT 1
+"""
+
+# ═══════════════════════════════════════════════════════════
+# Stats / health queries
+# ═══════════════════════════════════════════════════════════
+
+#: Count all nodes in the graph.
+COUNT_NODES = "MATCH (n) RETURN count(n) AS nodes"
+
+#: Count Memory nodes specifically.
+COUNT_MEMORIES = "MATCH (m:Memory) RETURN count(m) AS memories"
+
+#: Count all relationships/edges.
+COUNT_EDGES = "MATCH ()-[r]->() RETURN count(r) AS edges"
+
+#: Count Tag nodes and get their names for distribution.
+TAG_DISTRIBUTION = """
+MATCH (t:Tag)<-[:TAGGED]-(m:Memory)
+RETURN t.name AS tag, count(DISTINCT m) AS memory_count
+ORDER BY memory_count DESC
+LIMIT 20
+"""
+
+#: Retrieve a single memory node by ID.
+GET_MEMORY_BY_ID = """
+MATCH (m:Memory {id: $id})
+RETURN m.id AS id,
+       m.title AS title,
+       m.layer AS layer,
+       m.source AS source,
+       m.source_ref AS source_ref,
+       m.intensity AS intensity,
+       m.valence AS valence,
+       m.created_at AS created_at,
+       m.updated_at AS updated_at
+"""
+
+#: Delete a memory node and all attached edges.
+DELETE_MEMORY = "MATCH (m:Memory {id: $id}) DETACH DELETE m"

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

package/skmemory/importers/__init__.py

@@ -8,4 +8,12 @@ export format and feeds it through MemoryStore.snapshot().
 
 from .telegram import import_telegram
 
-__all__ = ["import_telegram"]
+try:
+    from .telegram_api import check_setup as check_telegram_setup
+    from .telegram_api import import_telegram_api
+except ImportError:
+    # telethon not installed — API import unavailable
+    import_telegram_api = None  # type: ignore[assignment]
+    check_telegram_setup = None  # type: ignore[assignment]
+
+__all__ = ["import_telegram", "import_telegram_api", "check_telegram_setup"]