context-memory

# 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

```bash
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

```bash
# 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:

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

Search archived conversations:

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

### Track Satisfaction

Record user reactions:

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

Signals: `negative`, `positive`, `interested`

Generate daily insights:

```bash
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:

```bash
# 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:

```bash
# 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):

```json
{
  "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.