mindforge-memory 6.4.1__py3-none-any.whl

mindforge/core/types.py

@@ -0,0 +1,314 @@
+"""
+MindForge v5.0 类型定义
+"""
+
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import List, Optional, Dict, Any
+
+
+class PrivacyLevel(Enum):
+    """隐私级别"""
+    PUBLIC = "PUBLIC"
+    INTERNAL = "INTERNAL"
+    PRIVATE = "PRIVATE"
+    STRICT = "STRICT"
+
+    @classmethod
+    def from_string(cls, value: str) -> "PrivacyLevel":
+        try:
+            return cls(value.upper())
+        except ValueError:
+            return cls.INTERNAL
+
+    def to_int(self) -> int:
+        mapping = {"PUBLIC": 0, "INTERNAL": 1, "PRIVATE": 2, "STRICT": 3}
+        return mapping[self.value]
+
+
+class Importance(Enum):
+    """重要性级别"""
+    LOW = "LOW"
+    MEDIUM = "MEDIUM"
+    HIGH = "HIGH"
+    CRITICAL = "CRITICAL"
+
+    @classmethod
+    def from_string(cls, value: str) -> "Importance":
+        try:
+            return cls(value.upper())
+        except ValueError:
+            return cls.MEDIUM
+
+    def to_int(self) -> int:
+        mapping = {"LOW": 0, "MEDIUM": 1, "HIGH": 2, "CRITICAL": 3}
+        return mapping[self.value]
+
+
+class MemoryType(Enum):
+    """记忆类型（多模态）"""
+    TEXT = "text"
+    IMAGE = "image"
+    AUDIO = "audio"
+    CODE = "code"
+    STRUCTURED = "structured"
+    MULTIMODAL = "multimodal"
+
+    @classmethod
+    def from_string(cls, value: str) -> "MemoryType":
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.TEXT
+
+
+class MemoryLayer(Enum):
+    """记忆层级（四层架构）"""
+    SENSORY = "sensory"
+    SHORT_TERM = "short_term"
+    LONG_TERM = "long_term"
+    PERMANENT = "permanent"
+
+    @classmethod
+    def from_string(cls, value: str) -> "MemoryLayer":
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.SHORT_TERM
+
+    def to_int(self) -> int:
+        mapping = {"sensory": 0, "short_term": 1, "long_term": 2, "permanent": 3}
+        return mapping[self.value]
+
+
+@dataclass
+class MemoryConfig:
+    """记忆系统配置"""
+    db_path: str = "./data/memory.db"
+    key_file: str = "./data/.key"
+    encrypted: bool = True
+    default_privacy: PrivacyLevel = PrivacyLevel.INTERNAL
+    default_importance: Importance = Importance.MEDIUM
+    default_layer: MemoryLayer = MemoryLayer.SHORT_TERM
+    auto_consolidate: bool = True
+    # v5.7.9：add/update 后自动抽取实体/关系入知识图谱（默认关闭，显式开启）
+    auto_extract_graph: bool = False
+    consolidate_interval_hours: int = 24
+    forget_curve_enabled: bool = True
+    vector_dim: int = 384
+    max_short_term_items: int = 100
+    sensory_buffer_size: int = 50
+    sensory_retention_seconds: int = 30
+    # v5.4.9 新增：Webhook / 事件通知配置
+    webhooks: Optional[List[Dict[str, Any]]] = None
+    webhook_secret: str = ""
+    event_bus_enabled: bool = True
+
+
+class DramaGenre(Enum):
+    """短剧类型"""
+    ROMANCE = "romance"
+    SUSPENSE = "suspense"
+    COMEDY = "comedy"
+    ACTION = "action"
+    HORROR = "horror"
+    SCIFI = "scifi"
+    FANTASY = "fantasy"
+    DRAMA = "drama"
+    OTHER = "other"
+
+    @classmethod
+    def from_string(cls, value: str) -> "DramaGenre":
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.OTHER
+
+
+class DramaStatus(Enum):
+    """短剧状态"""
+    WATCHING = "watching"
+    COMPLETED = "completed"
+    PLANNED = "planned"
+    DROPPED = "dropped"
+
+    @classmethod
+    def from_string(cls, value: str) -> "DramaStatus":
+        try:
+            return cls(value.lower())
+        except ValueError:
+            return cls.PLANNED
+
+
+@dataclass
+class DramaSeries:
+    """短剧系列"""
+    id: str
+    title: str
+    genre: DramaGenre = DramaGenre.OTHER
+    total_episodes: int = 0
+    current_episode: int = 0
+    status: DramaStatus = DramaStatus.PLANNED
+    platform: str = ""
+    rating: float = 0.0
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    cover_url: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: float = 0.0
+    updated_at: float = 0.0
+    last_watched_at: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "genre": self.genre.value,
+            "total_episodes": self.total_episodes,
+            "current_episode": self.current_episode,
+            "status": self.status.value,
+            "platform": self.platform,
+            "rating": self.rating,
+            "description": self.description,
+            "tags": self.tags,
+            "cover_url": self.cover_url,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "last_watched_at": self.last_watched_at,
+        }
+
+
+@dataclass
+class DramaScene:
+    """短剧场次"""
+    id: str
+    drama_id: str
+    episode: int
+    scene_number: int
+    title: str
+    content: str = ""
+    location: str = ""
+    time_of_day: str = ""
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "drama_id": self.drama_id,
+            "episode": self.episode,
+            "scene_number": self.scene_number,
+            "title": self.title,
+            "content": self.content,
+            "location": self.location,
+            "time_of_day": self.time_of_day,
+            "tags": self.tags,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+        }
+
+
+@dataclass
+class DramaCharacter:
+    """短剧角色"""
+    id: str
+    drama_id: str
+    name: str
+    role: str = "supporting"
+    actor: str = ""
+    description: str = ""
+    personality: str = ""
+    avatar_url: str = ""
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "drama_id": self.drama_id,
+            "name": self.name,
+            "role": self.role,
+            "actor": self.actor,
+            "description": self.description,
+            "personality": self.personality,
+            "avatar_url": self.avatar_url,
+            "tags": self.tags,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+        }
+
+
+@dataclass
+class DramaLine:
+    """短剧台词（可关联为记忆）"""
+    id: str
+    drama_id: str
+    line_text: str
+    scene_id: str = ""
+    character_id: str = ""
+    character_name: str = ""
+    context: str = ""
+    episode: int = 0
+    timestamp: str = ""
+    is_classic: bool = False
+    memory_id: str = ""
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    created_at: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "drama_id": self.drama_id,
+            "scene_id": self.scene_id,
+            "character_id": self.character_id,
+            "character_name": self.character_name,
+            "line_text": self.line_text,
+            "context": self.context,
+            "episode": self.episode,
+            "timestamp": self.timestamp,
+            "is_classic": self.is_classic,
+            "memory_id": self.memory_id,
+            "tags": self.tags,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+        }
+
+
+# ---------------------------------------------------------------------------
+# 入参归一助手（v6.1.2）
+# ---------------------------------------------------------------------------
+
+def coerce_memory_id(value: Any) -> Optional[str]:
+    """把 memory_id 入参归一为字符串，识别失败返回 None。
+
+    为什么需要它：`mf.add()` 返回的是 `MemoryEntry` 对象，用户很自然地把它原样
+    传回其它接口（如 `list_evolutions(m.add(...))`）。历史上各处写的是
+    `if not memory_id or len(memory_id) > 128`，对对象求 `len()` 直接抛
+    `TypeError: object of type 'MemoryEntry' has no len()`——对外表现为崩溃。
+    v6.1.1 已在三个入口（learn_from_outcome / follow_up_create / forget_explain）
+    修过这类问题，但每个模块各留了一份私有副本；v6.1.2 把规则收敛到此处的唯一
+    实现，供 storage 的演变/版本接口共用。
+
+    接受：
+      - `str`：原样返回；
+      - 带 `id` 字符串属性的对象（`MemoryEntry`、`ExperienceCase` 等）：返回其 `id`。
+    其余（int / list / dict / None / 空串 / 超长）一律返回 None，由调用方按各自的
+    错误约定处理（返回 error dict 或空列表），不再抛 TypeError。
+    """
+    if isinstance(value, str):
+        candidate = value
+    else:
+        try:
+            inner = getattr(value, "id", None)
+        except Exception:  # noqa: BLE001 病态对象（属性访问抛异常）与非法类型同等对待
+            return None
+        if not isinstance(inner, str):
+            return None
+        candidate = inner
+    if not candidate or len(candidate) > 128:
+        return None
+    return candidate

mindforge/core/version.py

@@ -0,0 +1,56 @@
+"""
+MindForge 版本号单一来源
+========================
+
+历史问题：`__version__` 的真值散落在 5 处（顶层包、core/storage.py、
+core/mindforge.py、cli/main.py、mcp/server.py），每处都带一份硬编码兜底。
+发版时要改 5 次，漏改就会出现「顶层 5.6.1 / storage 5.6.0」这类漂移。
+
+本模块把版本号收敛为唯一真值：
+
+- 运行时代码一律从这里 import，不再自带硬编码兜底；
+- `pyproject.toml` 通过 `[tool.setuptools.dynamic] version = {attr =
+  "mindforge.core.version.__version__"}` 读取同一份值，打包元数据与运行时
+  完全一致。
+
+发版清单：只改本文件的 `__version__`（与 `VERSION_INFO`），其余位置
+（pyproject 动态版本、CLI/MCP/API、README/官网徽章）全部自动跟随。
+"""
+
+from typing import Tuple
+
+#: 当前发布版本（唯一真值）
+__version__: str = "6.4.1"
+
+#: 结构化版本元组，便于比较（如 `VERSION_INFO >= (6, 1, 0)`）
+VERSION_INFO: Tuple[int, int, int] = (6, 4, 1)
+
+#: 下一个大版本的目标版本号（供 v6 端口预留引用）
+NEXT_MAJOR_TARGET: str = "7.0.0"
+
+
+def get_version() -> str:
+    """返回当前版本号字符串（等价于 `__version__`）。
+
+    Returns:
+        形如 "6.1.2" 的 semver 字符串。
+    """
+    return __version__
+
+
+def get_version_info() -> Tuple[int, int, int]:
+    """返回结构化版本元组。
+
+    Returns:
+        形如 (6, 1, 2) 的三元整数元组。
+    """
+    return VERSION_INFO
+
+
+__all__ = [
+    "__version__",
+    "VERSION_INFO",
+    "NEXT_MAJOR_TARGET",
+    "get_version",
+    "get_version_info",
+]

mindforge/daemon/server.py

@@ -0,0 +1,277 @@
+"""MindForge 常驻守护进程（daemon）——毫秒级调用路径。
+
+背景（2026-11-08 延迟实测）：引擎直连 2-3ms，但 CLI 子进程路径 698ms——
+差距全部来自 Python 解释器启动与导入开销。daemon 把引擎实例常驻在
+一个长生命周期进程里，宿主（dsh 插件等）通过 stdin/stdout 行式 JSON
+协议调用，消除每次调用的进程启动税。
+
+协议（v6.4.0）：
+    请求（stdin，每行一个 JSON）:
+        {"id": <int|str>, "cmd": "<command>", "args": {<kwargs>}}
+    响应（stdout，每行一个 JSON，立即可 flush）:
+        {"id": ..., "ok": true, "data": {...}}        成功
+        {"id": ..., "ok": false, "error": "<msg>"}    失败（进程不退出）
+    生命周期:
+        "ping"     → {"pong": true, "pid": ..., "uptime_ms": ...}
+        "shutdown" → 优雅退出（退出码 0）
+        EOF        → 退出
+    stderr: 启动横幅与日志（stdout 保持纯 JSON 行，严禁污染）
+
+命令集（v1，输出契约对齐 CLI --json）:
+    add / search / memory-recall / memory-context / stats /
+    compress / compress-list / decompress / adaptive-search
+
+设计原则:
+    - 单线程顺序处理：v1 目标是正确与低延迟，agent 场景以顺序调用为主
+    - 每请求独立 try/except：单条请求异常不杀进程
+    - 引擎实例只建一次、永不 close（daemon 生命周期 = 引擎生命周期）
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+
+from mindforge.core.types import (
+    Importance,
+    MemoryLayer,
+    MemoryType,
+    PrivacyLevel,
+)
+
+__all__ = ["run_daemon"]
+
+
+def _make_serializer():
+    """引擎对象 → CLI --json 兼容 dict 的转换集合（对齐 cli/main.py 契约）。"""
+
+    def add(entry):
+        return {
+            "status": "ok",
+            "id": entry.id,
+            "content": entry.content,
+            "category": entry.category,
+            "tags": entry.tags,
+            "layer": entry.layer.value,
+            "importance": entry.importance.value
+            if getattr(entry.importance, "value", None)
+            else str(entry.importance),
+        }
+
+    def search(result):
+        return {
+            "chunks": [
+                {
+                    "memory_id": c.memory_id,
+                    "content": c.content,
+                    "category": c.category,
+                    "layer": c.layer.value,
+                    "relevance_score": c.relevance_score,
+                    "tags": c.tags,
+                    "score_breakdown": c.score_breakdown,
+                }
+                for c in result.chunks
+            ],
+            "total_found": result.total_found,
+            "query_time_ms": result.query_time_ms,
+            "strategy_used": result.strategy_used,
+            "token_estimate": result.token_estimate,
+            "layers_used": result.layers_used,
+            "approximate": getattr(result, "approximate", False),
+        }
+
+    return add, search
+
+
+def run_daemon(db_path: str, key_file: str | None = None, encrypted: bool = False) -> int:
+    """启动常驻守护进程主循环。返回退出码。"""
+    from mindforge.core.types import MemoryConfig
+    from mindforge.core.mindforge import MindForge
+
+    t_start = time.time()
+    cm = MindForge(
+        config=MemoryConfig(db_path=db_path, key_file=key_file, encrypted=encrypted)
+    )
+    add_ser, search_ser = _make_serializer()
+    taxonomy = None  # lazy：add 缺省分类时才建
+
+    print(
+        json.dumps(
+            {
+                "event": "ready",
+                "pid": os.getpid(),
+                "db_path": db_path,
+                "startup_ms": int((time.time() - t_start) * 1000),
+            },
+            ensure_ascii=False,
+        ),
+        file=sys.stderr,
+        flush=True,
+    )
+
+    def cmd_add(args):
+        nonlocal taxonomy
+        content = args["content"]
+        category = args.get("category")
+        tags = args.get("tags")
+        if not category or not tags:
+            if taxonomy is None:
+                from mindforge.modules.categorizer import TaxonomyManager
+
+                taxonomy = TaxonomyManager()
+            if not category:
+                category = taxonomy.suggest_category(content)
+            if not tags:
+                tags = taxonomy.suggest_tags(content)
+        entry = cm.add(
+            content=content,
+            category=category,
+            tags=tags,
+            privacy=PrivacyLevel.from_string(args.get("privacy", "INTERNAL")),
+            importance=Importance.from_string(args.get("importance", "MEDIUM")),
+            memory_type=MemoryType.from_string(args.get("type", "text")),
+            layer=MemoryLayer.from_string(args.get("layer", "short_term")),
+            source_session=args.get("session", ""),
+            source_agent=args.get("agent", ""),
+        )
+        return add_ser(entry)
+
+    def cmd_search(args):
+        result = cm.search(
+            query=args["query"],
+            max_results=args.get("limit", 10),
+            min_relevance=0.2,
+            agent_id=args.get("agent", ""),
+            session_id=args.get("session", ""),
+            use_embedding=args.get("use_embedding", True),
+            explain=args.get("explain", False),
+        )
+        return search_ser(result)
+
+    def cmd_memory_recall(args):
+        return cm.memory_recall(
+            args["agent"], args["query"],
+            args.get("top_k", 10), args.get("days", 30),
+        )
+
+    def cmd_memory_context(args):
+        return cm.memory_context(
+            args["agent"], args["query"], args.get("max_tokens", 4000)
+        )
+
+    def cmd_stats(args):
+        return cm.detailed_stats()
+
+    def cmd_compress(args):
+        return cm.compress_memories(
+            threshold=args.get("threshold", 0.5),
+            dry_run=args.get("dry_run", False),
+            categories=[args["category"]] if args.get("category") else None,
+            min_cluster_size=args.get("min_cluster_size", 2),
+        )
+
+    def cmd_compress_list(args):
+        items = cm.list_compressions()
+        return {"total": len(items), "clusters": items}
+
+    def cmd_decompress(args):
+        return cm.decompress_cluster(args["cluster_id"])
+
+    def cmd_adaptive_search(args):
+        return cm.adaptive_search(
+            query=args["query"],
+            session_id=args.get("session", "cli"),
+            max_results=args.get("limit", 10),
+        )
+
+    handlers = {
+        "add": cmd_add,
+        "search": cmd_search,
+        "memory-recall": cmd_memory_recall,
+        "memory-context": cmd_memory_context,
+        "stats": cmd_stats,
+        "compress": cmd_compress,
+        "compress-list": cmd_compress_list,
+        "decompress": cmd_decompress,
+        "adaptive-search": cmd_adaptive_search,
+    }
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+            rid = req.get("id")
+            cmd = req.get("cmd", "")
+            args = req.get("args", {}) or {}
+        except json.JSONDecodeError as e:
+            sys.stdout.write(
+                json.dumps({"id": None, "ok": False, "error": f"bad json: {e}"}) + "\n"
+            )
+            sys.stdout.flush()
+            continue
+
+        if cmd == "ping":
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "id": rid,
+                        "ok": True,
+                        "data": {
+                            "pong": True,
+                            "pid": os.getpid(),
+                            "uptime_ms": int((time.time() - t_start) * 1000),
+                        },
+                    },
+                    ensure_ascii=False,
+                )
+                + "\n"
+            )
+            sys.stdout.flush()
+            continue
+        if cmd == "shutdown":
+            sys.stdout.write(
+                json.dumps({"id": rid, "ok": True, "data": {"bye": True}}) + "\n"
+            )
+            sys.stdout.flush()
+            break
+
+        handler = handlers.get(cmd)
+        if handler is None:
+            sys.stdout.write(
+                json.dumps(
+                    {
+                        "id": rid,
+                        "ok": False,
+                        "error": f"unknown cmd: {cmd}（支持: {sorted(handlers) + ['ping', 'shutdown']}）",
+                    },
+                    ensure_ascii=False,
+                )
+                + "\n"
+            )
+            sys.stdout.flush()
+            continue
+
+        try:
+            data = handler(args)
+            sys.stdout.write(
+                json.dumps({"id": rid, "ok": True, "data": data}, ensure_ascii=False)
+                + "\n"
+            )
+        except Exception as e:  # 单请求失败不杀进程
+            sys.stdout.write(
+                json.dumps(
+                    {"id": rid, "ok": False, "error": f"{type(e).__name__}: {e}"},
+                    ensure_ascii=False,
+                )
+                + "\n"
+            )
+        sys.stdout.flush()
+
+    try:
+        cm.close()
+    except Exception:
+        pass
+    return 0

mindforge/mcp/__init__.py

@@ -0,0 +1,4 @@
+"""MindForge MCP package — Model Context Protocol server."""
+from .server import main, serve_forever
+
+__all__ = ["main", "serve_forever"]