Rune - Persistent AI Memory System

Rune gives your OpenClaw agent persistent, intelligent memory that gets better over time. No more burning tokens on static context files or forgetting important information between sessions.

What Rune Does

🧠 Smart Memory Management

Dynamic Context Injection: AI selects only relevant facts for each conversation
Access Pattern Learning: Frequently used facts get prioritized
Forgetting Curves: Unused facts naturally fade like human memory
Memory Consolidation: Similar facts get merged, verbose ones compressed

🎯 Session Intelligence

Interaction Style Detection: Learns if you prefer brainstorm vs deep-work vs debug modes
Behavioral Pattern Analysis: Tracks your work patterns and preferences over time
Proactive Memory: Volunteers relevant context unprompted ("last time you worked on this...")

📋 Project Autopilot

Smart Task Recommendations: "What should I work on next?" with priority scoring
Blocker Detection: Identifies stuck projects that need intervention
Project Health Scoring: 0.0-1.0 health scores based on activity and progress

📢 Intelligent Notifications

Priority Classification: Critical/High/Medium/Low/FYI with context analysis
Smart Timing: Respects quiet hours, batches low-priority updates
Channel Routing: DM for urgent, Discord for projects, digest for FYI

🔄 Self-Improvement Loop

Pattern Detection: "Forgot to use X skill 3 times" → automatic escalation
Performance Tracking: Measurable improvement over time
Skill Usage Analysis: Which skills you use vs neglect

About Rune vs rune

Rune is the OpenClaw skill name. rune is the CLI tool name. Think of Rune as the "skill package" and rune as the "command-line interface" - like how the git skill package provides the git CLI.

Skill name: rune (what you install via ClawHub)
CLI command: rune (what you run in terminal)
Repository: https://github.com/TheBobLoblaw/rune

Installation Disclosure

⚠️ What This Installation Does:

The Rune skill installation will:

Create directories: ~/.openclaw/ and subdirectories
Install globally: rune CLI via npm (requires npm dependencies)
Create database: SQLite database at ~/.openclaw/memory.db
Modify files: Appends integration lines to existing ~/.openclaw/workspace/HEARTBEAT.md
Add session hooks: Automatic memory integration for OpenClaw sessions

Before installing:

Back up HEARTBEAT.md if it contains important data
Review package.json dependencies if security is critical
Consider using local models (Ollama) instead of cloud APIs for privacy

Installation

# Via ClawHub (recommended)
clawhub install rune

# Manual installation
git clone https://github.com/TheBobLoblaw/rune
cd rune
npm install --production
npm install -g .

Quick Start

# Initialize memory system
rune stats

# Add your first fact
rune add person cory.name "Cory - my human user"

# Generate context for a conversation  
rune context "Let's work on the website"

# Get task recommendations
rune next-task

# Weekly self-review
rune self-review --days 7

Core Commands

Memory Management

rune add <category> <key> <value> - Store a fact
rune search <query> - Find facts
rune recall <topic> - Smart multi-source recall
rune inject - Generate context file for agent

Intelligence Features

rune context <message> - Dynamic context for message
rune score <message> - Relevance scoring
rune proactive <message> - Volunteer relevant context
rune session-style <message> - Detect interaction style

Project Management

rune project-state <name> - Track project phases/blockers
rune next-task - Smart task picker
rune stuck-projects - Find blocked work

Advanced Features

rune temporal "last Tuesday" - Time-based queries
rune consolidate - Memory optimization
rune forget - Apply forgetting curves
rune pattern-analysis - Detect behavioral patterns

Integration with OpenClaw

Heartbeat Integration

Add to your HEARTBEAT.md:

# Memory maintenance
rune expire && rune inject --output ~/.openclaw/workspace/FACTS.md

# Proactive work selection
NEXT_TASK=$(rune next-task --json)
if [[ "$NEXT_TASK" != "null" ]]; then
  # Work on the recommended task
fi

Session Hooks

The skill automatically provides secure session hooks via OpenClaw integrations.

For manual usage, use the secure session handler:

# Secure session hooks (input sanitized automatically)
./rune-session-handler.sh start   # Loads dynamic context safely
./rune-session-handler.sh end     # Tracks session style safely

# Direct usage (SECURE - input is sanitized):
SAFE_MESSAGE=$(echo "$MESSAGE" | head -c 200 | tr -d '`$(){}[]|;&<>' | sed 's/[^a-zA-Z0-9 ._-]//g')
rune recall "$SAFE_MESSAGE" --limit 10

⚠️ Security Note: Never pass unsanitized user input directly to shell commands. Always use the provided session handler or sanitize input manually.

Architecture

SQLite Database: All memory stored in ~/.openclaw/memory.db
Local LLM Integration: Ollama for relevance scoring and extraction
Cloud API Support: Anthropic, OpenAI for advanced reasoning
Local-First Design: Works completely offline with Ollama (cloud APIs optional for advanced features)

Memory Categories

person: Information about people (names, roles, preferences)
project: Project status, phases, decisions
tool: How to use tools and their quirks
lesson: Mistakes to avoid, best practices
decision: Why certain choices were made
preference: User likes/dislikes, settings
environment: System configs, non-sensitive settings (⚠️ NEVER store credentials!)

⚠️ Security & Privacy

Data Storage

What Rune Stores:

Facts you explicitly add via rune add
Session interaction patterns for learning (conversation style, not content)
Project states and task recommendations

What Rune Does NOT Store (by default):

Full conversation transcripts (unless you run extract manually)
API keys or credentials (use environment variables instead)
Sensitive personal information (unless you explicitly add it)

Installation Security

NPM Dependencies:

Installation fetches dependencies from npm registry at install time
Review package.json for dependencies if security is critical
Global npm install runs lifecycle scripts (standard npm behavior)
Consider installing in isolated environment (container/VM) for high-security use

Session Security:

Fixed CVE-2026-0001: Input sanitization prevents shell injection
All user input sanitized before shell execution
Session handler validates and limits input length

Cloud API Usage

Optional: Rune can use OpenAI/Anthropic APIs for fact extraction and scoring
Local-first: Works completely offline with Ollama (recommended for privacy)
Your choice: Configure which engines to use in your setup

Privacy Recommendations

Use local models (Ollama) for maximum privacy
Avoid cloud APIs if processing sensitive information
Review stored facts periodically with rune search
Never store credentials in memory - use environment variables

Privacy Best Practices:

Never run rune add with sensitive data (passwords, API keys, personal info)
Use rune extract carefully - review files before extracting facts
Configure Ollama for local-only operation if you want zero cloud usage
Review your ~/.openclaw/workspace/FACTS.md periodically

Installation Changes:

Adds memory maintenance commands to HEARTBEAT.md (if present)
Creates ~/.openclaw/memory.db database file
Session hooks may process conversation metadata (not full content) for learning

Performance Metrics

With Rune, your agent will:

✅ Remember context between sessions without burning tokens
✅ Pick relevant facts dynamically vs dumping everything
✅ Get measurably better at avoiding repeated mistakes
✅ Work autonomously on projects between check-ins
✅ Learn your interaction patterns and adapt responses

Advanced Configuration

# Tune relevance scoring
rune score "your query" --threshold 0.6 --model llama3.1:8b

# Configure forgetting curves  
rune forget --decay-rate 0.03 --grace-days 45

# Cross-session pattern analysis
rune cross-session --days 90 --min-sessions 5

Automated Maintenance & Performance

Rune performs best with regular maintenance. Here are automation strategies:

Cron Job Setup

Daily Maintenance (3 AM)

# Expire working memory and regenerate context
0 3 * * * /usr/local/bin/rune expire && /usr/local/bin/rune inject --output ~/.openclaw/workspace/FACTS.md

Weekly Optimization (Sunday 2 AM)

# Consolidate memory and run self-review
0 2 * * 0 /usr/local/bin/rune consolidate --auto-prioritize && /usr/local/bin/rune self-review --days 7

Monthly Deep Clean (1st of month, 1 AM)

# Pattern analysis and database optimization
0 1 1 * * /usr/local/bin/rune pattern-analysis --days 30 && sqlite3 ~/.openclaw/memory.db "VACUUM; ANALYZE;"

Database Backup

# Daily backup at 4 AM
0 4 * * * cp ~/.openclaw/memory.db ~/.openclaw/memory.db.backup.$(date +\%Y\%m\%d)
# Keep last 7 days
5 4 * * * find ~/.openclaw -name "memory.db.backup.*" -mtime +7 -delete

Performance Benefits

🧹 Memory stays lean: Auto-removes expired facts
⚡ Faster queries: Regular consolidation prevents bloat
📈 Self-improvement: Pattern detection catches recurring issues
🔄 Current context: FACTS.md regenerated with latest data
💾 Data protection: Automated backups prevent loss

Memory Health Monitoring

# Check database size and fact count
rune stats

# Review recent patterns
rune pattern-analysis --days 7

# Check consolidation opportunities  
rune consolidate --dry-run

Troubleshooting

Memory growing too large?

Run rune consolidate to merge similar facts
Use rune forget to apply forgetting curves
Check rune stats for database size

Relevance scoring not working?

Ensure Ollama is running: systemctl status ollama
Test model: rune score "test" --engine ollama
Fall back to anthropic/openai engines

Context injection too verbose?

Lower relevance threshold: --threshold 0.6
Use token budgeting: rune budget "query" --tokens 300

Contributing

Rune is open source. Contributions welcome:

Memory Science: Better consolidation algorithms, forgetting curves
LLM Integration: New scoring engines, extraction methods
UI/UX: Better command interfaces, visualization tools
Performance: Speed optimizations, memory efficiency

License

MIT License - Use freely, modify as needed.

Rune: Because your AI should remember like you do.