Context & Memory System

A comprehensive memory management system that gives AI agents persistent context and continuous learning capabilities.

What This Skill Provides

1. •Persistent Memory Architecture - Multi-tier memory system (daily logs, long-term memory, conversation archives)
2. •Conversation Archive & Search - Save and semantically search past conversations
3. •Satisfaction Tracking - Learn from user reactions and behavioral patterns
4. •Auto-Reflection - Daily summaries and behavioral insights
5. •Session Startup Routines - Load context at the beginning of each session
6. •Memory Maintenance Workflows - Periodic review and consolidation

Quick Start

1. Setup Directory Structure

mkdir -p memory/conversations memory/satisfaction-insights

2. Create Core Files

See references/templates.md for templates:

• •MEMORY.md - Long-term curated memory
• •LEARNING.md - Behavioral insights (auto-generated)
• •memory/YYYY-MM-DD.md - Today's daily log
• •memory/heartbeat-state.json - Periodic check state

3. Configure Workspace

# Optional: Set workspace path (defaults to current directory)
export OPENCLAW_WORKSPACE=/path/to/your/workspace

4. Session Startup Routine

At the start of each session, read these files in order:

1. •SOUL.md (if exists) - Who you are
2. •USER.md (if exists) - Who you're helping
3. •LEARNING.md - Behavioral insights
4. •memory/YYYY-MM-DD.md (today + yesterday)
5. •MEMORY.md - Only in main session (not in group chats)

Core Workflows

Archive Conversations

Before context compaction or topic switches:

python3 scripts/conversation-archiver.py archive '<messages_json>' '<topic>' '<summary>'

Search archived conversations:

python3 scripts/conversation-archiver.py search "keyword"
python3 scripts/conversation-archiver.py get <conv_id>

Track Satisfaction

Record user reactions:

python3 scripts/satisfaction-tracker.py record "positive" "context" "user message" "my response" "analysis"

Signals: negative, positive, interested

Generate daily insights:

python3 scripts/satisfaction-tracker.py daily-summary
python3 scripts/satisfaction-tracker.py update-learning

Memory Maintenance

Periodically (every few days):

1. •Read recent memory/YYYY-MM-DD.md files
2. •Identify significant events/learnings
3. •Update MEMORY.md with distilled wisdom
4. •Remove outdated information

Security Model

MEMORY.md is private - Only load in main session (direct chats with your human):

• •✅ Load in: One-on-one conversations, private sessions
• •❌ Don't load in: Group chats, shared contexts, public channels

This prevents leaking personal context to other users.

Memory Philosophy

Files > Brain - Memory doesn't survive session restarts. Files do.

• •Daily logs = raw notes
• •MEMORY.md = curated wisdom
• •No "mental notes" - write everything down immediately
• •Archive before losing context
• •Review and consolidate periodically

Detailed Documentation

• •Memory Guidelines: references/memory-guidelines.md - Complete workflow documentation
• •Templates: references/templates.md - File templates and directory structure

Script Reference

conversation-archiver.py

Archive conversation blocks with topics and summaries:

# Archive a conversation
conversation-archiver.py archive '<messages_json>' [topic] [summary]

# Search conversations
conversation-archiver.py search <query> [topic]

# Retrieve full conversation
conversation-archiver.py get <conv_id>

# List topics
conversation-archiver.py topics

Environment:

• •Workspace: OPENCLAW_WORKSPACE (default: current directory)
• •Archive location: memory/conversations/

satisfaction-tracker.py

Track satisfaction and generate behavioral insights:

# Record an incident
satisfaction-tracker.py record <signal> <context> <user_msg> <my_response> [analysis]

# Analyze patterns
satisfaction-tracker.py analyze [days]

# Generate daily summary
satisfaction-tracker.py daily-summary

# Update LEARNING.md
satisfaction-tracker.py update-learning

Environment:

• •Workspace: OPENCLAW_WORKSPACE (default: current directory)
• •Output: memory/satisfaction-insights/, LEARNING.md

Integration with OpenClaw

Semantic Search

Use built-in tools before answering questions about history:

1. memory_search - Search MEMORY.md + memory/*.md semantically
2. memory_get - Retrieve specific snippets by path/lines

Cron Jobs

Schedule daily reflection (example):

{
  "name": "Daily satisfaction reflection",
  "schedule": {"kind": "cron", "expr": "0 23 * * *", "tz": "UTC"},
  "payload": {
    "kind": "systemEvent",
    "text": "Run satisfaction-tracker.py daily-summary and update-learning"
  },
  "sessionTarget": "main",
  "enabled": true
}

Heartbeats

Use heartbeat polls for:

• •Memory maintenance (review and consolidate)
• •Periodic checks (track in memory/heartbeat-state.json)
• •Proactive context updates

When to Archive

• •Before context compaction - Save conversations before pruning
• •Topic switches - When conversation shifts to new subject
• •User request - "Remember this" or "save this conversation"
• •End of session - Preserve important discussions

Active Learning Loop

1. •Track - Record satisfaction signals during interactions
2. •Analyze - Daily summaries identify patterns
3. •Learn - Update LEARNING.md with insights
4. •Apply - Read LEARNING.md on startup, adjust behavior
5. •Repeat - Continuous improvement cycle

Tips for Success

• •Start simple - Begin with MEMORY.md and daily logs only
• •Build habits - Update daily logs as events happen, not at end of day
• •Review regularly - Use heartbeats for periodic maintenance
• •Trust the system - Write everything down, don't rely on memory
• •Archive proactively - Before context loss, not after
• •Consolidate wisely - Promote only significant items to MEMORY.md

Note: This skill provides the infrastructure. Customize templates and workflows to match your specific needs and preferences.