用途:easymem 让项目维护一份由智能体编写的 markdown 维基,用编译后的知识代替反复阅读源码。核心主张是“搜索先于 grep”:命中可省去阅读文件的时间,未命中也只花一秒。
主要能力:
- 搜索:基于 BM25 对全部页面检索,随后沿 [[wikilinks]] 扩展一跳或多跳。即使某页不含你的关键词,只要被匹配页面链接到,也能返回。可用 --limit 控制结果数量,--hop 控制链接扩展深度(0 为仅直接命中,2 可获取答案周边上下文)。
- 结果解读:hop 为 0 是直接文本命中;hop≥1 是经由链接到达的上下文,未必直接回答问题;via 显示经由哪个页面到达;score 仅在同一结果内相对比较,没有绝对阈值;snippet 是页面一句话描述,只够判断是否打开,不足以据此作答;related 给出图谱中的邻近页面,便于继续阅读。
- 读取与管理:read 打印页面并在 frontmatter 中显示来源;list 列出全部页面及其来源;graph 显示可作起点的枢纽页面和需要修复的孤立页面。
- lint 检查:outdated(来源内容哈希变化)、staleSources(来源已不存在)、danglingLinks(链接无对应页面)、orphans(无人链接)、missingSources/untracked(页面无法校验或未跟踪来源)、missingLinks(正文提到其他页面却未加链接)、reviewForContradiction(同源页面,仅作候选,需先都读完再改)。建议先看 summary 的分类计数。
- 写入:先运行 guide 了解页面格式、类型列表、链接约定和更新协议。write 支持 --type、--title、--description、--sources、--body-file(多行 markdown 建议用文件而非内联)。只写“下个月仍成立且重新推导成本高”的知识,不写当日 bug 或 diff。对已存在的同名同类型页面,write 会直接覆盖(包括人工编辑过的页面),应先 read 再合并。
- 构建:pending 接收路径通配,返回 to_ingest(新增或变更)、skipped(已处理且未变,勿重读)、deleted(磁盘已删,对应页面过期)。逐个阅读 to_ingest 后按主题写页,一个源文件可能产生多页;最后用 reindex --ingested 更新索引,否则新页面不会被搜索到。
使用方式:可通过 npx easymem 各子命令调用;若希望索引在会话间保持温热,可作为 MCP 服务器接入,在 .mcp.json 中加入 {"mcpServers":{"easymem":{"command":"npx","args":["-y","easymem"]}}} 并重启,然后直接调用 wiki_search、wiki_read、wiki_write 等工具。npx 每次重建索引,约一千页需 200ms 左右。
存储位置:默认 .easymem/wiki/,与代码同处,纯 markdown 可提交、阅读、手改;.easymem/.state/ 是缓存,应加入 .gitignore。可用 --dir 或 EASYMEM_DIR 改变位置。
适用场景:源码庞大、分散或阅读成本高的项目;需要让智能体跨会话复用项目理解的场景。页面与代码冲突时以代码为准,说明并修正页面。项目只有二十来个整洁文件时,维基反而是负担,直接用 grep 更快。不要翻译,保持源码语言;不要写来源未说的内容。