openclaw-mem 1.0.4 → 1.3.0

package/HOOK.md

@@ -0,0 +1,125 @@
+---
+name: openclaw-mem
+description: "Persistent memory system - saves session context and injects history into new sessions"
+homepage: https://github.com/openclaw-mem
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🧠",
+        "events": ["command:new", "gateway:startup", "agent:bootstrap", "agent:response", "agent:stop", "tool:post", "user:prompt", "message"],
+        "requires": { "config": ["workspace.dir"] },
+        "install": [{ "id": "local", "kind": "local", "label": "Local installation" }],
+      },
+  }
+---
+
+# OpenClaw-Mem: Persistent Memory System
+
+A claude-mem inspired memory system for OpenClaw that automatically captures tool usage, generates summaries, and injects relevant context into new sessions.
+
+## Features
+
+- 🧠 **Persistent Memory** - Context survives across sessions
+- 📊 **Progressive Disclosure** - Shows index first, fetch details on demand
+- 🔍 **Hybrid Search** - Full-text + semantic search
+- 🤖 **AI Compression** - Automatic summarization of observations
+- ⚡ **Token Efficient** - Only loads what's relevant
+- 📡 **Real-time Capture** - Records messages as they happen
+
+## Events Captured
+
+- `gateway:startup` - Initialize memory system
+- `agent:bootstrap` - Inject historical context
+- `agent:response` - Capture assistant responses in real-time
+- `agent:stop` - Save session summary
+- `command:new` - Save session content before reset
+- `tool:post` - Capture tool usage
+- `user:prompt` - Capture user messages
+- `message` - Capture all messages
+
+## Configuration
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "openclaw-mem": {
+          "enabled": true,
+          "observationLimit": 50,
+          "fullDetailCount": 5,
+          "compressWithLLM": true
+        }
+      }
+    }
+  }
+}
+```
+
+## Storage
+
+Data is stored in SQLite at `~/.openclaw-mem/memory.db`:
+- `sessions` - Session records
+- `observations` - Tool call observations
+- `summaries` - Session summaries
+
+## Real-time Monitoring
+
+```bash
+node ~/.openclaw/hooks/openclaw-mem/monitor.js
+```
+
+## Usage
+
+The memory system works automatically. To search manually:
+
+```bash
+# Search memory
+openclaw memory search "authentication"
+
+# View status
+openclaw memory status
+```
+
+## MCP Server (Model Context Protocol)
+
+OpenClaw-Mem 提供 MCP Server，让 AI 可以按需查询记忆：
+
+### MCP 工具
+
+| Tool | Description |
+|------|-------------|
+| `__IMPORTANT` | 显示 3 层工作流说明 |
+| `search` | 搜索记忆索引 |
+| `timeline` | 获取某条记录的上下文 |
+| `get_observations` | 获取完整详情 |
+
+### 启动 MCP Server
+
+```bash
+# stdio 模式（标准 MCP）
+node ~/.openclaw/hooks/openclaw-mem/mcp-server.js
+
+# HTTP API 模式（兼容模式）
+node ~/.openclaw/hooks/openclaw-mem/mcp-http-api.js
+```
+
+### HTTP API 端点
+
+```bash
+# 搜索
+curl "http://127.0.0.1:18790/search?query=database&limit=10"
+
+# Timeline
+curl "http://127.0.0.1:18790/timeline?anchor=123"
+
+# 获取详情
+curl -X POST "http://127.0.0.1:18790/get_observations" -d '{"ids":[123,124]}'
+```
+
+## Disabling
+
+```bash
+openclaw hooks disable openclaw-mem
+```

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 OpenClaw Contributors
+Copyright (c) 2026 Aaron
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/MCP.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "openclaw-mem-search": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["mcp-server.js"],
+      "cwd": "${HOOK_ROOT}",
+      "description": "Memory search tools for OpenClaw-Mem"
+    }
+  }
+}

package/README.md

@@ -1,217 +1,208 @@
-<p align="center">
-  <img src="docs/logo.svg" alt="OpenClaw-Mem Logo" width="300"/>
-</p>
-
-<h1 align="center">OpenClaw-Mem 🧠</h1>
-
-<p align="center">
-  <strong>Give your OpenClaw AI agent persistent long-term memory</strong>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/openclaw-mem"><img src="https://img.shields.io/npm/v/openclaw-mem.svg" alt="npm version"/></a>
-  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a>
-  <a href="https://www.npmjs.com/package/openclaw-mem"><img src="https://img.shields.io/npm/dm/openclaw-mem.svg" alt="npm downloads"/></a>
-</p>
-
-<p align="center">
-  <a href="README_CN.md">🇨🇳 中文</a> •
-  <a href="docs/locales/README_JA.md">🇯🇵 日本語</a> •
-  <a href="docs/locales/README_KO.md">🇰🇷 한국어</a> •
-  <a href="docs/locales/README_ES.md">🇪🇸 Español</a> •
-  <a href="docs/locales/README_DE.md">🇩🇪 Deutsch</a> •
-  <a href="docs/locales/README_FR.md">🇫🇷 Français</a> •
-  <a href="docs/locales/README_PT.md">🇧🇷 Português</a>
-  <br/>
-  <a href="docs/locales/README_RU.md">🇷🇺 Русский</a> •
-  <a href="docs/locales/README_AR.md">🇸🇦 العربية</a> •
-  <a href="docs/locales/README_HE.md">🇮🇱 עברית</a> •
-  <a href="docs/locales/README_TR.md">🇹🇷 Türkçe</a> •
-  <a href="docs/locales/README_IT.md">🇮🇹 Italiano</a> •
-  <a href="docs/locales/README_NL.md">🇳🇱 Nederlands</a> •
-  <a href="docs/locales/README_PL.md">🇵🇱 Polski</a>
-  <br/>
-  <a href="docs/locales/README_UK.md">🇺🇦 Українська</a> •
-  <a href="docs/locales/README_VI.md">🇻🇳 Tiếng Việt</a> •
-  <a href="docs/locales/README_TH.md">🇹🇭 ไทย</a> •
-  <a href="docs/locales/README_HI.md">🇮🇳 हिन्दी</a> •
-  <a href="docs/locales/README_ID.md">🇮🇩 Indonesia</a>
-</p>
-
-<hr/>
-
-OpenClaw-Mem automatically captures your conversations and makes them searchable, allowing your AI assistant to remember what you've discussed across sessions.
-
-## ✨ Features
-
-- **🔄 Automatic Memory Capture** - Conversations are saved automatically
-- **🔍 Full-Text Search** - Search through your entire conversation history
-- **📊 Progressive Disclosure** - Efficient token usage with layered context
-- **🎯 Topic Detection** - Automatically indexes discussions by topic
-- **💾 Local Storage** - All data stays on your machine (SQLite)
-- **⚡ Zero Config** - Works out of the box
-
-## 🚀 Quick Start
+# OpenClaw-Mem
 
-```bash
-# Install and setup (one command!)
-npx openclaw-mem init
+A persistent memory system for [OpenClaw](https://github.com/openclaw) that automatically captures conversations, generates summaries, and injects relevant context into new sessions.
 
-# Restart OpenClaw gateway
-openclaw gateway restart
-```
+## Features
 
-That's it! Start chatting and your conversations will be remembered.
+- **Persistent Memory** - Context survives across sessions
+- **Progressive Disclosure** - Shows index first, fetch details on demand
+- **Hybrid Search** - Full-text + LIKE search with CJK support
+- **AI Compression** - Automatic summarization of observations
+- **Token Efficient** - Only loads what's relevant
+- **Real-time Capture** - Records messages as they happen
+- **MCP Compatible** - Model Context Protocol server included
+- **HTTP API** - REST API for memory queries
 
-## 📖 Usage
+## Installation
 
-### Recalling Memories in Chat
+### As OpenClaw Hook
 
-Ask your AI assistant:
-- "What did we discuss before?"
-- "What were we working on last time?"
-- "Remind me about the authentication issue"
+```bash
+# Clone to OpenClaw hooks directory
+git clone https://github.com/wenyupapa-sys/openclaw-mem.git ~/.openclaw/hooks/openclaw-mem
+cd ~/.openclaw/hooks/openclaw-mem
+npm install
+```
 
-### CLI Commands
+### As npm Package
 
 ```bash
-# Check memory status
-npx openclaw-mem status
+npm install openclaw-mem
+```
 
-# Search your memory
-npx openclaw-mem search "authentication"
-npx openclaw-mem search "AI memory"
+> ⚠️ **Important:** npm installation does NOT automatically prompt for API key configuration. You MUST manually configure your DeepSeek API key after installation. See [Configuration](#configuration) section below.
 
-# Remove (keeps database)
-npx openclaw-mem uninstall
-```
+**After npm install, choose one of these methods:**
 
-## 🏗️ How It Works
+```bash
+# Method 1: Run the setup wizard
+npx openclaw-mem-setup
 
+# Method 2: Set environment variable directly
+export DEEPSEEK_API_KEY="your-deepseek-api-key"
+# Add this line to your ~/.bashrc or ~/.zshrc to persist
 ```
-+-------------+     +------------------+     +------------+
-|  Telegram   | --> | OpenClaw Gateway | --> |  AI Agent  |
-+-------------+     +------------------+     +------------+
-                            |                      |
-                            v                      v
-                    +--------------+        +------------+
-                    | openclaw-mem |        | Read Tool  |
-                    |    hook      |        +------------+
-                    +--------------+               |
-                            |                      v
-        +-------------------+----------------------+
-        |                   |
-        v                   v
-+---------------+   +------------------+
-|   SQLite DB   |   | SESSION-MEMORY.md|
-|  (persistent) |   |    (injected)    |
-+---------------+   +------------------+
-```
 
-### Event Flow
+## Quick Start
+
+1. **Install the hook** (see above)
 
-1. **`gateway:startup`** - Initializes the memory database
-2. **`agent:bootstrap`** - Injects historical context into new sessions
-3. **`command:new`** - Saves session summary when you start fresh
+2. **Run setup** - configure your DeepSeek API key (prompted automatically after install)
+   ```bash
+   # Or run manually later
+   npm run setup
+   # or
+   npx openclaw-mem-setup
+   ```
 
-### Progressive Disclosure
+3. **Restart OpenClaw** to load the hook
 
-To optimize token usage, memories are organized in layers:
+4. **Start chatting** - conversations are automatically saved
 
-| Layer | Content | Tokens |
-|-------|---------|--------|
-| Index | Compact table of all observations | ~Low |
-| Topics | Key discussion summaries | ~Medium |
-| Details | Full content (on demand) | ~High |
+5. **Query memories** - ask "what did we discuss before?" and the AI will search the memory database
 
-## 📁 File Locations
+## Events Captured
 
-| File | Location | Purpose |
-|------|----------|---------|
-| Database | `~/.openclaw-mem/memory.db` | Persistent storage |
-| Hook | `~/.openclaw/hooks/openclaw-mem/` | Event handlers |
-| Memory Context | `~/.openclaw/workspace/SESSION-MEMORY.md` | Injected context |
+| Event | Description |
+|-------|-------------|
+| `gateway:startup` | Initialize memory system |
+| `agent:bootstrap` | Inject historical context |
+| `agent:response` | Capture assistant responses |
+| `agent:stop` | Save session summary |
+| `command:new` | Save session before reset |
+| `tool:post` | Capture tool usage |
+| `user:prompt` | Capture user messages |
 
-## ⚙️ Configuration
+## API Reference
 
-### Customize MEMORY.md
+### HTTP API (Port 18790)
 
-Add your preferences to `~/.openclaw/workspace/MEMORY.md`:
+```bash
+# Search memories
+curl -s -X POST "http://127.0.0.1:18790/search" \
+  -H "Content-Type: application/json" \
+  -d '{"query":"keyword","limit":10}'
+
+# Get observation details
+curl -s -X POST "http://127.0.0.1:18790/get_observations" \
+  -H "Content-Type: application/json" \
+  -d '{"ids":[123,124]}'
+
+# Get timeline context
+curl -s -X POST "http://127.0.0.1:18790/timeline" \
+  -H "Content-Type: application/json" \
+  -d '{"anchor":123}'
+
+# Health check
+curl "http://127.0.0.1:18790/health"
+```
 
-```markdown
-## User Preferences
-- Communication style: Technical and concise
-- Language: English
+### Shell Scripts
 
-## Long-Term Context
-- Working on: AI memory systems
-- Interests: Machine learning, distributed systems
+```bash
+# Search (handles CJK encoding automatically)
+~/.openclaw/hooks/openclaw-mem/mem-search.sh "关键词" 10
 
-## Ongoing Focus
-- Current project: Building a chat application
+# Get details
+~/.openclaw/hooks/openclaw-mem/mem-get.sh 123 124 125
 ```
 
-### Dynamic Topic Detection
+### MCP Server
 
-The system automatically extracts topics from your actual conversations:
-- Concepts mentioned frequently are detected automatically
-- No hardcoded keywords - everything comes from your data
-- Topics evolve as your discussions change
+```bash
+# Start MCP server (stdio mode)
+node mcp-server.js
+```
 
-## 🔧 Troubleshooting
+MCP Tools:
+- `search` - Search memory index
+- `timeline` - Get context around an observation
+- `get_observations` - Fetch full details
 
-### Memory not being recalled?
+## Configuration
 
-1. **Restart the gateway:**
-   ```bash
-   openclaw gateway restart
-   ```
+### Environment Variables
 
-2. **Check hook is installed:**
-   ```bash
-   ls ~/.openclaw/hooks/openclaw-mem/
-   ```
+```bash
+# Required for AI summarization (optional but recommended)
+export DEEPSEEK_API_KEY="your-deepseek-api-key"
 
-3. **Verify database has content:**
-   ```bash
-   npx openclaw-mem status
-   ```
+# Optional: Custom DeepSeek endpoint
+export DEEPSEEK_BASE_URL="https://api.deepseek.com/v1"
+
+# Optional: Custom model
+export DEEPSEEK_MODEL="deepseek-chat"
+```
+
+Get your DeepSeek API key at: https://platform.deepseek.com/
+
+> **Note:** Without `DEEPSEEK_API_KEY`, the system will still work but won't generate AI summaries for sessions.
 
-### Search not finding results?
+### OpenClaw Config
 
-- Try simpler search terms
-- Check for typos
-- Use keywords from the actual conversation
+Add to your OpenClaw config:
 
-### Database issues?
+```json
+{
+  "hooks": {
+    "internal": {
+      "entries": {
+        "openclaw-mem": {
+          "enabled": true,
+          "observationLimit": 50,
+          "fullDetailCount": 5
+        }
+      }
+    }
+  }
+}
+```
+
+## Storage
+
+Data is stored in SQLite at `~/.openclaw-mem/memory.db`:
+
+| Table | Description |
+|-------|-------------|
+| `sessions` | Session records |
+| `observations` | Tool calls and messages |
+| `summaries` | Session summaries |
+| `user_prompts` | User inputs |
+
+## Development
 
 ```bash
-# Reset database (⚠️ deletes all memories)
-rm ~/.openclaw-mem/memory.db
-openclaw gateway restart
+# Run tests
+npm test
+
+# Start HTTP API server
+npm run api
+
+# Start MCP server
+npm run mcp
+
+# Monitor real-time activity
+node debug-logger.js
 ```
 
-## 🤝 Contributing
+## 3-Layer Retrieval Workflow
+
+For efficient token usage, use progressive disclosure:
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+1. **Search** → Get index with IDs (~50-100 tokens/result)
+2. **Timeline** → Get context around interesting results
+3. **Get Observations** → Fetch full details ONLY for filtered IDs
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+This approach saves ~30% tokens compared to fetching everything.
 
-## 📄 License
+## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT
 
-## 🙏 Acknowledgments
+## Contributing
 
-- Inspired by [claude-mem](https://github.com/anthropics/claude-mem)
-- Built for [OpenClaw](https://openclaw.ai)
+Pull requests welcome! Please ensure tests pass before submitting.
 
----
+## Credits
 
-<p align="center">
-  Made with ❤️ for the AI community
-</p>
+Inspired by [claude-mem](https://github.com/anthropics/claude-code) plugin architecture.

package/backfill-embeddings.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Backfill embeddings for existing observations.
+ * Run manually: node backfill-embeddings.js
+ *
+ * Finds all observations without embeddings and generates them
+ * in batches of 16 using the DeepSeek embeddings API.
+ */
+
+import database from './database.js';
+import { batchEmbeddings } from './gateway-llm.js';
+
+const BATCH_SIZE = 16;
+
+async function backfill() {
+  const totalObs = database.getStats().total_observations;
+  const existingEmbeddings = database.getEmbeddingCount();
+  console.log(`Total observations: ${totalObs}`);
+  console.log(`Existing embeddings: ${existingEmbeddings}`);
+  console.log(`Missing: ~${totalObs - existingEmbeddings}`);
+  console.log('');
+
+  let processed = 0;
+  let saved = 0;
+  let failed = 0;
+
+  while (true) {
+    const batch = database.getObservationsWithoutEmbeddings(BATCH_SIZE);
+    if (batch.length === 0) break;
+
+    // Build text for each observation
+    const texts = batch.map(obs => {
+      const parts = [obs.summary, obs.narrative].filter(Boolean);
+      return parts.join(' ').trim() || `Observation #${obs.id}`;
+    });
+
+    console.log(`Batch ${Math.floor(processed / BATCH_SIZE) + 1}: generating embeddings for ${batch.length} observations (IDs ${batch[0].id}-${batch[batch.length - 1].id})...`);
+
+    const embeddings = await batchEmbeddings(texts);
+
+    for (let i = 0; i < batch.length; i++) {
+      const obs = batch[i];
+      const embedding = embeddings[i];
+
+      if (embedding) {
+        const result = database.saveEmbedding(obs.id, embedding);
+        if (result.success) {
+          saved++;
+        } else {
+          failed++;
+          console.error(`  Failed to save embedding for #${obs.id}: ${result.error}`);
+        }
+      } else {
+        failed++;
+        console.error(`  No embedding returned for #${obs.id}`);
+      }
+    }
+
+    processed += batch.length;
+    console.log(`  Progress: ${saved} saved, ${failed} failed, ${processed} processed`);
+
+    // Small delay between batches to avoid rate limiting
+    if (batch.length === BATCH_SIZE) {
+      await new Promise(r => setTimeout(r, 500));
+    }
+  }
+
+  console.log('');
+  console.log('=== Backfill Complete ===');
+  console.log(`Processed: ${processed}`);
+  console.log(`Saved: ${saved}`);
+  console.log(`Failed: ${failed}`);
+  console.log(`Total embeddings now: ${database.getEmbeddingCount()}`);
+}
+
+backfill().catch(err => {
+  console.error('Backfill failed:', err);
+  process.exit(1);
+});