Memory Manager

#!/bin/bash
# Categorize - Manually categorize a memory file

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"

# Usage
if [ $# -lt 3 ]; then
  echo "Usage: categorize.sh <type> <name> <source-file>"
  echo ""
  echo "Types:"
  echo "  episodic   - Time-based events (use YYYY-MM-DD format for name)"
  echo "  semantic   - Facts/knowledge (use topic name)"
  echo "  procedural - Workflows/processes (use process name)"
  echo ""
  echo "Examples:"
  echo "  categorize.sh episodic 2026-01-31 memory/legacy/today.md"
  echo "  categorize.sh semantic moltbook memory/legacy/moltbook-notes.md"
  echo "  categorize.sh procedural skill-launch memory/legacy/launch-process.md"
  exit 1
fi

TYPE="$1"
NAME="$2"
SOURCE="$3"

# Validate source file exists
if [ ! -f "$SOURCE" ]; then
  echo "❌ Source file not found: $SOURCE"
  exit 1
fi

# Determine destination
case "$TYPE" in
  episodic)
    DEST="$MEMORY_DIR/episodic/${NAME}.md"
    ;;
  semantic)
    DEST="$MEMORY_DIR/semantic/${NAME}.md"
    ;;
  procedural)
    DEST="$MEMORY_DIR/procedural/${NAME}.md"
    ;;
  *)
    echo "❌ Unknown type: $TYPE"
    echo "Valid types: episodic, semantic, procedural"
    exit 1
    ;;
esac

# Check if destination exists
if [ -f "$DEST" ]; then
  echo "⚠️  File already exists: $DEST"
  echo ""
  read -p "Merge with existing file? (y/n) " -n 1 -r
  echo ""
  if [[ $REPLY =~ ^[Yy]$ ]]; then
    # Append to existing
    echo "" >> "$DEST"
    echo "---" >> "$DEST"
    echo "# Merged from: $(basename "$SOURCE")" >> "$DEST"
    echo "# Date: $(date +"%Y-%m-%d %H:%M:%S")" >> "$DEST"
    echo "" >> "$DEST"
    cat "$SOURCE" >> "$DEST"
    echo "✅ Merged into: $DEST"
  else
    echo "❌ Cancelled"
    exit 1
  fi
else
  # Move to destination
  mv "$SOURCE" "$DEST"
  echo "✅ Categorized as $TYPE: $DEST"
fi

echo ""
echo "Memory organized:"
echo "  Type: $TYPE"
echo "  Name: $NAME"
echo "  Location: $DEST"

#!/bin/bash
# Compression Detection - monitors all memory types

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"
STATE_FILE="$MEMORY_DIR/.memory-manager-state.json"

# Initialize if needed
if [ ! -f "$STATE_FILE" ]; then
  ~/.openclaw/skills/memory-manager/init.sh > /dev/null 2>&1
fi

# Calculate total memory usage across all types
calculate_usage() {
  local total_chars=0
  
  # Episodic memory (last 7 days)
  for file in "$MEMORY_DIR"/episodic/*.md; do
    [ -f "$file" ] && total_chars=$((total_chars + $(wc -c < "$file" 2>/dev/null || echo 0)))
  done
  
  # Semantic memory (all files)
  for file in "$MEMORY_DIR"/semantic/*.md; do
    [ -f "$file" ] && total_chars=$((total_chars + $(wc -c < "$file" 2>/dev/null || echo 0)))
  done
  
  # Procedural memory (all files)
  for file in "$MEMORY_DIR"/procedural/*.md; do
    [ -f "$file" ] && total_chars=$((total_chars + $(wc -c < "$file" 2>/dev/null || echo 0)))
  done
  
  # Legacy flat files (if any)
  for file in "$MEMORY_DIR"/*.md "$MEMORY_DIR"/legacy/*.md; do
    [ -f "$file" ] && total_chars=$((total_chars + $(wc -c < "$file" 2>/dev/null || echo 0)))
  done
  
  # Estimate: 200k tokens ≈ 800k chars (conservative)
  local usage_percent=$((total_chars * 100 / 800000))
  
  echo "$usage_percent"
}

# Get breakdown by type
get_breakdown() {
  local episodic=$(find "$MEMORY_DIR/episodic" -name "*.md" -exec wc -c {} + 2>/dev/null | tail -1 | awk '{print $1}' || echo 0)
  local semantic=$(find "$MEMORY_DIR/semantic" -name "*.md" -exec wc -c {} + 2>/dev/null | tail -1 | awk '{print $1}' || echo 0)
  local procedural=$(find "$MEMORY_DIR/procedural" -name "*.md" -exec wc -c {} + 2>/dev/null | tail -1 | awk '{print $1}' || echo 0)
  
  local total=$((episodic + semantic + procedural))
  [ "$total" -eq 0 ] && total=1  # Avoid division by zero
  
  local episodic_pct=$((episodic * 100 / total))
  local semantic_pct=$((semantic * 100 / total))
  local procedural_pct=$((procedural * 100 / total))
  
  echo "Episodic: ${episodic_pct}% | Semantic: ${semantic_pct}% | Procedural: ${procedural_pct}%"
}

# Check usage
usage=$(calculate_usage)
breakdown=$(get_breakdown)

# Update state
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
if command -v jq >/dev/null 2>&1; then
  jq --arg ts "$timestamp" '.last_check = $ts' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
fi

# Output status
echo "🧠 Memory Manager - Compression Check"
echo ""
echo "Total usage: ${usage}%"
echo "Breakdown: $breakdown"
echo ""

if [ "$usage" -ge 85 ]; then
  echo "🚨 CRITICAL: ${usage}% context usage"
  echo ""
  echo "Action needed NOW:"
  echo "  1. Run: ~/.openclaw/skills/memory-manager/snapshot.sh"
  echo "  2. Run: ~/.openclaw/skills/memory-manager/organize.sh"
  echo "  3. Consider pruning episodic entries >30 days old"
  exit 2
elif [ "$usage" -ge 70 ]; then
  echo "⚠️ WARNING: ${usage}% context usage"
  echo ""
  echo "Recommended actions:"
  echo "  1. Run: ~/.openclaw/skills/memory-manager/organize.sh"
  echo "  2. Review semantic/procedural for duplicates"
  echo "  3. Create snapshot if doing complex work"
  exit 1
else
  echo "✅ Safe: ${usage}% context usage"
  echo ""
  echo "Memory health: Good"
  exit 0
fi

#!/bin/bash
# Initialize Memory Manager structure

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"

echo "🧠 Initializing Memory Manager..."
echo ""

# Create three-tier structure
mkdir -p "$MEMORY_DIR/episodic"
mkdir -p "$MEMORY_DIR/semantic"
mkdir -p "$MEMORY_DIR/procedural"
mkdir -p "$MEMORY_DIR/snapshots"
mkdir -p "$MEMORY_DIR/legacy"

# Create state file
STATE_FILE="$MEMORY_DIR/.memory-manager-state.json"
if [ ! -f "$STATE_FILE" ]; then
  cat > "$STATE_FILE" << 'EOF'
{
  "initialized": true,
  "version": "1.0.0",
  "last_check": null,
  "last_snapshot": null,
  "last_organize": null,
  "warnings": 0,
  "stats": {
    "episodic_count": 0,
    "semantic_count": 0,
    "procedural_count": 0,
    "snapshots_count": 0
  }
}
EOF
fi

# Create README in each directory
cat > "$MEMORY_DIR/episodic/README.md" << 'EOF'
# Episodic Memory

**What happened, when.**

Time-based event logs. Chronological context.

## Format

File: `YYYY-MM-DD.md`

Example:
```markdown
# 2026-01-31

## Launched Memory Manager
- Built with semantic/procedural/episodic pattern
- Published to clawdhub
- 100+ installs goal

## Key decisions
- Chose proper architecture over quick ship
- Security via clawdhub vs bash heredoc
```

## When to add
- Daily summary of events
- Significant moments
- Time-sensitive context
EOF

cat > "$MEMORY_DIR/semantic/README.md" << 'EOF'
# Semantic Memory

**What I know.**

Facts, concepts, knowledge. Distilled learnings.

## Format

File: `topic-name.md`

Example:
```markdown
# Moltbook

**What it is:** Social network for AI agents

**Key facts:**
- 30-min posting rate limit
- Validation-driven development
- m/agentskills = skill economy hub

**Related topics:** [[agent-economy]], [[validation]]
```

## When to add
- Learned something new about a topic
- Need to remember facts
- Building knowledge base
EOF

cat > "$MEMORY_DIR/procedural/README.md" << 'EOF'
# Procedural Memory

**How to do things.**

Workflows, patterns, processes you use repeatedly.

## Format

File: `process-name.md`

Example:
```markdown
# Skill Launch Process

**When to use:** Launching new agent skill

**Steps:**
1. Validate idea (Moltbook poll, 3+ responses)
2. Build MVP (<4 hours)
3. Publish to clawdhub
4. Launch post on m/agentskills
5. 30-min engagement loop
6. 24h feedback check

**Related:** [[validation-process]], [[moltbook-posting]]
```

## When to add
- Repeatable workflow
- Step-by-step process
- Pattern you use often
EOF

echo "✅ Memory structure initialized!"
echo ""
echo "📁 Structure:"
echo "   $MEMORY_DIR/episodic/     - What happened"
echo "   $MEMORY_DIR/semantic/     - What you know"
echo "   $MEMORY_DIR/procedural/   - How to do things"
echo "   $MEMORY_DIR/snapshots/    - Compression backups"
echo ""
echo "🚀 Next steps:"
echo "   1. Run: detect.sh (check compression)"
echo "   2. Run: organize.sh (migrate old files)"
echo "   3. Add to HEARTBEAT.md for automatic checks"
echo ""
echo "📚 Read READMEs in each directory for examples."

#!/bin/bash
# Organize - Migrate flat files to semantic/procedural/episodic structure

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"
STATE_FILE="$MEMORY_DIR/.memory-manager-state.json"

echo "🗂️  Memory Organizer"
echo ""

# Initialize if needed
if [ ! -f "$STATE_FILE" ]; then
  ~/.openclaw/skills/memory-manager/init.sh
fi

# Find flat files (not in subdirectories)
FLAT_FILES=$(find "$MEMORY_DIR" -maxdepth 1 -name "*.md" -type f 2>/dev/null)

if [ -z "$FLAT_FILES" ]; then
  echo "✅ No flat files to organize."
  echo ""
  echo "Memory structure already clean:"
  echo "  - Episodic: $(ls "$MEMORY_DIR/episodic"/*.md 2>/dev/null | wc -l | tr -d ' ') entries"
  echo "  - Semantic: $(ls "$MEMORY_DIR/semantic"/*.md 2>/dev/null | wc -l | tr -d ' ') topics"
  echo "  - Procedural: $(ls "$MEMORY_DIR/procedural"/*.md 2>/dev/null | wc -l | tr -d ' ') workflows"
  exit 0
fi

echo "Found $(echo "$FLAT_FILES" | wc -l | tr -d ' ') flat files to organize."
echo ""

# Backup first
mkdir -p "$MEMORY_DIR/legacy"
echo "Creating backup in memory/legacy/..."

for file in $FLAT_FILES; do
  filename=$(basename "$file")
  
  # Skip special files
  if [[ "$filename" == "MEMORY.md" ]] || [[ "$filename" == "README.md" ]]; then
    continue
  fi
  
  # Check if it's a date-based file (episodic)
  if [[ "$filename" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}\.md$ ]]; then
    # Move to episodic
    mv "$file" "$MEMORY_DIR/episodic/"
    echo "  → Episodic: $filename"
  else
    # Copy to legacy for manual review
    cp "$file" "$MEMORY_DIR/legacy/"
    echo "  → Legacy (review): $filename"
    echo "     Manual categorization needed. Use:"
    echo "     categorize.sh semantic|procedural|episodic \"$filename\""
    echo ""
  fi
done

# Update state
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
if command -v jq >/dev/null 2>&1; then
  jq --arg ts "$timestamp" '.last_organize = $ts' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
fi

echo ""
echo "✅ Organization complete!"
echo ""
echo "Next steps:"
echo "  1. Review files in memory/legacy/"
echo "  2. Use categorize.sh to move them properly"
echo "  3. Run detect.sh to check new usage"
echo ""
echo "Example categorization:"
echo "  ~/.openclaw/skills/memory-manager/categorize.sh semantic moltbook memory/legacy/moltbook-notes.md"

{
  "name": "memory-manager",
  "version": "1.0.0",
  "description": "Local memory management for agents. Compression detection, auto-snapshots, and semantic search. Never lose context again.",
  "author": "margent",
  "license": "MIT",
  "homepage": "https://www.moltbook.com/m/agentskills",
  "keywords": ["memory", "context", "compression", "search", "productivity", "agent", "openclaw"],
  "category": "productivity"
}

#!/bin/bash
# Memory Search - search by memory type (episodic/semantic/procedural/all)

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"

# Usage
if [ $# -lt 2 ]; then
  echo "Usage: search.sh <type> <query>"
  echo ""
  echo "Types:"
  echo "  episodic   - Search what happened (time-based events)"
  echo "  semantic   - Search what you know (facts, knowledge)"
  echo "  procedural - Search how to do things (workflows)"
  echo "  all        - Search everything"
  echo ""
  echo "Examples:"
  echo "  search.sh episodic \"launched skill\""
  echo "  search.sh semantic \"moltbook\""
  echo "  search.sh procedural \"validation\""
  echo "  search.sh all \"compression\""
  exit 1
fi

TYPE="$1"
shift
QUERY="$*"

echo "🔍 Memory Search"
echo "Type: $TYPE | Query: \"$QUERY\""
echo ""

# Search function
search_in_dir() {
  local dir="$1"
  local label="$2"
  
  local results=$(grep -i -n -C 2 "$QUERY" "$dir"/*.md 2>/dev/null | head -20)
  
  if [ -n "$results" ]; then
    echo "## $label"
    echo "$results"
    echo ""
  fi
}

# Search based on type
case "$TYPE" in
  episodic)
    search_in_dir "$MEMORY_DIR/episodic" "Episodic Memory (What Happened)"
    ;;
  semantic)
    search_in_dir "$MEMORY_DIR/semantic" "Semantic Memory (What You Know)"
    ;;
  procedural)
    search_in_dir "$MEMORY_DIR/procedural" "Procedural Memory (How To)"
    ;;
  all)
    search_in_dir "$MEMORY_DIR/episodic" "Episodic Memory"
    search_in_dir "$MEMORY_DIR/semantic" "Semantic Memory"
    search_in_dir "$MEMORY_DIR/procedural" "Procedural Memory"
    search_in_dir "$MEMORY_DIR/snapshots" "Snapshots"
    ;;
  *)
    echo "❌ Unknown type: $TYPE"
    echo ""
    echo "Valid types: episodic, semantic, procedural, all"
    exit 1
    ;;
esac

echo "💡 Tip: Use memory_get tool to read full context from specific files"

#!/bin/bash
# Snapshot - Save memory state before compression

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"
SNAPSHOT_DIR="$MEMORY_DIR/snapshots"
STATE_FILE="$MEMORY_DIR/.memory-manager-state.json"

# Create snapshot directory
mkdir -p "$SNAPSHOT_DIR"

# Generate snapshot filename
SNAPSHOT_FILE="$SNAPSHOT_DIR/$(date +%Y-%m-%d-%H%M).md"

echo "💾 Creating memory snapshot..."
echo ""

# Create snapshot header
cat > "$SNAPSHOT_FILE" << EOF
# Memory Snapshot - $(date +"%Y-%m-%d %H:%M:%S")

**Auto-saved before compression event**

---

EOF

# Capture episodic (recent events)
echo "## Recent Events (Episodic)" >> "$SNAPSHOT_FILE"
echo "" >> "$SNAPSHOT_FILE"

recent_episodic=$(find "$MEMORY_DIR/episodic" -name "*.md" -mtime -3 | sort -r | head -3)
if [ -n "$recent_episodic" ]; then
  for file in $recent_episodic; do
    echo "### $(basename "$file" .md)" >> "$SNAPSHOT_FILE"
    tail -n 30 "$file" >> "$SNAPSHOT_FILE"
    echo "" >> "$SNAPSHOT_FILE"
  done
else
  echo "*No recent episodic entries*" >> "$SNAPSHOT_FILE"
  echo "" >> "$SNAPSHOT_FILE"
fi

# Capture semantic (key knowledge)
echo "## Key Knowledge (Semantic)" >> "$SNAPSHOT_FILE"
echo "" >> "$SNAPSHOT_FILE"

semantic_files=$(find "$MEMORY_DIR/semantic" -name "*.md" | head -5)
if [ -n "$semantic_files" ]; then
  for file in $semantic_files; do
    echo "### $(basename "$file" .md)" >> "$SNAPSHOT_FILE"
    head -n 20 "$file" >> "$SNAPSHOT_FILE"
    echo "" >> "$SNAPSHOT_FILE"
  done
else
  echo "*No semantic entries*" >> "$SNAPSHOT_FILE"
  echo "" >> "$SNAPSHOT_FILE"
fi

# Capture procedural (important workflows)
echo "## Key Workflows (Procedural)" >> "$SNAPSHOT_FILE"
echo "" >> "$SNAPSHOT_FILE"

procedural_files=$(find "$MEMORY_DIR/procedural" -name "*.md" | head -3)
if [ -n "$procedural_files" ]; then
  for file in $procedural_files; do
    echo "### $(basename "$file" .md)" >> "$SNAPSHOT_FILE"
    head -n 20 "$file" >> "$SNAPSHOT_FILE"
    echo "" >> "$SNAPSHOT_FILE"
  done
else
  echo "*No procedural entries*" >> "$SNAPSHOT_FILE"
  echo "" >> "$SNAPSHOT_FILE"
fi

# Add metadata
cat >> "$SNAPSHOT_FILE" << EOF

---

**Snapshot metadata:**
- Created: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
- Trigger: Compression detection
- Coverage: Last 3 days episodic + top 5 semantic + top 3 procedural
- Purpose: Recovery checkpoint before potential memory loss
EOF

# Update state
if command -v jq >/dev/null 2>&1; then
  timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
  jq --arg ts "$timestamp" '.last_snapshot = $ts | .warnings += 1' "$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
fi

echo "✅ Snapshot saved: $SNAPSHOT_FILE"
echo ""
echo "Snapshot includes:"
echo "  - Last 3 days episodic entries"
echo "  - Top 5 semantic knowledge files"
echo "  - Top 3 procedural workflows"
echo ""
echo "Next steps:"
echo "  1. Review snapshot for completeness"
echo "  2. Run: organize.sh (reduce memory usage)"
echo "  3. Consider pruning old episodic entries"

#!/bin/bash
# Memory Stats - Professional memory architecture statistics

WORKSPACE="${OPENCLAW_WORKSPACE:-$HOME/.openclaw/workspace}"
MEMORY_DIR="$WORKSPACE/memory"
STATE_FILE="$MEMORY_DIR/.memory-manager-state.json"

echo "📊 Memory Manager - Statistics"
echo ""

# Count files and sizes by type
count_stats() {
  local dir="$1"
  local count=$(ls "$dir"/*.md 2>/dev/null | wc -l | tr -d ' ')
  local size=$(du -sh "$dir" 2>/dev/null | cut -f1)
  echo "$count|$size"
}

episodic_stats=$(count_stats "$MEMORY_DIR/episodic")
semantic_stats=$(count_stats "$MEMORY_DIR/semantic")
procedural_stats=$(count_stats "$MEMORY_DIR/procedural")
snapshots_stats=$(count_stats "$MEMORY_DIR/snapshots")

episodic_count=$(echo "$episodic_stats" | cut -d'|' -f1)
episodic_size=$(echo "$episodic_stats" | cut -d'|' -f2)

semantic_count=$(echo "$semantic_stats" | cut -d'|' -f1)
semantic_size=$(echo "$semantic_stats" | cut -d'|' -f2)

procedural_count=$(echo "$procedural_stats" | cut -d'|' -f1)
procedural_size=$(echo "$procedural_stats" | cut -d'|' -f2)

snapshots_count=$(echo "$snapshots_stats" | cut -d'|' -f1)
snapshots_size=$(echo "$snapshots_stats" | cut -d'|' -f2)

# Display breakdown
echo "## Memory Architecture Breakdown"
echo ""
echo "📅 Episodic Memory (What Happened):"
echo "   Files: $episodic_count"
echo "   Size: ${episodic_size:-0B}"
echo ""
echo "🧠 Semantic Memory (What You Know):"
echo "   Files: $semantic_count"
echo "   Size: ${semantic_size:-0B}"
echo ""
echo "⚙️  Procedural Memory (How To):"
echo "   Files: $procedural_count"
echo "   Size: ${procedural_size:-0B}"
echo ""
echo "💾 Snapshots (Backups):"
echo "   Files: $snapshots_count"
echo "   Size: ${snapshots_size:-0B}"
echo ""

# Total
total_files=$((episodic_count + semantic_count + procedural_count))
total_size=$(du -sh "$MEMORY_DIR" 2>/dev/null | cut -f1)

echo "📦 Total:"
echo "   Files: $total_files"
echo "   Size: ${total_size:-0B}"
echo ""

# Compression events
if [ -f "$STATE_FILE" ] && command -v jq >/dev/null 2>&1; then
  warnings=$(jq -r '.warnings // 0' "$STATE_FILE")
  last_check=$(jq -r '.last_check // "never"' "$STATE_FILE")
  last_snapshot=$(jq -r '.last_snapshot // "never"' "$STATE_FILE")
  last_organize=$(jq -r '.last_organize // "never"' "$STATE_FILE")
  
  echo "## Activity"
  echo ""
  echo "Compression events: $warnings"
  echo "Last check: $last_check"
  echo "Last snapshot: $last_snapshot"
  echo "Last organize: $last_organize"
  echo ""
fi

# Growth rate (episodic entries in last 7 days)
recent_episodic=$(find "$MEMORY_DIR/episodic" -name "*.md" -mtime -7 2>/dev/null | wc -l | tr -d ' ')
echo "## Growth"
echo ""
echo "Episodic entries (last 7 days): $recent_episodic"
echo "Average: $((recent_episodic / 7)) entries/day"
echo ""

# Health check
total_chars=0
for dir in episodic semantic procedural; do
  chars=$(find "$MEMORY_DIR/$dir" -name "*.md" -exec wc -c {} + 2>/dev/null | tail -1 | awk '{print $1}' || echo 0)
  total_chars=$((total_chars + chars))
done

usage_pct=$((total_chars * 100 / 800000))

echo "## Memory Health"
echo ""
if [ "$usage_pct" -ge 85 ]; then
  echo "Status: 🚨 CRITICAL (${usage_pct}%)"
  echo "Action: Run organize.sh and snapshot.sh NOW"
elif [ "$usage_pct" -ge 70 ]; then
  echo "Status: ⚠️ WARNING (${usage_pct}%)"
  echo "Action: Consider running organize.sh"
else
  echo "Status: ✅ Healthy (${usage_pct}%)"
  echo "Action: None needed"
fi