零依赖 · NODE ≥ 20 · 记忆层

Engram

仿人脑记忆引擎

把文本切成记忆、按语义召回、按「显著性 + 时间」淡忘、在夜里把零散情节归并成主题。它不是聊天机器人,也不是向量数据库——是可以塞进任何项目里的记忆层:会忘、会归并、会因为你反复想起而变得更牢。

0 依赖 · 无构建 308 个测试 BM25 + CJK 分词 平均召回 1.14ms
零依赖 海马体速记 皮层慢慢归纳
写下 → 想起 → 睡一觉 → 忘掉一点点
01 · 理念

为什么不是「又一个向量库」

先做实验、再定架构。三个「更像人脑」的方案都被实测打掉了,最后留下的是稀疏倒排 + 图:存储走 BM25,动力学只当调度器。

方案实测结果结论
LIF 脉冲网络 + STDP(N=1024)cue 35% 时额外点亮 976 个神经元,全网饱和打掉
E/I 平衡 + 全局抑制权重根本没学动(0.149 ≈ 初始值),召回只是输入直通打掉
稀疏 Hebbian + k-WTAtop1 0.0167 / top5 0.167,关键词基线 0.98 / 1.00打掉
VSA 稀疏码(D=4096)2000 条 top1 0.37 / top5 0.66,31.3 MB 内存不做主存储
BM25(自带 CJK 分词)2000 条带噪 top1 0.685 / top5 0.925,1.71ms采用

海马负责快速记下,皮层负责慢慢抽规律——这一层放在 consolidate.js(夜里归并)和 salience.js(显著性与遗忘曲线)里,而不是放在一个连权重都学不动的脉冲网络里。

红线一:索引不被召回污染

Rocchio 式 anchor 学习把 top1 从 0.67 打到 0.12;伪相关反馈打到 0.265。所以召回只读索引,写索引只从「记忆真值」出发。

红线二:语义 ≠ 情绪浓度

早期把两者放进同一个乘号,top1 掉到 0.238;改成「BM25 主分 + 同分时用显著性裁」后回到 0.611,与纯 BM25 完全一致——融合层零损耗。

02 · 生命周期

一条记忆的一生

从写进去到被忘掉,经过五个阶段。先跑 node examples/demo.mjs,一屏看完整个链条。

1

写入 · 编码

文本 → 记忆对象:simhash 判重、近重复合并、建倒排索引与图边。改写不算重复,叠词加标点才算。

汉明 ≤ 3/64 · LSH 4带
2

召回

同义扩展 → BM25 ∪ 图 1 跳 ∪ 同主题 → 覆盖率剪枝 → 排序 → 多样性过滤 → 按主题轮转。

MIN_COVERAGE 0.08
3

再巩固

置信够才动手:显著性 ×1.05、accessCount +1。宁可不动,也不让噪声污染显著性。

闸门 top1/top2 ≥ 1.6
4

睡眠 · tick

「过夜」:边衰减、逐条归簇成主题 schema、副本合并。零散情节在夜里长成一个主题。

边 ×0.995 · 合并 ≥0.6
5

归档

想不起来的先归档不参与默认召回,includeArchived 能看见、restore 能捞回,--hard 才真删。

strength < 0.12

注入预算

召回 10 条,塞进 prompt 的不能是 10 条。按簇折叠冗余、MMR 选条、按 token 精确累加,每条截断到 96 字——防止一条长记忆把整块注入堵成空字符串的「静默失忆」。

默认 90 token弱相关 ≤ 2 条

复习调度

遗忘曲线反解成「什么时候该复习」:I = S·ln(1/target),目标保留率 0.9(与 Anki 相同)。复习一次间隔就变长:0~6 次对应 3.16 → 7.6 天。

due 到期清单7 段经验计划

落盘与恢复

紧凑快照 + brotli:每条约 191 字节,仅为通用 JSON 的 5.4%。tmp + fsync + rename,rename 前先备份;主文件坏了自动回退 engram.bak.json。

魔数 ENGRAMZ1旧档免迁移
03 · 实验室

动手试一试:遗忘与召回

左边是引擎同款的艾宾浩斯曲线公式,右边是用网页简化模拟的召回管线。真实引擎的完整链路(同义扩展 / 覆盖率剪枝 / 主题轮转 / 置信闸门)比这里严谨得多。

遗忘曲线实验室

越常想起的事,忘得越慢。拖动「复习次数」,看稳定性 S 怎么把曲线拉平。

基础稳定性 τ0
30.0 天稳定性 S
36.8%30 天后保留率
3.16 天下次复习间隔(R=0.9)

R(t) = e^(−t/S) · S = τ0 · (1 + 0.5 · log2(1 + n)) · I = S · ln(1/0.9)

τ0 为什么是 30 天不是 7 天:7 天时一条日常记忆第 20 天强度只剩 0.03,等于「说过的话三周后彻底想不起来」——对人类来说那不叫记忆。

写一条,再想起来

简化演示:网页内用单字 + bigram 重叠与覆盖率闸门近似 BM25 召回,非引擎本体。

    04 · 实测

    数字不会说谎

    以下全部来自本机实测:tools/bench.mjs 与 50 个诊断探针,每一条优化都对应一次真实排查。

    47,348 条/秒写入吞吐5000 条 105.6ms
    1.14 ms平均召回p50 1.21 · p99 2.53
    2 ms召回 p956600 次查询
    191 B/条落盘体积紧凑快照 + brotli

    三条线终检(probe_final · 2000 条)

    指标改造前现在
    落盘字节 / 每条735191
    每次注入 token11774.5
    注入内残余冗余0.9640.246
    多主题双命中0.31.0
    双主题 190 对 both168/190190/190
    换说法召回3/109/10

    准确率从 0.3 跳到 1.0 不是打分变了,是同簇副本没了:改造前 20 个主题会造出 120 个中心几乎一样的 schema,一起占满召回名额。

    规模曲线(probe_scale)

    N写入 5000 条tick召回 avg / p95堆内存
    5,00095 ms76 ms1.93 / 2.73 ms50 MB
    20,000250 ms342 ms5.09 / 7.35 ms158 MB

    三个关键优化

    minIdf 截断:丢掉「第」「条」这类 idf≈0 却遍历全库的词,但永远保留 idf 最高的一个。
    惰性 allow 谓词:不再每次召回全库建 Set,4 万条时召回直接腰斩。
    schema 倒排预筛:只跟共享核心 token 的 schema 精算,否则一次 tick 要 5 秒。

    05 · 接入

    三种方式,塞进任何项目

    没有构建步骤、没有 node_modules、没有配置文件。数据目录默认 ./data,用 ENGRAM_DATA_DIR 覆盖。

    import { Engram, memory } from 'engram';
    
    const engine = memory();                       // 纯内存,不落盘(测试用)
    const e2 = new Engram({ maxMemories: 50000 }); // 自定义容量
    
    engine.write('今天加班到很晚,特别累,这个月第三次了', { tags: ['工作'] });
    engine.write('周末去爬山,山顶风很大');
    
    const r = engine.recall('加班 累', { limit: 3 });
    console.log(r.items.map((m) => m.text));

    adapters/prompt

    塞进 system prompt:buildMemoryBlock 默认最多 5 条 / 900 字符,头部「## 相关记忆」。分数低于 top1 的 50% 会标注(弱相关)——弱相关命中不能被模型当成事实。

    adapters/messages

    从对话历史里捞:writeMessages 跳过 system / tool / function 角色;minChars 按正文算,不算「我:嗯」这种前缀。单条消息可自带 tags,合并去重最多 16 个。

    adapters/qiyu

    和栖屿的记忆互通:结构化条目 {kind:'like', value:'下雨天'} 写入时拼成自由文本并把原始字段塞进 meta,取出时还原——双向保真,升级不丢结构。

    HTTP API 速查

    GET /healthGET /statsGET /metrics(Prometheus) POST /writePOST /write-batch(≤500)POST /recall GET /memory/:id?trace=1DELETE /memory/:id(软删,?hard=1 真删) POST /tickPOST /touchPOST /restore GET /due?target=0.9GET /curve/:id?days=0,1,7,30 GET /exportPOST /import

    设了 ENGRAM_TOKEN 后所有路径都要 Bearer;探针没凭据时用 ENGRAM_OPEN_HEALTH=1 放行 /health 与 /metrics。npm test 跑 308 个测试,5 秒内完成,不依赖网络。

    06 · 设计红线

    改代码前,先看这段

    README 里一共 21 条红线,每一条都是实测踩坑换来的。挑 6 条贴在这里:

    1. 01索引里永远有每一条记忆。归档、软删都不许删索引——可见性由召回时的 allow 谓词决定,否则 includeArchived 永远查不到东西。
    2. 02召回不写索引。再巩固只改显著性 / accessCount / 图边。Rocchio 与 PRF 的失败是硬证据。
    3. 05写入必须是 O(1)。相似边只跟最近 200 条比、判重只比同带。任何「全库扫」的写法都会在 2 万条时爆炸。
    4. 16注入预算按 token 算,且每条要截断。中文 1 字 ≈ 1 token;不截断的话一条 262 字的记忆会把整块注入堵成空字符串——召回成功、注入为空,等于静默失忆。
    5. 17S 必须随 accessCount 变。写成常量就没有间隔重复,「越复习越牢」是假的。有测试守着「复用 6 次后间隔翻倍以上」。
    6. 21双主题按主题轮转取条,弱组覆盖了没人回答的词就破格。「猫 和 外卖」的分数差来自 tokenizer 给多字词的额外份数,调阈值永远救不回来。
    07 · 已知边界

    它不做什么

    诚实比全能重要。这些边界写在 README 里,接入前请看清:

    • 没有语义向量。同义扩展靠 60 组人工词表:「累 ↔ 辛苦 ↔ 疲惫」认得,「报销单被驳回 ↔ 钱没批下来」认不得。架构留了 embedding 的位置,但默认不启用——不塞一个测不出提升的向量通道。词表可自己补:addSynonymGroup(['报销单','单子','票据'])。
    • 中英混排分词是启发式。CJK 单字 + bigram、拉丁整词小写,专有名词靠 bigram 召回,不如词典分词器精准。
    • 单进程。数据在内存、落盘整文件写;多实例请各用各的数据目录。
    • 20 万条以上没测过。瓶颈在 tick 的 pending 归簇与 schema 上限 512,两者都可调常量。
    • 注入 token 是估算值。CJK 按 1 字 1 token 算,真实 tokenizer 约 1–1.5 字/token,要精确就把预算往低调一档。
    • 不是完整的 SM-2 / FSRS。会算到期清单,但「答错了要重来」的反馈得由调用方写回:reinforce() 表示答对了,forget() 表示答错了。
    ↑ 顶部