openclaw/memory-persistence

🧠 Memory System

A flexible memory system for AI agents with optional embedding support and multiple storage backends.

Features

• Private & Shared Memories - Private by default, shared memories for multi-agent collaboration
• Embedding Search - Semantic search using sentence-transformers
• Multiple Backends - Local file / SQLite / GitHub / Gitee
• LLM Summarization - Auto-extract key info from conversations
• Memory Maintenance - Review, consolidate, tag suggestions
• Templates - Quick memory creation with templates

Installation

pip install sentence-transformers scikit-learn pyyaml numpy

Quick Start

Python API

from memory_system import MemoryManager

# Initialize (local storage)
mm = MemoryManager(backend='local')

# Add 
mm.add("User prefers dark theme", tags=["preference"])

# Search
results = mm.search("dark theme preference")

# List
entries = mm.list(tags=["preference"])

CLI

# Add 
python3 memory_cli.py add "User feedback: slow page load" --tags "bug,performance"

# List
python3 memory_cli.py list

# Search
python3 memory_cli.py -e search "performance issue"

# Semantic search (with embedding)
python3 memory_cli.py -e search "dark mode"

Private vs Shared Memory

| Type | Storage | Access | Use Case | |------|---------|--------|----------| | Private | ./memory_data/ | Current agent only | User preferences, personal notes | | Shared | ./shared_memory/ | All agents | Team decisions, collaboration |

Default: All memories are private. Use shared add only when other agents need to know.

# Private memory - user says "remember..."
mm.add("User name is Zhang San")

# Shared memory - user says "tell other agents..."
smm.add("Team decision: use React", agent_id="agent_a")

Storage Backends

Local (Default)

mm = MemoryManager(backend='local')

SQLite (High Performance)

mm = MemoryManager(backend='sqlite', base_path='./memory.db')

GitHub

export GITHUB_TOKEN="your_token"

mm = MemoryManager(
    backend='github',
    repo='owner/repo',
    branch='main'
)

Gitee

export GITEE_TOKEN="your_token"

mm = MemoryManager(
    backend='gitee',
    repo='owner/repo',
    branch='master'
)

Embedding & Semantic Search

Embedding is optional and auto-downloads on first use.

# Enable embedding
mm = MemoryManager(backend='local', use_embedding=True)

# Add (auto-generates vector)
mm.add("User works from 9am to 6pm")

# Semantic search - finds similar content
results = mm.search("what time does user work")

CLI with embedding:

python3 memory_cli.py -e search "working hours"

Shared Memory (Multi-Agent)

from memory_system import SharedMemoryManager

# Initialize
smm = SharedMemoryManager(backend='local', shared_path='./shared_memory')

# Add shared memory (from an agent)
smm.add("Bug #123 fixed", agent_id='agent_b')

# List shared memories
shared = smm.list()

# By agent
by_agent = smm.get_by_agent('agent_b')

CLI:

# Add shared 
python3 memory_cli.py shared add "Team decision: use Vue" --agent "agent_a"

# List
python3 memory_cli.py shared list

# Search
python3 memory_cli.py -e shared search "Vue decision"

Conversation Summarization

Auto-extract key information from conversation history.

from memory_system import MemoryManager, MemorySummarizer, ConversationMemoryProcessor

mm = MemoryManager(use_embedding=True)
summarizer = MemorySummarizer()  # Auto-detects OpenClaw model
processor = ConversationMemoryProcessor(mm, summarizer, auto_save=True)

conversation = """
User: I prefer dark theme
Assistant: Changed to dark theme
User: Page loads slowly
Assistant: Optimized images
"""

memories = processor.process(conversation)

CLI:

python3 memory_cli.py summarize --file conversation.txt --save

Memory Maintenance

# Generate report
python3 memory_cli.py maintenance report

# Review old memories
python3 memory_cli.py maintenance review --days 7

# Find similar memories
python3 memory_cli.py maintenance consolidate

# Suggest tags for untagged memories
python3 memory_cli.py maintenance suggest-tags

# Mark as outdated
python3 memory_cli.py maintenance outdated --mark <id> --reason "expired"

Templates

Predefined formats for quick memory creation.

# List templates
python3 memory_cli.py template list

# Show template
python3 memory_cli.py template show task

# Use template
python3 memory_cli.py template use task \
  --field title="Complete report" \
  --field priority="high"

Memory Groups

Organize memories into groups.

# Add to group
python3 memory_cli.py add "work task" --tags "work" --group "work"

# List groups
python3 memory_cli.py group list

# Show group
python3 memory_cli.py group show "work"

Batch Operations

# Batch add tags
python3 memory_cli.py batch-add-tags id1,id2 --tags "important,priority"

# Batch delete (requires confirmation)
python3 memory_cli.py batch-delete id1,id2 --force

API Reference

MemoryManager

| Method | Description | |--------|-------------| | add(content, tags, metadata, group) | Add memory | | get(id) | Get by ID | | delete(id) | Delete | | list(tags, limit, offset) | List with pagination | | search(query, tags, top_k, threshold) | Search | | batch_delete(ids) | Batch delete | | list_groups() | List groups | | export_json(filepath) | Export JSON |

SharedMemoryManager

| Method | Description | |--------|-------------| | add(content, agent_id, tags) | Add shared memory | | list(tags) | List shared | | get_by_agent(agent_id) | By agent | | search(query) | Search shared |

Files Structure

memory_system/
├── memory_manager.py   # Core manager
├── shared_memory.py    # Shared 
├── summarizer.py      # LLM summarization
├── maintenance.py      # Maintenance tools
├── templates.py       # Templates
├── embedding.py       # Embedding handler
├── storage/           # Storage backends
│   ├── local.py
│   ├── sqlite.py
│   ├── github.py
│   └── gitee.py
└── memory_cli.py         # CLI entry (run with python3)

Configuration

config.yaml:

STORAGE_BACKEND: "local"

USE_EMBEDDING: false
EMBEDDING_MODEL: "sentence-transformers/all-MiniLM-L6-v2"

storage:
  local:
    base_path: "./memory_data"
  sqlite:
    base_path: "./memory.db"
  github:
    repo: "owner/repo"
    token_env: "GITHUB_TOKEN"
  gitee:
    repo: "owner/repo"
    token_env: "GITEE_TOKEN"

License

MIT