Enhanced Memory

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.

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: AgeLocationStatus0–6 monthsmemory/current/Active, auto-retrieved6–12 monthsmemory/archived/YYYY-MM/Archived, searchable on demand12+ monthsmemory/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

ScriptPurposescripts/memory_tag_search.pyTag-based indexing and search (single/multi-tag AND queries, tag listing)scripts/memory_retrieval_strategy.pySmart retrieval — auto-classifies queries and routes to relevant memory directoriesscripts/memory_lifecycle_manager.pyAutomatic archival of old memories (configurable threshold, never deletes)

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 "<query>"`
• Tag search → `python3 scripts/memory_tag_search.py "<category>:<value>"`
• ### 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)