memory-lucia 2.0.1 → 2.0.3

package/migrations/v1-to-v2.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * Memory V1 to V2 Migration Script
+ * Migrates data from old memory format to V2 schema
+ */
+
+const sqlite3 = require('sqlite3').verbose();
+const fs = require('fs');
+const path = require('path');
+
+class MemoryMigration {
+    constructor(sourceDbPath, targetDbPath = './memory-v2.db') {
+        this.sourceDbPath = sourceDbPath;
+        this.targetDbPath = targetDbPath;
+        this.sourceDb = null;
+        this.targetDb = null;
+    }
+
+    async init() {
+        // Check if source exists
+        if (!fs.existsSync(this.sourceDbPath)) {
+            throw new Error(`Source database not found: ${this.sourceDbPath}`);
+        }
+
+        // Open source database
+        this.sourceDb = new sqlite3.Database(this.sourceDbPath, sqlite3.OPEN_READONLY);
+        
+        // Open/create target database
+        this.targetDb = new sqlite3.Database(this.targetDbPath);
+        
+        console.log('✅ Connected to source and target databases');
+    }
+
+    async runSchema() {
+        const schemaPath = path.join(__dirname, '..', 'database', 'schema.sql');
+        
+        if (!fs.existsSync(schemaPath)) {
+            throw new Error(`Schema file not found: ${schemaPath}`);
+        }
+
+        const schema = fs.readFileSync(schemaPath, 'utf8');
+        const statements = schema
+            .split(';')
+            .map(s => s.trim())
+            .filter(s => s.length > 0);
+
+        for (const statement of statements) {
+            await this.runTarget(statement);
+        }
+        
+        console.log('✅ Target database schema initialized');
+    }
+
+    async migratePriorities() {
+        console.log('🔄 Migrating priorities...');
+        
+        try {
+            const rows = await this.allSource(
+                "SELECT * FROM memory_priorities WHERE created_at >= datetime('now', '-90 days')"
+            );
+
+            for (const row of rows) {
+                await this.runTarget(
+                    `INSERT INTO memory_priorities 
+                     (msg_id, conv_id, priority_level, reasoning, category, created_at)
+                     VALUES (?, ?, ?, ?, ?, ?)`,
+                    [row.msg_id, row.conv_id, row.priority_level, row.reasoning, row.category, row.created_at]
+                );
+            }
+
+            console.log(`✅ Migrated ${rows.length} priority records`);
+        } catch (err) {
+            console.log('ℹ️ No priorities to migrate or table does not exist');
+        }
+    }
+
+    async migrateLearning() {
+        console.log('🔄 Migrating learning records...');
+        
+        try {
+            const rows = await this.allSource(
+                "SELECT * FROM memory_learning WHERE status != 'abandoned'"
+            );
+
+            for (const row of rows) {
+                await this.runTarget(
+                    `INSERT INTO memory_learning 
+                     (msg_id, conv_id, topic, description, status, progress, started_at, updated_at, completed_at)
+                     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+                    [row.msg_id, row.conv_id, row.topic, row.description, row.status, 
+                     row.progress, row.started_at, row.updated_at, row.completed_at]
+                );
+            }
+
+            console.log(`✅ Migrated ${rows.length} learning records`);
+        } catch (err) {
+            console.log('ℹ️ No learning records to migrate or table does not exist');
+        }
+    }
+
+    async migrateDecisions() {
+        console.log('🔄 Migrating decisions...');
+        
+        try {
+            const rows = await this.allSource(
+                "SELECT * FROM memory_decisions WHERE status IN ('pending', 'implemented')"
+            );
+
+            for (const row of rows) {
+                await this.runTarget(
+                    `INSERT INTO memory_decisions 
+                     (msg_id, conv_id, summary, context, expected_outcome, actual_outcome, 
+                      status, review_scheduled_at, reviewed_at, created_at)
+                     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+                    [row.msg_id, row.conv_id, row.summary, row.context, row.expected_outcome,
+                     row.actual_outcome, row.status, row.review_scheduled_at, row.reviewed_at, row.created_at]
+                );
+            }
+
+            console.log(`✅ Migrated ${rows.length} decision records`);
+        } catch (err) {
+            console.log('ℹ️ No decisions to migrate or table does not exist');
+        }
+    }
+
+    async migrateEvolution() {
+        console.log('🔄 Migrating skill evolution...');
+        
+        try {
+            const rows = await this.allSource(
+                "SELECT * FROM memory_evolution WHERE usage_count > 0"
+            );
+
+            for (const row of rows) {
+                await this.runTarget(
+                    `INSERT INTO memory_evolution 
+                     (skill_name, category, usage_count, success_count, last_used_at, first_used_at)
+                     VALUES (?, ?, ?, ?, ?, ?)`,
+                    [row.skill_name, row.category, row.usage_count, row.success_count, 
+                     row.last_used_at, row.first_used_at]
+                );
+            }
+
+            console.log(`✅ Migrated ${rows.length} skill evolution records`);
+        } catch (err) {
+            console.log('ℹ️ No evolution records to migrate or table does not exist');
+        }
+    }
+
+    async runTarget(sql, params = []) {
+        return new Promise((resolve, reject) => {
+            this.targetDb.run(sql, params, function(err) {
+                if (err) reject(err);
+                else resolve({ id: this.lastID, changes: this.changes });
+            });
+        });
+    }
+
+    async allSource(sql, params = []) {
+        return new Promise((resolve, reject) => {
+            this.sourceDb.all(sql, params, (err, rows) => {
+                if (err) reject(err);
+                else resolve(rows);
+            });
+        });
+    }
+
+    async close() {
+        if (this.sourceDb) {
+            await new Promise((resolve) => this.sourceDb.close(resolve));
+        }
+        if (this.targetDb) {
+            await new Promise((resolve) => this.targetDb.close(resolve));
+        }
+        console.log('✅ Database connections closed');
+    }
+
+    async migrate() {
+        try {
+            await this.init();
+            await this.runSchema();
+            await this.migratePriorities();
+            await this.migrateLearning();
+            await this.migrateDecisions();
+            await this.migrateEvolution();
+            
+            console.log('\n🎉 Migration completed successfully!');
+            console.log(`📁 New database: ${path.resolve(this.targetDbPath)}`);
+        } catch (err) {
+            console.error('\n❌ Migration failed:', err.message);
+            process.exit(1);
+        } finally {
+            await this.close();
+        }
+    }
+}
+
+// CLI usage
+if (require.main === module) {
+    const sourceDb = process.argv[2];
+    const targetDb = process.argv[3] || './memory-v2.db';
+
+    if (!sourceDb) {
+        console.log('Usage: node migrations/v1-to-v2.js <source-v1.db> [target-v2.db]');
+        console.log('Example: node migrations/v1-to-v2.js ./memory-v1.db ./memory-v2.db');
+        process.exit(1);
+    }
+
+    const migration = new MemoryMigration(sourceDb, targetDb);
+    migration.migrate();
+}
+
+module.exports = MemoryMigration;

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "memory-lucia",
-  "version": "2.0.1",
-  "description": "Advanced memory system for OpenClaw agents with priority analysis, learning tracking, decision recording, and skill evolution",
-  "main": "api/index.js",
-  "scripts": {
-    "start": "node api/index.js",
-    "init": "node scripts/init-memory.js",
-    "test": "node tests/test.js",
-    "backup": "node scripts/backup.js"
-  },
-  "keywords": [
-    "openclaw",
-    "skill",
-    "memory",
-    "learning",
-    "decision",
-    "priority",
-    "evolution",
-    "sqlite"
-  ],
-  "author": "Chief of Staff",
-  "license": "MIT",
-  "dependencies": {
-    "sqlite3": "^5.1.6"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/wen521/memory-lucia-.git"
-  },
-  "bugs": {
-    "url": "https://github.com/wen521/memory-lucia-/issues"
-  },
-  "homepage": "https://github.com/wen521/memory-lucia-#readme"
-}
+{
+  "name": "memory-lucia",
+  "version": "2.0.3",
+  "description": "Advanced memory system for OpenClaw agents with priority analysis, learning tracking, decision recording, and skill evolution",
+  "main": "api/index.js",
+  "scripts": {
+    "start": "node api/index.js",
+    "init": "node scripts/init-memory.js",
+    "test": "node tests/test.js",
+    "backup": "node scripts/backup.js"
+  },
+  "keywords": [
+    "openclaw",
+    "skill",
+    "memory",
+    "learning",
+    "decision",
+    "priority",
+    "evolution",
+    "sqlite"
+  ],
+  "author": "Chief of Staff",
+  "license": "MIT",
+  "dependencies": {
+    "sqlite3": "^5.1.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wen521/memory-lucia-.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wen521/memory-lucia-/issues"
+  },
+  "homepage": "https://github.com/wen521/memory-lucia-#readme"
+}

package/references/API.md

@@ -0,0 +1,364 @@
+# Memory V2 API Reference
+
+Complete API documentation for the Memory V2 system.
+
+## Table of Contents
+
+- [Initialization](#initialization)
+- [Priority Module](#priority-module)
+- [Learning Module](#learning-module)
+- [Decision Module](#decision-module)
+- [Evolution Module](#evolution-module)
+- [Dashboard](#dashboard)
+- [Version Management](#version-management)
+
+---
+
+## Initialization
+
+```javascript
+const MemoryAPI = require('./api');
+
+// Create instance
+const api = new MemoryAPI('./memory-v2.db');
+
+// Initialize database
+await api.init();
+
+// Close when done
+await api.close();
+```
+
+---
+
+## Priority Module
+
+### analyzePriority(message)
+Analyze a message and return priority assessment.
+
+**Parameters:**
+- `message` (string): The message to analyze
+
+**Returns:**
+```javascript
+{
+  priority_level: 'critical' | 'high' | 'medium' | 'low',
+  reasoning: string,
+  category: string
+}
+```
+
+### storePriority(msgId, convId, analysis)
+Store priority analysis in database.
+
+**Parameters:**
+- `msgId` (string): Message ID
+- `convId` (string): Conversation ID
+- `analysis` (object): Result from analyzePriority
+
+**Returns:** `Promise<{id: number}>`
+
+### getHighPriority(limit = 10)
+Get recent high/critical priority items.
+
+**Parameters:**
+- `limit` (number): Maximum results
+
+**Returns:** `Promise<Array>`
+
+### getPriorityStats()
+Get priority distribution statistics.
+
+**Returns:**
+```javascript
+{
+  critical: number,
+  high: number,
+  medium: number,
+  low: number,
+  total: number
+}
+```
+
+---
+
+## Learning Module
+
+### startLearning(msgId, convId, message)
+Start tracking a new learning topic.
+
+**Parameters:**
+- `msgId` (string): Message ID
+- `convId` (string): Conversation ID  
+- `message` (string): Message describing the learning topic
+
+**Returns:**
+```javascript
+{
+  id: number,
+  topic: string,
+  status: 'active',
+  progress: 0
+}
+```
+
+### updateLearningProgress(learningId, updates)
+Update learning progress.
+
+**Parameters:**
+- `learningId` (number): Learning record ID
+- `updates` (object):
+  - `progress` (number): 0-100
+  - `status` (string): 'active' | 'paused' | 'completed' | 'abandoned'
+
+### addMilestone(learningId, milestone)
+Add a milestone to a learning record.
+
+**Parameters:**
+- `learningId` (number): Learning record ID
+- `milestone` (object):
+  - `title` (string): Milestone title
+  - `description` (string): Optional description
+
+### getActiveLearning(limit = 5)
+Get currently active learning topics.
+
+**Parameters:**
+- `limit` (number): Maximum results
+
+**Returns:** `Promise<Array>`
+
+### getLearningStats()
+Get learning statistics.
+
+**Returns:**
+```javascript
+{
+  active: number,
+  completed: number,
+  total: number,
+  avg_progress: number
+}
+```
+
+---
+
+## Decision Module
+
+### recordDecision(msgId, convId, decisionData)
+Record a new decision.
+
+**Parameters:**
+- `msgId` (string): Message ID
+- `convId` (string): Conversation ID
+- `decisionData` (object):
+  - `summary` (string): Decision summary (required)
+  - `context` (string): Decision context
+  - `expectedOutcome` (string): Expected result
+  - `reviewDate` (string): ISO date for review
+
+**Returns:** `Promise<{id: number}>`
+
+### updateDecisionOutcome(decisionId, outcome)
+Update the actual outcome of a decision.
+
+**Parameters:**
+- `decisionId` (number): Decision ID
+- `outcome` (object):
+  - `actualOutcome` (string): What actually happened
+  - `status` (string): 'implemented' | 'validated' | 'rejected'
+
+### getPendingDecisions()
+Get decisions pending review or implementation.
+
+**Returns:** `Promise<Array>`
+
+### scheduleReview(decisionId, reviewDate)
+Schedule a review for a decision.
+
+**Parameters:**
+- `decisionId` (number): Decision ID
+- `reviewDate` (string): ISO date string
+
+---
+
+## Evolution Module
+
+### recordSkillUsage(skillName, category, result)
+Record skill usage.
+
+**Parameters:**
+- `skillName` (string): Name of the skill
+- `category` (string): Skill category
+- `result` (string): 'success' | 'failure'
+
+### getTopSkills(limit = 10)
+Get most frequently used skills.
+
+**Parameters:**
+- `limit` (number): Maximum results
+
+**Returns:** `Promise<Array>`
+
+### getSkillStats(skillName)
+Get statistics for a specific skill.
+
+**Parameters:**
+- `skillName` (string): Skill name
+
+**Returns:**
+```javascript
+{
+  skill_name: string,
+  category: string,
+  usage_count: number,
+  success_count: number,
+  success_rate: number,
+  last_used_at: string
+}
+```
+
+---
+
+## Dashboard
+
+### getDashboard()
+Get unified dashboard of all memory data.
+
+**Returns:**
+```javascript
+{
+  summary: {
+    total_priorities: number,
+    total_learning: number,
+    total_decisions: number,
+    total_skills: number
+  },
+  recent: {
+    priorities: Array,
+    learning: Array,
+    decisions: Array
+  },
+  stats: {
+    priorities: Object,
+    learning: Object,
+    skills: Array
+  }
+}
+```
+
+---
+
+## Version Management
+
+### createBackup(label)
+Create a database backup.
+
+**Parameters:**
+- `label` (string): Optional label for the backup
+
+**Returns:** `Promise<{backupPath: string}>`
+
+### listBackups()
+List all available backups.
+
+**Returns:** `Promise<Array>`
+
+### restoreBackup(backupPath)
+Restore from a backup.
+
+**Parameters:**
+- `backupPath` (string): Path to backup file
+
+**Returns:** `Promise<boolean>`
+
+### cleanupBackups(keepCount = 10)
+Clean up old backups, keeping only the specified number.
+
+**Parameters:**
+- `keepCount` (number): Number of backups to keep
+
+---
+
+## Database Views
+
+The following SQL views are available for direct queries:
+
+### v_pending_decisions
+Decisions that need attention (pending, overdue, or due soon).
+
+### v_skill_summary
+Skill usage statistics with success rates.
+
+### v_weekly_learning_report
+Learning activity summary for the past week.
+
+### v_high_priority
+Combined view of high priority items and pending decisions.
+
+---
+
+## Error Handling
+
+All API methods return Promises and may throw:
+
+```javascript
+try {
+  const result = await api.storePriority(msgId, convId, analysis);
+} catch (err) {
+  console.error('API Error:', err.message);
+}
+```
+
+Common errors:
+- Database not initialized
+- Invalid parameters
+- Constraint violations
+- File system errors (backups)
+
+---
+
+## Examples
+
+### Complete Workflow
+
+```javascript
+const MemoryAPI = require('./api');
+const api = new MemoryAPI('./memory-v2.db');
+
+async function example() {
+  await api.init();
+  
+  // Record a decision
+  const decision = await api.recordDecision('msg-123', 'conv-456', {
+    summary: 'Use SQLite for local storage',
+    context: 'Need embedded database for skill',
+    expectedOutcome: 'Simpler deployment'
+  });
+  
+  // Start learning
+  const learning = await api.startLearning('msg-124', 'conv-456', 
+    'Learning SQLite advanced features'
+  );
+  
+  // Update progress
+  await api.updateLearningProgress(learning.id, { progress: 50 });
+  
+  // Record skill usage
+  await api.recordSkillUsage('memory-v2', 'storage', 'success');
+  
+  // Get dashboard
+  const dashboard = await api.getDashboard();
+  console.log(dashboard);
+  
+  await api.close();
+}
+
+example();
+```
+
+---
+
+## License
+
+MIT