memory-vault

English

Memory Vault

面向编码代理的跨会话持久记忆插件：把对话中沉淀的经验、决策、偏好与踩坑记录保存到本地，并在未来的会话中按需召回。

• 存储：SQLite 本地数据库（唯一数据源），记录、标签、倒排词表全部落盘
• 检索：关键词（BM25）与语义向量（USearch，可用时）双通道融合排序，支持时间衰减
• 整理：写入时自动去重（正文精确去重 + 语义近似去重，合并/跳过两种策略）；tidy 一键把相似记录折叠为摘要，防止记忆膨胀
• 界面：内置 Web 查看界面（纯标准库实现），浏览、检索、新增、删除、整理
• 兼容：通用 markdown 记忆格式导入导出，支持 frontmatter 与按二级标题拆分
• 零依赖可运行：默认本地哈希嵌入器离线可用、确定性跨会话一致；可选接入 sentence-transformers 或任意 OpenAI 兼容嵌入 API；向量检索自动降级（USearch → numpy → 纯 Python）

快速开始

无需安装依赖，Python ≥ 3.9 即可：

# 存入一条记忆
python -m memory_vault put "项目架构" "后端采用微服务，服务间通过消息队列通信"

# 混合检索
python -m memory_vault ask "微服务架构"

# 从 markdown 目录批量导入
python -m memory_vault import ./notes --split

# 压缩整理
python -m memory_vault tidy

# 启动 Web 查看界面
python -m memory_vault serve
# 浏览器打开 http://127.0.0.1:8988

# 以 MCP 服务运行（供插件化 harness 加载）
python -m memory_vault mcp

数据默认存放在 ~/.memory-vault/（vault.sqlite3 与可选 config.json）。也可通过 --vault <目录> 或环境变量 VAULT_DIR 指定其他位置。

接入 dsh（插件化 harness）

在 DSH 中安装

dsh plugin --profile demo add github:JohnXu22786/memory-vault

仓库同时还带一份 dsh.bundle（package.json + cordis.patch.yml + index.js）。 安装后它会铺下一行 Cordis 插件注册，由 Node 桥接器在包目录内驱动 Python CLI， 把命令行能力以 dsh 工具形式暴露：vault_put / vault_ask / vault_take / vault_list / vault_drop / vault_tidy / vault_stats / vault_ingest。 加载期无需任何 npm 依赖；要求 PATH 上有 Python ≥ 3.9（可用环境变量 DSH_MV_PYTHON 指定解释器）。若 Python 缺失或包无法导入，桥接器会在启动时打印 清晰错误而不是崩溃。需要完整写入参数（tags / weight / source）时请走下面的 MCP 服务。

插件根目录包含 manifest.json，harness 按以下约定加载：

接口	启动方式	用途
MCP 工具（推荐）	python -m memory_vault mcp（stdio 传输）	向代理暴露 vault_put / vault_ask 等 8 个工具，会话内直接存取记忆
CLI	python -m memory_vault <命令>	脚本化、定时整理、批处理导入导出
Web	python -m memory_vault serve	人工浏览与维护界面
技能	读取 SKILL.md	指导代理何时写入、如何检索的说明文本

典型 harness 配置示意（MCP 风格）：

{
  "mcpServers": {
    "memory-vault": {
      "command": ["python", "-m", "memory_vault", "mcp"],
      "env": { "VAULT_DIR": "~/.memory-vault" }
    }
  }
}

harness 启动该进程后，先发 initialize 握手，再通过 tools/list 发现工具、tools/call 调用。协议为 stdio 上的 newline-delimited JSON-RPC 2.0（MCP 标准传输），无第三方依赖。

MCP 工具一览

工具	说明
vault_put	存入记录（自动去重；返回 action: new/merged/skipped）
vault_ask	混合检索，返回 id/title/score/kw/sem/updated_at
vault_take	按 id 取完整内容
vault_list	最近记录列表
vault_drop	按 id 删除
vault_tidy	压缩整理（相似记录折叠为摘要）
vault_stats	存储统计（数量、向量后端、嵌入配置）
vault_ingest	从 markdown 文件/目录批量导入

使用建议

• 存什么：项目决策与原因、踩过的坑、用户偏好、常用命令与约定、实验结论
• 检索时机：新会话开始时、接到任务但上下文不足时、提到历史话题时
• 不必过度存储：稳定的工程规则放入 AGENTS.md 类文档；记忆适合沉淀「从真实工作中长出来的上下文」

配置

配置文件默认 <数据目录>/config.json（JSON），也支持 VAULT_* 环境变量覆盖；命令行参数优先级最高。完整示例见 config.example.json。

节	键	默认	说明
database	dir	~/.memory-vault	数据目录
embedding	provider	local	local（内置哈希）/ sentence（sentence-transformers）/ api（OpenAI 兼容）
embedding	model	按 provider	sentence 默认 all-MiniLM-L6-v2；api 默认 text-embedding-3-small
embedding	dims	128	local 嵌入维度
embedding	api_url / api_key / api_model	空	api 提供方端点；密钥支持 env://VAR、file:///path 写法
search	keyword_weight / semantic_weight	0.4 / 0.6	双通道融合权重（自动钳制 0~1）
search	recency_days	180	时间衰减半衰期（天），0 关闭
search	top_k	8	默认返回条数
curation	dedup_threshold	0.92	写入去重相似度阈值
curation	dedup_mode	merge	merge 并入已有记录 / skip 保留原记录
curation	cluster_threshold	0.78	tidy 聚类阈值
curation	min_cluster	2	簇最小规模
curation	digest_member_chars	600	摘要中每条成员记录保留的字符数
web	host / port	127.0.0.1 / 8988	Web 界面监听地址
web	token	空	设置后所有 /api/* 需携带 Authorization: Bearer <token>（界面首次请求会提示输入并记住；也支持 ?token= 查询参数）

环境变量：VAULT_DIR、VAULT_CONFIG、VAULT_EMBED_PROVIDER、VAULT_EMBED_MODEL、VAULT_EMBED_DIMS、VAULT_EMBED_API_URL、VAULT_EMBED_API_KEY、VAULT_EMBED_API_MODEL、VAULT_KW_WEIGHT、VAULT_SEM_WEIGHT、VAULT_RECENCY_DAYS、VAULT_TOP_K、VAULT_DEDUP_THRESHOLD、VAULT_DEDUP_MODE、VAULT_CLUSTER_THRESHOLD、VAULT_MIN_CLUSTER、VAULT_DIGEST_MEMBER_CHARS、VAULT_WEB_HOST、VAULT_WEB_PORT、VAULT_WEB_TOKEN。

嵌入提供方

provider	前置条件	特点
local（默认）	无	零依赖、离线、确定性；语义能力有限，适合起步与测试
sentence	pip install sentence-transformers	本地真实语义模型，效果最好、完全离线
api	可访问的 OpenAI 兼容端点	配置 api_url + api_key（+ api_model），例如 https://api.openai.com/v1、本地 Ollama 兼容网关等

更换嵌入配置导致维度变化时，插件会在下次使用时自动对存量记录重新嵌入。

向量检索后端

优先使用 USearch（pip install usearch）近似最近邻；未安装时自动降级为 numpy 精确扫描，再降级为纯 Python 扫描。SQLite 始终是唯一数据源，内存索引每次启动由库重建。

Markdown 兼容

• 导入：import <文件或目录> [--split]。识别 YAML 风格 frontmatter（title/tags/weight/created/updated）、# 一级标题（作标题并从正文剥离，兼容 CRLF 换行）；--split 按 ## 二级标题 拆分为多条记录
• 导出：export <目录>，每条记录一个 .md 文件（frontmatter 含 id/时间/标签），可回读
• 边界说明：记录 id 始终由系统生成，frontmatter 中的 id 仅作导出信息，导入时忽略；标签请勿包含逗号；正文首尾空白在导出时会修剪
• 适合与现有 markdown 笔记库互通

命令行速查

python -m memory_vault init                    # 初始化数据目录
python -m memory_vault put "标题" "正文"        # 存入（正文可省略，此时读标准输入）
echo "正文" | python -m memory_vault put "标题"
python -m memory_vault ask "查询词" -k 5        # 混合检索
python -m memory_vault get <id>                 # 查看单条
python -m memory_vault list -n 20               # 最近列表
python -m memory_vault drop <id>                # 删除
python -m memory_vault tidy                     # 压缩整理
python -m memory_vault import ./notes --split   # 导入 markdown
python -m memory_vault export ./backup          # 导出 markdown
python -m memory_vault info                     # 统计
python -m memory_vault serve                    # Web 界面
python -m memory_vault mcp                      # MCP 服务

所有命令支持 --vault <目录>、--config <文件> 与 --json（机器可读输出）。--vault/--config 为全局选项，须置于子命令之前（如 python -m memory_vault --vault ~/mv put ...）。

安全提示：Web 界面默认只监听 127.0.0.1。如需绑定到非回环地址（如 0.0.0.0），务必同时设置 web.token；界面已内置跨源写入防护（强制 JSON Content-Type + Origin 校验）与请求超时/并发上限。

Web API

端点	方法	说明
/	GET	查看界面
/api/stats	GET	统计
/api/list?limit=&offset=	GET	最近记录
/api/query?q=&k=	GET	混合检索
/api/put	POST	{title, body, tags, source?, weight?}
/api/delete	POST	{id}
/api/tidy	POST	压缩整理
/api/ingest	POST	{path, split?}

架构

memory_vault/
├── __main__.py / cli.py   命令行入口（12 个子命令）
├── config.py              配置加载（默认值 <- 文件 <- 环境变量 <- 参数）
├── vault.py               门面：协调存储/嵌入/索引/去重/压缩（进程内锁保证多线程一致）
├── store.py               SQLite 持久层：记录 CRUD、倒排词表、BM25 打分
├── vectors.py             向量索引：USearch -> numpy -> 纯 Python 三级降级
├── embedders.py           嵌入器工厂：local / sentence / api
├── ranking.py             融合排序：双通道 min-max 归一化 + 时间衰减
├── curation.py            去重决策（merge/skip）与摘要构建
├── markdown_io.py         markdown 导入导出（frontmatter / 拆分）
├── webapp.py              内置 Web 界面（http.server + 单页前端）
└── mcp_server.py          MCP stdio 服务（newline-delimited JSON-RPC）

写入流程：put → 正文精确去重（checksum）→ 语义近似去重（向量检索 top-k）→ 入库 + 更新索引。检索流程：ask → BM25 关键词得分 + 语义得分 → min-max 归一化加权融合 → 时间衰减 → 排序输出。

开发与测试

python -m unittest discover -s tests -v   # 129 项测试：存储/检索/去重/压缩/markdown/CLI/MCP/Web/配置
pip install -e .                          # 可选：安装为命令 `vault`

可选依赖：pip install usearch（向量加速）、pip install sentence-transformers（本地语义嵌入）。

许可

MIT