nyx-memory 3.4.2__py3-none-any.whl

nexsandglass/__init__.py

@@ -0,0 +1,113 @@
+"""NexSandglass — 记忆感知系统
+
+夜神 Nyx：跨会话记忆、知识图谱、模糊感知（Déjà Vu）
+"""
+
+from .core.sandglass_paths import __version__
+from .utils import health_summary, tick
+
+from .core import (
+    NexSandglassProvider,
+    SearchRouter,
+    detect,
+    log_message,
+    register_provider,
+    validate,
+)
+from .l3 import (
+    entropy_ghost,
+    glass_reminder,
+    offset_check,
+    persona_build,
+    persona_project,
+    persona_update,
+    simhash,
+    stage_list,
+    task_pending,
+    weave_contradiction,
+    weave_graph,
+)
+from .features import (
+    count,
+    comprehensive_offset,
+    distill,
+    entropy_chart,
+    export_soul,
+    full_sanity,
+    log,
+    memory_migrate,
+    merge_soul,
+    night_watch,
+    pulse,
+    ratio,
+    recent,
+    search,
+    search_semantic,
+    session_context,
+    shadow_search,
+    timeline,
+    wthread_add,
+    wthread_extract,
+    wthread_graph,
+    wthread_query,
+    wthread_stats,
+    wthread_store,
+    wthread_weave,
+)
+
+__author__ = "sixgod"
+
+__all__ = [
+    # core
+    "NexSandglassProvider",
+    "register_provider",
+    "SearchRouter",
+    "log_message",
+    "validate",
+    # storage
+    "search",
+    "recent",
+    "count",
+    "timeline",
+    "search_semantic",
+    "shadow_search",
+    # thread graph
+    "wthread_extract",
+    "wthread_store",
+    "wthread_query",
+    "wthread_stats",
+    "wthread_weave",
+    "wthread_add",
+    "wthread_graph",
+    # persona / offset / emotion
+    "comprehensive_offset",
+    "offset_check",
+    "persona_build",
+    "persona_update",
+    "persona_project",
+    "stage_list",
+    "glass_reminder",
+    "entropy_ghost",
+    "weave_contradiction",
+    "weave_graph",
+    "simhash",
+    # task / think
+    "task_pending",
+    "distill",
+    "session_context",
+    "entropy_chart",
+    "full_sanity",
+    # decision particles
+    "log",
+    "ratio",
+    "detect",
+    # migrate / soul
+    "memory_migrate",
+    "export_soul",
+    "merge_soul",
+    # runtime
+    "pulse",
+    "night_watch",
+    "tick",
+    "health_summary",
+]

nexsandglass/core/__init__.py

@@ -0,0 +1,67 @@
+"""Core infrastructure: memory backend, search routing, storage."""
+
+from .emotion_vocab import detect, learn, load_vocab, mood_message, save_vocab
+from .l0_buffer import l0_context, l0_remember, l0_size
+from .memory_provider import NexSandglassProvider, register as register_provider
+from .sandglass import count, read
+from .sandglass_archive import (
+    archive_path,
+    archive_stats,
+    cold_migration,
+    is_old,
+    parse_ts,
+    search_archive,
+)
+from .sandglass_log import log_conversation, log_message
+from .sandglass_paths import validate
+from .sandglass_sqlite import search, search_in, search_year, sync_all, sync_incremental
+from .search_router import (
+    Fts5Search,
+    IdxSearch,
+    MmapFallback,
+    SearchRouter,
+    ShadowSearch,
+    TfidfSearch,
+)
+
+__all__ = [
+    # memory provider (Hermes plugin)
+    "NexSandglassProvider",
+    "register_provider",
+    # search routing
+    "SearchRouter",
+    "ShadowSearch",
+    "Fts5Search",
+    "IdxSearch",
+    "TfidfSearch",
+    "MmapFallback",
+    # sqlite FTS layer
+    "search",
+    "search_in",
+    "search_year",
+    "sync_all",
+    "sync_incremental",
+    # sandglass log / archive
+    "log_message",
+    "log_conversation",
+    "archive_path",
+    "archive_stats",
+    "cold_migration",
+    "is_old",
+    "parse_ts",
+    "search_archive",
+    # emotion vocab
+    "load_vocab",
+    "save_vocab",
+    "learn",
+    "detect",
+    "mood_message",
+    # paths / flat sandglass reader
+    "validate",
+    "read",
+    "count",
+    # L0 buffer
+    "l0_remember",
+    "l0_context",
+    "l0_size",
+]

nexsandglass/core/embedding_provider.py

@@ -0,0 +1,176 @@
+"""
+core/embedding_provider.py — 可插拔 Embedding 后端
+
+设计：
+- 抽象 EmbeddingProvider 接口，支持本地模型（sentence-transformers）和外部 API
+- 默认走本地免费方案（不强制联网/付费）
+- 懒加载：首次调用时才初始化模型，避免 import 时开销
+- Fail-safe：模型加载失败时返回 None（调用方退回词法检索）
+
+本地默认模型：paraphrase-multilingual-MiniLM-L12-v2
+  - 支持中英混合（50+ 语言）
+  - 向量维度 384（轻量）
+  - ~50MB 磁盘，首次下载后离线可用
+
+安装依赖（可选）：
+  pip install sentence-transformers numpy
+  未安装时自动降级为 None（不影响现有词法检索）
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# 向量维度常量（与默认模型一致）
+EMBEDDING_DIM: int = 384
+
+
+class EmbeddingProvider:
+    """Embedding 后端抽象接口。"""
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        """将文本列表编码为向量列表。失败返回空列表。"""
+        raise NotImplementedError
+
+    def encode_one(self, text: str) -> Optional[list[float]]:
+        """单条编码。"""
+        results = self.encode([text])
+        return results[0] if results else None
+
+    @property
+    def dim(self) -> int:
+        return EMBEDDING_DIM
+
+    @property
+    def available(self) -> bool:
+        return True
+
+
+class SentenceTransformerProvider(EmbeddingProvider):
+    """基于 sentence-transformers 的本地 Embedding（中英混合支持）。"""
+
+    def __init__(self, model_name: str = "paraphrase-multilingual-MiniLM-L12-v2"):
+        self._model_name = model_name
+        self._model = None
+
+    def _ensure_model(self):
+        if self._model is not None:
+            return
+        try:
+            from sentence_transformers import SentenceTransformer
+            # 本地缓存目录（离线可用）
+            cache_dir = os.path.expanduser("~/.cache/nexsandglass/models")
+            os.makedirs(cache_dir, exist_ok=True)
+            self._model = SentenceTransformer(self._model_name, cache_folder=cache_dir)
+            logger.info("[EmbeddingProvider] 本地模型加载成功: %s", self._model_name)
+        except Exception as e:
+            logger.warning("[EmbeddingProvider] 本地模型加载失败（将退回词法检索）: %s", e)
+            self._model = None
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        self._ensure_model()
+        if self._model is None:
+            return []
+        try:
+            import numpy as np
+            embeddings = self._model.encode(texts, normalize_embeddings=True, show_progress_bar=False)
+            return embeddings.tolist()
+        except Exception as e:
+            logger.warning("[EmbeddingProvider] 编码失败: %s", e)
+            return []
+
+    @property
+    def available(self) -> bool:
+        self._ensure_model()
+        return self._model is not None
+
+
+class ExternalAPIProvider(EmbeddingProvider):
+    """外部 Embedding API（OpenAI 兼容接口，可选）。"""
+
+    def __init__(self, api_url: str = "", api_key: str = "", model: str = "text-embedding-3-small"):
+        self._api_url = api_url or os.environ.get("EMBEDDING_API_URL", "")
+        self._api_key = api_key or os.environ.get("EMBEDDING_API_KEY", "")
+        self._model = model
+        self._dim = EMBEDDING_DIM if "3-small" in model else 1536
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        if not texts or not self._api_url:
+            return []
+        try:
+            import httpx
+            resp = httpx.post(
+                self._api_url,
+                headers={"Authorization": f"Bearer {self._api_key}", "Content-Type": "application/json"},
+                json={"input": texts, "model": self._model},
+                timeout=30,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            return [item["embedding"] for item in data.get("data", [])]
+        except Exception as e:
+            logger.warning("[ExternalAPIProvider] 调用失败: %s", e)
+            return []
+
+    @property
+    def dim(self) -> int:
+        return self._dim
+
+    @property
+    def available(self) -> bool:
+        return bool(self._api_url)
+
+
+class NullProvider(EmbeddingProvider):
+    """不可用时的空实现（fail-safe）。"""
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        return []
+
+    def encode_one(self, text: str) -> Optional[list[float]]:
+        return None
+
+    @property
+    def dim(self) -> int:
+        return EMBEDDING_DIM
+
+    @property
+    def available(self) -> bool:
+        return False
+
+
+# ── 全局单例（懒加载）──────────────────────────────────────────
+
+_provider: Optional[EmbeddingProvider] = None
+
+
+def get_embedding_provider() -> EmbeddingProvider:
+    """获取全局 EmbeddingProvider 单例（优先本地，可选外部 API）。"""
+    global _provider
+    if _provider is not None:
+        return _provider
+    # 检查是否配置外部 API
+    api_url = os.environ.get("EMBEDDING_API_URL", "")
+    if api_url:
+        _provider = ExternalAPIProvider(api_url=api_url)
+        if _provider.available:
+            return _provider
+    # 默认本地
+    local = SentenceTransformerProvider()
+    if local.available:
+        _provider = local
+    else:
+        _provider = NullProvider()
+    return _provider
+
+
+def reset_provider():
+    """测试用：重置单例。"""
+    global _provider
+    _provider = None

nexsandglass/core/emotion_vocab.py

@@ -0,0 +1,186 @@
+"""
+NexSandglass 情绪词库 — 七大情绪分类
+=====================================
+基于 Ekman + Plutchik 情绪理论。
+动态学习 + 主语判断 + 小二回应策略。
+"""
+
+import json
+import os
+import re
+
+from nexsandglass.core.sandglass_paths import _NB
+_VOCAB_FILE = os.path.join(_NB, "emotion_vocab.json")
+
+# ── 七大情绪分类 ──
+# 格式：{大类: {子类: [词], 管家策略: "xxx"}}
+_BUILTIN = {
+    "愤怒": {
+        "zh": ["气死", "恼火", "凭什么", "不公平", "过分", "太气人了", "火大", "无语", "受不了", "真恶心", "怎么这样", "太糟糕了", "烦死了", "气死我了", "烦死", "气炸", "真烦", "真火大", "要气死", "被气到", "好生气", "受够了", "崩溃了", "无语了", "恶心", "恼人", "操蛋", "扯淡", "折磨", "劝退", "坑爹", "垃圾", "烂", "废了", "有毒"],
+        "en": ["angry", "pissed off", "outrageous", "unfair", "ridiculous", "unacceptable"],
+        "策略": "缓提醒。先让情绪降下来，不提待办。",
+        "优先级": "高",
+    },
+    "悲伤": {
+        "zh": ["难过", "伤心", "好累", "不想动", "心累", "崩溃", "失望", "没劲", "没意思", "提不起劲", "好难过", "废物", "没用", "搞砸了", "又错了", "做不好", "失败", "不行了", "完蛋了", "好难", "太难了", "做不动", "撑不住", "痛苦"],
+        "en": ["sad", "depressed", "heartbroken", "disappointed", "exhausted", "drained",
+              "terrible", "failure", "useless", "messed up", "can't do this"],
+        "策略": "缓提醒。状态不好的时候不催。",
+        "优先级": "高",
+    },
+    "焦虑": {
+        "zh": ["焦虑", "紧张", "压力好大", "害怕", "不安", "担心",
+              "怎么办", "万一", "会不会", "好怕"],
+        "en": ["anxious", "nervous", "stressed", "worried", "afraid", "scared"],
+        "策略": "不催。给安全感，不提额外负担。",
+        "优先级": "中",
+    },
+    "放弃": {
+        "zh": ["不管了", "随便", "放弃", "累了", "不想做了", "就这样吧", "不做了", "算了算了",
+              "不纠结了", "爱咋咋地", "无所谓", "能用就行"],
+        "en": ["whatever", "give up", "i don't care", "fine, do what you want", "i quit"],
+        "策略": "红牌。提醒全停，优先级=自我修正。",
+        "优先级": "最高",
+    },
+    "开心": {
+        "zh": ["开心", "太好了", "太棒了", "满意", "有意思", "值得", "兴奋", "好棒", "哈哈", "nice", "真不错", "有成就感", "爽", "喜欢", "终于", "很好", "不错", "舒服", "完美", "真香", "赞", "厉害", "搞定", "跑通了", "稳了", "通了", "漂亮", "优秀", "强大", "惊喜", "感动", "成就感", "自豪", "高兴", "愉快", "轻松", "好使", "管用", "真快", "丝滑", "起飞", "牛批", "无敌", "爱了", "推荐", "好用", "简洁", "清晰", "优雅"],
+        "en": ["happy", "great", "excited", "awesome", "love it", "worth it", "amazing"],
+        "策略": "正常提醒。状态好可以多提醒。",
+        "优先级": "低",
+    },
+    "困惑": {
+        "zh": ["不懂", "不明白", "怎么回事", "啥意思", "搞不懂", "奇怪",
+              "不对劲", "不太对", "有点奇怪", "没搞明白"],
+        "en": ["confused", "don't understand", "what's going on", "doesn't make sense"],
+        "策略": "正常。帮助澄清，不影响提醒。",
+        "优先级": "低",
+    },
+    "意外": {
+        "zh": ["没想到", "竟然", "不是吧", "真的假的", "天哪",
+              "怎么回事这样", "原来是"],
+        "en": ["wow", "unexpected", "surprised", "really", "no way", "oh my"],
+        "策略": "正常。分享惊喜，不影响提醒。",
+        "优先级": "低",
+    },
+}
+
+# ── 主语标记 ──
+_SUBJECT_OTHERS = ["他", "她", "他们", "那个人", "别人",
+                   "he ", "she ", "they ", "that person", "someone"]
+_SUBJECT_IMPACT = ["他让", "她让", "他们让", "害得",
+                   "he makes", "she makes", "they make"]
+
+
+def load_vocab() -> dict:
+    """加载情绪词库。合并内置词库确保不丢失。"""
+    if os.path.exists(_VOCAB_FILE):
+        try:
+            with open(_VOCAB_FILE, "r", encoding="utf-8") as f:
+                vocab = json.loads(f.read())
+            for mood, data in _BUILTIN.items():
+                if mood not in vocab:
+                    vocab[mood] = {}
+                for key in ["zh", "en", "策略", "优先级"]:
+                    if key not in vocab[mood]:
+                        vocab[mood][key] = data.get(key, [])
+                    elif isinstance(data[key], list):
+                        existing = set(vocab[mood][key])
+                        existing.update(data[key])
+                        vocab[mood][key] = sorted(existing)
+            return vocab
+        except Exception:
+            pass
+
+    vocab = {mood: {k: v for k, v in data.items()} for mood, data in _BUILTIN.items()}
+    save_vocab(vocab)
+    return vocab
+
+
+def save_vocab(vocab: dict):
+    os.makedirs(os.path.dirname(_VOCAB_FILE), exist_ok=True)
+    with open(_VOCAB_FILE, "w", encoding="utf-8") as f:
+        json.dump(vocab, f, ensure_ascii=False, indent=2)
+
+
+def learn(word: str, mood: str, lang: str = "zh") -> bool:
+    """学习新情绪词。"""
+    vocab = load_vocab()
+    if mood not in vocab:
+        return False
+    if lang not in vocab[mood]:
+        vocab[mood][lang] = []
+    if word not in vocab[mood][lang]:
+        vocab[mood][lang].append(word)
+        vocab[mood][lang] = sorted(vocab[mood][lang])
+        save_vocab(vocab)
+        return True
+    return False
+
+
+def detect(message: str) -> dict:
+    """检测情绪：返回 {mood, emitter, keywords, strategy, priority}。"""
+    # 静默模式
+    if os.environ.get("NX_MODE") == "neutral":
+        return {"mood": "", "emitter": "自我", "keywords": [], "strategy": "", "priority": "低"}
+    # ── 否定词列表 ──
+    _NEGATION = ["不", "没", "不是", "不太", "并不", "并不太",
+                 "not ", "don't ", "doesn't ", "isn't ", "aren't ",
+                 "never ", "no ", "hardly "]
+
+    vocab = load_vocab()
+    msg_lower = message.lower()
+
+    mood_order = ["放弃", "愤怒", "悲伤", "焦虑", "困惑", "意外", "开心"]
+
+    for mood in mood_order:
+        all_words = vocab.get(mood, {}).get("zh", []) + vocab.get(mood, {}).get("en", [])
+        for word in sorted(all_words, key=len, reverse=True):
+            idx = msg_lower.find(word.lower())
+            if idx >= 0:
+                # ── 否定检查：开心词前面有否定 → 跳过 ──
+                if mood in ("开心", "积极"):
+                    ctx8 = msg_lower[max(0, idx-8):idx]
+                    if any(n in ctx8 for n in _NEGATION):
+                        continue
+
+                ctx = message[max(0, idx-30):idx].lower()
+                if any(w in ctx for w in _SUBJECT_OTHERS):
+                    emitter = "他人"
+                elif any(w in ctx for w in _SUBJECT_IMPACT):
+                    emitter = "影响"
+                else:
+                    emitter = "自我"
+
+                return {
+                    "mood": mood, "emitter": emitter, "keywords": [word],
+                    "strategy": vocab[mood].get("策略", ""),
+                    "priority": vocab[mood].get("优先级", "低"),
+                }
+
+    return {"mood": "", "emitter": "自我", "keywords": [], "strategy": "", "priority": "低"}
+
+
+def mood_message(detection: dict) -> str:
+    """管家回应。"""
+    mood = detection["mood"]
+    emitter = detection["emitter"]
+    words = detection["keywords"][:2]
+    strat = detection.get("strategy", "")
+
+    if not mood:
+        return ""
+
+    emoji_map = {
+        "愤怒": "😡", "悲伤": "😢", "焦虑": "😰", "放弃": "🔴",
+        "开心": "😊", "困惑": "🤔", "意外": "😲",
+    }
+    emoji = emoji_map.get(mood, "🟡")
+
+    if emitter == "他人":
+        return f"{emoji} 觉察：别人{mood}——「{'、'.join(words)}」。不影响你的状态。"
+    elif emitter == "影响":
+        return f"{emoji} 觉察：别人的情绪影响到你了——「{'、'.join(words)}」。{strat}"
+    elif mood == "放弃":
+        return f"🔴 红牌——「{'、'.join(words)}」。优先级=自我修正。{strat}"
+    else:
+        return f"{emoji} 觉察：{mood}——「{'、'.join(words)}」。{strat}"

nexsandglass/core/l0_buffer.py

@@ -0,0 +1,75 @@
+"""
+NexSandglass — L0 短期记忆缓冲区
+=================================
+记录最近5轮对话，不进入倒排索引（不污染搜索）。
+满5轮自动蒸馏最新一轮到L1。
+
+用法:
+  from nexsandglass.core.l0_buffer import l0_remember, l0_context
+  l0_remember("用户说了一句重要的话")
+  context = l0_context()  # 返回最近5轮的上下文
+"""
+import os
+import json
+from datetime import datetime
+from nexsandglass.core.sandglass_paths import _NB
+
+L0_PATH = os.path.join(_NB, "l0_buffer.jsonl")
+L0_MAX = 5  # 最多保留5轮
+
+
+def l0_remember(text: str, speaker: str = "user") -> None:
+    """记入L0缓冲区。满L0_MAX时蒸馏最旧一条到L1。"""
+    entry = {"ts": datetime.now().isoformat(), "speaker": speaker, "text": text[:500]}
+    os.makedirs(os.path.dirname(L0_PATH), exist_ok=True)
+
+    with open(L0_PATH, "a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    # 检查是否满了——满则蒸馏最旧一条到L1
+    with open(L0_PATH, "r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    if len(lines) > L0_MAX:
+        # 蒸馏最旧一条
+        oldest = json.loads(lines[0].strip())
+        try:
+            from nexsandglass.core.sandglass_log import log_message
+            log_message(f"[L0-auto] {oldest['speaker']}: {oldest['text'][:300]}", oldest.get("speaker", "user"))
+            from nexsandglass.features.decision_particles import log as dp_log
+            dp_log(oldest["text"][:100], f"L0_buffer_distill")
+            # 🆕 蒸馏即偏移检测——用全文，不只是前100字
+            from nexsandglass.l3.offset_l3 import offset_check
+            offset_check(oldest["text"][:300], user_persisted=False)
+        except Exception:
+            pass
+
+        # 只保留最近 L0_MAX 条
+        with open(L0_PATH, "w", encoding="utf-8") as f:
+            f.writelines(lines[-L0_MAX:])
+
+
+def l0_context() -> str:
+    """返回L0缓冲区的上下文（最近5轮）。"""
+    if not os.path.exists(L0_PATH):
+        return ""
+    with open(L0_PATH, "r", encoding="utf-8") as f:
+        lines = f.readlines()[-L0_MAX:]
+    if not lines:
+        return ""
+    parts = []
+    for line in lines:
+        try:
+            e = json.loads(line.strip())
+            parts.append(f"[{e.get('speaker','?')}] {e.get('text','')[:200]}")
+        except Exception:
+            pass
+    return "## L0 短期记忆\n" + "\n".join(parts)
+
+
+def l0_size() -> int:
+    """L0当前条数。"""
+    if not os.path.exists(L0_PATH):
+        return 0
+    with open(L0_PATH, "r", encoding="utf-8") as f:
+        return sum(1 for _ in f)