# M2wise

> Memory-to-Wisdom Engine for AI companions. Use when building AI assistants that need long-term memory, extracting user preferences/facts from conversations, generating actionable wisdom, or tracking wisdom evolution.

- Skill: `zengyi-thinking/m2wise-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add zengyi-thinking/m2wise-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zengyi-thinking/m2wise-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zengyi-thinking (https://skillmd.com/u/zengyi-thinking)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zengyi-thinking/m2wise-2

---


# M2Wise - Memory-to-Wisdom Engine

> Enable AI companion robots to grow wisdom from experience

## What This Skill Does

M2Wise extracts memories from conversations and generates actionable wisdom that evolves over time. It's designed for AI companions that need persistent user understanding.

## When to Use

Use M2Wise when you need:
- Long-term user memory (preferences, facts, commitments)
- Personalized wisdom generation from accumulated interactions
- Self-improving AI behavior based on feedback
- Context-aware responses that remember user patterns

## Quick Reference

| Situation | Action |
|-----------|--------|
| User expresses preference | `engine.add()` → memory extracted as `preference` type |
| User provides factual info | `engine.add()` → memory extracted as `fact` type |
| Need contextual memory | `engine.search(query, user_id)` → returns memory + wisdom |
| Generate wisdom | `engine.sleep(user_id)` → creates wisdom drafts |
| Publish wisdom | `engine.dream(user_id)` → verifies and publishes |
| Check effectiveness | Automatic confidence tracking via Dream phase |

## Installation

### Prerequisites

```bash
# Python 3.11+
python3 --version

# Install M2Wise
pip install m2wise

# Or install with all features
pip install m2wise[all]
```

### Environment Setup

```bash
# Option 1: OpenAI
export OPENAI_API_KEY="sk-..."

# Option 2: SiliconFlow (recommended for Chinese)
export M2WISE_SILICONFLOW_API_KEY="sk-..."

# Option 3: Anthropic
export ANTHROPIC_API_KEY="sk-..."
```

### OpenClaw Integration

```bash
# Manual installation
git clone https://github.com/your-repo/m2wise.git ~/.openclaw/skills/m2wise

# Or via ClawHub
npx clawdhub@latest install m2wise
```

## Core Usage

### Basic Workflow

```python
from m2wise import M2Wise, M2WiseConfig

# Initialize
config = M2WiseConfig(data_dir="./m2wise_data")
engine = M2Wise(config=config)

# 1. Add conversation
engine.add(
    [{"role": "user", "content": "I prefer concise Chinese answers for technical questions"}],
    user_id="alice"
)

# 2. Search memories and wisdom
bundle = engine.search("How to debug Python?", user_id="alice")
print(bundle.as_prompt())

# 3. Generate wisdom (Sleep phase)
sleep_report = engine.sleep(user_id="alice")
print(f"Created {sleep_report.drafts_created} wisdom drafts")

# 4. Publish wisdom (Dream phase)
dream_report = engine.dream(user_id="alice")
print(f"Published {dream_report.published} wisdoms")
```

### SDK Usage (Recommended)

```python
from m2wise_sdk import M2WiseSDK

sdk = M2WiseSDK()

# Add messages
sdk.add_message("alice", "I'm a Python developer")
sdk.add_message("alice", "I prefer short responses")

# Get context
context = sdk.get_context("alice", "How should I answer?")

# Trigger wisdom generation
sdk.trigger_sleep("alice")
sdk.trigger_dream("alice")

# Get stats
stats = sdk.get_stats("alice")
```

## Memory Types

| Type | Description | Example |
|------|-------------|---------|
| `preference` | User's explicit preferences | "I like concise answers" |
| `fact` | Factual information | "User is a software engineer" |
| `explicit` | Direct memory requests | "Remember that I hate spam" |
| `commitment` | User commitments | "I will exercise every morning" |

## Wisdom Types

| Type | Description | Example |
|------|-------------|---------|
| `principle` | Interaction principles | "Prefer concise Chinese answers" |
| `schema` | Behavioral patterns | "Technical questions need examples" |
| `skill` | Operational skills | "Use tmux for long-running tasks" |
| `causal_hypothesis` | Causal assumptions | "User delays = task is low priority" |

## Three-Phase Evolution

```
┌────────────────────────────────────────────────────────────┐
│  Online → Sleep → Dream                                    │
│     ↓        ↓          ↓                                 │
│  Add/Search Extract    Verify & Publish                    │
│     ↓        ↓          ↓                                 │
│  Real-time  Memory      Counterexample                     │
│  Interaction Clustering Mining                            │
└────────────────────────────────────────────────────────────┘

Phase 1: Online (real-time)
  - engine.add() - Store conversation
  - engine.search() - Retrieve context

Phase 2: Sleep (consolidation)
  - engine.sleep() - Extract memories
  - Generate wisdom drafts from clusters

Phase 3: Dream (verification)
  - engine.dream() - Mine counterexamples
  - Verify and publish wisdom
  - Auto-evolve based on hit rates
```

## Configuration

```python
from m2wise import M2WiseConfig

config = M2WiseConfig(
    data_dir="./data",                    # Storage path
    embedder="siliconflow",              # openai, siliconflow, anthropic, local
    embedder_model="BAAI/bge-large-zh-v1.5",
    vector_store="faiss",                # faiss, qdrant, postgres
    similarity_threshold=0.7,            # Retrieval threshold
    max_memories=100,                   # Max memories to retrieve
    auto_sleep=True,                    # Auto-trigger sleep
    auto_dream=True,                    # Auto-trigger dream
    cache_enabled=True,                 # Enable caching
    cache_ttl=3600,                    # Cache TTL (seconds)
)
```

## MCP Server Tools

When using MCP server:

| Tool | Description |
|------|-------------|
| `m2wise_add` | Add memory from conversation |
| `m2wise_search` | Search memories and wisdom |
| `m2wise_sleep` | Generate wisdom drafts |
| `m2wise_dream` | Verify and publish wisdom |
| `m2wise_list_wisdom` | List all wisdom |
| `m2wise_forget` | Delete memory or wisdom |
| `m2wise_stats` | Get user statistics |
| `m2wise_chat` | Full conversation interaction |

## Adapter Support

| Adapter | Status | Description |
|---------|--------|-------------|
| M2Wise | ✅ Native | Native format |
| mem0 | ✅ Compatible | mem0.ai compatible |
| Letta | ✅ Compatible | Letta memory format |
| Anthropic | ✅ Compatible | Anthropic messages |

## Detection Triggers

Automatically detect these patterns:

**Preferences**:
- "I prefer..."
- "I like..."
- "Don't use..."
- "Please use..."

**Facts**:
- "I'm a..."
- "I work as..."
- "I have..."

**Commitments**:
- "I will..."
- "I promise..."
- "I'm going to..."

## Best Practices

1. **Regular Sleep**: Call `engine.sleep()` periodically to extract memories
2. **Dream Verification**: Call `engine.dream()` to verify and publish wisdom
3. **Confidence Tracking**: Wisdom confidence auto-evolves based on hit rates
4. **Use SDK**: Use M2WiseSDK for simpler API

## Performance

| Component | Performance |
|-----------|-------------|
| Similarity Calculation | ~300x speedup with caching |
| Confidence Evaluation | 1000 evaluations/10ms |
| Full Workflow | 45000+ memories/sec |

## Related Resources

- **API Reference**: See [REFERENCE.md](REFERENCE.md)
- **Examples**: See [EXAMPLES.md](EXAMPLES.md)
- **GitHub**: https://github.com/your-repo/m2wise