Skip to content

Releases

v0.2.7 App 窗口版 + UI 美化

Choose a tag to compare

@yuannuo233 yuannuo233 released this 21 Nov 05:02

Membrane v0.2.7 - App 窗口版 + UI 美化

新增:像原生应用一样用

零黑窗启动器(启动器.vbs)
双击桌面快捷方式,全程不出现任何命令行黑窗:

  1. 服务已在跑 -> 直接复用,不重复启动
  2. 否则隐藏启动 node serve
  3. 等服务写出带 token 的控制台地址
  4. 用 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 安全审查修复

Choose a tag to compare

@yuannuo233 yuannuo233 released this 19 Nov 16:55

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 向量桶

Choose a tag to compare

@yuannuo233 yuannuo233 released this 19 Nov 12:28

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 七条修复

Choose a tag to compare

@yuannuo233 yuannuo233 released this 19 Nov 11:46

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 处硬编码全部改为 import
  • noGraph 改走 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 双语控制台 + 零依赖澄清

Choose a tag to compare

@yuannuo233 yuannuo233 released this 19 Nov 09:04

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 向量检索 + 图检索

Choose a tag to compare

@yuannuo233 yuannuo233 released this 19 Nov 08:44

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)。