MemoryMesh 🧠

---
name: memorymesh
description: A lightweight, token-efficient hierarchical memory system for AI agents. Manages session context, daily logs, and long-term memory with local-first processing, semantic indexing, and minimal AI model dependency. Use when agents need persistent memory across sessions, task tracking, decision logging, or user preference storage. Supports automatic memory compaction, versioned upgrades, and cross-agent skill reuse.
---

# MemoryMesh 🧠

**Version**: 2.0.2  
**Codename**: "Echo"  
**Architecture**: Hierarchical Local-First Memory System

## What's New in v2.0.2

### 🔧 Bug Fixes
- **Chinese Search Support**: Fixed `mm_query.py --local` to properly handle Chinese queries
  - Added UTF-8 encoding for all file read operations (`encoding='utf-8'`)
  - Added support for Chinese date keywords: "今日", "今天", "today"
  - Added Chinese keyword extraction in semantic search (2+ character words)
  - Enhanced error messages with file-specific warnings
  - Improved match type reporting (date match vs content match)

## What's New in v2.0.1

### 🔒 Security Improvements
- **Content Length Limit**: Max 100KB per entry (DoS protection)
- **File Size Limit**: Max 10MB per file (storage protection)
- **Filename Whitelist**: Only allow `tasks.md`, `decisions.md`, `facts.md`, `preferences.md`
- **Sensitive Data Filtering**: Auto-filter passwords, API keys, secrets, tokens, credit cards
  - `password: xxx` → `[FILTERED_PASSWORD]`
  - `api_key: xxx` → `[FILTERED_API_KEY]`
  - `secret: xxx` → `[FILTERED_SECRET]`
  - `token: xxx` → `[FILTERED_TOKEN]`
  - Credit cards → `[FILTERED_CARD]`
  - OpenAI keys → `[FILTERED_SK_KEY]`

### 🐛 Bug Fixes
- Fixed missing `get_memory_base()` function in `mm_write.py`
- Removed unused `subprocess` import from `mm_query.py`
- Added proper error handling with return codes

## System Overview

MemoryMesh is a three-tier memory architecture designed for token efficiency and local processing priority. It minimizes AI model calls by using deterministic scripts for memory operations.

┌─────────────────────────────────────────────────────────────┐
│ TIER 3: Session Cache (Hot) │
│ - Active conversation context (~64k tokens) │
│ - Runtime-only, volatile │
│ - Auto-hydrated from daily logs on session start │
├─────────────────────────────────────────────────────────────┤
│ TIER 2: Daily Chronicle (Warm) │
│ - memory/chronicle/YYYY-MM-DD.md │
│ - 30-day sliding window, auto-compacted │
│ - Structured entries with metadata │
├─────────────────────────────────────────────────────────────┤
│ TIER 1: Core Archive (Cold) │
│ - memory/core/ENTITY.md (tasks, decisions, facts) │
│ - Indefinite retention, manual curation │
│ - Semantic index for fast retrieval │
└─────────────────────────────────────────────────────────────┘

## When to Use This Skill

Use MemoryMesh when you need to:
- Persist conversation context across session restarts
- Track tasks, decisions, and user preferences
- Query historical information from previous sessions
- Maintain a searchable knowledge base
- Share memory system across multiple agents

## Quick Start

### 1. Initialize MemoryMesh

```bash
# Run initialization (one-time setup)
python ~/.openclaw/skills/memorymesh/scripts/mm_init.py

# This creates:
# ~/.openclaw/workspace/memory/
# ├── chronicle/          # Daily logs
# ├── core/               # Long-term archive
# │   ├── tasks.md
# │   ├── decisions.md
# │   ├── facts.md
# │   └── entities/       # Per-entity files
# └── index/              # Semantic indices
#     ├── keywords.json
#     └── vectors/        # Optional vector cache

2. Write Memory (Deterministic Script)

# Add to daily chronicle
python scripts/mm_write.py \
  --tier chronicle \
  --content "User asked about Shenzhen high school entrance exam" \
  --tags "education,shenzhen,exam"

# Add to core archive
python scripts/mm_write.py \
  --tier core \
  --file tasks.md \
  --content "Task-20260412-001: Research Shenzhen exam policies" \
  --priority high

3. Query Memory (Local-First)

# Local grep search (no AI, instant)
python scripts/mm_query.py --local "shenzhen exam"

# Semantic search (uses embeddings only for core archive)
python scripts/mm_query.py --semantic "education policies" --limit 10

Architecture Deep Dive

Tier 3: Session Cache

Purpose: Maintain conversation continuity within a session

Implementation:

• Stored in runtime memory (not persisted)
• Hydrated from today's chronicle on session start
• Auto-summarized when exceeding token budget

Access Pattern:

# On session start, agent loads:
1. memory/core/tasks.md (active tasks)
2. memory/chronicle/$(date +%Y-%m-%d).md (today's context)

Tier 2: Daily Chronicle

Purpose: Capture session history with structured metadata

Format:

# Chronicle: 2026-04-12

## Entry: 2026-04-12T18:07:00+08:00
**Type**: conversation
**Tags**: shenzhen, education, exam
**Session**: 9494e22b-6c57-4a9b-acb5-7d5f088adc16

**Summary**: User asked about Shenzhen high school entrance exam policies.
Agent explained memory system limitations and offered to help.

**Key Points**:
- Topic: Shenzhen zhongkao (中考)
- User expectation: Memory of previous discussion
- Issue identified: Cross-session memory gap

**Decisions**:
- [ ] Design improved memory system (assigned)

Compaction Rules:

• Trigger: File size > 50KB OR age > 7 days
• Action: Summarize entries, move details to core archive
• Preserve: Task states, decisions, unresolved items

Tier 1: Core Archive

Purpose: Long-term storage for high-value information

Files:

File	Content	Update Frequency
tasks.md	Active and completed tasks	Per task change
decisions.md	Key decisions with rationale	Per decision
facts.md	Verified facts about user/domain	As discovered
entities/*.md	Per-entity files (people, projects)	As needed

Schema for tasks.md:

## Task Registry

### Active

#### T-20260412-001: Memory System Optimization
**Status**: 🔄 In Progress  
**Priority**: High  
**Created**: 2026-04-12  
**Due**: 2026-04-13  

**Description**: Design and implement token-efficient memory system  
**Acceptance Criteria**:
- [ ] Architecture document
- [ ] Core scripts implemented
- [ ] Skill packaging complete
- [ ] GitHub repository created

**Related**: T-20260327-001 (Polymarket audit)

### Completed

#### T-20260410-001: Example completed task
**Status**: ✅ Done  
**Completed**: 2026-04-10  
**Outcome**: [summary]

Token Efficiency Design

Principle: Local Processing First

Operation	Local	AI Model	Token Savings
Write chronicle	✅ Bash script	❌	~500 tokens/op
Grep search	✅ ripgrep	❌	~1000 tokens/query
File listing	✅ ls/find	❌	~200 tokens
Archive compaction	✅ Python	❌ (summarize only)	~2000 tokens/file
Semantic indexing	✅ Local embeddings	❌ (API only)	~500 tokens/doc

Key Optimizations

1. Deterministic Scripts: All CRUD operations use local scripts
2. Lazy Loading: Core archive files loaded on-demand
3. Semantic Index: Pre-computed keyword index for fast filtering
4. Incremental Updates: Only changed entries trigger re-indexing
5. Compression: Old chronicles gzip-compressed after 30 days

Script Reference

All scripts in scripts/ are designed for local execution without AI model calls.

mm_write.py

usage: mm_write.py [-h] --tier {chronicle,core} --content CONTENT
                   [--file FILE] [--tags TAGS] [--priority {low,medium,high}]

Write entry to memory system

options:
  -h, --help            show this help message and exit
  --tier {chronicle,core}
                        Target memory tier
  --content CONTENT     Entry content (plaintext or markdown)
  --file FILE           Target file for core tier (default: auto)
  --tags TAGS           Comma-separated tags
  --priority {low,medium,high}
                        Entry priority (core tier only)

mm_query.py

usage: mm_query.py [-h] [--local QUERY] [--semantic QUERY] [--limit N]
                   [--since DATE] [--tags TAGS]

Query memory system

options:
  -h, --help            show this help message and exit
  --local QUERY         Local grep search (fast, no tokens)
  --semantic QUERY      Semantic search (uses embeddings)
  --limit N             Max results (default: 10)
  --since DATE          Filter entries after date (YYYY-MM-DD)
  --tags TAGS           Filter by tags (comma-separated)

mm_compact.py

usage: mm_compact.py [-h] [--dry-run] [--force]

Compact old chronicles and archive completed tasks

options:
  -h, --help   show this help message and exit
  --dry-run    Preview changes without applying
  --force      Skip confirmation prompts

mm_migrate.py

usage: mm_migrate.py [-h] --from-version VERSION --to-version VERSION

Migrate memory schema between versions

options:
  -h, --help           show this help message and exit
  --from-version VERSION
                       Current schema version
  --to-version VERSION
                       Target schema version

Integration with Agents

For Skill Users (Other Agents)

When an agent uses MemoryMesh:

1. On Session Start:

   # Auto-loaded by OpenClaw AGENTS.md rules
   # No action needed - context hydrated automatically

2. During Conversation:

   # To remember something important:
   exec("python ~/.openclaw/skills/memorymesh/scripts/mm_write.py \
         --tier core --file facts.md \
         --content 'User prefers concise answers'")

3. To Recall Information:

   # Local search (preferred):
   result = exec("python scripts/mm_query.py --local 'shenzhen exam'")
   
   # If no results, try semantic:
   result = exec("python scripts/mm_query.py --semantic 'education'")

For Memory System Developers

To extend MemoryMesh:

1. Add New Core Files: Create in memory/core/ following existing schema
2. Custom Scripts: Add to scripts/ with mm_ prefix
3. Schema Migrations: Use mm_migrate.py pattern for upgrades
4. Version Bumping: Update version in:
   • SKILL.md frontmatter
   • scripts/mm_version.py
   • Git tag

Version History

Version	Codename	Date	Changes
2.0.2	Echo	2026-04-12	Chinese search fix, UTF-8 encoding, Chinese date keywords
2.0.1	Echo	2026-04-12	Security enhancement, content limits, sensitive data filtering
2.0.0	Echo	2026-04-12	Complete rewrite, local-first architecture, skill packaging
1.0.0	Genesis	2026-03-28	Initial memory system (flat structure)

Migration from Legacy System

If upgrading from MemoryMesh 1.x:

# Run migration script
python scripts/mm_migrate.py --from-version 1.0.0 --to-version 2.0.0

# This will:
# 1. Backup existing memory/ to memory/.backup-v1/
# 2. Create new directory structure
# 3. Migrate MEMORY.md → core/tasks.md, core/decisions.md
# 4. Migrate memory/*.md → chronicle/
# 5. Generate semantic index

GitHub Repository Structure

memorymesh/
├── README.md              # User-facing documentation
├── LICENSE                # MIT License
├── SKILL.md               # This file (for OpenClaw)
├── CHANGELOG.md           # Version history
├── scripts/
│   ├── mm_init.py
│   ├── mm_write.py
│   ├── mm_query.py
│   ├── mm_compact.py
│   ├── mm_migrate.py
│   └── mm_version.py
├── references/
│   ├── ARCHITECTURE.md    # Detailed technical spec
│   ├── API.md             # Script API reference
│   └── SCHEMA.md          # Data schemas
└── examples/
    └── demo_session.md    # Example memory files

License

MIT License - See LICENSE file for details.

**操作步骤**：
1. 访问 https://github.com/tplove2010/memorymesh/edit/main/SKILL.md
2. 全选内容，粘贴上面的完整内容
3. 提交更改，Commit message: `docs: Update SKILL.md to v2.0.2`