memex-agent-memory 0.1.0__py3-none-any.whl

memex/SKILL.md

@@ -0,0 +1,178 @@
+# Memex Skill — 通用 Agent 记忆系统
+
+## 简介
+
+Memex 是 Agent 的长期记忆系统，让 Agent 能在跨会话中积累知识和偏好。
+
+**通用设计**：任何 Agent 框架都可以接入（OpenClaw、Claude Code、Cursor、Codex 等）。
+
+**核心理念**：
+- 原文存储 — 原文保留，不依赖 LLM 提取
+- 向量语义搜索 — 支持自然语言查询
+- 隐私可控 — 用户可随时查看、删除记忆
+
+---
+
+## 何时使用
+
+| 时机 | 命令 | 说明 |
+|------|------|------|
+| 对话结束 | `memex save` | 提炼关键信息存入记忆 |
+| 新对话开始 | `memex search` | 检索相关记忆 |
+| 遇到决策点 | `memex search` | 查询约束/策略 |
+| 发现新 pattern | `memex save --type system_pattern` | 存入系统模式 |
+| 用户明确偏好 | `memex save --type user_model` | 存入用户偏好 |
+
+---
+
+## 记忆类型
+
+| 类型 | 何时用 | importance | 示例 |
+|------|--------|-----------|------|
+| `constraint` | 用户强制的规则 | 0.9 | "用户不喜欢废话" |
+| `user_model` | 用户偏好/习惯 | 0.85 | "用户喜欢简洁回复" |
+| `strategy` | 验证过的方法论 | 0.8 | "用 divide and conquer 解决复杂问题" |
+| `system_pattern` | 系统设计模式 | 0.75 | "项目采用前后端分离架构" |
+| `belief` | 验证过的结论 | 0.7 | "Python 适合快速原型" |
+| `journal` | 工作日志 | 0.4 | "今天完成了 xxx" |
+
+---
+
+## 命令参考
+
+### 存入记忆
+
+```bash
+memex save --type <type> --content "<内容>" --repo <namespace>
+```
+
+**示例**：
+```bash
+memex save --type user_model --content "用户喜欢简洁的回复风格，不喜欢废话" --repo user
+memex save --type belief --content "这个项目使用 Python FastAPI" --repo myproject
+```
+
+### 语义搜索
+
+```bash
+memex search "<查询内容>" --repo <namespace> --limit <数量>
+```
+
+**示例**：
+```bash
+memex search "用户的偏好是什么" --repo user --limit 5
+```
+
+**返回格式**（JSON，Agent 自行解析）：
+```json
+{
+  "query": "用户的偏好是什么",
+  "results": [
+    {
+      "id": "uuid",
+      "type": "user_model",
+      "content": "用户喜欢简洁的回复风格，不喜欢废话",
+      "importance": 0.85,
+      "confidence": 0.8,
+      "stability": "medium",
+      "score": 0.92
+    }
+  ],
+  "total": 1
+}
+```
+
+### 其他命令
+
+```bash
+# 列出记忆
+memex list --repo <namespace> --limit 20
+
+# 获取单条记忆
+memex get <memory-id>
+
+# 删除记忆
+memex delete <memory-id>
+
+# 查看统计
+memex stats --repo <namespace>
+```
+
+---
+
+## 隐私控制
+
+用户可以随时查看和删除自己的记忆：
+
+```bash
+# 查看被记住的内容
+memex recall --repo user
+
+# 删除单条记忆
+memex purge <memory-id>
+
+# 清空所有记忆
+memex purge --all
+```
+
+---
+
+## 混合评分
+
+搜索结果按以下公式排序：
+
+```
+final_score = 0.55×similarity + 0.20×importance + 0.15×freshness + 0.10×frequency
+```
+
+- `similarity`：向量余弦相似度
+- `importance`：记忆类型预设重要性
+- `freshness`：最近访问时间
+- `frequency`：访问频率
+
+---
+
+## 多 Agent 支持
+
+每个 Agent 用不同的 `--repo` 命名空间：
+
+| Repo | 用途 |
+|------|------|
+| `user` | 跨 Agent 共享的用户偏好 |
+| `<agent-name>` | 特定 Agent 的记忆 |
+| `default` | 通用记忆 |
+
+---
+
+## 安装
+
+```bash
+# 安装 memex
+pip install memex
+
+# 初始化
+memex init
+
+# 验证
+memex stats
+```
+
+### OpenClaw Agent 接入
+
+将 skill 复制到 `~/.openclaw/skills/memex/`，Agent 在合适的时机调用 `memex search` / `memex save`。
+
+### 其他 Agent 框架
+
+直接调用 CLI 命令即可：
+```bash
+memex search "用户偏好" --repo user --limit 5
+```
+
+---
+
+## 注意事项
+
+1. **模型升级兼容**：`raw_text` 字段保存原始文本，换 embedding 模型后自动重建索引
+2. **向量维度**：BGE-base-zh-v1.5 = 768 维
+3. **存储位置**：`~/.memex/memory/`
+4. **网络需求**：首次下载 BGE 模型约 400MB，之后离线可用

memex/__init__.py

@@ -0,0 +1 @@
+# Memex — Agent 记忆系统

memex/_config.py

@@ -0,0 +1,88 @@
+"""
+Config — 配置管理
+~/.memex/config.toml
+"""
+import os
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class MemoryConfig(BaseModel):
+    """记忆配置"""
+    storage_path: str = "~/.memex/memory"
+
+
+class VectorStoreConfig(BaseModel):
+    """向量存储配置"""
+    provider: str = "lancedb"  # lancedb | chroma | memory
+
+
+class EmbeddingConfig(BaseModel):
+    """Embedding 配置"""
+    model: str = "BAAI/bge-base-zh-v1.5"
+    dimension: int = 768
+
+
+class RetrievalConfig(BaseModel):
+    """检索配置"""
+    default_limit: int = 10
+    min_similarity: float = 0.4
+
+
+class Config(BaseModel):
+    """完整配置"""
+    memory: MemoryConfig = MemoryConfig()
+    vector_store: VectorStoreConfig = VectorStoreConfig()
+    embedding: EmbeddingConfig = EmbeddingConfig()
+    retrieval: RetrievalConfig = RetrievalConfig()
+
+
+# 全局配置实例
+_config: Optional[Config] = None
+
+
+def get_config_path() -> Path:
+    """获取配置路径"""
+    return Path.home() / ".memex" / "config.toml"
+
+
+def load_config() -> Config:
+    """加载配置"""
+    global _config
+    
+    if _config is not None:
+        return _config
+    
+    config_path = get_config_path()
+    
+    if config_path.exists():
+        import toml
+        data = toml.load(config_path)
+        _config = Config(**data)
+    else:
+        _config = Config()
+    
+    return _config
+
+
+def save_config(config: Config) -> None:
+    """保存配置"""
+    config_path = get_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    import toml
+    with open(config_path, "w") as f:
+        toml.dump(config.model_dump(), f)
+    
+    global _config
+    _config = config
+
+
+def get_storage_path() -> Path:
+    """获取存储路径"""
+    config = load_config()
+    path = Path(config.memory.storage_path).expanduser()
+    path.mkdir(parents=True, exist_ok=True)
+    return path

memex/_consolidation.py

@@ -0,0 +1,142 @@
+"""
+Consolidation — 记忆合并
+
+当两条记忆相似度 > 阈值时，合并为一条，保留信息更丰富的内容。
+阈值：0.85（向量相似度）
+"""
+
+from typing import List, Tuple, Optional
+import math
+
+from ._types import MemoryRecord, MemoryType
+
+
+# 合并阈值
+SIMILARITY_THRESHOLD = 0.85
+
+
+def cosine_similarity(vec_a: List[float], vec_b: List[float]) -> float:
+    """计算两个向量的余弦相似度"""
+    dot_product = sum(a * b for a, b in zip(vec_a, vec_b))
+    norm_a = math.sqrt(sum(a * a for a in vec_a))
+    norm_b = math.sqrt(sum(b * b for b in vec_b))
+    
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    
+    return dot_product / (norm_a * norm_b)
+
+
+def find_similar_pairs(
+    records: List[MemoryRecord],
+    vectors: List[List[float]],
+    threshold: float = SIMILARITY_THRESHOLD,
+) -> List[Tuple[int, int, float]]:
+    """
+    找出所有相似度 > threshold 的记忆对
+    
+    Returns:
+        [(idx_a, idx_b, similarity), ...]
+    """
+    if len(records) != len(vectors):
+        raise ValueError("records and vectors must have same length")
+    
+    pairs = []
+    for i in range(len(records)):
+        for j in range(i + 1, len(records)):
+            sim = cosine_similarity(vectors[i], vectors[j])
+            if sim >= threshold:
+                pairs.append((i, j, sim))
+    
+    # 按相似度降序
+    pairs.sort(key=lambda x: x[2], reverse=True)
+    return pairs
+
+
+def consolidate_pair(
+    record_a: MemoryRecord,
+    record_b: MemoryRecord,
+) -> MemoryRecord:
+    """
+    合并两条记忆
+    
+    策略：
+    - 保留 content 更长/更详细的那条
+    - importance 取两者较高
+    - confidence 取两者平均
+    - revision_count 取两者较大
+    - 更新 last_updated
+    - 记录合并来源
+    """
+    # 选择更好的内容（更长更详细）
+    if len(record_b.content) > len(record_a.content):
+        primary, secondary = record_b, record_a
+    else:
+        primary, secondary = record_a, record_b
+    
+    import time
+    
+    merged = MemoryRecord.from_dict(primary.to_dict())
+    merged.importance = max(primary.importance, secondary.importance)
+    merged.confidence = (primary.confidence + secondary.confidence) / 2
+    merged.revision_count = max(primary.revision_count, secondary.revision_count) + 1
+    merged.last_updated = int(time.time() * 1000)
+    merged.metadata["consolidated"] = True
+    merged.metadata["consolidated_from"] = [primary.id, secondary.id]
+    merged.metadata["consolidated_at"] = int(time.time() * 1000)
+    
+    return merged
+
+
+def consolidate_all(
+    records: List[MemoryRecord],
+    vectors: List[List[float]],
+    threshold: float = SIMILARITY_THRESHOLD,
+) -> List[Tuple[List[MemoryRecord], List[List[float]]]]:
+    """
+    合并所有相似的记忆
+    
+    Returns:
+        每次合并的结果 [(remaining_records, remaining_vectors), ...]
+        最终返回所有合并轮次的结果
+    """
+    import copy
+    
+    remaining_records = list(records)
+    remaining_vectors = list(vectors)
+    history = []
+    
+    while True:
+        pairs = find_similar_pairs(remaining_records, remaining_vectors, threshold)
+        if not pairs:
+            break
+        
+        # 合并第一对（最高相似度）
+        idx_a, idx_b, sim = pairs[0]
+        
+        merged = consolidate_pair(remaining_records[idx_a], remaining_records[idx_b])
+        
+        # 移除被合并的两个，插入合并结果
+        # 先处理索引较大的，再处理索引小的
+        max_idx = max(idx_a, idx_b)
+        min_idx = min(idx_a, idx_b)
+        
+        new_records = remaining_records.copy()
+        new_vectors = remaining_vectors.copy()
+        
+        del new_records[max_idx]
+        del new_vectors[max_idx]
+        del new_records[min_idx]
+        del new_vectors[min_idx]
+        
+        new_records.insert(min_idx, merged)
+        # 用被合并的两个向量的平均作为新向量
+        avg_vector = [(v1 + v2) / 2 for v1, v2 in zip(remaining_vectors[idx_a], remaining_vectors[idx_b])]
+        new_vectors.insert(min_idx, avg_vector)
+        
+        history.append((list(remaining_records), list(remaining_vectors)))
+        
+        remaining_records = new_records
+        remaining_vectors = new_vectors
+    
+    return history

memex/_contradiction.py

@@ -0,0 +1,206 @@
+"""
+Contradiction Detection — 矛盾检测
+
+检测两条记忆之间的语义矛盾。
+当检测到矛盾时，降低双方的 importance。
+
+矛盾模式：
+1. 否定模式：A 说"X 是 Y"，B 说"X 不是 Y"
+2. 行为冲突模式：A 说"做 X"，B 说"不做 X"
+"""
+
+from dataclasses import dataclass
+from typing import Optional, List, Tuple
+
+from ._types import MemoryRecord
+
+
+@dataclass
+class ContradictionResult:
+    """矛盾检测结果"""
+    has_contradiction: bool
+    confidence: float           # 0-1，矛盾置信度
+    pattern: str               # 矛盾模式
+    details: str               # 详细描述
+
+
+def detect_record_pair_contradiction(
+    record_a: MemoryRecord,
+    record_b: MemoryRecord,
+) -> ContradictionResult:
+    """
+    检测两条记忆之间的矛盾
+    
+    Returns:
+        ContradictionResult
+    """
+    content_a = record_a.content.lower()
+    content_b = record_b.content.lower()
+    
+    # 1. 检测否定模式
+    pattern = _detect_negation_pattern(content_a, content_b)
+    if pattern:
+        return ContradictionResult(
+            has_contradiction=True,
+            confidence=0.8,
+            pattern="negation",
+            details=pattern,
+        )
+    
+    # 2. 检测行为冲突（做 vs 不做）
+    pattern = _detect_action_pattern(content_a, content_b)
+    if pattern:
+        return ContradictionResult(
+            has_contradiction=True,
+            confidence=0.7,
+            pattern="action_conflict",
+            details=pattern,
+        )
+    
+    return ContradictionResult(
+        has_contradiction=False,
+        confidence=0.0,
+        pattern="none",
+        details="",
+    )
+
+
+def _detect_negation_pattern(a: str, b: str) -> Optional[str]:
+    """检测否定模式矛盾"""
+    import re
+    
+    # 英文单词集合
+    def get_english_words(text: str) -> set:
+        return set(re.findall(r'[a-z]+', text))
+    
+    english_words_a = get_english_words(a)
+    english_words_b = get_english_words(b)
+    
+    # 英文否定词
+    en_neg = {"no", "not", "never", "dont", "doesnt", "cant", "shouldnt", "wont", "noone"}
+    
+    # 检测英文否定
+    a_has_en_neg = bool(en_neg & english_words_a)
+    b_has_en_neg = bool(en_neg & english_words_b)
+    
+    # 检测中文否定（直接搜索否定词）
+    def has_cn_negation(text: str) -> bool:
+        cn_negations = [
+            "不用", "不是", "不支持", "不可以", "不应", "不推荐", "不建议", "不愿意",
+            "不使用", "不应该", "不建议", "不鼓励", "不允许",
+        ]
+        return any(neg in text for neg in cn_negations)
+    
+    a_has_cn_neg = has_cn_negation(a)
+    b_has_cn_neg = has_cn_negation(b)
+    
+    # 英文肯定词
+    en_pos = {"use", "uses", "is", "are", "was", "were", "do", "does", "can", "should", "recommend", "like"}
+    
+    # 检测英文矛盾：A 无否定，B 有否定，且有共同肯定词
+    if not a_has_en_neg and b_has_en_neg:
+        common = en_pos & english_words_a & english_words_b
+        if common:
+            return f"A 说\"{a[:50]}\"，B 说\"{b[:50]}\"（英文否定矛盾）"
+    if not b_has_en_neg and a_has_en_neg:
+        common = en_pos & english_words_a & english_words_b
+        if common:
+            return f"A 说\"{a[:50]}\"，B 说\"{b[:50]}\"（英文否定矛盾）"
+    
+    # 检测中文矛盾：当一方有否定词时，必须有共同关键词
+    def has_shared_content(text_a: str, text_b: str) -> bool:
+        """检查两句话是否有共同的内容词（排除停用词）"""
+        stop_words = {"的", "是", "在", "有", "了", "和", "与", "很", "也", "都", "the", "a", "an", "is", "are", "was", "were", "this", "that", "it"}
+        # 提取中文词（简单按字符，不精确但够用）
+        def get_cn_words(text):
+            import re
+            # 提取连续中文字符序列
+            cn_phrases = re.findall(r'[\u4e00-\u9fff]+', text)
+            words = set()
+            for phrase in cn_phrases:
+                for char in phrase:
+                    words.add(char)
+            return words
+        
+        cn_a = get_cn_words(text_a) - stop_words
+        cn_b = get_cn_words(text_b) - stop_words
+        
+        # 英文词
+        en_a = set(re.findall(r'[a-z]+', text_a))
+        en_b = set(re.findall(r'[a-z]+', text_b))
+        
+        return bool((cn_a & cn_b) or (en_a & en_b))
+    
+    if a_has_cn_neg and not b_has_cn_neg:
+        if has_shared_content(a, b):
+            return f"A 说\"{a[:50]}\"，B 说\"{b[:50]}\"（中文否定矛盾）"
+    if b_has_cn_neg and not a_has_cn_neg:
+        if has_shared_content(a, b):
+            return f"A 说\"{a[:50]}\"，B 说\"{b[:50]}\"（中文否定矛盾）"
+    if a_has_cn_neg and b_has_cn_neg:
+        if has_shared_content(a, b):
+            return f"A 说\"{a[:50]}\"，B 说\"{b[:50]}\"（中文双重否定矛盾）"
+    
+    return None
+
+
+def _detect_action_pattern(a: str, b: str) -> Optional[str]:
+    """检测行为冲突（做 vs 不做）"""
+    # 英文行为词对
+    action_pairs = [
+        ("use", "avoid"),
+        ("recommend", "don't recommend"),
+        ("should", "shouldn't"),
+    ]
+    
+    for pos, neg in action_pairs:
+        if pos in a and neg in b:
+            return f"行为冲突：A 推荐\"{pos}\"，B 反对\"{neg}\""
+        if neg in a and pos in b:
+            return f"行为冲突：A 反对\"{neg}\"，B 推荐\"{pos}\""
+    
+    return None
+
+
+def find_contradictions(
+    records: List[MemoryRecord],
+) -> List[Tuple[MemoryRecord, MemoryRecord, ContradictionResult]]:
+    """
+    在记忆列表中找出所有相互矛盾的记忆对
+    """
+    contradictions = []
+    
+    for i in range(len(records)):
+        for j in range(i + 1, len(records)):
+            result = detect_record_pair_contradiction(records[i], records[j])
+            if result.has_contradiction:
+                contradictions.append((records[i], records[j], result))
+    
+    return contradictions
+
+
+def apply_contradiction_penalty(
+    record_a: MemoryRecord,
+    record_b: MemoryRecord,
+) -> Tuple[MemoryRecord, MemoryRecord]:
+    """
+    当检测到矛盾时，降低双方 importance
+    """
+    import time
+    
+    def _penalize(r: MemoryRecord, confidence: float) -> MemoryRecord:
+        factor = 0.7 if confidence >= 0.8 else 0.85
+        updated = MemoryRecord.from_dict(r.to_dict())
+        updated.importance = max(0.1, updated.importance * factor)
+        updated.metadata["contradiction_penalty"] = True
+        updated.metadata["contradiction_at"] = int(time.time() * 1000)
+        return updated
+    
+    result = detect_record_pair_contradiction(record_a, record_b)
+    if not result.has_contradiction:
+        return record_a, record_b
+    
+    updated_a = _penalize(record_a, result.confidence)
+    updated_b = _penalize(record_b, result.confidence)
+    
+    return updated_a, updated_b