ultra-memory 3.0.0

package/platform/tools_openai.json

@@ -0,0 +1,207 @@
+[
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_init",
+      "description": "Initialize ultra-memory session. Call at conversation start to create three-layer memory structure and inject historical context.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "project": {
+            "type": "string",
+            "description": "Project name (default: 'default')"
+          },
+          "resume": {
+            "type": "boolean",
+            "description": "Try to resume the most recent session for this project"
+          }
+        },
+        "required": []
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_status",
+      "description": "Query current session status: operation count, last milestone, context pressure level (low/medium/high/critical). Use to decide when to compress.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "session_id": {
+            "type": "string",
+            "description": "Session ID returned by memory_init"
+          }
+        },
+        "required": ["session_id"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_log",
+      "description": "Record an operation to the current session log (Layer 1). Call after every significant action: file write, bash command, tool call, decision, error, or milestone.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "session_id": {
+            "type": "string",
+            "description": "Current session ID"
+          },
+          "op_type": {
+            "type": "string",
+            "enum": ["tool_call", "file_write", "file_read", "bash_exec", "reasoning", "user_instruction", "decision", "error", "milestone"],
+            "description": "Operation type"
+          },
+          "summary": {
+            "type": "string",
+            "description": "Operation summary (under 50 words)"
+          },
+          "detail": {
+            "type": "object",
+            "description": "Additional detail fields (optional)"
+          },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Tag list (optional, auto-generated if omitted)"
+          }
+        },
+        "required": ["session_id", "op_type", "summary"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_recall",
+      "description": "Retrieve relevant records from all memory layers (ops log, summary, semantic, entity index). Use when you need to recall past work, decisions, or errors.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "session_id": {
+            "type": "string",
+            "description": "Current session ID"
+          },
+          "query": {
+            "type": "string",
+            "description": "Search keywords (Chinese or English)"
+          },
+          "top_k": {
+            "type": "number",
+            "description": "Number of results to return (default: 5)"
+          }
+        },
+        "required": ["session_id", "query"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_summarize",
+      "description": "Trigger summary compression of the current session (compresses ops log into summary.md). Call when context pressure is high or critical, or every ~50 operations.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "session_id": {
+            "type": "string",
+            "description": "Current session ID"
+          },
+          "force": {
+            "type": "boolean",
+            "description": "Force compression even if operation count is low"
+          }
+        },
+        "required": ["session_id"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_restore",
+      "description": "Restore the last session context for a project. Use at conversation start to continue a previous task across days.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "project": {
+            "type": "string",
+            "description": "Project name (default: 'default')"
+          },
+          "verbose": {
+            "type": "boolean",
+            "description": "Show detailed operation records"
+          }
+        },
+        "required": []
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_profile",
+      "description": "Read or update user profile (tech stack, preferences, project list). Persist user-level preferences across all sessions.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": ["read", "update"],
+            "description": "Operation type"
+          },
+          "updates": {
+            "type": "object",
+            "description": "Fields to update (required when action=update)"
+          }
+        },
+        "required": ["action"]
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_entities",
+      "description": "Query structured entity index (functions, files, dependencies, decisions, errors). Use for precise questions like 'which functions were used', 'which packages were installed', 'what decisions were made'.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "entity_type": {
+            "type": "string",
+            "enum": ["function", "file", "dependency", "decision", "error", "class", "all"],
+            "description": "Entity type filter (all = no filter)"
+          },
+          "query": {
+            "type": "string",
+            "description": "Search keyword (optional, empty returns all of that type)"
+          },
+          "top_k": {
+            "type": "number",
+            "description": "Number of results to return (default: 10)"
+          }
+        },
+        "required": []
+      }
+    }
+  },
+  {
+    "type": "function",
+    "function": {
+      "name": "memory_extract_entities",
+      "description": "Re-extract all structured entities from a session's ops.jsonl. Use to repair or initialize the entity index.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "session_id": {
+            "type": "string",
+            "description": "Session ID"
+          }
+        },
+        "required": ["session_id"]
+      }
+    }
+  }
+]

package/scripts/cleanup.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+ultra-memory: 会话清理脚本
+清理 N 天前的历史会话，支持 --archive-only 模式（只归档不删除）
+"""
+
+import os
+import sys
+import json
+import shutil
+import argparse
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+if sys.stdout.encoding != "utf-8":
+    sys.stdout.reconfigure(encoding="utf-8")
+if sys.stderr.encoding != "utf-8":
+    sys.stderr.reconfigure(encoding="utf-8")
+
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+
+
+def parse_session_date(meta: dict) -> datetime:
+    """从 meta 中解析会话开始时间"""
+    ts_str = meta.get("started_at", "")
+    try:
+        return datetime.fromisoformat(ts_str.rstrip("Z")).replace(tzinfo=timezone.utc)
+    except Exception:
+        return datetime.min.replace(tzinfo=timezone.utc)
+
+
+def cleanup(days: int = 30, archive_only: bool = False, dry_run: bool = False, project: str = None):
+    """
+    清理或归档 N 天前的会话。
+
+    Args:
+        days: 清理多少天前的会话（默认 30 天）
+        archive_only: True 时只将旧会话移动到 archive/，不删除
+        dry_run: True 时只打印将要操作的会话，不实际执行
+        project: 只清理指定项目的会话（None 表示所有项目）
+    """
+    sessions_dir = ULTRA_MEMORY_HOME / "sessions"
+    archive_dir = ULTRA_MEMORY_HOME / "archive"
+
+    if not sessions_dir.exists():
+        print("[ultra-memory] 会话目录不存在，无需清理")
+        return
+
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    print(f"[ultra-memory] 清理 {cutoff.strftime('%Y-%m-%d')} 之前的会话")
+    if archive_only:
+        print(f"[ultra-memory] 模式: 归档（不删除）")
+    if dry_run:
+        print(f"[ultra-memory] 模式: 演习（dry-run，不实际执行）")
+
+    removed = 0
+    archived = 0
+    skipped = 0
+
+    for session_dir in sessions_dir.iterdir():
+        if not session_dir.is_dir():
+            continue
+
+        meta_file = session_dir / "meta.json"
+        if not meta_file.exists():
+            continue
+
+        with open(meta_file, encoding="utf-8") as f:
+            meta = json.load(f)
+
+        # 过滤项目
+        if project and meta.get("project") != project:
+            skipped += 1
+            continue
+
+        session_date = parse_session_date(meta)
+        session_id = meta.get("session_id", session_dir.name)
+
+        if session_date >= cutoff:
+            skipped += 1
+            continue
+
+        age_days = (datetime.now(timezone.utc) - session_date).days
+        print(f"  {'[DRY]' if dry_run else ''} 处理: {session_id} ({age_days} 天前, 项目: {meta.get('project', '?')})")
+
+        if dry_run:
+            continue
+
+        if archive_only:
+            # 移动到 archive 目录
+            archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = archive_dir / session_dir.name
+            if not dest.exists():
+                shutil.move(str(session_dir), str(dest))
+                archived += 1
+                print(f"    → 已归档到 {dest}")
+            else:
+                print(f"    ⚠️  归档目标已存在，跳过: {dest}")
+        else:
+            # 直接删除
+            shutil.rmtree(session_dir)
+            removed += 1
+            print(f"    → 已删除")
+
+    # 同步更新 session_index.json（移除已清理的条目）
+    if not dry_run and (removed > 0 or archived > 0):
+        _update_session_index(cutoff, project, archive_only)
+
+    print(f"\n[ultra-memory] 清理完成：")
+    print(f"  删除: {removed} 个会话")
+    print(f"  归档: {archived} 个会话")
+    print(f"  跳过: {skipped} 个会话（未到期或不匹配项目）")
+
+
+def _update_session_index(cutoff: datetime, project: str, archive_only: bool):
+    """从 session_index.json 中移除已清理的会话条目"""
+    index_file = ULTRA_MEMORY_HOME / "semantic" / "session_index.json"
+    if not index_file.exists():
+        return
+
+    with open(index_file, encoding="utf-8") as f:
+        index = json.load(f)
+
+    original_count = len(index.get("sessions", []))
+    kept = []
+    for s in index.get("sessions", []):
+        ts_str = s.get("started_at", "")
+        try:
+            ts = datetime.fromisoformat(ts_str.rstrip("Z")).replace(tzinfo=timezone.utc)
+        except Exception:
+            kept.append(s)
+            continue
+        if ts >= cutoff:
+            kept.append(s)
+        elif project and s.get("project") != project:
+            kept.append(s)
+        elif archive_only:
+            # 归档模式：标记为 archived，保留索引条目
+            s["archived"] = True
+            kept.append(s)
+
+    index["sessions"] = kept
+    with open(index_file, "w", encoding="utf-8") as f:
+        json.dump(index, f, ensure_ascii=False, indent=2)
+
+    print(f"[ultra-memory] session_index.json: {original_count} → {len(kept)} 条记录")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="清理历史会话")
+    parser.add_argument("--days", type=int, default=30, help="清理多少天前的会话（默认 30 天）")
+    parser.add_argument("--archive-only", action="store_true", help="只归档到 archive/ 目录，不删除")
+    parser.add_argument("--dry-run", action="store_true", help="演习模式，只打印不执行")
+    parser.add_argument("--project", default=None, help="只清理指定项目（默认所有项目）")
+    args = parser.parse_args()
+    cleanup(args.days, args.archive_only, args.dry_run, args.project)

package/scripts/export.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+ultra-memory: 记忆导出脚本
+将所有记忆（会话日志、摘要、语义层）打包为 zip 备份文件
+"""
+
+import os
+import sys
+import json
+import shutil
+import argparse
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+if sys.stdout.encoding != "utf-8":
+    sys.stdout.reconfigure(encoding="utf-8")
+if sys.stderr.encoding != "utf-8":
+    sys.stderr.reconfigure(encoding="utf-8")
+
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+
+
+def export_memory(
+    output_path: str = None,
+    project: str = None,
+    include_archive: bool = False,
+    days: int = None,
+):
+    """
+    导出 ultra-memory 数据为 zip 备份。
+
+    Args:
+        output_path: 输出 zip 文件路径（默认 ~/ultra-memory-backup-<date>.zip）
+        project: 只导出指定项目（None 表示全部）
+        include_archive: 是否包含 archive/ 目录中的归档会话
+        days: 只导出最近 N 天的会话（None 表示全部）
+    """
+    if not ULTRA_MEMORY_HOME.exists():
+        print(f"[ultra-memory] 记忆目录不存在: {ULTRA_MEMORY_HOME}")
+        return
+
+    # 默认输出路径
+    if not output_path:
+        date_str = datetime.now().strftime("%Y%m%d_%H%M%S")
+        output_path = str(Path.home() / f"ultra-memory-backup-{date_str}.zip")
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now(timezone.utc)
+    cutoff = None
+    if days is not None:
+        from datetime import timedelta
+        cutoff = now - timedelta(days=days)
+
+    added_files = 0
+    skipped_files = 0
+
+    print(f"[ultra-memory] 开始导出到: {output_path}")
+    if project:
+        print(f"[ultra-memory] 过滤项目: {project}")
+    if cutoff:
+        print(f"[ultra-memory] 只导出 {cutoff.strftime('%Y-%m-%d')} 之后的数据")
+
+    with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        # 1. 导出 semantic 目录（用户画像、知识库、会话索引）
+        semantic_dir = ULTRA_MEMORY_HOME / "semantic"
+        if semantic_dir.exists():
+            for file in semantic_dir.rglob("*"):
+                if file.is_file():
+                    arcname = file.relative_to(ULTRA_MEMORY_HOME)
+                    zf.write(file, arcname)
+                    added_files += 1
+            print(f"[ultra-memory] ✅ 导出语义层: {semantic_dir}")
+
+        # 2. 导出 sessions 目录
+        sessions_dir = ULTRA_MEMORY_HOME / "sessions"
+        if sessions_dir.exists():
+            for session_dir in sessions_dir.iterdir():
+                if not session_dir.is_dir():
+                    continue
+
+                meta_file = session_dir / "meta.json"
+                if not meta_file.exists():
+                    continue
+
+                with open(meta_file) as f:
+                    meta = json.load(f)
+
+                # 过滤项目
+                if project and meta.get("project") != project:
+                    skipped_files += 1
+                    continue
+
+                # 过滤时间
+                if cutoff:
+                    ts_str = meta.get("started_at", "")
+                    try:
+                        ts = datetime.fromisoformat(ts_str.rstrip("Z")).replace(tzinfo=timezone.utc)
+                        if ts < cutoff:
+                            skipped_files += 1
+                            continue
+                    except Exception:
+                        pass
+
+                # 将整个会话目录打包
+                for file in session_dir.rglob("*"):
+                    if file.is_file():
+                        arcname = file.relative_to(ULTRA_MEMORY_HOME)
+                        zf.write(file, arcname)
+                        added_files += 1
+
+                print(f"  + {session_dir.name} (项目: {meta.get('project', '?')}, "
+                      f"操作数: {meta.get('op_count', 0)})")
+
+        # 3. 可选：导出 archive 目录
+        if include_archive:
+            archive_dir = ULTRA_MEMORY_HOME / "archive"
+            if archive_dir.exists():
+                for file in archive_dir.rglob("*"):
+                    if file.is_file():
+                        arcname = file.relative_to(ULTRA_MEMORY_HOME)
+                        zf.write(file, arcname)
+                        added_files += 1
+                print(f"[ultra-memory] ✅ 导出归档层: {archive_dir}")
+
+        # 4. 写入导出元信息
+        export_meta = {
+            "exported_at": now.isoformat(),
+            "ultra_memory_home": str(ULTRA_MEMORY_HOME),
+            "filter_project": project,
+            "filter_days": days,
+            "include_archive": include_archive,
+            "total_files": added_files,
+        }
+        zf.writestr("export_meta.json", json.dumps(export_meta, ensure_ascii=False, indent=2))
+
+    # 统计 zip 大小
+    zip_size_kb = output_path.stat().st_size / 1024
+
+    print(f"\n[ultra-memory] ✅ 导出完成")
+    print(f"  输出文件: {output_path}")
+    print(f"  文件大小: {zip_size_kb:.1f} KB")
+    print(f"  已打包: {added_files} 个文件")
+    if skipped_files:
+        print(f"  已跳过: {skipped_files} 个会话（不符合过滤条件）")
+    print(f"\n  恢复方式: unzip {output_path} -d ~/.ultra-memory/")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="导出 ultra-memory 数据为 zip 备份")
+    parser.add_argument("--output", default=None, help="输出 zip 路径（默认 ~/ultra-memory-backup-<date>.zip）")
+    parser.add_argument("--project", default=None, help="只导出指定项目（默认全部）")
+    parser.add_argument("--include-archive", action="store_true", help="同时导出归档会话")
+    parser.add_argument("--days", type=int, default=None, help="只导出最近 N 天的会话")
+    args = parser.parse_args()
+    export_memory(args.output, args.project, args.include_archive, args.days)