OpenCode Memory System：为 AI 编程助手打造跨会话记忆系统

📖 目录

• 项目背景
• 技术架构
• 核心功能
• 快速开始
• 技术细节
• 性能优化
• 实战案例
• 未来展望

---

项目背景

为什么需要记忆系统？

这段时间在使用 OpenCode 时，经常会碰到AI 遗忘各种关键信息，就得不厌其烦地跟他提醒，实在忍不了了，决定
为OpenCode手搓一个记忆增强系统解决以下痛点：

❌ 跨会话遗忘：每次对话都是"从零开始"，AI 不记得你之前的偏好、决策、技术栈
❌ 重复输入：每次都要重新说明"项目使用 FastAPI + PostgreSQL"、“偏好订阅制商业模式”
❌ 缺乏上下文：AI 无法理解项目历史决策，导致建议不一致
❌ 知识碎片化：重要信息散落在不同会话中，难以整合

OpenCode Memory System 旨在解决这些问题，为 AI 编程助手提供持久化记忆能力。

---

技术架构

整体架构图

┌─────────────────────────────────────────────────────┐
│                用户对话输入                           │
└─────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────┐
│  AutoDetector（自动识别引擎）                        │
│  ├─ 关键词触发检测                                   │
│  ├─ 正则模式匹配                                     │
│  └─ 置信度评估                                       │
└─────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────┐
│  MemoryManager（核心管理类）                        │
│  ├─ 手动保存                                         │
│  ├─ 自动保存                                         │
│  ├─ 检索管理                                         │
│  └─ 统计导出                                         │
└─────────────────────────────────────────────────────┘
                       ↓
┌──────────────┬──────────────────┬─────────────────┐
│ SQLite       │ ChromaDB         │ ONNX Runtime    │
│ 元数据库     │ 向量数据库       │ Embedding服务   │
│ ├─ 记忆ID    │ ├─ HNSW索引      │ ├─ 模型加载     │
│ ├─ 内容      │ ├─ 384维向量     │ ├─ 3ms推理      │
│ ├─ 类型      │ ├─ 余弦相似度    │ └─ 本地缓存     │
│ ├─ 时间      │ └─ 作用域过滤    │                 │
│ └─ 元数据    │                  │                 │
└──────────────┴──────────────────┴─────────────────┘
                       ↓
┌─────────────────────────────────────────────────────┐
│  Retriever（检索引擎）                               │
│  ├─ 相似度检索                                       │
│  ├─ 按类型检索                                       │
│  ├─ 最近记忆检索                                     │
│  └─ 格式化输出                                       │
└─────────────────────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────┐
│             返回相关记忆给 AI/用户                   │
└─────────────────────────────────────────────────────┘

技术栈选择

组件	技术选型	选择理由
Embedding	ONNX Runtime + all-MiniLM-L6-v2	加载快（0.2秒），推理快（3ms），模型小（90MB）
向量数据库	ChromaDB 1.5.9	本地嵌入式，HNSW索引，支持多条件过滤
元数据库	SQLite	轻量级，本地存储，无需额外服务
自动检测	关键词触发 + 正则匹配	简单高效，可扩展性强
开发语言	Python 3.14	生态丰富，易于集成

---

核心功能

1. 自动识别记忆内容

系统能自动检测用户对话中值得记忆的内容：

用户消息: "项目使用 FastAPI + PostgreSQL 架构，选择 DeepSeek V4 Flash 作为 LLM"

自动检测结果:
✓ project_context: "项目使用 FastAPI + PostgreSQL 架构"
✓ decision: "选择 DeepSeek V4 Flash 作为 LLM"
✓ constraint: "必须使用 DeepSeek V4 Flash"

支持的记忆类型：

• user_preference: 用户偏好（喜欢、偏好、习惯）
• project_context: 项目上下文（技术栈、架构、数据库）
• decision: 决策（选择、决定、采用方案）
• constraint: 限制（必须、仅使用、不超过）
• goal: 目标（需求、希望、要实现）
• feedback: 反馈（修复、改进、优化）

2. 语义相似度检索

不同于传统的关键词匹配，使用向量语义相似度检索：

# 传统关键词匹配（无法找到）
搜索 "DeepSeek" → ✗ 无法匹配 "使用 DeepSeek V4 Flash"

# 语义相似度检索（能找到）
搜索 "DeepSeek" → ✓ 找到 "决定使用 DeepSeek V4 Flash 作为 LLM"
                  相似度: 0.53

3. 跨会话记忆持久化

记忆数据存储在本地，不同会话间共享：

~/.opencode/memory/
├── global_metadata.db      # SQLite 元数据库
├── global_vectors/         # ChromaDB 向量数据库
└── global_raw/             # 原始文本备份

4. 多种检索方式

# 相似度检索
manager.retrieve_relevant("架构", top_k=5, min_similarity=0.5)

# 按类型检索
manager.retrieve_by_type("DeepSeek", memory_type="decision")

# 最近记忆检索
manager.retrieve_recent(days=7, limit=10)

# 关键词搜索
manager.search_by_keywords("订阅", limit=20)

---

快速开始

安装依赖

pip install --user --break-system-packages \
  onnxruntime transformers chromadb sqlite3 numpy

初始化数据库

cd /home/gomeswang/studio/opencode-memory
./memory init

输出：

✓ 数据库初始化成功: /home/gomeswang/.opencode/memory/global_metadata.db
✓ 数据库初始化成功

保存记忆

手动保存：

./memory save "用户偏好订阅制商业模式，价格 ¥99-199/月" \
  --type user_preference

自动检测保存：

./memory auto "项目使用 FastAPI + PostgreSQL 架构，选择 DeepSeek V4 Flash"

输出：

✓ 自动保存 3 条记忆
  - mem_e2907c38_20260506_234249
  - mem_f39f2aa9_20260506_234249
  - mem_8f5113e7_20260506_234249

检索记忆

./memory search "DeepSeek" --top-k 3 --min-similarity 0.3

输出：

找到 3 条相关记忆:

1. [decision] 相似度: 0.61
   内容: 选择 DeepSeek V4 Flash 作为 LLM

2. [project_context] 相似度: 0.57
   内容: 架构，选择 DeepSeek V4 Flash 作为 LLM

3. [project_context] 相似度: 0.45
   内容: 项目使用 FastAPI + PostgreSQL 架构，选择 DeepSeek V4 Flash 作为 LLM

查看统计

./memory stats

输出：

=== 记忆统计信息 ===
总计: 4 条
最近7天: 4 条

按类型分布:
  project_context: 2
  decision: 1
  user_preference: 1

按作用域分布:
  global: 4

导出记忆

./memory export --format markdown --output memories.md

---

技术细节

EmbeddingService 实现（ONNX Runtime）

为什么选择 ONNX Runtime？

传统 sentence-transformers 使用 PyTorch，存在以下问题：

• ❌ 模型加载慢（多进程池初始化超时）
• ❌ 推理速度慢（CPU 上 100ms+）
• ❌ 内存占用大（PyTorch 运行时）

ONNX Runtime 解决方案：

import onnxruntime as ort
from transformers import AutoTokenizer

# 加载 tokenizer（本地缓存）
tokenizer = AutoTokenizer.from_pretrained(
    'sentence-transformers/all-MiniLM-L6-v2',
    local_files_only=True  # 强制使用本地缓存
)

# 加载 ONNX 模型
model_path = '~/.cache/huggingface/hub/sentence-transformers/all-MiniLM-L6-v2/onnx/model.onnx'
session = ort.InferenceSession(model_path)

# 推理
inputs = tokenizer(text, return_tensors='np', return_token_type_ids=True)
outputs = session.run(None, {
    'input_ids': inputs['input_ids'],
    'attention_mask': inputs['attention_mask'],
    'token_type_ids': inputs['token_type_ids']
})

# Mean pooling
embedding = outputs[0].mean(axis=1).squeeze()

性能对比：

指标	sentence-transformers (PyTorch)	ONNX Runtime
模型加载	超时（120秒+）	0.19秒 ⚡
单条推理	100ms+	2-3ms ⚡
批量推理	50ms/条	1ms/条 ⚡
内存占用	~500MB	~150MB ⚡

ChromaDB 向量数据库配置

{
  "vector_db": {
    "type": "chromadb",
    "path": "~/.opencode/memory/global_vectors",
    "collection_name": "opencode_memory_global",
    "index_type": "hnsw",
    "metric": "cosine"
  }
}

HNSW 算法优势：

• ⚡ 检索速度快（O(log N)）
• 🎯 高召回率（95%+）
• 💾 内存占用小（无需存储全量距离矩阵）

多条件过滤语法（ChromaDB 1.5.x）：

# 单条件过滤
results = collection.query(
    query_embeddings=[embedding],
    where={"scope": "global"}
)

# 多条件过滤（$and 操作符）
results = collection.query(
    query_embeddings=[embedding],
    where={
        "$and": [
            {"scope": "global"},
            {"tags": {"$contains": "decision"}}
        ]
    }
)

AutoDetector 自动识别逻辑

关键词触发检测：

trigger_keywords = {
    "decision": ["选择", "决定", "采用", "方案", "决策"],
    "config": ["配置", "密钥", "API", "设置", "环境"],
    "knowledge": ["重要", "关键", "注意", "要点", "最佳"],
    "preference": ["喜欢", "偏好", "习惯", "常用"],
    "workflow": ["流程", "步骤", "命令", "操作"]
}

# 检测逻辑
for category, keywords in trigger_keywords.items():
    for keyword in keywords:
        if keyword in user_message:
            # 提取包含关键词的句子
            sentences = extract_sentences(user_message, keyword)
            matches.append({
                'type': category,
                'content': sentence,
                'confidence': 0.7
            })

正则模式匹配：

patterns = {
    'user_preference': [
        r'我喜欢(.+)',
        r'我偏好(.+)',
        r'用户偏好(.+)'
    ],
    'constraint': [
        r'必须(.+)',
        r'限制(.+)',
        r'仅使用(.+)'
    ],
    'decision': [
        r'决定(.+)',
        r'选择(.+)',
        r'采用(.+)方案'
    ]
}

---

性能优化

1. 模型缓存策略

使用 local_files_only=True 强制使用本地缓存，避免网络延迟：

tokenizer = AutoTokenizer.from_pretrained(
    'sentence-transformers/all-MiniLM-L6-v2',
    local_files_only=True  # 0.03秒加载
)

对比网络加载：

tokenizer = AutoTokenizer.from_pretrained(
    'sentence-transformers/all-MiniLM-L6-v2'
    # 38秒加载（网络延迟）
)

2. 批量推理优化

批量处理多条文本，减少 tokenizer 调用次数：

# 单条推理（慢）
for text in texts:
    embedding = model.encode(text)  # 3ms × N

# 批量推理（快）
embeddings = model.encode(texts)  # 1ms × N

性能提升：批量处理 10 条文本，总耗时从 30ms 降低到 10ms。

3. ChromaDB 索引优化

使用 HNSW 算法（Hierarchical Navigable Small World）：

collection = client.get_or_create_collection(
    name="opencode_memory_global",
    metadata={"hnsw:space": "cosine"}  # 余弦相似度
)

检索性能：

• 100 条记忆：5ms
• 1000 条记忆：10ms
• 10000 条记忆：20ms

4. 禁用多进程池

设置环境变量避免 tokenizer 多进程池初始化超时：

export TOKENIZERS_PARALLELISM=false

---

实战案例

案例1：项目配置记忆

场景：用户在不同会话中多次说明项目配置

# 第一次会话
用户: "项目使用 FastAPI + PostgreSQL，数据库端口 5432"
./memory auto "项目使用 FastAPI + PostgreSQL，数据库端口 5432"
✓ 自动保存 2 条记忆

# 第二次会话（2天后）
用户: "项目的技术栈是什么？"
./memory search "技术栈"
找到 2 条相关记忆:
  - [project_context] 项目使用 FastAPI + PostgreSQL
  - [constraint] 数据库端口 5432

AI回答: 根据记忆，项目使用 FastAPI + PostgreSQL，数据库端口 5432。

案例2：决策历史记录

场景：团队决策历史记录

# 决策1
./memory save "决定使用订阅制商业模式，价格 ¥99-199/月" --type decision

# 决策2
./memory save "选择 DeepSeek V4 Flash 作为 LLM（成本低速度快）" --type decision

# 决策3
./memory save "采用 B 方案记忆作用域（全局+项目）" --type decision

# 查询决策历史
./memory search "商业模式决策" --type decision
找到 1 条决策:
  - [decision] 决定使用订阅制商业模式，价格 ¥99-199/月

案例3：用户偏好追踪

场景：追踪用户编程偏好

./memory save "用户喜欢使用 Tailwind CSS 进行前端开发" --type user_preference
./memory save "用户偏好订阅制商业模式" --type user_preference
./memory save "用户习惯使用 Git 进行版本控制" --type user_preference

# AI 推荐时参考用户偏好
./memory search "前端开发建议"
找到 1 条偏好:
  - [user_preference] 用户喜欢使用 Tailwind CSS 进行前端开发

AI: 根据您的偏好，建议使用 Tailwind CSS + React 组件方案。

---

未来展望

1. LLM集成（DeepSeek V4 Flash）

将记忆系统集成到 DeepSeek V4 Flash：

# 当前对话 + 相关记忆 → DeepSeek V4 Flash
prompt = f"""
当前用户问题: {user_query}

相关历史记忆:
{format_memories(relevant_memories)}

请基于历史记忆回答用户问题：
"""

response = deepseek_api.chat(prompt)

2. 工作流记忆

记录操作流程和步骤：

workflow_memory = {
    'type': 'workflow',
    'steps': [
        'git clone https://github.com/xxx/project',
        'cd project && npm install',
        'npm run dev'
    ],
    'context': '项目启动流程'
}

3. 项目知识库

为每个项目创建独立知识库：

# 项目作用域记忆
./memory save "淘宝客服智能体使用 RAG 技术" \
  --scope project \
  --project-path /home/user/taobao-ai-agent

4. 记忆质量评分

自动评估记忆质量：

quality_score = calculate_quality(memory)
# 评估维度：
# - 访问频率（使用次数）
# - 时间衰减（旧记忆权重降低）
# - 用户反馈（点赞/删除）
# - 相关性（与其他记忆的关联度）

5. 记忆关联图谱

构建记忆间关系网络：

memory_relations = {
    'mem_001': ['mem_002', 'mem_003'],  # mem_001 与 mem_002、mem_003 相关
    'relation_type': 'cause_effect',     # 因果关系
    'strength': 0.8                      # 关联强度
}

---

总结

OpenCode Memory System 是一个轻量级、高性能的跨会话记忆系统，解决了 AI 编程助手"健忘"的问题。

核心优势：

• ⚡ 性能优异：模型加载0.19秒，推理3ms，检索10ms
• 💾 本地部署：无需云服务，数据完全本地化
• 🎯 智能识别：自动检测6种记忆类型
• 🔍 语义检索：向量相似度检索，超越关键词匹配
• 📊 易于管理：CLI命令接口，10个常用命令

适用场景：

• AI 编程助手（OpenCode、Cursor、Copilot）
• 项目知识管理
• 团队决策记录
• 用户偏好追踪
• 工作流程记录

---

参考资料

• ONNX Runtime官方文档
• ChromaDB官方文档
• sentence-transformers模型库
• HNSW算法原理

---

作者: gomes
发布时间: 2026-05-06
标签: AI, 记忆系统, 向量检索, OpenCode, Python