ultra-memory 3.1.0 → 4.0.0

package/integrations/__init__.py

@@ -0,0 +1 @@
+# ultra-memory integrations package

package/integrations/langchain_memory.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""
+ultra-memory: LangChain Memory 集成
+提供 UltraMemoryMemory 类，实现 LangChain BaseMemory 接口，
+可直接用于 LC agents。
+
+用法:
+    from integrations.langchain_memory import UltraMemoryMemory
+    memory = UltraMemoryMemory(session_id="sess_langchain_test", project="my-agent")
+    agent = OpenAIAgent(..., memory=memory)
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    from langchain.schema import BaseMemory
+    from langchain.schema import HumanMessage, AIMessage
+    HAS_LANGCHAIN = True
+except ImportError:
+    HAS_LANGCHAIN = False
+
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+_SCRIPTS_DIR = Path(__file__).parent.parent / "scripts"
+
+
+class UltraMemoryMemory:
+    """
+    LangChain memory backed by ultra-memory's 5-layer system.
+    Implements BaseMemory-compatible interface.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        project: str = "langchain",
+        top_k: int = 5,
+    ):
+        self.session_id = session_id
+        self.project = project
+        self.top_k = top_k
+
+    @property
+    def memory_variables(self) -> list[str]:
+        return ["ultra_memory_context"]
+
+    def load_memory_variables(self, inputs: dict) -> dict:
+        """加载与当前上下文相关的记忆"""
+        query = inputs.get("query", "")
+
+        if not self.session_id:
+            return {"ultra_memory_context": ""}
+
+        if query:
+            # 使用 recall 获取相关记忆
+            import subprocess, io
+            recall_script = _SCRIPTS_DIR / "recall.py"
+            old_stdout = sys.stdout
+            sys.stdout = io.StringIO()
+            try:
+                subprocess.run(
+                    [sys.executable, str(recall_script),
+                     "--session", self.session_id,
+                     "--query", query,
+                     "--top-k", str(self.top_k)],
+                    capture_output=True,
+                    timeout=30,
+                )
+                context = sys.stdout.getvalue()
+            except Exception:
+                context = ""
+            finally:
+                sys.stdout = old_stdout
+        else:
+            # 加载最新摘要
+            summary_file = ULTRA_MEMORY_HOME / "sessions" / self.session_id / "summary.md"
+            if summary_file.exists():
+                context = summary_file.read_text(encoding="utf-8")
+            else:
+                context = ""
+
+        return {"ultra_memory_context": context}
+
+    def save_context(self, inputs: dict, outputs: dict) -> None:
+        """保存一轮对话到 ultra-memory"""
+        import subprocess
+
+        input_text = inputs.get("input", "")[:200]
+        output_text = outputs.get("output", "")[:200]
+
+        detail = {
+            "input": inputs.get("input", ""),
+            "output": outputs.get("output", ""),
+        }
+
+        try:
+            subprocess.run(
+                [
+                    sys.executable,
+                    str(_SCRIPTS_DIR / "log_op.py"),
+                    "--session", self.session_id,
+                    "--type", "tool_call",
+                    "--summary", f"LC: {input_text[:60]}",
+                    "--detail", json.dumps(detail, ensure_ascii=False),
+                    "--tags", "langchain",
+                ],
+                capture_output=True,
+                timeout=5,
+            )
+        except Exception:
+            pass
+
+    def clear(self) -> None:
+        """清除当前记忆（不删除 session）"""
+        self.session_id = None

package/integrations/langgraph_checkpointer.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""
+ultra-memory: LangGraph Checkpointer 集成
+提供 UltraMemoryCheckpointer 类，作为 LangGraph 的状态持久化后端。
+
+用法:
+    from integrations.langgraph_checkpointer import UltraMemoryCheckpointer
+    checkpointer = UltraMemoryCheckpointer(session_id="sess_langgraph_proj")
+    compiled = graph.compile(checkpointer=checkpointer)
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+
+
+class UltraMemoryCheckpointer:
+    """
+    LangGraph checkpointer backed by ultra-memory。
+    在每个节点执行后保存/恢复 agent graph 状态。
+    """
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        self.checkpoint_dir = ULTRA_MEMORY_HOME / "sessions" / session_id / "checkpoints"
+        self.checkpoint_dir.mkdir(parents=True, exist_ok=True)
+
+    def _checkpoint_file(self, thread_id: str, step: int) -> Path:
+        """获取检查点文件路径"""
+        return self.checkpoint_dir / f"thread_{thread_id}_step_{step:04d}.json"
+
+    def get(self, thread_id: str, step: int) -> Optional[dict[str, Any]]:
+        """获取指定 thread 和 step 的检查点状态"""
+        checkpoint_file = self._checkpoint_file(thread_id, step)
+        if not checkpoint_file.exists():
+            return None
+        try:
+            with open(checkpoint_file, encoding="utf-8") as f:
+                data = json.load(f)
+            return data.get("state")
+        except (json.JSONDecodeError, IOError):
+            return None
+
+    def put(self, thread_id: str, step: int, state: dict[str, Any]) -> None:
+        """保存检查点状态"""
+        checkpoint_file = self._checkpoint_file(thread_id, step)
+        data = {
+            "step": step,
+            "state": state,
+            "session_id": self.session_id,
+            "thread_id": thread_id,
+        }
+        with open(checkpoint_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+
+    def get_latest(self, thread_id: str) -> Optional[dict[str, Any]]:
+        """获取指定 thread 的最新检查点"""
+        checkpoints = sorted(
+            self.checkpoint_dir.glob(f"thread_{thread_id}_step_*.json"),
+            key=lambda p: int(p.stem.split("_")[-1]),
+        )
+        if not checkpoints:
+            return None
+        return self.get(thread_id, int(checkpoints[-1].stem.split("_")[-1]))
+
+    def list_threads(self) -> list[str]:
+        """列出所有已有 thread ID"""
+        threads = set()
+        for f in self.checkpoint_dir.glob("thread_*_step_*.json"):
+            parts = f.stem.split("_")
+            if len(parts) >= 2:
+                threads.add(parts[1])
+        return sorted(threads)

package/integrations/n8n_nodes.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+ultra-memory: n8n 集成节点
+作为 n8n "Execute Command" 节点的 Python 脚本后端，
+支持 init / log / recall 三种操作。
+
+n8n 配置示例：
+  Execute Command 节点
+    命令: python3
+    参数: /path/to/ultra-memory/integrations/n8n_nodes.py <operation> <args>
+
+Operations:
+  init --project <proj>                    → 返回 session_id
+  log --session <id> --summary "..." --type <type> --detail '{}'
+  recall --session <id> --query "..."
+  profile --action read|update --field <field> --value <value>
+"""
+
+import json
+import os
+import sys
+import re
+from pathlib import Path
+
+ULTRA_MEMORY_HOME = Path(os.environ.get("ULTRA_MEMORY_HOME", Path.home() / ".ultra-memory"))
+_SCRIPTS_DIR = Path(__file__).parent.parent / "scripts"
+
+
+def _run_script(script_name: str, args: list[str]) -> str:
+    """运行脚本并返回输出"""
+    import subprocess
+
+    script_path = _SCRIPTS_DIR / script_name
+    result = subprocess.run(
+        [sys.executable, str(script_path)] + args,
+        capture_output=True, text=True, timeout=30,
+    )
+    return result.stdout + result.stderr
+
+
+def cmd_init(project: str) -> dict:
+    """初始化会话"""
+    output = _run_script("init.py", ["--project", project, "--resume"])
+
+    session_id = None
+    memory_ready = False
+
+    for line in output.split("\n"):
+        if "session_id:" in line:
+            match = re.search(r"session_id:\s*(sess_\w+)", line)
+            if match:
+                session_id = match.group(1)
+        if "MEMORY_READY" in line:
+            memory_ready = True
+
+    return {
+        "success": memory_ready,
+        "session_id": session_id,
+        "output": output,
+    }
+
+
+def cmd_log(session_id: str, summary: str, op_type: str, detail: str = "{}") -> dict:
+    """记录操作"""
+    output = _run_script("log_op.py", [
+        "--session", session_id,
+        "--type", op_type,
+        "--summary", summary,
+        "--detail", detail,
+    ])
+    return {"success": True, "output": output}
+
+
+def cmd_recall(session_id: str, query: str, top_k: int = 5) -> dict:
+    """检索记忆"""
+    output = _run_script("recall.py", [
+        "--session", session_id,
+        "--query", query,
+        "--top-k", str(top_k),
+    ])
+    return {"success": True, "output": output}
+
+
+def cmd_profile(action: str, field: str = None, value: str = None) -> dict:
+    """读取或更新用户画像"""
+    if action == "read":
+        output = _run_script("evolve_profile.py", [])
+        return {"success": True, "output": output}
+    elif action == "update" and field and value:
+        output = _run_script("evolve_profile.py", [
+            "--field", field, "--value", value,
+        ])
+        return {"success": True, "output": output}
+    return {"success": False, "error": "invalid profile command"}
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: n8n_nodes.py <init|log|recall|profile> [args...]")
+        sys.exit(1)
+
+    operation = sys.argv[1].lower()
+    args = sys.argv[2:]
+
+    result = {}
+    try:
+        if operation == "init":
+            project = next((a for a in args if a.startswith("--project=")),
+                          "--project=default").split("=", 1)[1]
+            result = cmd_init(project)
+
+        elif operation == "log":
+            session_id = next((a for a in args if a.startswith("--session=")),
+                             None).split("=", 1)[1]
+            summary = next((a for a in args if a.startswith("--summary=")),
+                          "").split("=", 1)[1]
+            op_type = next((a for a in args if a.startswith("--type=")),
+                          "tool_call").split("=", 1)[1]
+            detail = next((a for a in args if a.startswith("--detail=")),
+                         "{}").split("=", 1)[1]
+            result = cmd_log(session_id, summary, op_type, detail)
+
+        elif operation == "recall":
+            session_id = next((a for a in args if a.startswith("--session=")),
+                             None).split("=", 1)[1]
+            query = next((a for a in args if a.startswith("--query=")),
+                        "").split("=", 1)[1]
+            result = cmd_recall(session_id, query)
+
+        elif operation == "profile":
+            action = next((a for a in args if a.startswith("--action=")),
+                         "read").split("=", 1)[1]
+            field = next((a for a in args if a.startswith("--field=")),
+                        None)
+            field = field.split("=", 1)[1] if field else None
+            value = next((a for a in args if a.startswith("--value=")),
+                        None)
+            value = value.split("=", 1)[1] if value else None
+            result = cmd_profile(action, field, value)
+
+        else:
+            result = {"success": False, "error": f"unknown operation: {operation}"}
+
+    except Exception as e:
+        result = {"success": False, "error": str(e)}
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-memory",
-  "version": "3.1.0",
-  "description": "超长会话记忆系统 — 5层记忆架构，零外部依赖，支持所有LLM平台（Claude/GPT/Gemini/Qwen等）",
+  "version": "4.0.0",
+  "description": "超长会话记忆系统 — 5层记忆架构+自我进化引擎+时序矛盾检测，支持所有LLM平台",
   "keywords": [
     "ai",
     "memory",
@@ -46,7 +46,9 @@
     "ultra-memory-recall": "scripts/recall.py",
     "ultra-memory-summarize": "scripts/summarize.py",
     "ultra-memory-restore": "scripts/restore.py",
-    "ultra-memory-knowledge": "scripts/log_knowledge.py"
+    "ultra-memory-knowledge": "scripts/log_knowledge.py",
+    "ultra-memory-extract-facts": "scripts/extract_facts.py",
+    "ultra-memory-evolve": "scripts/evolve_profile.py"
   },
   "scripts": {
     "test": "python3 test_e2e.py",
@@ -57,6 +59,14 @@
     "node": ">=18.0.0",
     "python": ">=3.8.0"
   },
+  "optionalDependencies": {
+    "pdfminer.six": "*",
+    "pytesseract": "*",
+    "whisper": "*"
+  },
+  "peerDependencies": {
+    "langchain": ">=0.1.0"
+  },
   "os": [
     "darwin",
     "linux",
@@ -64,7 +74,9 @@
   ],
   "files": [
     "scripts/",
+    "scripts/multimodal/",
     "platform/",
+    "integrations/",
     "SKILL.md",
     "README.md",
     "CLAWHUB.md"
@@ -102,7 +114,8 @@
       "2": "summary.md — 会话摘要层（里程碑压缩）",
       "3": "semantic/ — 跨会话语义层（知识库+实体索引）",
       "4": "entities.jsonl — 结构化实体索引（7类实体）",
-      "5": "tfidf_cache.json — 向量语义层（TF-IDF/sentence-transformers）"
+      "5": "tfidf_cache.json — 向量语义层（TF-IDF/sentence-transformers）",
+      "6": "evolution/ — 自我进化层（事实提取+矛盾检测+遗忘）"
     }
   }
 }