\r \r

HuiMemory 集成指南\r

\r HuiMemory 是一个"延长单窗口对话"的本地语义记忆系统，核心设计哲学：检索系统 = 搜索引擎，不负责语义理解和答案生成。\r \r

集成模式\r

\r HuiMemory 采用 "默认增强、可选接管" 的集成模式，与 Mem0、Zep 等主流记忆库保持一致：\r \r

增强模式（默认）\r

• 无侵入外挂：宿主应用保留自己的对话存储和短期记忆管理\r
• 只做增强：HuiMemory 负责存储历史对话、检索相关内容、返回结果\r
• 不碰内部逻辑：完全不影响宿主原有的记忆系统\r
• 适用场景：已有记忆系统的应用，想增加长期记忆能力\r \r

宿主应用                    HuiMemory\r
┌─────────────┐            ┌─────────────┐\r
│ 短期对话存储 │            │ 长期记忆存储 │\r
│ 上下文管理   │  ← 调用 →  │ 语义检索     │\r
│ 业务逻辑     │            │ 时间过滤     │\r
└─────────────┘            └─────────────┘\r
```\r
\r
### 接管模式（可选）\r
- **完整记忆内核**：宿主不再维护对话存储，所有记忆读写都交给 HuiMemory\r
- **需要主动配合**：宿主需要调用 HuiMemory 的 API 进行所有记忆操作\r
- **适用场景**：新应用、需要完整记忆方案的应用\r
\r
```\r
宿主应用                    HuiMemory\r
┌─────────────┐            ┌─────────────┐\r
│ 业务逻辑     │  ← 全部 →  │ 短期+长期记忆 │\r
│             │            │ 上下文管理   │\r
│             │            │ 语义检索     │\r
└─────────────┘            └─────────────┘\r
```\r
\r
**默认情况下，HuiMemory 作为增强模式的外挂技能使用，不会接管或破坏宿主原有的记忆系统。**\r
\r
## 核心特性\r
\r
- ✅ **三层架构**：LLM 提炼 → 检索系统（关键词+时间）→ LLM 回答\r
- ✅ **轮次锚点系统**：`[id:xxx | prev: yyy | next: zzz]` 双向链表导航\r
- ✅ **时间解析**：自然语言时间 → 分段扫描（周步长）\r
- ✅ **轻量模型**：默认使用 `bge-base-zh-v1.5`（768 维，~430MB）\r
\r
## 快速开始\r
\r
### 1. 安装依赖\r
\r
```bash\r
# 克隆项目\r
git clone https://gitee.com/HuiMengAI/hui-memory.git\r
cd hui-memory\r
\r
# 安装依赖\r
pip install -r requirements.txt\r
\r
# 安装 embedding 依赖（轻量模型）\r
pip install -r requirements-embedding.txt\r
```\r
\r
### 2. 下载模型\r
\r
```bash\r
# 下载轻量中文模型（推荐，平衡性能和体积）\r
git clone https://gitcode.com/hf_mirrors/BAAI/bge-base-zh-v1.5.git models/bge-base-zh-v1.5\r
\r
# 或使用极致轻量版（嵌入式设备）\r
# git clone https://gitcode.com/hf_mirrors/BAAI/bge-small-zh-v1.5.git models/bge-small-zh-v1.5\r
\r
# 或使用 BGE-M3（重模型，性能最好）\r
# git clone https://gitcode.com/hf_mirrors/BAAI/bge-m3.git models/bge-m3\r
```\r
\r
### 3. 配置文件\r
\r
创建 `configs/config.yaml`：\r
\r
```yaml\r
embedding:\r
  model_path: "models/bge-base-zh-v1.5"  # 轻量模型（推荐）\r
  dimension: 768                          # base=768, small=384, m3=1024\r
  # model_path: "models/bge-small-zh-v1.5"  # 极致轻量版\r
  # model_path: "models/bge-m3"             # 重模型（可选）\r
  device: "cpu"                            # 或 "cuda"\r
  batch_size: 32\r
\r
storage:\r
  db_path: "data/huimemory.db"\r
  cache_dir: ".cache"\r
  cache_ttl_hours: 72\r
\r
archive:\r
  base_dir: "memory/sessions"\r
  compression: "zstd"\r
  level: 3\r
\r
retriever:\r
  default_top_k: 5\r
  enable_progressive_scan: true\r
  max_scan_weeks: 16\r
```\r
\r
### 4. 基本用法\r
\r
```python\r
from huimemory import Retriever, Archiver, TopicManager\r
from huimemory.embedding import BGEMockEmbedding  # 或 BGEEmbedding\r
\r
# 初始化\r
embedding = BGEMockEmbedding()  # 或 BGEEmbedding(model_path="models/bge-base-zh-v1.5")\r
retriever = Retriever(embedding=embedding, config_path="configs/config.yaml")\r
\r
# 索引对话\r
from huimemory.chunker import TurnChunker\r
\r
chunker = TurnChunker()\r
chunks = chunker.chunk_file("memory/sessions/2026-W15/2026-04-13/chat_xxx.md")\r
retriever.store.add(chunks)\r
\r
# 检索\r
results = retriever.search(\r
    query="用户问过什么关于 AI 意识的问题？",\r
    top_k=5,\r
    enable_progressive_scan=True\r
)\r
\r
# 格式化输出\r
for r in results:\r
    print(retriever.format_search_result(r))\r
    print("---")\r
```\r
\r
## LLM 集成\r
\r
### System Prompt 模板\r
\r
```markdown\r
你是一个拥有长期记忆的 AI 助手。你可以通过 `recall_memory` 工具检索历史对话。\r
\r
## 记忆检索规则\r
\r
1. **关键词检索**：当用户提到具体内容时，使用关键词搜索\r
   - 用户："我之前问过什么关于 AI 意识的问题？"\r
   - 调用：`recall_memory(query="AI 意识", top_k=5)`\r
\r
2. **时间过滤**：当用户提到时间范围时，使用时间过滤\r
   - 用户："上周我们讨论了什么？"\r
   - 调用：`recall_memory(query="", filter_expr="timestamp >= '2026-04-06' AND timestamp \x3C= '2026-04-13'")`\r
\r
3. **分段扫描**：当时间模糊时，系统会自动分段扫描\r
   - 用户："前段时间我们聊过什么项目？"\r
   - 系统自动：从最近一周开始，逐步向前扫描\r
\r
4. **轮次导航**：当需要查看上下文时，使用 `recall_by_id`\r
   - 检索结果：`[id:a3f2c7 | prev: k7f2a1 | next: d2n7p3]`\r
   - 调用：`recall_by_id(turn_id="k7f2a1")` 查看上一轮\r
\r
## 输出格式\r
\r
检索结果格式：\r
```\r
[id:a3f2c7 | prev: k7f2a1 | next: d2n7p3 | 相似度: 0.778]\r
📁 2026-W11/2026-03-05/chat_xxx.md | 话题: 本地模型部署 | 2026-03-05 Mon 10:00:07\r
\r
\x3Cuser timestamp="...">...\x3C/user>\r
\x3Cassistant timestamp="...">...\x3C/assistant>\r
```\r
\r
使用 `prev`/`next` 值调用 `recall_by_id` 查看相邻轮次。\r
```\r
\r
### Tool Schema\r
\r
```json\r
{\r
  "tools": [\r
    {\r
      "name": "recall_memory",\r
      "description": "检索历史对话记忆。支持关键词搜索、时间过滤、分段扫描。",\r
      "parameters": {\r
        "type": "object",\r
        "properties": {\r
          "query": {\r
            "type": "string",\r
            "description": "搜索关键词或问题"\r
          },\r
          "filter_expr": {\r
            "type": "string",\r
            "description": "时间过滤表达式，如 \"timestamp >= '2026-04-06'\""\r
          },\r
          "top_k": {\r
            "type": "integer",\r
            "description": "返回结果数量，默认 5",\r
            "default": 5\r
          }\r
        },\r
        "required": ["query"]\r
      }\r
    },\r
    {\r
      "name": "recall_by_id",\r
      "description": "根据轮次 ID 检索特定对话。用于导航到相邻轮次。",\r
      "parameters": {\r
        "type": "object",\r
        "properties": {\r
          "turn_id": {\r
            "type": "string",\r
            "description": "轮次 ID，如 'a3f2c7'"\r
          }\r
        },\r
        "required": ["turn_id"]\r
      }\r
    }\r
  ]\r
}\r
```\r
\r
## 架构设计\r
\r
### 三层架构\r
\r
```\r
┌─────────────────────────────────────────────────────────────┐\r
│                      LLM 层（理解+回答）                      │\r
│  - 意图理解：关键词提取、时间范围推断                          │\r
│  - 答案组织：基于检索结果生成回答                              │\r
│  - 追问决策：是否需要更多上下文                                │\r
└─────────────────────────────────────────────────────────────┘\r
                              ↓ 调用工具\r
┌─────────────────────────────────────────────────────────────┐\r
│                   检索系统层（搜索引擎）                       │\r
│  - 关键词检索：向量相似度搜索                                  │\r
│  - 时间过滤：metadata 范围查询                                 │\r
│  - 分段扫描：周步长渐进式扫描                                  │\r
│  - 轮次导航：prev/next 指针                                   │\r
└─────────────────────────────────────────────────────────────┘\r
                              ↓ 读取文件\r
┌─────────────────────────────────────────────────────────────┐\r
│                      存储层（数据持久化）                      │\r
│  - 向量存储：SQLite + Faiss                                   │\r
│  - 元数据索引：timestamp, turn_index, topic, session_file    │\r
│  - 归档管理：月包压缩（.tar.zst）                              │\r
└─────────────────────────────────────────────────────────────┘\r
```\r
\r
### 核心原则\r
\r
1. **检索系统 = 搜索引擎**：只负责"捞"候选，不做判断\r
2. **LLM = 决策者**：负责判断、追问、组织答案\r
3. **向量模型无上下文**：不做"哪个是对的"判断\r
\r
## 高级功能\r
\r
### 1. 分段扫描（Progressive Scan）\r
\r
当时间模糊时，系统自动从近到远扫描：\r
\r
```python\r
results = retriever.search_with_progress(\r
    query="项目讨论",\r
    on_round=lambda week, results: print(f"扫描 {week}，找到 {len(results)} 条"),\r
    max_weeks=16\r
)\r
```\r
\r
### 2. 上下文窗口扩展\r
\r
检索到结果后，自动扩展相邻轮次：\r
\r
```python\r
results = retriever.search(\r
    query="AI 意识",\r
    context_window=2  # 包含 ±2 轮\r
)\r
```\r
\r
### 3. 时间解析\r
\r
支持自然语言时间：\r
\r
```python\r
from huimemory.utils.time_resolver import TimeResolver\r
\r
resolver = TimeResolver()\r
result = resolver.parse("上周三下午")\r
# {"start": "2026-04-09T12:00:00", "end": "2026-04-09T18:00:00"}\r
```\r
\r
## 常见问题\r
\r
### Q1: 为什么不用 BGE-M3？\r
\r
**模型对比**：\r
- **BGE-M3**：1024 维，2G+ 模型，性能最好（C-MTEB ~65）\r
- **bge-base-zh-v1.5**：768 维，~430MB，性能优秀（C-MTEB ~63.1）\r
- **bge-small-zh-v1.5**：384 维，~100MB，性能合格（C-MTEB ~57.8）\r
\r
**推荐**：\r
- 默认使用 `bge-base-zh-v1.5`：平衡性能和体积，适合大多数应用\r
- 极致轻量场景用 `bge-small-zh-v1.5`：嵌入式设备、移动端\r
- 追求极致性能用 `BGE-M3`：服务器部署、专业应用\r
\r
### Q2: 如何处理模糊时间？\r
\r
系统采用**分段扫描**策略：\r
1. 规则引擎解析精确时间（"上周三"）\r
2. 模糊时间触发分段扫描（"前段时间"）\r
3. 从最近一周开始，逐步向前扫描\r
4. 每周最多返回 5 个候选，交给 LLM 判断\r
\r
### Q3: 如何扩展上下文？\r
\r
使用 `context_window` 参数：\r
\r
```python\r
results = retriever.search(\r
    query="项目架构",\r
    context_window=3  # 包含 ±3 轮\r
)\r
```\r
\r
结果会标记 `_context_role`：`hit`（命中）、`neighbor`（邻居）\r
\r
## 参考文档\r
\r
- `references/architecture.md` - 详细架构设计\r
- `references/api-reference.md` - 完整 API 文档\r
- `references/llm-integration.md` - LLM 集成深度指南\r
\r
## 示例项目\r
\r
- `examples/quickstart.py` - 快速入门示例\r
- `examples/llm_integration_demo.py` - LLM 集成完整示例\r
\r
---\r
\r
**核心设计哲学**：检索系统只负责"捞"，LLM 负责"判断"。保持简单，避免过度设计。\r