mindforge-memory 6.4.1__py3-none-any.whl

MindForge.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""
+MindForge - AI Agent 终身记忆系统
+=======================================
+四层记忆架构 · 知识图谱引擎 · 多模态支持 · 人格化记忆 · 联邦网络 · AI短剧记忆
+
+兼容入口（自 v5.8.13 起）：全部源码已迁入 `mindforge.*` 命名空间，
+本文件仅为向后兼容保留，使 `from MindForge import MindForge` 在 pip install
+后仍然可用。新代码请统一使用 `from mindforge import MindForge`。
+"""
+
+from mindforge import *  # noqa: F401,F403
+from mindforge import (  # noqa: F401
+    __version__,
+    VERSION_INFO,
+    NEXT_MAJOR_TARGET,
+)
+
+__author__ = "MindForge Project"
+__license__ = "MIT"

mindforge/__init__.py

@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+"""
+MindForge — AI Agent 终身记忆系统
+
+四层记忆架构 · 知识图谱引擎 · 多模态支持 · 人格化记忆 · 联邦网络 · AI短剧记忆
+
+包入口（mindforge.* 命名空间）：自 v5.8.13 起全部源码统一位于 mindforge/
+子包下，不再以 core/modules/mcp/api/cli/adapters 等顶层名称安装进
+site-packages，避免与其它库冲突。旧式 `from MindForge import ...` 仍可通过
+仓库根目录的 MindForge.py 兼容模块使用（不推荐新代码使用）。
+"""
+
+from .core import (
+    MindForge,
+    MemoryEntry,
+    MemoryLayer,
+    PrivacyLevel,
+    Importance,
+    MemoryType,
+    MemoryConfig,
+    StorageEngine,
+    EncryptionEngine,
+    IndexEngine,
+    QueryEngine,
+    AuditRecord,
+    MemoryChunk,
+    RecallResult,
+    VectorIndex,
+    init_engine,
+    get_engine,
+)
+from .modules import (
+    RecallEngine,
+    RecallConfig,
+    KnowledgeGraph,
+    MemoryEvolution,
+    PersonalityEngine,
+    MultimodalMemory,
+    FederatedMemory,
+    TaxonomyManager,
+    PrivacyEngine,
+    MemoryIntegrator,
+    # v6.0.0 扩展端口预留（默认不启用，仅暴露发现/注册入口）
+    V6_TARGET_VERSION,
+    V6Capability,
+    V6Status,
+    V6Port,
+    MultiAgentCollaborationPort,
+    MultiAgentAdapterPort,
+    MemoryPreviewPort,
+    create_multi_agent_adapter,
+    register_v6_port,
+    get_v6_port,
+    list_v6_ports,
+    v6_status,
+)
+from .modules.event_bus import EventBus
+from .modules.experience import ExperienceCase, SkillStore
+from .core.version import __version__, VERSION_INFO, NEXT_MAJOR_TARGET
+
+__author__ = "MindForge Project"
+__license__ = "MIT"
+
+__all__ = [
+    "MindForge",
+    "MemoryEntry",
+    "MemoryLayer",
+    "PrivacyLevel",
+    "Importance",
+    "MemoryType",
+    "MemoryConfig",
+    "StorageEngine",
+    "EncryptionEngine",
+    "IndexEngine",
+    "QueryEngine",
+    "AuditRecord",
+    "MemoryChunk",
+    "RecallResult",
+    "VectorIndex",
+    "init_engine",
+    "get_engine",
+    "RecallEngine",
+    "RecallConfig",
+    "KnowledgeGraph",
+    "MemoryEvolution",
+    "PersonalityEngine",
+    "MultimodalMemory",
+    "FederatedMemory",
+    "TaxonomyManager",
+    "PrivacyEngine",
+    "MemoryIntegrator",
+    "EventBus",
+    "ExperienceCase",
+    "SkillStore",
+    "__version__",
+    "VERSION_INFO",
+    "NEXT_MAJOR_TARGET",
+    # v6.0.0 端口预留
+    "V6_TARGET_VERSION",
+    "V6Capability",
+    "V6Status",
+    "V6Port",
+    "MultiAgentCollaborationPort",
+    "MultiAgentAdapterPort",
+    "MemoryPreviewPort",
+    "create_multi_agent_adapter",
+    "register_v6_port",
+    "get_v6_port",
+    "list_v6_ports",
+    "v6_status",
+]

mindforge/adapters/__init__.py

@@ -0,0 +1,18 @@
+"""
+MindForge v5.0 适配器
+OpenClaw · Claude Code · 通用 API · LangGraph Store · CrewAI Memory
+"""
+
+from .openclaw_adapter import OpenClawAdapter
+from .generic_api import GenericAPIAdapter
+from .claude_adapter import ClaudeCodeAdapter
+from .langgraph_store import MindForgeStore
+from .crewai_memory import CrewAIMemory
+
+__all__ = [
+    "OpenClawAdapter",
+    "GenericAPIAdapter",
+    "ClaudeCodeAdapter",
+    "MindForgeStore",
+    "CrewAIMemory",
+]

mindforge/adapters/claude_adapter.py

@@ -0,0 +1,84 @@
+"""
+MindForge v5.0 Claude Code 适配器
+"""
+
+import os
+from typing import List, Dict, Optional
+
+
+class ClaudeCodeAdapter:
+    """Claude Code 记忆适配器"""
+
+    def __init__(self, MindForge):
+        self.cm = MindForge
+        self.session_id = os.environ.get("CLAUDE_SESSION_ID", "claude")
+        self.agent_id = "claude_code"
+
+    @classmethod
+    def from_env(cls):
+        """从环境变量创建"""
+        from mindforge.core import MindForge, MemoryConfig
+
+        db_path = os.environ.get("MindForge_DB_PATH", "./data/memory.db")
+        key_file = os.environ.get("MindForge_KEY_FILE", "./data/.key")
+        encrypted = os.environ.get("MindForge_ENCRYPTED", "true").lower() == "true"
+
+        config = MemoryConfig(
+            db_path=db_path,
+            key_file=key_file,
+            encrypted=encrypted,
+        )
+        cm = MindForge(config=config)
+        return cls(cm)
+
+    def remember(self, content: str, tags: Optional[List[str]] = None) -> str:
+        """记住某件事"""
+        entry = self.cm.add(
+            content=content,
+            tags=tags or [],
+            source_agent=self.agent_id,
+            source_session=self.session_id,
+        )
+        return entry.id
+
+    def recall(self, query: str, limit: int = 5) -> List[str]:
+        """回忆相关内容"""
+        result = self.cm.search(
+            query=query,
+            max_results=limit,
+            agent_id=self.agent_id,
+            session_id=self.session_id,
+        )
+        return [chunk.content for chunk in result.chunks]
+
+    def forget(self, memory_id: str) -> bool:
+        """忘记某件事"""
+        return self.cm.delete(memory_id, self.agent_id, self.session_id)
+
+    def get_context(self, current_task: str, limit: int = 10) -> str:
+        """获取相关上下文"""
+        result = self.cm.search(
+            query=current_task,
+            max_results=limit,
+            agent_id=self.agent_id,
+            session_id=self.session_id,
+        )
+
+        context_parts = ["# Relevant Memory\n"]
+        for i, chunk in enumerate(result.chunks, 1):
+            context_parts.append(f"## Memory {i} ({chunk.category})\n")
+            context_parts.append(f"{chunk.content}\n")
+
+        return "\n".join(context_parts)
+
+    def learn_user_preference(self, user_message: str, response: str):
+        """学习用户偏好"""
+        from mindforge.modules.personality import PersonalityEngine
+        pe = PersonalityEngine(self.cm.storage)
+        pe.learn_from_interaction("default", user_message, response)
+
+    def get_user_style(self) -> Dict:
+        """获取用户风格偏好"""
+        from mindforge.modules.personality import PersonalityEngine
+        pe = PersonalityEngine(self.cm.storage)
+        return pe.get_recommended_style()

mindforge/adapters/crewai_memory.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""CrewAI Memory 适配器（v5.8.4 新增）
+
+把 MindForge 包装为 CrewAI 生态的长期记忆后端（Memory 接口）：
+
+    from mindforge.adapters.crewai_memory import CrewAIMemory
+
+    memory = CrewAIMemory(mindforge, namespace="crew_travel")
+    memory.save("用户偏好靠窗座位", metadata={"trip": "tokyo"})
+    memory.search("座位偏好", limit=3)
+
+设计要点：
+- 零硬依赖：未安装 crewai 时类仍可导入（基类回退 object）。
+- 写：save() -> MindForge add()，namespace 编码进 category，metadata 扁平为 tags；
+- 读：search() -> MindForge 混合检索（mf.search().chunks 解密明文路径）；
+- reset() 仅清空本 namespace 条目（list 定位 id 后逐条 delete），不影响其他应用。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+try:
+    from crewai.memory.memory import Memory as _CrewMemory  # type: ignore
+    _CREWAI_AVAILABLE = True
+except Exception:  # pragma: no cover - 无 crewai 环境回退
+    _CrewMemory = object  # type: ignore
+    _CREWAI_AVAILABLE = False
+
+
+class CrewAIMemory(_CrewMemory):
+    """CrewAI Memory 协议的 MindForge 后端（v5.8.4）。"""
+
+    def __init__(self, mindforge, namespace: str = "crewai"):
+        self.mf = mindforge
+        self.namespace = namespace
+
+    def save(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> None:
+        """保存一条记忆。value 序列化为文本，metadata 扁平为 tags。"""
+        metadata = metadata or {}
+        tags = ["%s:%s" % (k, v) for k, v in metadata.items()
+                if isinstance(v, (str, int, float, bool))]
+        self.mf.add(
+            str(value),
+            category=self.namespace,
+            tags=tags,
+            source_agent="crewai",
+        )
+
+    def search(self, query: str, limit: int = 3,
+               filters: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """搜索记忆，返回 CrewAI 风格 list[dict]（context 为解密明文）。"""
+        rr = self.mf.search(query, max_results=limit,
+                            categories=[self.namespace])
+        results: List[Dict[str, Any]] = []
+        for c in (rr.chunks or []):
+            results.append({
+                "context": getattr(c, "content", "") or "",
+                "metadata": {
+                    "id": getattr(c, "memory_id", ""),
+                    "category": getattr(c, "category", self.namespace),
+                    "tags": getattr(c, "tags", []),
+                },
+            })
+        return results
+
+    def reset(self) -> None:
+        """清空本 namespace 的全部记忆（不影响其他应用）。循环删直到空。"""
+        for _ in range(100):  # 安全上限，防意外死循环
+            rows = self.mf.list(category=self.namespace, limit=500) or []
+            if not rows:
+                return
+            for h in rows:
+                self.mf.delete(getattr(h, "id", ""))
+
+
+__all__ = ["CrewAIMemory", "_CREWAI_AVAILABLE"]

mindforge/adapters/generic_api.py

@@ -0,0 +1,183 @@
+"""
+MindForge v5.0 通用 API 适配器
+REST API / SDK 风格接口
+"""
+
+from typing import List, Dict, Optional, Callable, Any
+
+
+class GenericAPIAdapter:
+    """通用 API 适配器"""
+
+    def __init__(self, MindForge):
+        self.cm = MindForge
+        self._handlers: Dict[str, Callable] = {}
+        self._register_default_handlers()
+
+    def _register_default_handlers(self):
+        self._handlers = {
+            "memory.add": self._handle_add,
+            "memory.get": self._handle_get,
+            "memory.search": self._handle_search,
+            "memory.list": self._handle_list,
+            "memory.update": self._handle_update,
+            "memory.delete": self._handle_delete,
+            "stats.get": self._handle_stats,
+            "graph.stats": self._handle_graph_stats,
+            "graph.related": self._handle_graph_related,
+            "personality.profile": self._handle_personality,
+            "evolution.consolidate": self._handle_consolidate,
+        }
+
+    def handle_request(self, request: Dict) -> Dict:
+        """处理 API 请求
+
+        P2 #19 修复：
+        - 校验 request 结构（action 必选且为字符串）
+        - 异常信息脱敏，不暴露内部调用栈细节
+        """
+        if not isinstance(request, dict):
+            return {"success": False, "error": "Invalid request format"}
+
+        action = request.get("action", "")
+        params = request.get("params", {})
+
+        if not action or not isinstance(action, str):
+            return {"success": False, "error": "Missing required field: action"}
+        if not isinstance(params, dict):
+            return {"success": False, "error": "Invalid params format"}
+
+        handler = self._handlers.get(action)
+        if not handler:
+            return {
+                "success": False,
+                "error": f"Unknown action: {action}",
+            }
+
+        try:
+            result = handler(params)
+            return {
+                "success": True,
+                "data": result,
+            }
+        except (ValueError, TypeError) as e:
+            # 预期内的错误：返回消息（用户输入类）
+            return {
+                "success": False,
+                "error": str(e),
+            }
+        except Exception as e:
+            # 未预期的错误：脱敏返回，防止内部细节泄露
+            import logging as _logging
+            _logging.getLogger(__name__).exception("API handler error: %s", action)
+            return {
+                "success": False,
+                "error": "Internal error",
+            }
+
+    @staticmethod
+    def _require(params: Dict, field: str, error_msg: str = "") -> Any:
+        """校验必需字段，缺失时返回友好错误"""
+        if field not in params:
+            raise ValueError(error_msg or f"Missing required field: {field}")
+        return params[field]
+
+    def _handle_add(self, params: Dict) -> Dict:
+        entry = self.cm.add(
+            content=self._require(params, "content"),
+            category=params.get("category", "general"),
+            tags=params.get("tags", []),
+            source_agent=params.get("agent", "api"),
+            source_session=params.get("session", "api"),
+        )
+        return entry.to_dict()
+
+    def _handle_get(self, params: Dict) -> Optional[Dict]:
+        entry = self.cm.get(
+            self._require(params, "id"),
+            actor=params.get("actor", ""),  # v5.7.3：未传 actor 视同本机内部调用
+            session_id=params.get("session_id", ""),
+        )
+        return entry.to_dict() if entry else None
+
+    def _handle_search(self, params: Dict) -> Dict:
+        result = self.cm.search(
+            query=params["query"],
+            max_results=params.get("limit", 10),
+            categories=params.get("categories"),
+            agent_id=params.get("actor", ""),  # v5.7.3：未传 actor 视同本机内部调用
+            session_id=params.get("session_id", ""),
+        )
+        return {
+            "total": result.total_found,
+            "time_ms": result.query_time_ms,
+            "results": [
+                {
+                    "id": c.memory_id,
+                    "content": c.content,
+                    "category": c.category,
+                    "relevance": c.relevance_score,
+                }
+                for c in result.chunks
+            ],
+        }
+
+    def _handle_list(self, params: Dict) -> List[Dict]:
+        # F1 修复：适配器列表入口接入隐私过滤（params.actor / params.session_id）。
+        # 未传 actor 时保持原有"返回全部"语义，兼容既有集成方。
+        entries = self.cm.list(
+            category=params.get("category"),
+            limit=params.get("limit", 50),
+            offset=params.get("offset", 0),
+            actor=str(params.get("actor") or ""),
+            session_id=str(params.get("session_id") or ""),
+        )
+        return [e.to_dict() for e in entries]
+
+    def _handle_update(self, params: Dict) -> bool:
+        return self.cm.update(
+            memory_id=self._require(params, "id"),
+            content=params.get("content"),
+            category=params.get("category"),
+            tags=params.get("tags"),
+            actor=params.get("actor", ""),  # v5.7.3：未传 actor 视同本机内部调用
+            session_id=params.get("session_id", ""),
+        )
+
+    def _handle_delete(self, params: Dict) -> bool:
+        return self.cm.delete(
+            self._require(params, "id"),
+            actor=params.get("actor", ""),  # v5.7.3：未传 actor 视同本机内部调用
+            session_id=params.get("session_id", ""),
+        )
+
+    def _handle_stats(self, params: Dict) -> Dict:
+        return self.cm.stats()
+
+    def _handle_graph_stats(self, params: Dict) -> Dict:
+        from mindforge.modules.knowledge_graph import KnowledgeGraph
+        kg = KnowledgeGraph(storage=self.cm.storage)
+        return kg.get_entity_stats()
+
+    def _handle_graph_related(self, params: Dict) -> List:
+        from mindforge.modules.knowledge_graph import KnowledgeGraph
+        kg = KnowledgeGraph(storage=self.cm.storage)
+        related = kg.get_related_entities(
+            self._require(params, "entity"),
+            depth=params.get("depth", 2),
+        )
+        return [{"name": n, "relation": r, "weight": w} for n, r, w in related]
+
+    def _handle_personality(self, params: Dict) -> Dict:
+        from mindforge.modules.personality import PersonalityEngine
+        pe = PersonalityEngine(self.cm.storage)
+        return pe.get_recommended_style(params.get("user_id", "default"))
+
+    def _handle_consolidate(self, params: Dict) -> Dict:
+        from mindforge.modules.evolution import MemoryEvolution
+        evo = MemoryEvolution(self.cm.storage)
+        return evo.consolidate()
+
+    def register_handler(self, action: str, handler: Callable):
+        """注册自定义处理器"""
+        self._handlers[action] = handler