Repository navigation
Releases
v0.2.7 App 窗口版 + UI 美化
Membrane v0.2.7 - App 窗口版 + UI 美化
新增:像原生应用一样用
零黑窗启动器(启动器.vbs)
双击桌面快捷方式,全程不出现任何命令行黑窗:
- 服务已在跑 -> 直接复用,不重复启动
- 否则隐藏启动 node serve
- 等服务写出带 token 的控制台地址
- 用 Edge --app 模式打开无边框独立窗口,看起来就是个桌面应用
配套 停止服务.vbs 一键关闭。传统终端用户仍可用 启动控制台.bat。
吉祥物机制(版权双保险)
- 随仓库发布一只原创「记忆小水母」SVG(Membrane = 膜),MIT 授权
- 想换成自己喜欢的图:放一张 web/assets/mascot-local.png 即可覆盖,该文件被 .gitignore 忽略,不会进仓库
- 应用窗口 favicon 已换成 membrane 图标
新增:可选 LLM 图抽取
原来只有 6 类中文句式的规则抽取。现在多了 src/graph-extract-llm.ts:配了 LLM 就用模型抽实体关系,没配则回退规则抽取。零依赖底线不变。
新增:向量索引适配层
src/vector-index.ts 定义统一接口,另有两个可选实现:
- vector-index-hnsw.ts(HNSW 图索引)
- vector-index-sqlite-vec.ts(sqlite-vec 扩展)
都是可选的:不装这些依赖时,默认仍走零依赖 LSH 桶索引。想要更快可自行接入。
修复(找 bug 轮)
- mem0 兼容路径双斜杠(/v1/memories//)现在也能正确路由
- /api/health 真正免鉴权落地(App 启动器靠它判断服务状态)
- getMany 分批查询,避免超大 IN 列表
- add 全流程事务化
- link 幂等:重复建立同一关系不再产生重复边
性能
百万级压测数据与两处性能修复见 bench/。临时压测库已清理,只保留结果 JSON。
安装
尚未发布到 npm。
git clone https://github.com/yuannuo233/membrane-memory.git
cd membrane-memory && npm install && npm test && npm run build
然后双击 启动器.vbs(建议先建桌面快捷方式)。需要 Node >= 24。
或下载下方 tgz。
测试:249 个(19 个测试文件),CI 全绿。
v0.2.6 安全审查修复
Membrane v0.2.6 - 安全审查修复
安全修复(两项可被网页 drive-by 利用)
1. 数据接口强制令牌 + CORS 默认零放行
配了 MEMBRANE_TOKEN 后,浏览器仍可从任意恶意网页跨域打到本地 127.0.0.1:8317 读写记忆库。现在所有 /api/* /v1/* 强制要求令牌,且默认不返回 Access-Control-Allow-Origin。静态控制台仍可匿名打开但不返回数据。
2. IPv6 绑定修复
MEMBRANE_HOST=::1 或 :: 时走的是 IPv4 判断逻辑,"绑非本机地址必须设令牌"被绕过。现按地址族分别判断。
其它修复
- embed-purge:批量清理失效向量(换 embedding 模型后旧向量会污染检索)
- 端口占用提示:EADDRINUSE 时给中文提示而非原始 Node 错误
- MCP 响应串行化:并发 tools/call 原可能交错写 stdout 破坏 JSON-RPC 协议
- 证据计数按候选查询:不再扫全表 GROUP BY
文档与工程一致性
- 一键安装.bat 是 v0.1 老文件:写死 E:[路径]、不显示版本、调废弃命令。三个启动脚本全部重写为 %~dp0 自定位 + 运行时读版本
- 找出根因:git ls-files 默认转义中文路径,导致所有中文文件(安装说明.md、使用场景.md、适配配置/*、三个 .bat)从未被任何一致性检查扫到过。这才是"代码 0.2.6 文档却留 0.2.5/0.1.0"一直查不出的原因
- 新增 scripts/scan-stale-versions.mjs:逐文件扫所有 x.y.z,非当前版本且不在历史白名单即报错
安装
尚未发布到 npm。
git clone https://github.com/yuannuo233/membrane-memory.git
cd membrane-memory && npm install && npm test && npm run build
node dist/cli.js doctor
或下载下方 tgz。需要 Node >= 24。
测试:227 个(17 个测试文件),CI 全绿。
v0.2.5 十万级压测 + LSH 向量桶
Membrane v0.2.5 — 10 万级压测 + 零依赖 LSH 向量桶
本版把向量检索从"能跑"推到"十万条可用",并且没有引入任何新依赖。
核心:LSH 桶索引
原来向量检索是全表线性扫——10 万条 × 1536 维,每次查询要把所有向量读进内存算余弦。
现在用局部敏感哈希(LSH)分桶:先用随机超平面把向量分到桶里,查询时只扫同一桶的向量。
实测对比(10 万条,1536 维,同一库同一查询):
| 方式 | 向量检索耗时 | 相对 |
|---|---|---|
| 精确全扫 | 10,912 ms | 1× |
| LSH 分桶 | 298 ms | 36.6× 更快 |
两种方式 top1Hit 都是 true,即结果一致,只是快了 36 倍。
完整的十万级压测数据
| 规模 | 检索方式 | FTS 全文 | 向量 | 混合 |
|---|---|---|---|---|
| 1 万 | LSH | 11.4 ms | 37.3 ms | 54.1 ms |
| 10 万 | 精确 | 128.0 ms | 10,912 ms | 10,942 ms |
| 10 万 | LSH | 125.5 ms | 297.6 ms | 463.0 ms |
内存占用(RSS):1 万条 71 MB,10 万条 91 MB —— 不随数据量线性膨胀。
为什么不用 sqlite-vec / hnswlib / faiss
这三个都能让向量检索更快,但都要编译原生模块,会让 npm install 失败率飙升,违背项目"装完就能用"的底线。
LSH 是纯 JS 实现,零依赖,代价是理论上可能漏召回(分桶有概率把相近向量分到不同桶)。实测 top1 命中一致,但这个风险实存在,已写进 README 的已知局限。
可复现
压测脚本随包发布:
node scripts/bench-scale.mjs --count 100000 --dim 1536
原始结果在 bench/results-*.json,自己跑一遍就能对上数字。
安装
尚未发布到 npm。
git clone https://github.com/yuannuo233/membrane-memory.git
cd membrane-memory && npm install && npm test && npm run build
或下载下方 tgz。需要 Node ≥ 24。
测试:222 个,CI 全绿。
v0.2.4 外部 review 七条修复
Membrane v0.2.4
外部 review 对 main 做了全量静态审查,指出 7 条问题。逐条复现后确认全部属实,本版全部修复。
⚠️ 三处破坏性变更
| 变更 | 影响 |
|---|---|
公开 API containment → tokenOverlap |
直接 import 该函数的代码需要改名 |
冲突判定 |A∩B|/min → |A∩B|/max |
短记忆不再以 1.0 相似度取代完整事实 |
REST /api/recall 默认 full → brief |
不传 detail 的调用方字段变少(省 token) |
公式变化的影响举例:"北京市" 对 "用户住在北京市海淀区" 从 1.0 降到约 0.22,不再误取代完整事实;同长度换地名仍保持 0.6,可正常取代。
P0 修复
1. 配 token 后 Web 控制台打不开
静态页与 /api/* 分离鉴权,控制台首屏不再被 401 拦。支持 Authorization: Bearer 与 ?token=;浏览器用 ?token= 打开后存 localStorage 并从地址栏抹掉。补 OPTIONS 204 预检与 CORS 头。
2. 中文标点把分词劈成两半
。 , 《》 曾进入 bigram 并切断连续文本。现在分词前统一剥离标点。
3. 短记忆误杀长记忆
见上方公式变更。
P1 / P2 修复
- CLI 布尔 flag 不再吞下一个位置参数
src/version.ts成为版本唯一事实源,4 处硬编码全部改为 importnoGraph改走asBoolean,字符串"true"生效- 导入校验:
normalizeImportRecord校验 kind/confidence/时间戳/namespace/tags;向量含 NaN/Infinity/字符串时整条跳过
安装
尚未发布到 npm。
git clone https://github.com/yuannuo233/membrane-memory.git
cd membrane-memory && npm install && npm test && npm run build
node dist/cli.js doctor
或下载下方 tgz。需要 Node ≥ 24。
测试:221 个(16 个文件),CI 全绿。
v0.2.3 双语控制台 + 零依赖澄清
Membrane v0.2.3
本版更新
双语 Web 控制台
- 中文 / English 可切换,静态页面与动态数据同步切换,刷新后保持
- 支持
data-i18n/data-i18n-ph/data-i18n-title三类本地化属性 - Ops 面板、召回结果、审计链、弹窗全部跟随语言
澄清"零依赖"的准确含义
有人指出"还要依赖浏览器,就这还敢说零依赖"——这个批评成立。原说法只讲了安装依赖数,没讲清用法差异。
| 用法 | 需要浏览器 |
|---|---|
CLI(add / search / stats) |
不需要 |
| MCP(接 Claude Code / Cursor 等) | 不需要 |
| SDK(写代码调用) | 不需要 |
serve(Web 控制台,可选) |
需要 |
零依赖 = 安装时不下载第三方 npm 包(除 ulid)、无需编译原生模块。不等于所有用法都不碰浏览器。
新增不依赖浏览器的用法
命令行.bat:打开就是提示符,直接输入命令,全程不启动浏览器- 两个
.bat都改为%~dp0自定位,换机器也能用
应用图标
assets/membrane.ico:七种尺寸(16–256),双脑半球 + 脑回 + 记忆节点网
安装
尚未发布到 npm。两种方式:
git clone https://github.com/yuannuo233/membrane-memory.git
cd membrane-memory && npm install && npm test && npm run build
node dist/cli.js doctor
或下载下方 tgz。
需要 Node ≥ 24。
可复现自检
node dist/cli.js doctor
测试:212 个,CI 全绿(Ubuntu + Windows × Node 24/25)。
v0.2.2 向量检索 + 图检索
Membrane v0.2.2
Temporal-aware, local-first, explainable memory engine for AI agents.
Zero runtime dependencies (only ulid), single SQLite file, works fully offline.
本版核心更新
向量检索从"只留接口"变成真能用
add({vec})写入时同事务落库;addAsync自动调/embeddings;backfillEmbeddings回填老库- 分批扫描(keyset,默认 512/批),内存占用不随库膨胀
- 维度守卫:混用两套 embedding 模型时跳过并提示,绝不阻断写入;算向量失败也不丢记忆
图检索从零实现
entities/relations/memory_entities三表,schema 1→2 加法式迁移,老库不丢数据- 唯一键用
(namespace, name)而非(namespace, name, type),避免同名实体被劈成两个节点 - 手动标注优先;否则按 6 类中文句式抽取,宁缺毋滥
relations(a, b?, {maxHops, asOf}):一跳邻居 / 两跳路径 / 整句自动认实体- 关系跟随记忆取代与遗忘关闭
valid_to(不删行,asOf仍可查)
记忆可编辑
engine.update/updateAsync:版本化编辑,新版本取代旧版本,历史/证据/关系保留
控制台重做
- 三模式 + 运维日志与诊断后台
安装
尚未发布到 npm。两种方式:
从源码构建(推荐,能顺带验证测试)
git clone https://github.com/yuannuo233/membrane-memory.git
cd membrane-memory
npm install
npm test # 应显示 212 passed
npm run build
node dist/cli.js doctor
或下载下方 tgz
npm install -g ./membrane-memory-0.2.2.tgz
需要 Node ≥ 24(node:sqlite 在 22/23 需 flag,24 起默认启用)。
已知局限
无同义词检索(需自算 embedding)、只验证过中英文分词、无真实用户验证。
完整清单见 README 的「已知局限」。
可复现自检
node dist/cli.js doctor
测试:212 个,CI 全绿(Ubuntu + Windows × Node 24/25)。