Enhanced Memory

---

name: enhanced-memory description: > An enhanced memory system for OpenClaw agents that replaces the default single-file MEMORY.md with a complete memory architecture: hierarchical directory organization by category, [category:value] tag indexing with multi-tag AND search, automatic lifecycle management (active → archive, never delete), and intelligent cross-category retrieval that auto-routes queries to the right memory module. Gives your agent structured, searchable, long-lived memory out of the box.

---

Enhanced Memory

A structured memory system that gives your OpenClaw agent organized, searchable, long-lived memory instead of a single monolithic MEMORY.md.

Why?

The default MEMORY.md approach hits a wall fast:

One file grows endlessly → slow to read, expensive on tokens

No categorization → food logs mixed with project notes mixed with relationship context

No retrieval strategy → agent re-reads everything or misses what matters

No lifecycle → old entries clutter active memory forever

Tagged Memory fixes all of this.

Core Features

1. Hierarchical Directory Organization

Memories are stored in purpose-built directories:

memory/
├── current/          # Active memories (last 6 months)
├── archived/         # Auto-archived older memories (permanent, never deleted)
│   └── YYYY-MM/      # Organized by month
├── RELATION/         # One file per person (relationship context)
├── food/             # Meal and food logs
├── training/         # Exercise and workout records
├── connections.md    # Global relationship graph
├── system/           # System config and logs
└── misc/             # Everything else

2. Tag-Based Indexing

Tag any line in any memory file with [category:value] markers:

## 2026-02-20
Had lunch with Zhang Hao [人物:张浩东] [类型:聚餐] [地点:campus]
Discussed the new project deadline [项目:openclaw] [类型:会议]
Yoyo learned a new trick today [宠物:悠悠] [类型:milestone]

Tags support multi-tag AND search — find the exact memory you need:

# Single tag search
python3 scripts/memory_tag_search.py "人物:张浩东"
Multi-tag AND search (all tags must match)
python3 scripts/memory_tag_search.py "人物:王隆哲" "类型:开票信息"
List all tags in the system
python3 scripts/memory_tag_search.py --list-tags
List tags under a specific category
python3 scripts/memory_tag_search.py --list-tags --category 人物

3. Lifecycle Management

Memories age gracefully — never lost, always accessible:

| Age | Location | Status | |-----|----------|--------| | 0–6 months | memory/current/ | Active, auto-retrieved | | 6–12 months | memory/archived/YYYY-MM/ | Archived, searchable on demand | | 12+ months | memory/archived/ | Permanent archive, manual query |

Run the lifecycle manager manually or via cron:

# Default: archive memories older than 6 months
python3 scripts/memory_lifecycle_manager.py
Custom threshold (e.g., 90 days)
python3 scripts/memory_lifecycle_manager.py 90

4. Smart Cross-Category Retrieval

The retrieval strategy script auto-classifies queries and searches the right directories:

python3 scripts/memory_retrieval_strategy.py "What did I eat yesterday?"
→ Searches memory/food/ + memory/current/
python3 scripts/memory_retrieval_strategy.py "How is Yoyo doing?"
→ Searches memory/RELATION/悠悠.md + memory/connections.md
python3 scripts/memory_retrieval_strategy.py "Yang Lingxiao"
→ Searches memory/RELATION/ + memory/connections.md

Query type detection covers: food, training, relationships, pets, system, mood, projects, and more.

Scripts

| Script | Purpose | |--------|---------| | scripts/memory_tag_search.py | Tag-based indexing and search (single/multi-tag AND queries, tag listing) | | scripts/memory_retrieval_strategy.py | Smart retrieval — auto-classifies queries and routes to relevant memory directories | | scripts/memory_lifecycle_manager.py | Automatic archival of old memories (configurable threshold, never deletes) |

Integration

AGENTS.md

Add the following to your AGENTS.md memory section:

## Memory
Directory Structure
memory/current/ — active memories (6 months)
memory/archived/ — permanent archive
memory/RELATION/ — per-person relationship files
memory/food/ — meal logs
memory/training/ — workout logs
Retrieval Strategy
Exact queries (names, dates, codes) → grep the file system
Fuzzy/semantic queries → python3 scripts/memory_retrieval_strategy.py ""
Tag search → python3 scripts/memory_tag_search.py ":"
Tagging Convention
When writing memory entries, tag important lines:
  [人物:name] [类型:type] [地点:place] [项目:project] [情绪:mood]

HEARTBEAT.md

Add periodic memory maintenance to your heartbeat checklist:

## Memory Maintenance (every few days)
[ ] Run python3 scripts/memory_lifecycle_manager.py to archive old memories
[ ] Run python3 scripts/memory_tag_search.py --list-tags to review tag health
[ ] Check memory/current/ file count — if growing large, verify archival is running

Cron (optional)

Set up monthly auto-archival:

# Run on the 1st of every month at 03:00
0 3 1 * * cd /path/to/workspace && python3 scripts/memory_lifecycle_manager.py

Customization

Archive threshold: Edit ARCHIVE_THRESHOLD_DAYS in memory_lifecycle_manager.py (default: 180 days)

Query patterns: Add new regex patterns to QUERY_TYPES in memory_retrieval_strategy.py

Memory directories: Add new modules to MODULES_TO_ARCHIVE in memory_lifecycle_manager.py

Tag categories: Tags are freeform — just use [category:value] in any .md file

Requirements

Python 3.8+

No external dependencies (stdlib only)