Autonomous Memory Skill

README

# Autonomous Memory Skill for OpenClaw

> **Zero-dependency autonomous memory for AI agents.** Store experiences, retrieve by semantic similarity, learn from past mistakes — all in pure JavaScript.

## Why

Every OpenClaw agent starts fresh. No memory of:
- Which skill worked for a task
- Errors made and how they were fixed  
- User preferences and project context
- Domain knowledge accumulated over sessions

This skill changes that.

## Features

| Feature | Description |
|---------|-------------|
| 🔍 **Semantic Retrieval** | 128-dim vector embeddings for meaning-based search |
| 📝 **Zero Dependencies** | Pure JS, no ML models or external services |
| ⚡ **Fast Setup** | One command to initialize, one to store, one to retrieve |
| 🔄 **Multi-Agent Sync** | Git-based shared memory across team agents |
| 📉 **Optional Decay** | Old memories fade, fresh ones stay relevant |
| 🧠 **Context Compression** | Retrieved memories inject as 30-char summaries |

## Quick Start

```bash
# 1. Clone
https://github.com/shumi-123/autonomous-memory-skill.git

# 2. Copy to your OpenClaw workspace
mkdir -p ~/.openclaw/workspace/skills/autonomous-memory
cp -r autonomous-memory-skill/* ~/.openclaw/workspace/skills/autonomous-memory/

# 3. Initialize memory store
cd ~/.openclaw/workspace
node skills/autonomous-memory/scripts/memory-manager.js init

# 4. Store your first memory
node skills/autonomous-memory/scripts/memory-manager.js store \
  --content "Always check installed skills before using generic APIs" \
  --tags "skill,workflow,tool-selection"

# 5. Retrieve relevant memories
node skills/autonomous-memory/scripts/memory-manager.js retrieve \
  --query "which tool should I use" \
  --threshold 0.7 \
  --topK 3
```

## Use Cases

### 1. Skill Discovery
```bash
# Store
node scripts/memory-manager.js store \
  --content "tencent-channel-cli has QQ channel posting permissions" \
  --tags "skill,qqbot,tencent-channel"

# Later, when facing a similar task
node scripts/memory-manager.js retrieve \
  --query "how to post in QQ channel"
# → Returns the correct skill automatically
```

### 2. Error Prevention
```bash
# Store mistake + correction
node scripts/memory-manager.js store \
  --content "Spent 35min debugging permissions because I used the wrong tool" \
  --tags "error,qqbot,permissions,tool-selection"

# Before repeating the same mistake
node scripts/memory-manager.js retrieve \
  --query "qqbot permission error"
# → Warns about the previous error
```

### 3. User Preferences
```bash
# Store preference
node scripts/memory-manager.js store \
  --content "Boss prefers structured task templates with WHY, INPUT, OUTPUT, DONE" \
  --tags "context,boss-preference,task-management"

# Before generating output
node scripts/memory-manager.js retrieve \
  --query "how does boss like tasks formatted"
# → Returns formatting preference
```

## Memory Types

| Type | Tag | Example |
|------|-----|---------|
| **Skill** | `skill` | Tool usage patterns, API workflows |
| **Error** | `error` | Mistakes and corrections |
| **Context** | `context` | User preferences, project state |
| **Fact** | `fact` | Domain knowledge |

## Configuration

Edit `references/config-reference.md` or set environment variables:

| Setting | Default | Description |
|---------|---------|-------------|
| `similarityThreshold` | 0.6 | Min cosine similarity for retrieval |
| `topK` | 10 | Max memories per query |
| `maxMemoryItems` | 1000 | Auto-prune oldest when exceeded |
| `decayEnabled` | false | Fade old memories over time |
| `decayHalfLifeDays` | 30 | Days for memory weight to halve |

## Context Compression Rules

To prevent context bloat:

1. **Query-specific retrieval** — Don't load all memories, only relevant ones
2. **Strict filtering** — threshold ≥ 0.65, topK ≤ 5
3. **Summary injection** — Max 30 chars per memory, max 200 chars total
4. **Auto-prune** — Weekly `prune --keep 500`

## Multi-Agent Sync (Teams)

For teams with multiple AI agents:

```bash
# 1. Store memories in a shared Git repo
git clone <shared-repo>
cp autonomous-memory.json <shared-repo>/
git add . && git commit -m "memory update" && git push

# 2. Each agent pulls on startup
git pull origin main

# 3. Tag by agent
node scripts/memory-manager.js store \
  --content "Learned X" \
  --tags "skill,agent:seven"
```

See `references/multi-agent-sync.md` for full setup.

## Command Reference

```bash
memory-manager.js init                          # Create memory store
memory-manager.js store --content "..." [--tags "a,b"]    # Store memory
memory-manager.js retrieve --query "..." [--threshold 0.6] [--topK 10]  # Retrieve
memory-manager.js list [--tag "skill"] [--limit 20]        # List memories
memory-manager.js delete --id <memory-id>                   # Delete memory
memory-manager.js prune [--keep 1000]                       # Prune oldest
memory-manager.js stats                                   # Show stats
```

## Requirements

- Node.js >= 14
- OpenClaw workspace with `skills/` directory

## License

MIT

---

**Built by:** Seven (The Grinder) for the Triangular Collaboration Team  
**Team:** 摸鱼小哥 (Windows) | 唐娜 (Writing) | Seven (Linux)