memex

memex

让 Claude 更了解你。

npm install -g @evan-moon/memex

让 Claude 更了解你。

本地优先的第二大脑，通过 MCP 连接 Claude。笔记以纯 Markdown 格式存储，并使用本地 ML 模型建立索引，完全离线运行，无需 API 密钥，数据不会离开你的设备。

---

问题

Claude 的聪明程度取决于对话中包含的信息。你的决定、背景和想法，除非每次都粘贴进去，否则它都看不到。

You:    What did we decide about the auth approach last sprint?
Claude: I don't have context from previous conversations...

解决方案

You:    What did we decide about the auth approach last sprint?

Claude: [memex · search_notes · "auth approach decision"]

        Found 2 notes:

        Auth Architecture Decision  Apr 14  #auth #backend
        ─────────────────────────────────────────────────────
        Chose JWT + refresh tokens over sessions. Rationale:
        stateless design fits horizontal scaling plan.

        Based on your April 14th note: you went with JWT +
        refresh tokens. Tom also flagged keeping auth decoupled
        from payment logic, separate bounded contexts.

Claude 会在回答前搜索你的笔记，并在每次对话结束时自动保存有用信息，无需你提出要求。

---

安装

npm install -g @evan-moon/memex

连接你的应用：

memex mcp install

这会将 memex 注册到这台设备上的所有 MCP 客户端——Claude、Claude Code、Codex、Cursor——方法是分别写入各自的配置文件。之后请重启这些客户端。

就这么简单。首次运行时，嵌入模型（约 450MB）会下载到 ~/.memex/models/，只需下载一次。

自动回忆（可选）

memex recall install

这会将检索从 Claude 必须决定是否执行的操作，变成自动发生的过程。你输入的每条提示词都会与笔记进行语义搜索，并在 Claude 回答前将排名最高的 3 个标题作为上下文注入——方式与原生记忆相同。如果标题看起来相关，Claude 随后会通过 get_note 获取完整笔记。

后台守护进程会让嵌入模型保持就绪（~/.memex/recall.sock），因此查询耗时约为 30ms，而不是冷启动 CLI 搜索加载模型所需的约 1.5 秒。闲置 2 小时后会自动退出。

开销：模型就绪时常驻内存约 200MB，每条提示词最多增加 3 个笔记标题的上下文。使用 memex recall uninstall 移除。

---

功能

• 语义搜索，按含义而非仅按关键词查找笔记。支持多语言（韩语 + 英语），通过 multilingual-e5-base 完全离线运行
• 混合检索，结合向量搜索、BM25 全文搜索和标签匹配，并通过 Reciprocal Rank Fusion 融合结果
• 分块嵌入，长笔记会被拆分为约 340 个 token 的段落，并分别进行嵌入，因此埋在第三页的答案和开头段落中的答案一样容易找到。搜索会返回匹配的段落，而不是笔记的开头几行
• 交叉编码器重排（可选，MEMEX_RERANK=1），检索两倍数量的候选项，并使用 bge-reranker-v2-m3 重新排序。在黄金集上的 hit@1 提升约 20 个百分点，每次搜索耗时约 1.8 秒；默认关闭，因为自动召回和命令行都以即时查找为设计目标
• 日期筛选，使用 --from / --to 将搜索范围限定在某个时间段
• 笔记层级，每条笔记都属于 past（不可变记录）、state（可变计划）或 rule（Claude 行为指南）。Past 笔记拒绝更新；rule 笔记会自动注入 Claude 的系统提示词
• 往事闪回，保存和搜索时会自动显示来自不同文件夹、语义相关的较早笔记：“你在 124 天前的另一种情境下写过这件事”
• 推理引擎，确定性的信号会呈现尚未综合整理的模式（跨年脉络、过时的 state 笔记、标签复现）；你可以将有价值的信号提升为推断（带有来源信息的假设），当其源笔记发生变化时会自动失效。核心功能不使用 LLM
• MCP 服务，Claude 会自动搜索和保存。无需额外配置 CLAUDE.md
• 自动召回，可选的钩子，会在每次提示词到来时搜索你的笔记，并在 Claude 作答前注入匹配结果，因此召回不会依赖 Claude 记得去查找
• 重复检测，save_note 会在发现语义相似的笔记时发出警告，提示 Claude 更新而非新建
• 反向链接，使用 [[Title]] 语法链接笔记；get_note 会显示哪些笔记引用了它
• 系列折叠，带日期的工作日志（“… 2026-07-20”、“… 2026-07-23”）在结果页中最多占两个位置，搜索还会报告有多少条被折叠
• 修订说明，更正内容会记录其更正对象（amends），因此搜索会标记被取代的笔记，并指向最新的修正，而不是返回你已知有误的说法
• 摘要，memex digest 会按文件夹汇总最近 N 天保存的笔记
• 命令行工具，可在终端中添加、搜索、标记、浏览和索引笔记
• 兼容 Obsidian，笔记以 .md 文件形式保存；可与现有知识库搭配使用
• 本地数据库，SQLite + sqlite-vec，位于 ~/.memex/memex.db

---

命令行工具

# Add notes
memex add                                    # interactive prompt (asks for layer)
memex add --title "Note title" --content "..." --layer past
memex add --title "Note title" --file ./note.md --layer state
memex add --title "Note title" --content "..." --folder work/people/tom --layer past
memex add --title "Note title" --content "..." -T typescript -T architecture --layer past

# Layers
memex layer                               # distribution of past / state / rule
memex layer <id> state                     # move a note to a different layer

# Search
memex search "semantic search query"         # multilingual
memex search "knowledge management" --limit 10    # multilingual: matches Korean/Japanese notes too
memex search "query" --tag typescript        # filter by tag
memex search "query" --from 2026-04-01       # notes since a date
memex search "query" --from 2026-04-01 --to 2026-04-30

# Browse
memex list                                   # recent 10 notes
memex list --limit 20
memex show <id>
memex tags                                   # all tags with counts
memex related <id>                           # semantically related notes
memex digest                                 # last 7 days + signals + inferences
memex digest --days 30                       # summary of last 30 days

# Insights (inference engine)
memex signals                                # detect un-synthesized patterns
memex signals --type hidden_arc              # one type only
memex signals dismiss <id>                   # triage (also: snooze)
memex signals mint <signalId>                        # print evidence bundle to synthesize
memex signals mint <signalId> --title "..." --summary "..." --confidence 0.7
memex inferences                             # list inferences (auto-flags stale)
memex schedule                               # print cron/launchd snippet (no daemon)

# Edit / delete
memex edit <id>
memex delete <id>
memex delete --yes <id>                      # skip confirmation

# Index external directories
memex source add ~/Documents/My\ Notes       # register a vault
memex source list
memex source remove ~/Documents/My\ Notes
memex index                                  # scan vault + all sources
memex index --force                          # re-index everything
memex reembed                                # re-embed with current model

# Config
memex config show
memex config set vault-path ~/Documents/Second\ Brain

# MCP
memex mcp install                            # register with every MCP client on this machine

# Auto-recall
memex recall install                         # search notes on every prompt, inject hits
memex recall uninstall                       # remove the hook
memex mcp path                               # print MCP binary path

---

MCP 服务

Claude、Claude Code、Codex、Cursor

memex mcp install

它会写入每个客户端自己的配置文件，并保留其中已有的服务。如果客户端仍在运行较旧版本的 memex，它会将其重新指向新版。对于 memex 尚不认识的客户端，memex mcp path 会打印服务路径。

可用工具

工具	描述
save_note	保存笔记，需要指定 layer；如果存在相似笔记，会发出警告并显示闪回
search_notes	语义搜索；支持 category、tag、date_from、date_to 筛选；为排名最高的结果附加闪回
list_notes	列出最近的笔记
list_tags	列出所有标签及其笔记数量
list_folders	列出所有文件夹及其笔记数量
get_note	根据 ID 获取笔记的完整内容和反向链接
update_note	更新标题或内容。拒绝修改 past 笔记（建议使用 [Amendment]），也拒绝修改 rule 笔记（仅限用户操作）
delete_note	根据 ID 删除笔记
get_signals	获取确定性、未经综合处理的模式（hidden_arc / stale_state / dangling_link / tag_burst）
update_signal_status	处理信号，将其忽略或暂缓
list_inferences	列出综合生成的假设（会先重新检查是否过时）
get_inference	获取一条假设及其完整来源信息和变更／删除标记
mint_inference	保存已批准的假设，需要明确确认

推断与笔记分开保存（不纳入搜索），引用时始终视为假设，而非事实。检测过程保持确定性；唯一涉及 LLM 的步骤是综合生成推断摘要，这由 Claude 完成，而不是 memex。

笔记层级

每条笔记都会根据其可变性归入以下三个层级之一：

层级	含义	Claude 的权限
past	对已发生事件的记录、回顾、会议、决策依据、调试过程	仅可追加。update_note 会拒绝修改，并建议另建一条 [Amendment] 笔记
state	当前状态或计划、项目进度、路线图、某人当前担任的角色	可自由更新
rule	面向 Claude 的行为指南、编码风格、搜索策略	Claude 只能读取。仅用户可写入

CLI 会在 list、search 和 show 中的每条笔记旁显示颜色编码的 [past] / [state] / [rule] 徽标。

• save_note（MCP）和 memex add（CLI）都需要明确指定 layer。分类规则记录在工具描述中，以便 Claude 正确选择。
• 首次运行时，会根据文件夹为现有笔记补充层级：projects/dev/herald → state，coding → rule，其他所有文件夹 → past。迁移可重复执行且不会产生副作用。
• rule 笔记也会自动注入 MCP 服务的指令中，详见下文的 规则层自动注入。

闪回

保存笔记或进行搜索时，memex 会自动显示来自其他文件夹的旧笔记，这些笔记在语义上与当前内容相似，例如“你在 124 天前曾在不同情境下写过这件事”。这些笔记会作为系统生成的反向链接存储（note_links.source = 'flashback'），并与 [[wikilinks]] 分开（source = 'wiki'）。

通过环境变量调整：

环境变量	默认值	行为
MEMEX_FLASHBACK_DAYS	90	最小时间间隔，单位为天
MEMEX_FLASHBACK_DIST	0.4	最大向量距离（值越小，匹配越严格）
MEMEX_FLASHBACK_LIMIT	3	每次展示的建议数量上限

规则层自动注入

layer = 'rule' 的笔记会在启动时追加到 MCP 服务的指令中，放在 ## House Rules 部分下。Claude 会在每次对话开始时看到这些内容，无需调用 search_notes。编码风格指南或其他行为指南都适合放在这里。

环境变量	默认值	行为
MEMEX_INJECT_RULES	启用	设为 0 可完全停用注入
MEMEX_RULES_MAX_CHARS	8000	注入部分的字节预算；超出部分会被截断，并通过 console.warn 发出警告

对规则笔记的更新会在下次重启 Claude Desktop / Claude Code 后生效。

---

配置

配置文件位于 ~/.memex/config.json。

键	默认值	描述
vault_path	~/Documents/Second Brain	保存 .md 文件的目录
sources	[]	要建立索引的其他目录（例如现有的 Obsidian 知识库）
aliases	{}	搜索别名映射，例如 { "js": ["javascript", "ecmascript"] }；值可以是任何语言，用于跨文字体系检索

memex config set vault-path ~/my-vault

---

架构

~/.memex/
  config.json, vault path, sources, and aliases
  memex.db, SQLite DB (notes + note/chunk vec embeddings + FTS5 index)
  models/, cached embedding model

<vault>/
  *.md, notes (Obsidian-compatible)

包	作用
@memex/db	SQLite 架构、drizzle 查询、sqlite-vec + FTS5 集成
@memex/embed	通过 @huggingface/transformers 实现的本地嵌入器
@memex/rerank	本地交叉编码器重排器（可选启用）
@memex/core	CLI 和 MCP 共用的笔记服务：保存、编辑、搜索、向量索引
@memex/utils	配置、路径辅助工具、共享实用程序
@memex/mcp	MCP 服务（打包到 CLI dist 中）

---

生态系统

memex 是三款本地优先工具之一，它们秉持同一理念：你的数据留在自己的设备上，AI 则来到你的设备上。 它们可通过任何 MCP 客户端互操作，且彼此之间没有依赖关系。

flowchart TB
    U([You])
    subgraph I["Interfaces, talk to your tools"]
        direction LR
        CD[Claude Desktop]
        CC[Claude Code]
        CU[Cursor]
    end
    subgraph T["Local-first tools, each owns its data, on your machine"]
        direction LR
        F["firma · money<br/>~/.firma"]
        M["memex · memory<br/>~/.memex"]
        S["skope · news<br/>~/.skope"]
    end
    U --> I
    I -- MCP --> F & M & S
    F <-. never call each other .-> M
    M <-.-> S

• firma · 财务、投资组合、净资产、现金流
• memex · 跨会话的记忆、笔记及其背后的上下文
• skope · 新闻、个性化的世界观察视角

你可以通过 Claude Desktop、Claude Code、Cursor 或任何其他 MCP 客户端使用它们。这些工具通过模型组合，而不会互相调用。

---

未来方向

memex 是一款记忆引擎，而不是阅读笔记的地方。它没有窗口、没有编辑器， 也没有需要持续关注的界面。人们原本会手动监督的一切——哪些内容仍然有效、后续笔记更正了什么、哪些笔记能回答一个措辞与原文不同的问题——都必须在 Agent 发起提问时，由检索流程本身解决。

放弃桌面应用的原因：LLM 写的文档，没人会读。需要整理维护的知识库，终将腐朽。因此，目标是构建一种能够无需阅读、无需维护便能正确检索的结构：

目标	状态
检索回答实际问题，而非只匹配提问措辞（混合检索 + 重排 + 分块）	已发布
更正能够传递到所有会返回被更正笔记的界面	已发布
信号和推断能够确定性地指出哪些内容已过时	已发布
分层与模板可在写入时明确笔记的生命周期	已发布
在读取时解决内容过时问题，而非由人员清空队列	进行中
强制要求提供证据（derives_from），以便无需猜测即可重新核查声明	进行中

不在范围内：GUI、同步、协作、发布、插件系统和图谱画布。

设计记录见 docs/plans/。这些文档记录的是决策历程，而非路线图；为桌面应用编写的文档已被移除。

---

llms.txt

llms.txt 是本项目面向 LLM Agent 的机器可读摘要，包含简明描述和文档链接，并遵循 llms.txt 标准。

---

许可证

MIT