memory-lucia 2.0.1 → 2.0.2

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

package/GITHUB-SETUP.md

@@ -1,81 +0,0 @@
-# GitHub 发布步骤
-
-## 🚀 创建 GitHub 仓库
-
-### 方式 1: 命令行 (推荐)
-
-```bash
-cd C:\Users\snowya\.openclaw\workspace-chief_of_staff\memory-v2-skill
-
-# 初始化 git
-git init
-
-# 添加所有文件
-git add .
-
-# 提交
-git commit -m "Initial commit: Memory Lucia v2.0.0"
-
-# 创建 GitHub 仓库 (需要安装 gh CLI)
-# 或者手动在 https://github.com/new 创建
-
-# 关联远程仓库
-git remote add origin https://github.com/snowya/memory-lucia.git
-
-# 推送
-git push -u origin main
-```
-
-### 方式 2: 网页操作
-
-1. 访问 https://github.com/new
-2. 填写信息：
-   - **Repository name**: `memory-lucia`
-   - **Description**: `Advanced memory system for OpenClaw agents`
-   - **Public** (勾选)
-   - **Add a README file** (不要勾选，已有 README)
-3. 点击 **Create repository**
-4. 按页面提示推送代码
-
-## 📦 创建 Release
-
-1. 访问 https://github.com/snowya/memory-lucia/releases
-2. 点击 **"Create a new release"**
-3. 填写信息：
-   - **Tag**: `v2.0.0`
-   - **Title**: `Memory Lucia v2.0.0`
-   - **Description**:
-```markdown
-## Memory Lucia v2.0.0
-
-Advanced memory system for OpenClaw agents.
-
-### Features
-- Priority Analysis
-- Learning Tracking
-- Decision Recording
-- Skill Evolution
-- Version Management
-
-### Installation
-```bash
-npm install memory-lucia
-```
-
-### Links
-- npm: https://www.npmjs.com/package/memory-lucia
-```
-4. 点击 **Publish release**
-
-## ✅ 完成检查
-
-- [ ] GitHub 仓库已创建
-- [ ] 代码已推送
-- [ ] Release 已发布
-- [ ] README 中的链接可点击
-- [ ] npm 页面显示 GitHub 链接
-
-## 🔗 相关链接
-
-- GitHub: https://github.com/snowya/memory-lucia
-- npm: https://www.npmjs.com/package/memory-lucia

package/NPM-PUBLISH-GUIDE.md

@@ -1,169 +0,0 @@
-# Memory V2 Skill - NPM 发布指南
-
-> 将 Memory V2 发布为 npm 包，供 ClawHub Skill 使用
-
----
-
-## 📋 发现：ClawHub Skill 格式
-
-**ClawHub 上的 Skill 只有 SKILL.md**，代码通过 npm 安装。
-
-### 标准结构
-
-```
-clawhub-skill/
-└── SKILL.md          # 只有描述文件
-```
-
-### npm 包结构
-
-```
-memory-v2/            # npm 包
-├── package.json
-├── README.md
-├── LICENSE
-├── api/
-│   └── index.js      # 主入口
-├── modules/          # 核心模块
-└── ...
-```
-
----
-
-## 🚀 发布流程
-
-### 步骤 1: 准备 npm 包
-
-```bash
-cd memory-v2-skill
-
-# 1. 确保 package.json 正确
-# 2. 更新版本号
-npm version 2.0.0
-
-# 3. 创建 .npmignore
-echo "tests/" > .npmignore
-echo "backups/" >> .npmignore
-echo "*.db" >> .npmignore
-
-# 4. 发布到 npm
-npm publish
-```
-
-### 步骤 2: 创建 ClawHub Skill
-
-创建 `clawhub-memory-v2/` 目录，只包含 SKILL.md：
-
-```yaml
----
-name: memory-v2
-description: |
-  Advanced memory system for OpenClaw agents with priority analysis, 
-  learning tracking, decision recording, and skill evolution.
-  Use when: (1) Tracking learning progress and milestones, (2) Recording decisions with outcomes, 
-  (3) Analyzing message priorities, (4) Monitoring skill usage and growth.
-  Requires: npm install memory-v2-skill
----
-
-# Memory V2
-
-## Installation
-
-```bash
-npm install memory-v2-skill
-```
-
-## Usage
-
-```javascript
-const MemoryAPI = require('memory-v2-skill');
-
-const api = new MemoryAPI('./memory-v2.db');
-await api.init();
-
-// Track learning
-await api.startLearning(msgId, convId, message);
-
-// Record decision
-await api.recordDecision(msgId, convId, decisionData);
-
-// Get dashboard
-const dashboard = await api.getDashboard();
-```
-
-## API
-
-See: https://github.com/YOUR_USERNAME/memory-v2-skill#api
-```
-
-### 步骤 3: 打包并提交
-
-```bash
-# 打包 ClawHub Skill
-cd clawhub-memory-v2
-zip ../memory-v2.skill SKILL.md
-
-# 提交到 ClawHub
-# 上传 memory-v2.skill 文件
-```
-
----
-
-## 📦 两种发布方式对比
-
-| 方式 | 适用场景 | 复杂度 |
-|------|---------|--------|
-| **npm + ClawHub** | 正式发布，用户易安装 | 高 |
-| **GitHub 直接安装** | 快速分享，开发者使用 | 低 |
-
----
-
-## 🎯 推荐方案：GitHub 直接安装
-
-对于 Memory V2，推荐直接 GitHub 安装：
-
-### 用户使用
-
-```bash
-# 克隆到 skills 目录
-cd ~/.openclaw/skills
-git clone https://github.com/YOUR_USERNAME/memory-v2-skill.git memory-v2
-
-# 安装依赖
-cd memory-v2
-npm install
-
-# 使用
-const MemoryAPI = require('memory-v2');
-```
-
-### 优点
-- 无需 npm 账号
-- 无需打包
-- 用户可直接修改
-- 适合自用和分享
-
----
-
-## ✅ 当前状态
-
-您的 `memory-v2-skill/` 已经可以直接使用：
-
-```bash
-# 本地测试
-cd memory-v2-skill
-npm install
-node -e "const M = require('./api'); console.log('OK')"
-
-# 打包 (zip 格式)
-zip -r memory-v2.skill . -x "*.db" "node_modules/*"
-```
-
-**用户安装后可以直接使用！**
-
----
-
-## 📚 参考
-
-- npm 发布: https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry
-- ClawHub: https://clawhub.com

package/PUBLISH-STEPS.md

@@ -1,102 +0,0 @@
-# Memory Lucia 发布步骤
-
-## 🚀 一键发布
-
-在 `memory-v2-skill` 目录下执行：
-
-### Windows
-```bash
-publish.bat
-```
-
-### Linux/Mac
-```bash
-bash publish.sh
-```
-
----
-
-## 📋 手动发布步骤
-
-### 步骤 1: 进入目录
-```bash
-cd C:\Users\snowya\.openclaw\workspace-chief_of_staff\memory-v2-skill
-```
-
-### 步骤 2: 登录 npm
-```bash
-npm login --auth-type=legacy
-```
-
-**输入信息：**
-- Username: `712724810@qq.com`
-- Password: `Q6Ymk#x_4dqM#T@`
-- Email: `712724810@qq.com`
-- Enter one-time password: (如果开启 2FA，输入验证码)
-
-### 步骤 3: 发布
-```bash
-npm publish --access=public
-```
-
----
-
-## ✅ 验证发布
-
-发布成功后，访问：
-https://www.npmjs.com/package/memory-lucia
-
----
-
-## 📦 用户使用
-
-发布后，用户可以直接安装：
-
-```bash
-npm install memory-lucia
-```
-
-```javascript
-const MemoryAPI = require('memory-lucia');
-const api = new MemoryAPI('./memory.db');
-await api.init();
-```
-
----
-
-## 🔧 如果发布失败
-
-### 错误 1: 包名已存在
-```bash
-# 修改 package.json 中的 name
-# 或者使用 scoped name: @yourname/memory-lucia
-```
-
-### 错误 2: 未登录
-```bash
-npm login --auth-type=legacy
-# 重新登录
-```
-
-### 错误 3: 版本已存在
-```bash
-# 更新版本号
-npm version patch  # 2.0.0 -> 2.0.1
-npm publish
-```
-
----
-
-## 📊 发布信息
-
-| 属性 | 值 |
-|------|-----|
-| 包名 | `memory-lucia` |
-| 版本 | `2.0.0` |
-| 大小 | 14.4 KB |
-| 主入口 | `api/index.js` |
-| 依赖 | `sqlite3` |
-
----
-
-**执行 `publish.bat` 或 `publish.sh` 即可发布！**

package/publish-with-otp.bat

@@ -1,13 +0,0 @@
-@echo off
-echo 🚀 Publishing memory-lucia to npm...
-echo.
-echo This package requires 2FA authentication.
-echo.
-echo Please enter your 6-digit 2FA code from your Authenticator app:
-set /p OTP="2FA Code: "
-echo.
-echo Publishing with OTP: %OTP%
-npm publish --access=public --otp=%OTP%
-echo.
-echo ✅ Done!
-pause