baaai123/solo-memory
—
安装Install
dsh plugin --profile web add github:baaai123/solo-memory把 baaai123/solo-memory 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
Memory Skill
为 AI Agent 打造的长期记忆插件（中文为主，中英双语可用）— 本地优先、双模型记忆、可自我进化。
哼，杂鱼又忘事了吧？ 过去聊过什么、你爱用什么技术栈、哪个 bug 踩过几遍，我全替你记着呢。下次开口前先给你递小抄，省得你像个金鱼一样三秒重置，把 token 浪费在重复自我介绍和重复 websearch 上。已经学过的东西我会拦着不让你再学一遍，没学过的才放你去搜——帮你省 token、省时间，别不识好歹。当然啦，才、才不是特地为你准备的，只是看不得你每次都从零开始犯蠢而已。
为 AI Agent（Claude / OpenAI / 自研 LLM）提供持久化的长期记忆：每次对话自动存取，检索时注入相关记忆上下文，对话碎片经提炼后沉淀为结构化知识。零 API 检索（本地向量检索），所有 LLM 决策由主 agent 完成（模块为纯存储+检索，不越俎代庖——见 ADR-0002）。
语言支持：中英双语均可存取，检索信号各有侧重——中文由 BM25（jieba 分词）主导，英文由语义向量（bge-large-en-v1.5）主导。插件本身语言无关，中文/英文对话都能自动记忆。
特性
| 特性 | 说明 |
|---|---|
| 两半记忆模型 | 非结构化对话 + 结构化知识（pref/pers/skill/mission/conclusion） |
| 自动存取 | weave 自动注入上下文；透明代理下 Agent 零改动 |
| 主动检索 | Agent 引用记忆标题 → 自动展开为完整上下文 |
| 碎片隔离 | 未分类对话碎片不污染 weave 注入（tier2/nudge/[近期记忆] 只显示结构化记忆），碎片仍可显式搜索 |
| 候选提炼 | distill 将对话碎片压缩为带证据的候选卡 → 主 agent 审核 → 自动转正结构化记忆 |
| 反馈演化 | 记忆权重随使用自动演化（去重+0.05 / 引用+0.02 / 反馈+0.05） |
| 三层注入 | tier1 场景感知 + tier2 结构化记忆 + nudge 高优记忆 |
| 透明接入 | MCP 工具 / OpenAI 兼容代理 / Python API 三通道 |
架构
┌────────────────────────────── Agent 层 ──────────────────────────────┐
│ MCP 工具 (15个) 透明代理 (auto_context) Python API │
│ 决策权全部在主 agent：分类/拆解/教学/审核 —— 模块不越俎代庖 │
└──────────────────────────────┬──────────────────────────────────────┘
│
┌─────────────────────────── MemorySystem ────────────────────────────┐
│ 写链 (IngestPipeline) 读链 (Weaver 10区块) 检索 (RRF) │
│ │ ingest_dialogue │ tier1/tier2 │ BM25 ×2.5 │
│ │ dedup (语义合并) │ nudge/[历史结论] │ semantic ×0.5 │
│ │ 碎片 → default 分类 │ skill/mission/pref/pers │ temporal ×0.5 │
│ └ teach_skill (结构化) └ 树导航/[待审核提炼] └ │
├──────────────────────────────────────────────────────────────────────┤
│ 提炼层 (distill) 审核层 (pending_store) 存储层 │
│ 碎片→候选卡(带证据) accepted→自动转正 SQLite FTS5 │
│ offset 窗口遍历历史 rejected→丢弃 ChromaDB (1024-dim) │
│ 只压缩不断言(防捏造) skill 保留人工 teach SawRingBuffer │
│ evidence 必须真实存在 (source_urls 铁律) TreeManager │
└──────────────────────────────────────────────────────────────────────┘
数据流（闭环）
对话 → Ingestor → [SQLite 对话库] + [ChromaDB 向量库] + [记忆树]
│
├── 碎片 (default 分类) ──→ distill ──→ pending 候选
│ │ │
│ [待审核提炼]提醒 ├─ accepted → 自动转正
│ │ │ ↓
│ │ └─ rejected → 丢弃
│ │ 结构化记忆
│ │ (skill/pref/pers/
│ │ mission/conclusion)
└── 检索 (RRF k=60) ←──────────┘ ↓
↓ Weaver 组装 10 区块
注入 Agent 提示词 ←────────────────────┘
检索信号（RRF 融合）
| 信号 | 权重 | 来源 |
|---|---|---|
| BM25 全文 | 2.5 | SQLite FTS5，jieba 中文分词（中文主导） |
| 语义向量 | 0.5 | ChromaDB，bge-large-en-v1.5 (1024-dim)（英文主导） |
| 时间衰减 | 0.5 | weight × exp(-0.01 × hours) |
语言说明：检索是 RRF 融合——中文内容主要靠 BM25（jieba 对中文分词准确），英文内容主要靠语义向量（bge-large-en-v1.5 是英文专用模型）。两路互补：中文记忆靠 BM25 召回，英文记忆靠语义召回，均可在同库中检索。若需单模型统一中英语义检索，可替换为多语言嵌入模型（如 bge-m3，需重新嵌入历史记忆）。
15 个 MCP 工具
| 工具 | 用途 |
|---|---|
memory_weave |
注入分层记忆上下文（含自动存取） |
memory_search |
检索记忆（RRF 融合，碎片也可显式查） |
memory_ingest |
存储对话 |
memory_status |
健康检查 |
memory_feedback |
反馈权重演化 |
memory_classify |
分类对话（chat/skill/mission/pref/pers）——协议门控要求每轮调用 |
memory_check_skill |
检查技能是否已掌握（known/partial/unknown） |
memory_teach_skill |
教学写入（强制 source_urls 防捏造） |
memory_update_skill |
更新技能 |
memory_learning_queue |
查看学习队列（待学习/待拆解） |
memory_learning_mark |
关闭学习队列条目 |
memory_distill |
提炼对话碎片为候选卡（offset 遍历历史） |
memory_pending |
查看待审核候选 |
memory_pending_mark |
确认/拒绝候选（accepted 自动转正） |
memory_conclusions |
查询结论条目 |
安装
依赖
| 依赖 | 用途 | 必需 |
|---|---|---|
chromadb |
向量存储 | ✅ |
numpy |
向量运算 | ✅ |
jieba |
中文分词（BM25） | ✅ |
mcp |
MCP 服务器 | ✅（工具模式） |
click |
CLI | ✅ |
pydantic / tenacity / openai / requests |
LLM 调用 | ✅ |
python-dotenv |
环境变量 | ✅ |
onnxruntime + tokenizers |
ONNX 嵌入 | ⚠️ 可选（缺则 SHA-256 fallback，检索精度大幅下降） |
llama-cpp-python |
本地 LLM（查询改写/自动反馈） | ⚠️ 可选 |
# 基础安装
pip install -e . # 核心（含 mcp/jieba）
pip install -e ".[onnx]" # 加 ONNX 嵌入（推荐，检索精度关键）
pip install -e ".[full]" # 全部（ONNX + 本地 LLM）
# 或直接
pip install -r requirements.txt
下载嵌入模型
./download_model.sh # 下载 bge-large-en-v1.5 → models/
配置环境变量
复制 .env.example 为 .env 并填入：
IMPORTANCE_API_KEY=sk-xxx # LLM 分类/合成用
MEMORY_SKILL_DB_PATH=memory.db # 数据库路径
MEMORY_MODEL_PATH=models/bge-large-en-v1.5
LLM 模型配置（默认 DeepSeek V4 Flash，可换任意 OpenAI 兼容模型）
系统通过 OpenAI 兼容接口调用 LLM（用于记忆分类/合成/学习）。默认指向 DeepSeek V4 Flash，但你可以用任何 OpenAI 兼容模型/服务——只需改 3 个环境变量：
IMPORTANCE_API_BASE=https://api.deepseek.com/v1 # API 地址（OpenAI 兼容）
IMPORTANCE_API_KEY=sk-xxx # 你的 key
IMPORTANCE_MODEL=deepseek-v4-flash # 模型名
# 示例：换 OpenAI
# IMPORTANCE_API_BASE=https://api.openai.com/v1
# IMPORTANCE_MODEL=gpt-4o-mini
# 示例：换本地 vLLM / Ollama
# IMPORTANCE_API_BASE=http://127.0.0.1:8000/v1
# IMPORTANCE_MODEL=qwen2.5-7b-instruct
兼容任何提供
/v1/chat/completions的服务（OpenAI、Qwen、GLM、Moonshot、本地 vLLM 等）。默认值经过 DeepSeek V4 Flash 调优（如max_tokens预留），换模型后若分类/合成结果异常，可调整IMPORTANCE_*相关参数。
使用教程（从零到会用）
方式 A：让 AI 自己安装（最快，推荐）
把仓库 URL 直接交给你的 AI Agent，告诉它：
安装 https://github.com/baaai123/solo-memory 并接入我的 OpenCode。
步骤：
1. git clone https://github.com/baaai123/solo-memory
2. 运行 ./setup.sh（创建 venv + 安装依赖 + 配置嵌入模型）
3. 在 opencode.json 注册插件 opencode-auto-memory
4. 在 .env 里填我自己的 IMPORTANCE_API_KEY（用我自己的 LLM API key）
注：./setup.sh 一键完成环境搭建；opencode-auto-memory 插件会自动注入记忆
上下文并自动存储对话，Agent 无需手动调用记忆工具。
AI 会自主完成 clone → 环境搭建 → 插件注册。你只需在 .env 里填你自己的 LLM API key（用于记忆分类/合成/学习，走你自己的 API 账号计费）。
为什么可行：
setup.sh已封装环境搭建；opencode-auto-memory插件含首次运行自动引导（venv 缺失时自动创建）。唯一人肉步骤是提供 API key——任何记忆系统都无法替你保管私钥。
方式 B：手动安装（逐步）
下面以 OpenCode + 自动记忆插件 为例。其他 Agent（Claude Code / Cursor）流程相同，只是配置文件名不同。
第 1 步：下载并安装
git clone https://github.com/baaai123/solo-memory
cd solo-memory
# 一键环境搭建（创建 venv + 安装依赖 + 配置嵌入模型）
./setup.sh
# 或手动：
# python3 -m venv venv && source venv/bin/activate && pip install -e ".[onnx]"
# ./download_model.sh # bge-large-en-v1.5 → models/
第 2 步：配置密钥
cp .env.example .env
# 编辑 .env，填入 LLM API Key（用于记忆分类/合成/学习）
# IMPORTANCE_API_KEY=sk-xxx
第 3 步：把 SKILL.md 交给 Agent
SKILL.md 是 Agent 的记忆使用协议——把它放进你的 Agent 知识库，或在配置中引用：
- OpenCode: 放到项目根（Agent 自动读取
AGENTS.md/技能目录），或通过prompt_append注入协议 - Claude Code: 放入
CLAUDE.md引用，或作为 skill 文件 - Cursor: 放入
.cursor/rules/或项目 rules
协议核心（SKILL.md 全文见仓库）：
BEFORE responding: memory_weave(user_message) → 注入记忆上下文
AFTER 重要交互: memory_ingest(role, content) → 存入记忆
需要更多时: memory_search(query) → 深度检索
会话开始: memory_status → 健康检查
第 4 步：注册自动记忆插件
在 ~/.config/opencode/opencode.json 的 plugin 数组加入插件路径：
{
"plugin": [
"/abs/path/to/solo-memory/opencode-auto-memory"
]
}
插件会自动注入记忆上下文（chat.message hook）并自动存储对话（event hook）——Agent 无需手动调工具。
如需 MCP 工具方式（手动调用
memory_search等），见下方 快速开始 → 方式 2。
第 5 步：重启 Agent 并验证
重启 Agent 会话，让 Agent 调用记忆工具：
# Agent 应能看到并调用这些工具（15 个，核心 5 个）：
memory_search / memory_weave / memory_ingest / memory_status
memory_feedback / memory_classify / memory_teach_skill / memory_distill
快速验证：让 Agent 说一句重要信息（如"我偏好用 Python 写后端"），重启会话后再问它——如果它还记得，说明记忆已生效。
快速开始
方式 1：透明代理（Agent 零改动）
DEEPSEEK_API_KEY=sk-xxx ./start.sh --port 8888
# Agent 设置
export OPENAI_API_BASE=http://127.0.0.1:8888/v1
每次 chat 请求自动注入记忆、响应自动存回——Agent 完全不感知记忆系统。
方式 2：MCP 工具（OpenCode / Claude Code 等）
{
"mcp": {
"opencode-memory": {
"type": "local",
"command": ["/abs/path/venv/bin/python", "-m", "memory_skill.mcp_server"],
"environment": {
"MEMORY_SKILL_DB_PATH": "/abs/path/opencode_memory.db",
"IMPORTANCE_API_KEY": "sk-xxx"
}
}
}
}
Hermes Agent：也支持 MCP——在
mcp_servers配置段接入本 server 作为增强记忆（RRF 双信号检索 + 学习闭环）。配置见 docs/INTEGRATION.md。
方式 4：自动记忆插件（推荐，agent 零感知）
{
"plugin": ["/abs/path/to/solo-memory/opencode-auto-memory"]
}
chat.message 自动注入记忆、event 自动存储——agent 不需要记得调任何工具。详见 opencode-auto-memory/README.md。
方式 3：Python API
from memory_skill import MemorySkill, MemorySkillConfig, DialogueTurn
skill = MemorySkill(MemorySkillConfig(db_path="memory.db"))
# 存储对话
skill.ingest(DialogueTurn(role="user", content="我推荐使用 FastAPI", ...))
# 注入记忆上下文
ctx = skill.weave("FastAPI 是什么？")
print(ctx.to_prompt_block())
# 主动检索
skill.expand("FastAPI")
# 提炼候选（对话碎片 → 待审核候选）
skill.distill() # 或 MCP: memory_distill
# 查看/审核候选
skill.pending() # 或 MCP: memory_pending / memory_pending_mark
提炼与审核（主动学习 v2）
08-11 重写后，记忆模块为纯存储+检索，所有学习决策由主 agent 完成（ADR-0002）。主动学习闭环变为：
对话碎片 ── memory_distill ──→ 候选卡 (topic/summary/evidence/suggested)
│ evidence 必须引用真实对话 id（防捏造）
│ 只压缩不断言，suggested 只是建议
↓
pending_store (SQLite，不进检索库)
│
weave 注入 [待审核提炼] 提醒（每轮可见）
↓
主 agent 审核 (memory_pending)
│
┌────────────────────┼────────────────────┐
↓ ↓ ↓
accepted rejected skill 候选
(conclusion/pref/pers) → 丢弃 → 保留人工 teach
自动转正入库 (source_urls 铁律)
关键设计（防捏造防线）：
distill只总结已有对话，绝不新增事实；每条evidence必须是真实存在的 dialogue id，否则候选被拒收- 候选存独立
pending_store，不参与检索——审核前不会污染 weave - skill 候选不自动转正：
teach_skill强制source_urls非空（ADR-0002 防止主 agent 凭训练数据捏造） memory_distill支持offset/limit窗口遍历历史——旧记忆也能被提炼，不只是最新对话
文档
| 文档 | 内容 |
|---|---|
| SKILL.md | Agent 使用协议（分层 weave 注入 + 提炼闭环） |
| COMPREHENSIVE.md | 完整架构设计 |
| docs/INTEGRATION.md | OpenCode / Cursor / 代理接入指南 |
| docs/PROTOCOL.md | 记忆协议与工具规范 |
| CHANGELOG.md | 版本历史 |
性能
| 指标 | 数值 |
|---|---|
| 中文检索精度 | 93%（300 条记忆） |
| 检索延迟 | 35-100ms |
| 测试 | 115 快速/集成（25 network/slow 需真实 API key 时运行） |
License
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…