openclaw-mem 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OpenClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# OpenClaw-Mem 🧠
+
+> Give your OpenClaw AI agent persistent long-term memory
+
+[![npm version](https://badge.fury.io/js/openclaw-mem.svg)](https://www.npmjs.com/package/openclaw-mem)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+```bash
+# Install and setup (one command!)
+npx openclaw-mem init
+
+# Restart OpenClaw gateway
+openclaw gateway restart
+```
+
+That's it! Start chatting and your conversations will be remembered.
+
+## 📖 Usage
+
+### Recalling Memories in Chat
+
+Ask your AI assistant:
+- "What did we discuss before?"
+- "我们之前讨论过什么？"
+- "What were we working on last time?"
+- "Remind me about the authentication issue"
+
+### CLI Commands
+
+```bash
+# Check memory status
+npx openclaw-mem status
+
+# Search your memory
+npx openclaw-mem search "authentication"
+npx openclaw-mem search "AI memory"
+
+# Remove (keeps database)
+npx openclaw-mem uninstall
+```
+
+## 🏗️ How It Works
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│    Telegram     │────▶│  OpenClaw Gateway │────▶│   AI Agent      │
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                               │                         │
+                               ▼                         ▼
+                        ┌──────────────┐          ┌─────────────┐
+                        │ openclaw-mem │          │  Read Tool  │
+                        │    hook      │          └─────────────┘
+                        └──────────────┘                 │
+                               │                         ▼
+        ┌──────────────────────┼─────────────────────────┘
+        ▼                      ▼
+┌───────────────┐      ┌──────────────────┐
+│  SQLite DB    │      │ SESSION-MEMORY.md │
+│ (persistent)  │      │   (injected)      │
+└───────────────┘      └──────────────────┘
+```
+
+### Event Flow
+
+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
+
+### Progressive Disclosure
+
+To optimize token usage, memories are organized in layers:
+
+| Layer | Content | Tokens |
+|-------|---------|--------|
+| Index | Compact table of all observations | ~Low |
+| Topics | Key discussion summaries | ~Medium |
+| Details | Full content (on demand) | ~High |
+
+## 📁 File Locations
+
+| 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 |
+
+## ⚙️ Configuration
+
+### Customize MEMORY.md
+
+Add your preferences to `~/.openclaw/workspace/MEMORY.md`:
+
+```markdown
+## User Preferences
+- Communication style: Technical and concise
+- Language: English
+
+## Long-Term Context
+- Working on: AI memory systems
+- Interests: Machine learning, distributed systems
+
+## Ongoing Focus
+- Current project: Building a chat application
+```
+
+### Topic Keywords
+
+The system automatically searches for these topic keywords:
+- AI/Machine Learning: `短期记忆`, `长期记忆`, `向量数据库`, `RAG`
+- Health/Fitness: `长寿`, `禁食`, `力量训练`, `有氧运动`
+- Programming: `Node.js`, `TypeScript`, `微服务`, `架构`
+
+## 🔧 Troubleshooting
+
+### Memory not being recalled?
+
+1. **Restart the gateway:**
+   ```bash
+   openclaw gateway restart
+   ```
+
+2. **Check hook is installed:**
+   ```bash
+   ls ~/.openclaw/hooks/openclaw-mem/
+   ```
+
+3. **Verify database has content:**
+   ```bash
+   npx openclaw-mem status
+   ```
+
+### Search not finding results?
+
+- Try simpler search terms
+- Check for typos
+- Use keywords from the actual conversation
+
+### Database issues?
+
+```bash
+# Reset database (⚠️ deletes all memories)
+rm ~/.openclaw-mem/memory.db
+openclaw gateway restart
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+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
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- Inspired by [claude-mem](https://github.com/anthropics/claude-mem)
+- Built for [OpenClaw](https://openclaw.ai)
+
+---
+
+<p align="center">
+  Made with ❤️ for the AI community
+</p>

package/bin/openclaw-mem.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * OpenClaw-Mem CLI
+ *
+ * Usage:
+ *   npx openclaw-mem init     - Install hook to OpenClaw
+ *   npx openclaw-mem status   - Show memory statistics
+ *   npx openclaw-mem search   - Search memory
+ *   npx openclaw-mem uninstall - Remove hook
+ */
+
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Colors for terminal output
+const c = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m'
+};
+
+function log(msg, color = 'reset') {
+  console.log(`${c[color]}${msg}${c.reset}`);
+}
+
+function printBanner() {
+  console.log(`
+${c.cyan}╔══════════════════════════════════════════════════════════╗
+║                                                          ║
+║   ${c.bold}OpenClaw-Mem${c.reset}${c.cyan} - Persistent Memory for OpenClaw        ║
+║                                                          ║
+╚══════════════════════════════════════════════════════════╝${c.reset}
+`);
+}
+
+function printUsage() {
+  console.log(`
+${c.bold}Usage:${c.reset}
+  npx openclaw-mem <command>
+
+${c.bold}Commands:${c.reset}
+  ${c.green}init${c.reset}        Install openclaw-mem hook to your OpenClaw setup
+  ${c.green}status${c.reset}      Show memory database statistics
+  ${c.green}search${c.reset}      Search your memory (e.g., npx openclaw-mem search "topic")
+  ${c.green}uninstall${c.reset}   Remove openclaw-mem from OpenClaw
+  ${c.green}help${c.reset}        Show this help message
+
+${c.bold}Examples:${c.reset}
+  ${c.dim}# First time setup${c.reset}
+  npx openclaw-mem init
+
+  ${c.dim}# Check what's stored${c.reset}
+  npx openclaw-mem status
+
+  ${c.dim}# Search for conversations about AI${c.reset}
+  npx openclaw-mem search "AI memory"
+
+${c.bold}Learn more:${c.reset}
+  https://github.com/anthropics/openclaw-mem
+`);
+}
+
+async function main() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printBanner();
+    printUsage();
+    process.exit(0);
+  }
+
+  switch (command) {
+    case 'init': {
+      const { init } = await import('../scripts/init.js');
+      await init();
+      break;
+    }
+    case 'status': {
+      const { status } = await import('../scripts/commands.js');
+      await status();
+      break;
+    }
+    case 'search': {
+      const query = args.slice(1).join(' ');
+      if (!query) {
+        log('Error: Please provide a search query', 'red');
+        log('Usage: npx openclaw-mem search "your query"', 'dim');
+        process.exit(1);
+      }
+      const { search } = await import('../scripts/commands.js');
+      await search(query);
+      break;
+    }
+    case 'uninstall': {
+      const { uninstall } = await import('../scripts/init.js');
+      await uninstall();
+      break;
+    }
+    default:
+      log(`Unknown command: ${command}`, 'red');
+      printUsage();
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  log(`Error: ${err.message}`, 'red');
+  process.exit(1);
+});