# MEMORY.md — Long-Term Memory

*Curated memories. The distilled essence, not raw logs.*

---

## Identity & Names
- **My name:** Kimi 🎙️
- **Human's name:** Rob
- **Other agent:** Max 🤖 (formerly Jarvis)
- **Relationship:** Direct 1:1, private and trusted

---

## Core Preferences

### Infrastructure Philosophy
- **Privacy first** — Always prioritize privacy in all decisions
- **Free > Paid** — Primary requirement for all tools
- **Local > Cloud** — Self-hosted over SaaS when possible
- **Private > Public** — Keep data local, avoid external APIs
- **Accuracy** — Best quality, no compromises
- **Performance** — Optimize for speed

### Research Policy
- **Always search web before installing** — Research docs, best practices
- **Local docs exception** — If docs are local (OpenClaw, ClawHub), use those first

### Communication Rules
- **Voice in → Voice out** — Reply with voice-only when voice received
- **Text in → Text out** — Reply with text when voice received  
- **Never both** — Don't send voice + text for same reply
- **No transcripts to Telegram** — Transcribe internally only, don't share text

### Voice Settings
- **TTS:** Local Kokoro @ `10.0.0.228:8880`
- **Voice:** `af_bella` (American Female)
- **Filename:** `Kimi-YYYYMMDD-HHMMSS.ogg`
- **STT:** Faster-Whisper (CPU, base model)

---

## Memory System — Manual Mode (2026-02-10)

### Overview
**Qdrant memory is now MANUAL ONLY.**

Memories are stored to Qdrant ONLY when explicitly requested by the user.
- **Daily file logs** (`memory/YYYY-MM-DD.md`) continue automatically
- **Qdrant vector storage** — Manual only when user says "store this"
- **No automatic storage** — Disabled per user request
- **No proactive retrieval** — Disabled
- **No auto-consolidation** — Disabled

### Storage Layers

```
Session Memory (this conversation) - Normal operation
    ↓
Daily Logs (memory/YYYY-MM-DD.md) - Automatic file-based
    ↓
Manual Qdrant Storage - ONLY when user explicitly requests
```

### Manual Qdrant Usage

When user says "remember this" or "store this in Qdrant":

```bash
# Store with metadata
python3 store_memory.py "Memory text" \
  --importance high \
  --confidence high \
  --verified \
  --tags "preference,setup"

# Search stored memories
python3 search_memories.py "query" --limit 5

# Hybrid search (files + vectors)
python3 hybrid_search.py "query" --file-limit 3 --vector-limit 3
```

### Available Metadata

When manually storing:
- **text** — Content
- **date** — Created
- **tags** — Topics
- **importance** — low/medium/high
- **confidence** — high/medium/low (accuracy)
- **source_type** — user/inferred/external
- **verified** — bool
- **expires_at** — For temporary memories
- **related_memories** — Linked concepts
- **access_count** — Usage tracking
- **last_accessed** — Recency

### Scripts Location

`/skills/qdrant-memory/scripts/`:
- `store_memory.py` — Manual storage
- `search_memories.py` — Search stored memories
- `hybrid_search.py` — Search both files and vectors
- `init_collection.py` — Initialize Qdrant collection

### DISABLED (Per User Request)

❌ Auto-storage triggers
❌ Proactive retrieval
❌ Automatic consolidation
❌ Memory decay cleanup
❌ `auto_memory.py` pipeline

---

## Agent Messaging — Manual Mode (2026-02-10)

### Overview
**Redis agent messaging is now MANUAL ONLY.**

All messaging with Max (other agent) is done ONLY when explicitly requested.
- **No automatic heartbeat checks** — Disabled per user request
- **No auto-notification queue** — Disabled
- **Manual connections only** — When user says "check messages" or "send to Max"

### Manual Redis Usage

When user requests agent communication:

```bash
# Check for messages from Max
cd /root/.openclaw/workspace/skills/qdrant-memory/scripts && python3 notify_check.py

# Send message to Max (manual only)
redis-cli -h 10.0.0.36 XADD agent-messages * type user_message agent Kimi message "text"

# Check delayed notification queue
redis-cli -h 10.0.0.36 LRANGE delayed:notifications 0 0
```

### DISABLED (Per User Request)

❌ Auto-checking Redis streams on heartbeat
❌ Auto-sending notifications from queue
❌ Auto-logging heartbeat timestamps to Redis

---

## Setup Milestones

### 2026-02-04 — Initial Bootstrap
- ✅ Established identity (Kimi) and user (Rob)
- ✅ Configured SearXNG web search (local)
- ✅ Set up bidirectional voice:
  - Outbound: Kokoro TTS with custom filenames
  - Inbound: Faster-Whisper for transcription
- ✅ Created skills:
  - `local-whisper-stt` — CPU-based voice transcription
  - `kimi-tts-custom` — Custom voice filenames, voice-only mode
  - `qdrant-memory` — Vector memory augmentation (Option 2: Augment)
- ✅ Documented installation policy (Skill → TOOLS.md → Other)

### 2026-02-04 — Qdrant Memory System v1
- **Location:** Local Proxmox LXC @ `10.0.0.40:6333`
- **Collection:** `openclaw_memories`
- **Vector size:** 768 (nomic-embed-text)
- **Distance:** Cosine similarity
- **Architecture:** Hybrid (Option 2 - Augment)
  - Daily logs: `memory/YYYY-MM-DD.md` (file-based)
  - Qdrant: Vector embeddings for semantic search
  - Both systems work together for redundancy + better retrieval
- **Mode:** Automatic — stores/retrieves without user prompting
- **Scripts available:**
  - `store_memory.py` — Store memory with embedding
  - `search_memories.py` — Semantic search
  - `hybrid_search.py` — Search both files and vectors
  - `init_collection.py` — Initialize Qdrant collection
  - `auto_memory.py` — Automatic memory management

### 2026-02-04 — Memory System v2.0 Enhancement
- ✅ Enhanced metadata (confidence, source, verification, expiration)
- ✅ Auto-tagging based on content
- ✅ Proactive context retrieval
- ✅ Memory consolidation (weekly/monthly)
- ✅ Memory decay and cleanup
- ✅ Cross-referencing between memories
- ✅ Access tracking (count, last accessed)

### 2026-02-05 — ACTIVE.md Enforcement Rule
- ✅ **MANDATORY:** Read ACTIVE.md BEFORE every tool use
- ✅ Added enforcement to AGENTS.md, TOOLS.md, and MEMORY.md
- ✅ Stored in Qdrant memory (ID: `bb5b784f-49ad-4b50-b905-841aeb2c2360`)
- ✅ Violations result in failed tool calls and loss of trust

### 2026-02-06 — Agent Name Change
- ✅ Changed other agent name from "Jarvis" to "Max"
- ✅ Updated all files: HEARTBEAT.md, activity_log.py, agent_chat.py, log_activity.py, memory/2026-02-05.md
- ✅ Max uses minimax-m2.1:cloud model
- ✅ Shared Redis stream for agent messaging: `agent-messages`

### 2026-02-10 — Memory System Manual Mode + New Collections
- ✅ Disabled automatic Qdrant storage
- ✅ Disabled proactive retrieval
- ✅ Disabled auto-consolidation
- ✅ Created `kimi_memories` collection (1024 dims, snowflake-arctic-embed2) for personal memories
- ✅ Created `kimi_kb` collection (1024 dims, snowflake-arctic-embed2) for knowledge base (web, docs, data)
- ✅ Qdrant now manual-only when user requests
- ✅ Daily file logs continue normally
- ✅ Updated SKILL.md, TOOLS.md, MEMORY.md
- **Command mapping**:
  - "remember this..." or "note" → File-based daily logs (automatic)
  - "q remember", "q recall", "q save" → `kimi_memories` (personal, manual)
  - "add to KB", "store doc" → `kimi_kb` (knowledge base, manual)

### 2026-02-10 — Agent Messaging Changed to Manual Mode
- ✅ Disabled automatic Redis heartbeat checks
- ✅ Disabled auto-notification queue
- ✅ Redis messaging now manual-only when user requests
- ✅ Updated HEARTBEAT.md and MEMORY.md

---

### 2026-02-10 — Perplexity API + Unified Search Setup
- ✅ Perplexity API configured at `/skills/perplexity/`
  - Key: `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`
  - Endpoint: `https://api.perplexity.ai/chat/completions`
  - Models: sonar, sonar-pro, sonar-reasoning, sonar-deep-research
  - Format: OpenAI-compatible, ~$0.005 per query
- ✅ Unified search script created: `skills/perplexity/scripts/search.py`
  - **Primary**: Perplexity (AI-curated answers, citations)
  - **Fallback**: SearXNG (local, raw results)
  - **Usage**: `search "query"` (default), `search p "query"` (Perplexity only), `search local "query"` (SearXNG only)
  - Rob pays for Perplexity, so use it as primary
- ✅ SearXNG remains available for: privacy-sensitive searches, simple lookups, rate limit fallback

---

## Personality Notes

### How to Be Helpful
- Actions > words — skip the fluff, just help
- Have opinions — not a search engine with extra steps
- Resourceful first — try to figure it out before asking
- Competence earns trust — careful with external actions

### Boundaries
- Private stays private
- Ask before sending emails/tweets/public posts
- Not Rob's voice in group chats — I'm a participant, not his proxy

---

## Things to Remember

*(Add here as they come up)*

---

## Lessons Learned

### Tool Usage Patterns
✅ **Read tool:** Use `file_path`, never `path`
✅ **Edit tool:** Always provide `old_string` AND `new_string`
✅ **Search:** `searx_search` not enabled - check available tools first

### ⚠️ CRITICAL: ACTIVE.md Enforcement (2026-02-05)
**MANDATORY RULE:** Must read ACTIVE.md section BEFORE every tool use.

**Why it exists:** Prevent failed tool calls from wrong parameter names.

**What I did wrong:**
- Used `path` instead of `file_path` for `read`
- Used `newText`/`oldText` instead of `new_string`/`old_string` for `edit`
- Failed to check ACTIVE.md before using tools
- Wasted tokens and time on avoidable errors

**Enforcement Protocol:**
1. Identify the tool needed
2. **Read ACTIVE.md section for that tool**
3. Check "My Common Mistakes Reference" table
4. Verify parameter names
5. Only then execute

**Recovery:** After 2 failed `edit` attempts, switch to `write` tool.

### Voice Skill Paths
- Whisper: `/skills/local-whisper-stt/scripts/transcribe.py`
- TTS: `/skills/kimi-tts-custom/scripts/voice_reply.py <chat_id> "text"`

### Memory System Mode (2026-02-10)
- Qdrant: Manual only when user requests
- File logs: Continue automatically
- No auto-storage, no proactive retrieval

### Agent Messaging Mode (2026-02-10)
- Redis: Manual only when user requests
- No auto-check on heartbeat
- No auto-notification queue

### ⚠️ CRITICAL: Config Backup Rule (2026-02-10)
**MANDATORY RULE:** Before making any changes to `openclaw.json`, create a backup first.

**Naming convention:** `openclaw.json.bak.DDMMYYYY` (day month year)
- Example: `openclaw.json.bak.10022026` for February 10, 2026

**Command:**
```bash
DATE=$(date +%d%m%Y); cp /root/.openclaw/openclaw.json /root/.openclaw/openclaw.json.bak.${DATE}
```

**Why it matters:** Prevents configuration corruption, allows rollback if changes break something.
**MANDATORY RULE:** When hitting a blocking error during an active task, report immediately — don't wait for user to ask.

**What I did wrong:**
- Started a task ("q save ALL memories") and said "let me know when it's complete"
- Discovered Qdrant was unreachable (host down, 100% packet loss)
- Stayed silent instead of immediately reporting the failure
- User had to ask "let me know when it's complete" to discover I was blocked

**Correct behavior:**
- Hit blocking error → immediately report: "Stopped — [reason]. Cannot proceed."
- Do not wait for user to check in
- Do not imply progress is happening when it's not

**Applies to:**
- Service outages (Qdrant, Redis, Ollama down)
- Permission errors
- Resource exhaustion
- Any error that prevents task completion

---

## Active Projects

*(What Rob is working on — add as discovered)*

### 2026-02-10 — Git Repository Initialized
- ✅ Git repo initialized at `/root/.openclaw/workspace`
- ✅ Initial commit: `d1357c5` — "Initial commit: workspace setup with skills, memory, config"
- ✅ 77 files, 10,822 insertions committed
- ✅ Status: clean working tree
- **Qdrant stored:** Git setup details (ID: `1d35af8e-76ec-4ea0-952d-6e2c3555ebf7`)

### 2026-02-10 — Sub-Agent Setup (Option B)
- ✅ Configured sub-agent defaults in `openclaw.json`
- ✅ Model: `qwen3:30b-a3b-instruct-2507-q8_0` at 10.0.0.10:11434 (via `ollama-remote` provider)
- ✅ Max concurrent: 2
- ✅ Tool restrictions: deny write, edit, apply_patch, browser, cron
- ✅ Purpose: Offload background tasks to .10 GPU

---

*Last updated: 2026-02-10