opencode-memory

查询 "GBK 编码踩坑"
       │
       ├─► BM25 关键词检索   ─────────────────────┐
       │   (CJK bigram 分词，精确词汇命中)          │
       │                                          ├─► RRF 融合排序
       ├─► FAISS 向量检索    ─────────────────────┤   (Reciprocal Rank
       │   (核心文件语义索引)                       │    Fusion)
       │                                          │
       └─► STM 实时向量搜索  ─────────────────────┘
           (无需 reindex，写入即可检索)             │
                                                  ↓
                                        Cross-encoder 精排
                                        (ms-marco-MiniLM)
                                                  │
                                                  ↓
                                    #1 (relv 1.00) [pitfall] ...
                                    #2 (relv 0.87) [decision] ...

export MEMORY_MODEL_NAME=BAAI/bge-large-zh-v1.5  # 切换到中文专项模型

# 查看记忆变更历史
memory_history()
# → 📜 记忆变更历史 (共 138 次提交)
#     be365be  v3.0: memory_prime + Cross-encoder 重排 + ...
#     07caece  BUG修复: Cross-encoder logits 改用 min-max 归一化
#     966c571  v2.0: 索引用多语言模型重建 (11 chunks, 384d)

# 回滚到任意版本
memory_rollback(hash="07caece")

memory_reflect(apply=True, threshold=0.82)
# → 贪心聚类：相似度 ≥ 0.82 的记忆归为一簇
# → 每簇保留信息量最大的记忆（内容最长）
# → 合并标签，记录 merged_from
# → 高价值记忆自动提升到 MEMORY.md（LTM）

git clone https://github.com/Shine8592/universal-agent-memory
cd universal-agent-memory

pip install -r requirements.txt

# 安装到所有已检测到的 Agent
python scripts/install_memory_mcp.py --all

# 或安装到指定 Agent
python scripts/install_memory_mcp.py claude-code cursor kiro

pip install sentence-transformers faiss-cpu numpy

{
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["python", "-u", "/path/to/scripts/mcp_server.py"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-u", "/path/to/scripts/mcp_server.py"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["-u", "/path/to/scripts/mcp_server.py"]
    }
  }
}

{
  "context_servers": {
    "memory": {
      "command": { "path": "python", "args": ["-u", "/path/to/scripts/mcp_server.py"] }
    }
  }
}

python scripts/install_memory_mcp.py --list  # 检测已安装的 Agent

项目根目录/
└── .opencode/
    ├── SOUL.md          ─── Agent 核心人格
    ├── USER.md          ─── 用户画像
    ├── MEMORY.md        ─── 长期记忆（LTM）
    ├── AGENTS.md        ─── Agent 配置
    └── memory/
        ├── stm/             ─── 短期记忆（JSON，24h 窗口）
        ├── semantic_index.faiss   ─── 向量索引
        ├── semantic_metadata.json ─── 索引元数据
        ├── memory_diff.jsonl      ─── 操作审计日志
        ├── archive/         ─── 冷存储归档
        └── daily/           ─── 每日日志

写入 (memory_remember)
  → 精确去重检查
  → 语义去重 (相似度 > 0.9)
  → 自动 type 推断
  → 重要性评分
  → 写入 STM (JSON)
  → Git auto-commit
  → diff 审计日志

检索 (memory_recall)
  → BM25 关键词 + FAISS 向量 + STM 实时向量
  → RRF 融合排序
  → Cross-encoder 精排
  → type_filter 精准过滤

演化 (memory_reflect)
  → 贪心聚类（余弦相似度 ≥ 阈值）
  → 冗余合并（保留信息量最大项）
  → 高价值记忆提升 LTM

过期 (24h 后)
  → 重要性评估
  → 高分记忆语义蒸馏写入 MEMORY.md
  → 低分记忆清理

stdin 字节流
  ① 先试 UTF-8（MCP 协议标准）
  ② 失败 → 系统编码（cp936/cp1252）
  ③ 再失败 → UTF-8 + replace 兜底

+ _clean_surrogates() 递归清洗 UTF-16 代理字符
+ 所有文件 IO 显式指定 encoding="utf-8"

sentence-transformers  # 语义嵌入 + Cross-encoder 精排
faiss-cpu             # 向量索引
numpy                 # 数值计算

scripts/
├── mcp_server.py          # MCP Server 主入口（12 个工具，JSON-RPC over stdio）
├── hybrid_search.py       # BM25 + RRF 混合检索（纯标准库，中文 bigram）
├── semantic_search.py     # FAISS 向量检索
├── dual_memory_engine.py  # 双记忆引擎（STM/LTM 协同，自动分类，语义蒸馏）
├── memory_config.py       # 路径 + 模型配置（全环境变量可覆盖）
├── memory_git.py          # Git 原生版本管理
├── build_full_index.py    # 全量索引构建
├── install_memory_mcp.py  # 跨 Agent 一键安装器（13 个 Agent）
├── storage_tiers.py       # 热/温/冷三层存储
├── memory_dedup.py        # 语义去重引擎
├── plugin_bridge.py       # JSON CLI 桥接（Daemon 模式）
└── memory_maintain.py     # 定时维护工具

skill-memory-logic (2026-04)  → 最早的规则日志版
      ↓
SuperMemo-Du (2026-04)        → 双记忆引擎 + 三层存储
      ↓
super-memory-hermes-v1 (2026-05) → 语义向量记忆版（含已归档的 hermes-memory-system）
      ↓
universal-agent-memory (2026-07) → 当前主项目：MCP 架构 + 混合检索 + 跨 Agent 安装