Memex - Giving Claude a memory

Memex

你的 Claude.ai 聊天记录和 Claude Code 会话分属两个互不相通的世界。Memex 将它们汇集到同一份记忆中，让你可以从两边搜索。

本地优先的 MCP 服务，可为你的 Claude.ai 聊天记录以及本地 Claude Code / 终端会话建立索引，并将它们提供给 Claude Code（stdio）和 Claude.ai（远程 MCP 连接器）。

状态： alpha，已在 PyPI 发布 0.3.1。阶段 0 至 7 均已完成，并通过安全审计（另有四轮对抗式红队测试）。已发布功能：混合搜索、实时捕获、自动摘要、聊天 ↔ 仓库关联、Claude.ai 远程连接器（GitHub OAuth）、Claude Code / 终端数据导入与机密信息脱敏、一键设置、跨平台自动启动，以及一键回填 claude.ai 历史记录。

端到端演示：你在 Claude Code 中询问在 claude.ai 上讨论过的内容。Memex 会搜索你的聊天记录（search_chats），Claude 则根据真实对话作答。无需复制粘贴，也无需手动传递上下文。

安装

一条命令即可安装 uv 和 Memex，并运行 memex setup（注册 MCP 服务、安装常驻捕获服务、为本地会话建立索引，并打印配对令牌）：

# macOS / Linux
curl -LsSf https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.ps1 | iex"

接下来只需完成终端无法执行的一步：安装 Chrome 扩展程序，粘贴它打印的令牌，然后点击“Backfill claude.ai history”。其他安装方式（pipx、uv tool install、从源代码安装）请参阅安装。

问题

头脑风暴和规划在 Claude.ai 中进行，执行则在 Claude Code 中进行。这两个世界互不相通：Claude Code 无法读取你在 Claude.ai 中的聊天记录，甚至无法读取当前任务的源头聊天。Anthropic 于 2026 年 3 月在 Claude.ai 上推出的记忆经过筛选，并非完整历史记录，而且只存在于 Claude.ai 内部。

Memex 弥补了这一空缺：它在本地运行，为你的全部聊天记录建立索引，并将它们作为 MCP 工具提供，以便 Claude 在需要时搜索并获取过往上下文。

工作原理

[Claude.ai]
    ↓  (official JSON export / Chrome ext)
[Ingestor]  →  [SQLite + sqlite-vec]  →  [local embeddings (fastembed / Ollama)]
                                    ↓
                          [core: storage + retrieval]
                                    ↓
                  [MCP stdio]  ───→  Claude Code, Claude Desktop
                  [MCP Streamable HTTP] ─→ Claude.ai connector

设计：将纯核心（存储、数据导入、嵌入、检索）与传输层解耦。同一引擎可同时为 stdio 和远程 MCP 提供服务，无需重写。

安装

快速安装（一条命令）

如有需要，会先安装 uv（它会安装合适的 Python），再从 PyPI 安装 Memex，并运行 memex setup 将其接入 Claude Code（MCP 服务 + 常驻捕获服务 + 本地会话索引 + 配对令牌）。无需克隆 git 仓库。

# macOS / Linux
curl -LsSf https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/dioniipereyraa/memex/main/scripts/install-pypi.ps1 | iex"

唯一需要在终端之外完成的是浏览器操作：安装 Chrome 扩展程序，粘贴安装程序打印的令牌， 然后点击“Backfill claude.ai history”导入历史记录。嵌入功能开箱即用（首次导入时会下载量化的 130 MB fastembed 模型；无需 Ollama，也无需 API 密钥）。

只需两步：先运行 pipx install memex-chats（或 uv tool install memex-chats）， 再运行 memex setup，效果相同。wheel 安装也会生成自动启动服务（launchd / systemd / 登录时运行的 Scheduled Task），因此无需克隆仓库。

从源代码安装（用于开发）

克隆仓库即可获得可编辑安装，以及扩展程序源代码和服务模板。你需要安装 git；脚本会为你安装 uv 和固定版本的 Python。

macOS / Linux

git clone https://github.com/dioniipereyraa/memex
cd memex
./scripts/install.sh

如果尚未安装 uv，install.sh 会为你安装，然后运行 uv sync，并通过 memex doctor 验证安装。这就是全部设置步骤。

Windows（PowerShell）

git clone https://github.com/dioniipereyraa/memex
cd memex
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

与 macOS 脚本的三个步骤相同（安装 uv、同步、验证）。如果尚未安装 git，请先从 git-scm.com 获取。

手动安装（适用于任何操作系统，适合偏好明确步骤的用户）

# 1. Install uv (skip if you already have it):
#    macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh
#    Windows:      powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
git clone https://github.com/dioniipereyraa/memex
cd memex
uv sync               # installs Python 3.13 + dependencies into .venv
uv run memex doctor   # verify

升级（已安装 memex）

请使用安装 memex 时所用的同一工具升级，否则新版本不会出现在 PATH 中。之前的安装会占用 memex 可执行文件，因此使用其他管理器重新安装会失败并提示“Executables already exist”，而 memex 仍会运行旧版本。（这是升级后 memex sync 看起来“并不存在”的常见原因：由旧版 pipx 管理的 memex 遮蔽了通过较新版 uv tool 安装的版本。）

# 1. Find which tool owns it:
which memex            # macOS / Linux
Get-Command memex      # Windows (PowerShell)

# 2. Upgrade with that tool:
pipx upgrade memex-chats        # if pipx owns it
uv tool upgrade memex-chats     # if uv owns it

如果要更换管理器，请先卸载旧管理器中的版本（pipx uninstall memex-chats 或 uv tool uninstall memex-chats），然后重新安装。升级后，memex --version 会显示新版本，且 memex doctor 应能通过。

多设备（可选）

若要让 Claude 在多台设备之间共享同一份记忆，请先安装 Tailscale（这样每台设备都有稳定的私有地址），然后在每台设备上选择启用一次：

memex setup --sync     # opt-in, persisted: the always-on service is sync-reachable

它会打印一条 memex sync connect ... 命令，供你在其他设备上运行。此选项会保存下来，因此服务在重启后仍可通过同步访问，无需重新运行任何命令。完整流程、安全模型和手动单次运行的替代方案请参阅在设备间同步。

对于双启动设备（Linux 和 Windows 不会同时运行），请改用基于文件的同步：在每个操作系统上运行 memex setup --sync-dir <shared-folder>，并指向同一文件夹。无需 Tailscale，也无需让两台设备同时在线。请参阅双启动或无法同时在线的设备。

首次运行

最快的方式是运行一条命令：

uv run memex setup

memex setup 会端到端地完成所有配置，且可安全地重复运行：它会将 MCP 服务注册到 Claude Code（claude mcp add）、安装持续运行的实时捕获服务（macOS 上使用 launchd，Linux 上使用 systemd，Windows 上使用计划任务）、为本地 Claude Code 会话建立索引，并打印访问令牌，供你粘贴到 Chrome 扩展程序中。每个步骤遇到问题时都会显示警告，而不会中止后续步骤。可用标志：--no-mcp、--no-autostart、--no-ingest、--remote（同时安装 claude.ai connector Agent）、-y（不显示提示）。

之后，唯一需要手动完成的步骤是安装 Chrome 扩展程序并粘贴令牌，这样后续的新聊天就会在进行时被捕获。

手动步骤（如果你更愿意自行运行）

# 1. Request your official Claude.ai export (Settings → Privacy → Export data),
#    then ingest it (first run downloads the embedding model, ~30s):
uv run memex ingest /path/to/your-export.zip

# 2. Optionally index your local Claude Code / terminal sessions:
uv run memex ingest-claude-code

# 3. Search, or wire it into Claude Code (see "Wiring it into Claude Code"):
uv run memex search "your query" -n 5
uv run memex stats

（如果你通过脚本安装，上述命令可直接使用。如果你安装的是已发布到 PyPI 的软件包，请去掉 uv run 前缀。）

数据存储位置。 从克隆的仓库运行时，数据库和导出文件会保留在 <repo>/data 中。通过 uvx/pip 安装时，它们会存放在操作系统的数据目录中（macOS 上为 ~/Library/Application Support/memex，Windows 上为 %LOCALAPPDATA%\memex，其他系统上为 ~/.local/share/memex）。可通过 MEMEX_DB_PATH / MEMEX_EXPORTS_DIR 覆盖。memex doctor 会打印解析后的路径。

使用 Memex（安装后）

memex setup 完成后，无需再启动任何东西：捕获服务器和索引器会在后台运行。你可以通过三种方式使用 Memex。

1. 在 Claude Code 中（主要方式）。 安装程序会注册 MCP 服务，因此 Claude Code 可以使用以下工具搜索你的全部历史记录并保持数据最新：

只需自然地向 Claude Code 提问（“我在 claude.ai 聊天记录中对 X 做了什么决定？”，“索引此会话”，“将此内容同步到我的其他设备”），它就会调用这些工具。index_terminal_sessions 和 sync_now 仅限本地使用（绝不会暴露给远程 claude.ai 连接器）。请注意，sync_now 发送的是已索引的内容，因此若要包含当前所在的会话，请先让 Claude 调用 index_terminal_sessions。若要在会话开始时自动注入上下文，请添加可选的 SessionStart hook。

2. 在终端中。 memex search "..."、memex stats、memex doctor、memex token（重新打印扩展程序配对令牌）、memex --version。

3. 捕获（自动运行，无需操作）。 Chrome 扩展程序会在你打开或重新加载 claude.ai 聊天时为其建立索引（其“Backfill”按钮可导入你的旧聊天记录）；Claude Code 会话则会在会话结束时建立索引，此外还有 15 分钟的补充索引。

数据的实时性如何？

同一设备上的同步基本上是实时的。跨设备不是实时中继（它是无云端的点对点同步）：已配对设备在双方都在线时每 15 分钟自动协调一次，你也可以通过 memex sync now 立即强制同步。claude.ai 聊天会在打开 / 重新加载时由扩展程序捕获，因此若要同步进行中的聊天的最新内容，请重新加载聊天（让扩展程序重新捕获），然后运行 memex sync now。终端无法直接读取 claude.ai，因此始终由扩展程序负责捕获；同步只会传播本地已索引的内容。

嵌入后端

默认使用 fastembed（无需配置）。若要改用本地 Ollama（例如你已在运行它以处理其他模型）：

export MEMEX_EMBED_BACKEND=ollama
ollama pull nomic-embed-text          # install Ollama first: https://ollama.com/download

在 Windows 上，设置 MEMEX_EMBED_BACKEND=ollama 之前，请先从 ollama.com/download 安装 Ollama。这是可选操作；使用 fastembed 无需安装 Ollama。

诊断

遇到问题时随时运行 memex doctor。它会检查 Python 版本、数据库、嵌入器、实时捕获服务器、摘要器配置、已注册仓库和已索引语料库。每项检查都会报告 OK / WARN / FAIL。

故障排除

首先运行 memex doctor（见上文）：以下大多数问题也会在那里显示。

安装后立即出现 memex: command not found。 memex 可执行文件位于工具的 bin 目录中，该目录可能尚未添加到当前 shell 的 PATH。打开新的终端，或立即添加：

• macOS / Linux：export PATH="$HOME/.local/bin:$PATH"
• Windows：重新打开终端，让安装程序对 PATH 的更改生效（对于 uv tool，bin 目录为 %USERPROFILE%\.local\bin；对于 pipx，则为 Scripts 目录）。 然后确认使用的是正确的二进制文件：which memex（macOS/Linux）或 where memex（Windows）。它应该指向 uv-tool / pipx 安装的位置，而不是旧的克隆版本。

扩展程序显示服务未响应，或摄取时返回 401。

• 服务是否正在运行？curl -s http://127.0.0.1:5777/health 应返回 JSON。如果没有，请启动服务（memex serve），或检查下文中的自动启动服务。
• 401 表示配对令牌缺失或已过期：运行 memex token，复制令牌值，将其粘贴到扩展程序弹窗中，然后点击 保存令牌。

自动启动服务未能启动。 检查其状态，然后查看日志：

• Linux：systemctl --user status memex-serve；日志位于 ~/.local/share/memex/serve.log。Failed to connect to bus 表示当前会话没有用户 systemd 管理器（通过普通 SSH 连接时很常见）：运行 loginctl enable-linger "$USER"，确保已设置 XDG_RUNTIME_DIR=/run/user/$(id -u)，然后重新运行 memex install-service。
• macOS：运行 launchctl list | grep memex；日志位于数据目录中（PyPI 安装时为 ~/Library/Application Support/memex/com.memex.serve.log，从源代码运行时为 <repo>/data/serve.log）。
• Windows：查看任务计划程序，或运行 schtasks /Query /TN MemexServe /V；日志位于 %LOCALAPPDATA%\memex\serve.log。如果旧安装留下了同名任务，可能会悄无声息地遮蔽新任务：删除旧任务（schtasks /Delete /TN MemexServe /F），然后重新运行 memex install-service。

注销或重启后自动启动失效（Linux）。 除非启用了持久运行，否则会话结束时 systemd 用户单元也会被停止：loginctl enable-linger "$USER"。

一键安装程序因 shell 错误而失败。 安装程序使用 POSIX sh。如果你使用的是非常旧或不常见的 shell，且管道执行失败，请改用 bash 下载并运行：curl -LsSf <url>/install-pypi.sh | bash。

Windows：uv tool install 复制 memex-mcp.exe 时失败，并显示 "Acceso denegado (os error 5)"。 通常是以下两个原因同时导致：

• Claude Code / Claude Desktop 正在运行，其 MCP 子进程占用了正在运行的 .exe。关闭 Claude Code 和 Claude Desktop，然后重试。
• Windows Defender 会阻止写入全新的 .exe，即使该文件未被占用。判断方法：目标文件尚不存在（Test-Path "$env:USERPROFILE\.local\bin\memex-mcp.exe" 的结果为 False），但复制仍然失败。为 %USERPROFILE%\.local\bin 和 %APPDATA%\uv 添加 Defender 排除项。

然后重新运行 uv tool install --force memex-chats（从分支更新时运行 uv tool install --reinstall --refresh <spec>）。

Windows：已配对设备连接同步端口（5777）时超时。 在可从同步端口访问的模式下，常驻服务会绑定到 0.0.0.0:5777，但 Windows 防火墙会悄悄丢弃入站连接（对端只会超时，不会收到“连接被拒绝”），直到添加允许该端口的规则。memex setup --sync 会为你添加该规则（可重复执行，尽力而为）；如果运行 setup 时未提升权限，它会打印一条需要以管理员身份运行的一次性命令：New-NetFirewallRule -DisplayName "Memex sync 5777" -Direction Inbound -Protocol TCP -LocalPort 5777 -Action Allow。

tailscale ping 正常，但同步超时。 如果 tailscale ping <peer> 成功，但常规 ping/TCP（以及 memex 同步）在两个方向上都超时，问题出在其中一台机器的本地 TUN/路由冲突，而不是 memex 或防火墙规则：另一个 VPN 类型的适配器（Hamachi、其他 VPN 或虚拟交换机）正在截获本应通过 Tailscale 接口传输的系统流量。禁用或移除其他适配器，然后重启 Tailscale 服务。（实际案例：为游戏托管安装的 Hamachi 适配器导致一台 Windows 电脑的 Tailscale 流量异常，但 tailscale ping 仍然正常。）

首次回填（或首次摄取）速度较慢。 首次嵌入时会下载一个约 130 MB 的量化模型；这只需下载一次，后续运行会很快。回填是增量且可安全重复运行的，因此首次执行即使较慢或中断，也会从上次停止的位置继续。 **导入占用内存过多。**峰值 RAM 会随嵌入批次大小而变化。请调低批次大小：在环境或 .env 中设置 MEMEX_EMBED_BATCH_SIZE=1（峰值约为 0.67 GB）。

我的数据在哪里？memex doctor 会打印数据库路径。对于 PyPI 安装，默认路径为 ~/.local/share/memex（Linux）、~/Library/Application Support/memex（macOS）或 %LOCALAPPDATA%\memex（Windows）；如果是从克隆的仓库运行，则为 <repo>/data。可通过 MEMEX_DB_PATH / MEMEX_EXPORTS_DIR 覆盖。

MCP 服务工具（v1）

• search_chats(query, limit=5, source?, mode="hybrid", repo?) 搜索语料库。模式：hybrid（默认，结合向量搜索和通过 Reciprocal Rank Fusion 实现的 FTS5 BM25）、semantic（仅向量）、lexical（仅 FTS5，适用于专有名词或精确术语）。source 按来源筛选（conversations、design_chat、memory）。repo 会提升与已注册仓库相关的结果（见下方“仓库关联”）。每段对话的结果会去重。
• get_chat(uuid, messages_limit=10, messages_offset=0) 获取一段对话及其消息，支持分页。会省略 raw_content；每条消息会截断至 1500 个字符，以适应客户端的令牌预算（最坏情况下响应约为 17k 个字符）。较长的对话可通过 messages_offset 分页；messages_limit 最大为 100。
• list_recent_chats(limit=10, source?) 按最近更新时间列出最新对话。
• find_related(context, limit=5, repo?) 接受自由格式文本（一段文字、文件内容、当前讨论），并返回语义相关的对话。仅使用向量搜索，不使用 FTS，输入上限为 4000 个字符。适合在不输入关键词查询的情况下查找“类似内容”。

stdio 服务（memex-mcp，供 Claude Code 使用）还提供两个写入/维护工具，因此你可以让 Claude 保持记忆更新，而不必转到终端。这些工具仅限本地：绝不会注册到远程 claude.ai 连接器（它们会修改存储并访问网络）。

• index_terminal_sessions() 运行增量式 ingest-claude-code 扫描（为本地新增或变更的 Claude Code 会话编制索引，包括当前会话中已写入其记录的内容）。共用单飞导入锁；返回数量统计。
• sync_now() 与每台已配对设备立即执行双向协调；如果已配置共享文件夹，也会同步文件。需要启用同步。它会传播已编制索引的内容，因此若要包含当前会话，请先调用 index_terminal_sessions。

也可以通过 CLI 使用 memex search "query" --mode {hybrid|semantic|lexical} 进行搜索。对于在混合 FTS5 功能实现前创建的数据库，请运行一次 memex reindex-fts 来填充词法索引。

将其接入 Claude Code

本地数据库填充完成后（memex ingest），使用 uv run memex-mcp 启动 MCP 服务。若要让 Claude Code 自动发现该服务，请在项目根目录添加 .mcp.json 文件（或在 ~/.claude.json 中添加用户级服务）：

{
  "mcpServers": {
    "memex": {
      "command": "uv",
      "args": ["run", "memex-mcp"],
      "cwd": "/absolute/path/to/the/memex/repo"
    }
  }
}

将 cwd 设为克隆 Memex 的绝对路径（即 pyproject.toml 所在位置）。重启 Claude Code 后，search_chats、get_chat、list_recent_chats 这些工具就会出现在会话中。

如果你更希望在 Claude Code 之外使用相同的搜索，也可以通过 CLI 执行 uv run memex search "..."。

从 claude.ai 连接（远程 MCP，第 4 阶段）

memex serve-remote 会将相同的 4 个工具作为 自定义连接器 提供给 claude.ai 使用。一个连接器可在 claude.ai 网页版、Claude Desktop 和移动应用中通用：连接由你的 Claude 账号代理，始终从 Anthropic 的云端发起，而非你的设备。这会带来两个影响：

1. 服务必须可通过公共 HTTPS URL访问（主机名必须有公共 IPv4 A 记录；出于设计考虑，localhost 和私有 IP 会被拒绝）。预期的配置方式是使用一个隧道，在该隧道终止 TLS 并将请求代理到本机环回地址上的 Memex。
2. 身份验证要么是无身份验证，要么是完整的 OAuth 2.0（claude.ai 没有可粘贴令牌的输入框）。Memex 使用由 GitHub OAuth App 支持的 OAuth，并限制为 GitHub 用户名允许列表：任何其他人即使完成 OAuth 授权流程，每次请求仍会收到 401。连接器要正常响应，你的机器必须处于运行状态（且隧道必须已启动）。

1. 使用 Tailscale Funnel 发布 URL

安装 Tailscale 并登录，然后：

tailscale funnel --bg 8377

这会输出你的公共 URL，例如 https://my-mac.my-tailnet.ts.net，其中包含 TLS。其他隧道的工作方式相同（ngrok、Cloudflare Tunnel）；Memex 只需要最终生成的 https:// URL。

2. 创建 GitHub OAuth App

前往 github.com/settings/developers > OAuth Apps > New OAuth App：

• Homepage URL：你的 Funnel URL。
• Authorization callback URL：<funnel URL>/auth/callback。

复制 Client ID 并生成 Client Secret。

3. 配置并运行

在 .env 中（参见 .env.example）：

MEMEX_REMOTE_BASE_URL=https://my-mac.my-tailnet.ts.net
MEMEX_GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxx
MEMEX_GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxx
MEMEX_REMOTE_ALLOWED_GITHUB_LOGINS=your-github-username

uv run memex serve-remote   # listens on 127.0.0.1:8377, endpoint at /mcp

配置不完整时，服务会拒绝启动（没有不安全的默认值：空的允许列表会将你的全部聊天记录暴露给任何 GitHub 账号）。

4. 在 claude.ai 中添加连接器

Settings > Connectors > Add custom connector，URL 填写 https://my-mac.my-tailnet.ts.net/mcp。claude.ai 会通过动态客户端注册完成注册，并引导你进行 GitHub 授权，随后工具就会出现在你的聊天中。OAuth 状态会加密后持久化到磁盘，因此重启 serve-remote 不会中断连接。

简而言之，安全模型包括：绑定到环回地址并使用隧道；通过 GitHub 的 OAuth 代理，并在每个请求上强制执行用户名允许列表（在 GitHub 上撤销该应用会立即阻止其访问）；将 TrustedHostMiddleware 固定到公共主机名；以及在工具结果上采用与 stdio 传输相同的间接提示词注入防护机制。

为 Claude Code / 终端会话建立索引（阶段 6）

Memex 还会为本地的 Claude Code 和终端会话建立索引，因此一次搜索就能涵盖你的完整历史记录：既包括你在 claude.ai 上讨论的内容，也包括你用 Claude Code 构建的内容。Claude Code 会将每个会话记录为 ~/.claude/projects/ 下的 JSONL 文件；Memex 会直接读取这些文件（无需扩展程序，也不会联网）。无论 Claude Code 在哪里运行，这种方式都适用，包括终端 CLI 和 VS Code / JetBrains 扩展：它们写入的都是相同的会话记录。

uv run memex ingest-claude-code        # scans ~/.claude/projects/**/*.jsonl
uv run memex ingest-claude-code --path /custom/path   # alternate root

这些会话存储在 claude_code 来源下，可像其他聊天记录一样搜索（也可通过 source="claude_code" 筛选）。详情如下：

• 增量处理。 未更改的会话会被跳过（依据内容哈希），因此完成更多工作后重新运行，开销很小。会话以仅追加的方式增长，因此重新扫描即可获取新消息和新会话。你可以在想要更新时重新运行，也可以将其接入定时任务。
• 自动关联仓库。 每个会话都会记录其工作目录，因此会自动关联到该 cwd 对应的已注册仓库（请先运行 memex repos add <path>）。随后，search_chats(repo=...) 会优先显示你在该项目中工作的会话。
• 索引内容： 你的提示词、助手回复，以及以 [tool_use: ...] / [result] 标记表示的工具调用。不包括：助手的内部推理（thinking）、并行子 Agent 的旁支会话，以及 CLI 的管道内容（斜杠命令回显、bash 包装器）。所有内容都保留在本地 SQLite 数据库中。
• 敏感信息脱敏。 会话日志会捕获真实的终端输出和文件内容，其中通常包含凭据。存储前，Memex 会将常见格式的敏感信息（API 密钥、bearer/JWT 令牌、PEM 私钥、KEY=/SECRET= 赋值，以及嵌入密码的 URL）替换为 [REDACTED:...]，并且不会为此来源持久化原始区块内容。此功能仅尽力而为，并非保证：它会捕获广为人知的格式，避免将实际上从未属于对话的第三方凭据纳入索引（这一点很重要，因为远程连接器可能会向 claude.ai 展示已索引的文本）。

为 Claude Code 会话建立索引

扫描会话记录后，该会话即可搜索。日常使用中，你可以通过以下三种方式自行触发：

• 询问 Claude。 说“为这个会话建立索引”，Claude 就会调用 index_terminal_sessions MCP 工具（当前对话会被记录到 Claude Code 当时已写入会话记录的内容）。如果想立即在其他设备上使用，接着说“同步我的设备”（sync_now）。
• 结束对话。 安装下方的 SessionEnd 钩子后，结束 Claude Code 聊天（只结束对话，不是整个终端），该会话就会在关闭时立即导入。
• 运行命令。 memex ingest-claude-code 会立即扫描所有新增内容。

即使你不使用上述任何方式，下方的定期兜底机制也会在新会话或有更新的会话最后一次写入后的约 15 分钟内将其收录。两种自动机制相辅相成（它们都会以低优先级在后台运行，并且只有在有新内容时才会加载嵌入模型，因此几乎不会消耗资源）：

1. SessionEnd 钩子 — 在会话关闭时立即导入（无延迟，不会遗漏）。添加到 ~/.claude/settings.json：

   {
     "hooks": {
       "SessionEnd": [
         { "matcher": "*", "hooks": [
           { "type": "command", "command": "/absolute/path/to/memex/scripts/session-end-hook.sh" }
         ] }
       ]
     }
   }
   

   该钩子会读取已关闭会话的 transcript_path，仅导入该会话，并在后台独立运行后立即返回（SessionEnd 钩子不能阻塞 Claude Code）。

2. 定期兜底机制 — 定时扫描，捕获钩子遗漏的内容（例如崩溃导致的遗漏）。在 macOS 上使用 launchd：

   sed "s|__REPO__|$(pwd)|g" scripts/com.memex.ingest-claude-code.plist.template \
     > ~/Library/LaunchAgents/com.memex.ingest-claude-code.plist
   launchctl load ~/Library/LaunchAgents/com.memex.ingest-claude-code.plist
   

   它会每 15 分钟以低优先级后台任务的方式运行 scripts/scheduled-ingest.sh。在 macOS 或 Windows 上通过 PyPI 安装时，无需手动执行这些步骤：memex setup（或 memex install-service）已会在这些系统上安排兜底任务（com.memex.ingest-claude-code launchd 代理 / MemexIngest 计划任务）。在 Linux 上，安装程序只会配置服务，因此你需要自行使用 systemd 用户定时器或 cron 运行 memex ingest-claude-code 来配置兜底机制。

   两种机制在各操作系统上的状态：SessionEnd 钩子脚本使用 bash，因此可在 macOS 和 Linux 上运行；Windows 需要一个与 session-end-hook.sh 等效的 PowerShell 脚本，目前尚未提供，因此在 Windows 上可通过兜底任务、询问 Claude 或运行手动命令来导入会话。

在设备间同步

如果你在多台设备上运行 memex（例如笔记本电脑和台式机），memex sync 就能让 Claude 在这些设备间共用一份记忆：在一台设备上为聊天建立索引，就能在另一台设备上搜索。每台设备都保留自己的本地存储，并通过点对点方式同步，不需要中央服务器，也不会有任何数据离开你的硬件。同步要求两台设备同时开机且可相互访问（这是重叠时段同步，而非云中继）。该功能从 memex 0.4.0 起提供；如果安装版本较旧，请先升级（uv tool upgrade memex-chats）。

此功能默认关闭，启用前不会暴露任何内容。关闭时，同步端点会返回 404，同步命令也会拒绝运行，因此普通的单设备安装不会增加额外的攻击面。

一次设置（推荐）

先在每台设备上安装 Tailscale，然后只需启用一次：

memex setup --sync

这是常规设置，外加一项操作：启用同步，并让你的常驻捕获服务可通过这台设备的 Tailscale 地址进行同步访问（它会绑定到 0.0.0.0，这样同一服务仍可响应本地扩展程序；Host 允许列表会固定为环回地址 + 你的 Tailscale IP，并在启动时解析；访问权限由每次安装的令牌控制）。该选项会持久保存：设置一次后，服务每次重启都会启用同步访问，因此你无需手动运行 serve 命令。它会打印一行命令，供你在其他每台设备上运行：

memex sync connect --url http://100.x.y.z:5777 --token <TOKEN> --name my-mac

connect 会在那台设备上启用同步、完成配对并执行双向协调，因此一步即可完成设置并同步最新内容。

设置后无需操心： memex setup --sync 还会启用自动同步，因此配对的设备在都处于在线状态时，会每 15 分钟自动协调一次（无需环境变量，也无需 cron）。这是设备间同步，不是云中继：如果另一台设备处于关机状态，本次同步会跳过，并在两台设备下次同时开机时追上进度。除定时同步外，捕获完成后几秒内也会触发同步：当 Chrome 扩展程序捕获聊天且 Memex 将其编入索引后，这段新对话会立即推送到你的其他设备（无需运行任何命令）。一批捕获内容（例如回填数据或多个已打开的标签页）会合并为一次同步，并在捕获完成后执行；只有两台设备都开机时才会触发（双启动时，另一操作系统会在下次启动时获取变更）。如需仅关闭此功能，请设置 MEMEX_SYNC_ON_CAPTURE=false；如需调整合并等待时间，请设置 MEMEX_SYNC_ON_CAPTURE_DEBOUNCE_SECONDS（默认值为 10）。你仍可以在两次定时同步之间手动立即同步（例如，推送你当前正在进行的聊天）：

memex sync now          # immediate two-way reconcile with every paired device

memex sync now 会传播本地已编入索引的内容；claude.ai 聊天会在扩展程序捕获时（打开或重新加载时）编入索引，因此，如果你想包含进行中聊天的最新内容，请先重新加载该聊天。memex sync status 会显示已配对的设备以及上次同步时间；memex sync reconcile 与 now 功能相同。使用 memex setup --no-sync 可完全关闭所有功能（仅限环回地址，关闭同步和自动同步）。使用 MEMEX_SYNC_INTERVAL_SECONDS 调整同步间隔（默认值为 900）。

单次同步（无需更改你的设置）

如果你不想让服务永久可访问，可以在存有对话的设备上启动一个临时端点：

# SOURCE device:
memex sync serve
# -> Memex sync serve reachable at http://100.x.y.z:5777
#    On the other device, run this one command:
#      memex sync connect --url http://100.x.y.z:5777 --token <TOKEN> --name my-mac

memex sync serve 在 macOS、Linux 和 Windows 上的运行方式相同（它使用你的 Tailscale 地址，因此无需按操作系统配置网络，也不必折腾 --host/允许列表）。如果你不使用 Tailscale，请传入 --host <address the other device can reach>。它只绑定到该地址，并且可以与本地回环捕获服务同时运行，不会发生端口冲突；在另一台设备连接期间保持运行，完成后按 Ctrl+C 停止。之后，memex sync reconcile 会重新同步已配对的设备。

reconcile 是通常使用的命令：它会双向同步并使两台设备保持一致；对于两边都存在的内容，保留较新的副本（按更新时间遵循最后写入者胜出）。如果同一段对话在两台设备上编辑过，且时间戳完全相同，就会发生冲突：reconcile 会保留两份副本不变并报告冲突，你可以通过单向的 memex sync pull --peer mac（采用对端的版本）或 push --peer mac（发送你的版本）来选择保留哪一份。

每次同步只传输新增或已更改的对话，并会一并传输它们的嵌入向量，因此你的设备无需重新生成嵌入向量；同步操作具有幂等性（重复运行不会传输新内容）。较大的历史记录会自动分批传输，并限制每批大小，因此无论你有多少段对话都能正常同步（使用 MEMEX_SYNC_MAX_BATCH_BYTES 调整目标大小，默认值为 8 MB；如果单段对话超过对端的 MEMEX_INGEST_MAX_BODY_BYTES，则会跳过并显示清晰的提示）。两台设备必须使用相同的嵌入模型（模型不匹配时，同步会被拒绝）。对端的令牌会以仅用户可访问的权限（0600）存储在 DB 旁边。配对意味着信任（会共享访问令牌），因此只与自己控制的设备配对。切勿使用文件夹同步工具直接同步 SQLite 文件；请始终使用 memex sync，它能确保对话级别的一致性。

memex setup --sync 会为你开启自动同步（每 15 分钟执行一次 reconcile），无需设置环境变量。在后台，它会在启动时以及每隔 MEMEX_SYNC_INTERVAL_SECONDS（默认值为 900）与每个已配对的对端进行 reconcile；如果对端离线，则会跳过；如果正在执行摄取任务，则会延迟同步。如果你没有使用 setup --sync（例如手动设置或开发环境设置），仍可在运行 memex serve 前设置 MEMEX_SYNC_AUTO=true 来启用自动同步；无论是已保存的标记还是环境变量，都会启动同步循环。只有启用同步时才会运行；使用 memex sync disable（或 memex setup --no-sync）即可关闭整个功能。

双启动或从不同设备不同时在线（基于文件的同步）

网络同步要求两台设备同时在线。双启动机器（Linux 和 Windows 安装在同一块磁盘上，一次只运行一个系统）无法做到这一点；对于任何很少同时开机的一组设备，这种方式也不太方便。为此，memex 还提供了第二种同步模式：使用共享文件夹，而不是实时连接。每个操作系统都会将其存储的快照导出到文件夹，并导入其他操作系统的快照。无需服务器、端口、令牌或第三台设备。该功能已在 memex 0.4.4 及更高版本中提供。

让每个操作系统都指向同一个共享文件夹（每个操作系统运行一条命令）：

# On Linux (the Windows partition mounted at, e.g., /mnt/windows):
memex setup --sync-dir /mnt/windows/memex-sync --device-name linux

# On Windows (the SAME physical folder, its path there):
memex setup --sync-dir C:\memex-sync --device-name windows

就这样。此后，每个操作系统启动时都会通过该文件夹自动同步（运行期间每 15 分钟一次），运行 memex sync now 则会立即同步。如果文件夹不存在，系统会为你创建；设置也会保存，因此只需配置一次。

双启动时文件夹应放在哪里：它必须能被两个操作系统读取，因此应放在 Windows / NTFS 分区上。Linux 开箱即可读写 NTFS；Windows 无法读取 Linux 的 ext4。（对于很少同时在线的两台独立机器，任何共享位置都可以：USB 驱动器，或 Dropbox 之类的云同步文件夹。）

双启动注意事项：Windows 的快速启动（以及休眠）会使 NTFS 分区处于未正常关闭状态，因此 Linux 会以只读模式挂载它，而文件同步需要向其中写入快照（如果无法写入，首次导出会明确报错）。如果 Linux 上的文件夹以只读方式挂载，请在 Windows 中禁用快速启动（或运行 powercfg /h off），然后完整关闭一次 Windows。

同步如何收敛：每台设备只会写入自己的 <device>.memexsync.gz，并读取其他设备的文件，因此它们不会冲突。同步采用按更新时间的最后写入者胜出规则，与网络模式完全相同；如果出现相同时间戳冲突（分叉），则不会修改相关数据，并会报告冲突。另一个操作系统上较新的对话会在你下次启动时同步到本机（它已将快照留在磁盘上），而你的数据会在它下次启动时同步过去。如果两个操作系统的主机名相同，请为它们指定不同的 --device-name 值，否则它们会覆盖彼此的快照。快照包含你的对话文本和向量，因此请将共享文件夹放在只有你能读取的位置（与配对设备时遵循相同的“只分享你能控制的内容”规则）。两种模式彼此独立：你可以使用文件同步、网络同步，或同时使用两者。

轮换令牌

每台设备都有一个访问令牌（数据库旁的 ingest_token 文件；memex doctor 会显示其所在文件夹）。如果令牌被粘贴到了不该出现的地方，请立即轮换：例如聊天、屏幕截图或工单。目前还没有轮换命令，而且运行中的服务器只会读取一次该文件，因此操作顺序很重要：

1. 删除令牌文件（rm <data-dir>/ingest_token；PowerShell： Remove-Item -Force $env:LOCALAPPDATA\memex\ingest_token）。
2. 重启始终运行的服务（macOS：对 com.memex.serve 依次运行 launchctl unload 和 load；Linux：systemctl --user restart memex-serve；Windows： 依次运行 schtasks /End /TN MemexServe 和 schtasks /Run /TN MemexServe）。如果跳过这一步，旧令牌仍会被接受（它缓存在内存中），新文件则会被忽略。
3. 运行 memex token 查看新值。将它重新粘贴到该设备 Chrome 扩展弹出窗口中，并重新配对所有连接到这台设备的设备： memex sync connect --url http://<this-device>:5777 --name <name> --token "..." （传入 --token 可避免使用隐藏提示词，以免输入错误。）

始终运行

memex serve（claude.ai 捕获）是一个长期运行的服务，Claude Code 摄取后备任务则按计划运行。要让它们在登录时启动并保持运行（崩溃后自动重启），可以让 memex setup 安装服务，也可以在任何操作系统上直接调用：

memex install-service            # install (launchd / systemd / Scheduled Task)
memex install-service status     # show what is registered
memex install-service uninstall  # remove it

此方案跨平台：在 macOS 上使用 launchd 代理，在 Linux 上使用 systemd 用户单元，在 Windows 上使用计划任务。默认情况下，它会管理实时捕获服务，以及每 15 分钟运行一次的 Claude Code 摄取后备任务。空闲时的开销很低：只有在有实际任务时才会加载嵌入模型。无论通过 PyPI / pipx / uv tool 安装（使用独立的 launchd / systemd / 计划任务直接运行已安装的 memex serve），还是从克隆的仓库运行，效果都一样。请使用持久化安装方式（pipx 或 uv tool），而不要使用临时的 uvx，这样服务才能在启动时使用稳定的解释器。

若还要将 claude.ai 远程连接器作为服务运行，请传入 --remote（macOS）：memex install-service --remote。只有在 .env 中配置了 MEMEX_REMOTE_*，并且同一端口上的 Tailscale Funnel 已启动（tailscale funnel --bg 8377）时，这才有意义；否则 Agent 会陷入崩溃重启循环，因此此选项默认不启用。

cd /path/to/memex
for svc in serve ingest-claude-code; do
  sed "s|__REPO__|$(pwd)|g" "scripts/com.memex.$svc.plist.template" \
    > ~/Library/LaunchAgents/com.memex.$svc.plist
  launchctl load ~/Library/LaunchAgents/com.memex.$svc.plist
done
launchctl list | grep memex

自动摘要（第 3 阶段，可选）

当 search_chats 返回的聊天尚无摘要时，Memex 可以使用 Claude Haiku 即时生成摘要。摘要会持久保存，因此下次搜索同一聊天时会命中缓存，不会再次产生 API 费用。这样，你只需为实际查看的聊天付费，而不必为整个语料库付费。

需主动启用。默认关闭。上限：每次 search_chats 调用最多并行生成 3 条摘要，以限制延迟和每次查询的成本。

1. 安装额外依赖（会添加 anthropic SDK）：

   uv sync --extra summaries
   

2. 在 .env 中（或作为环境变量）设置：

   ANTHROPIC_API_KEY=sk-ant-...
   MEMEX_SUMMARY_ENABLED=true
   

3. 像往常一样在 Claude Code 中使用 search_chats。聊天首次出现在结果中且没有缓存摘要时，Memex 会生成摘要。之后的搜索会立即返回缓存的摘要。

可通过环境变量配置：MEMEX_SUMMARY_MODEL（默认值为 claude-haiku-4-5-20251001）、MEMEX_SUMMARY_MAX_TOKENS（默认值为 200）。如果某个聊天的 API 调用失败（缺少密钥、触发速率限制或网络故障），该条结果不会附带摘要；搜索本身不会中止，并会记录警告。

成本模型：批量摄取包含 74 条聊天的导出内容，费用为 $0（摄取时不会生成摘要）。每条实际在搜索中打开的独立聊天费用约为 $0.01（Haiku，约 5-10k 输入 token + 约 200 输出 token）。$5 的 API 额度足以轻松支撑数月使用。

仓库关联（第 3 阶段）

Memex 可以将每段聊天关联到涉及的本地代码仓库，并在从仓库内部调用 search_chats 时提升这些聊天的排名。因此，当你向 Claude Code 提出类似“还记得我们讨论过的身份验证重构吗？”的问题时，涉及 当前 仓库的聊天会排在关键词相同但无关的聊天之前。

工作原理：

1. 注册仓库：

   uv run memex repos add /path/to/your/repo
   

   Memex 会读取 .git/config（origin URL），以及 pyproject.toml / package.json / Cargo.toml（软件包名称）。规范键优先使用 git 远程地址（在不同克隆之间保持稳定），而不是路径。

2. 对已导入的聊天执行一次性扫描：

   uv run memex repos scan
   

   系统会将每段聊天与所有已注册仓库进行匹配。匹配器使用 4 种信号（取最高值）：聊天文本中的远程 URL 字面值（置信度为 1.0）、绝对路径字面值（0.9）、按单词边界匹配的清单名称（0.8）、按单词边界匹配的显示名称（0.5）。低于 0.5 的结果会被丢弃。注册仓库后导入的新聊天会在导入时自动扫描。

3. 在 Claude Code 中，使用仓库参数进行搜索：

   search_chats(query="auth refactor", repo="d:/dionisio/memex")
   

   也可以传入 git 远程 URL，或传入 memex repos list 显示的规范键。与仓库关联的聊天，其距离会降低 0.3 * confidence。仓库之外的聊天仍会显示在较靠后的位置（这是提升排名，而不是筛选）。

CLI 辅助命令：

uv run memex repos list           # show registered repos
uv run memex repos remove <key>   # unregister + cascade-remove associations
uv run memex tag <chat-uuid> <repo-key>    # manual override (sticky vs auto-scan)
uv run memex untag <chat-uuid> <repo-key>  # remove an association

manual 标签会在后续自动扫描中保留：手动标记聊天后，匹配器不会覆盖该标签。

主动注入上下文（SessionStart hook）

Claude Code 支持在会话开始和结束时运行 shell 命令的 hook。Memex 提供了 memex session-context，专为接入 SessionStart hook 设计，这样每次在已注册仓库中启动新的 Claude Code 会话时，都会以 Markdown 内容列出最相关的历史聊天。无需查询。

要启用此功能，请在 .claude/settings.json（项目本地）或 ~/.claude/settings.json（用户全局）中添加：

{
  "hooks": {
    "SessionStart": [{
      "command": "uv run memex session-context"
    }]
  }
}

该命令会从 cwd 开始向上查找，直到找到 .git，以此自动检测当前仓库。如果该仓库已在 Memex 中注册且有关联聊天，命令就会输出一段简短的 Markdown 内容，其中包含排名靠前的 N 段聊天（默认 5 段），按 manual 优先、然后按 auto 的置信度排序。如果发生任何错误（没有 .git、仓库未注册、没有关联），命令不会向 stdout 输出任何内容（只会向 stderr 输出诊断信息），因此 hook 在这种情况下会静默地不执行任何操作。

你也可以手动运行该命令进行调试：uv run memex session-context [--repo <path>] [--limit N]。

实时捕获（第 2 阶段）

让新的 Claude.ai 聊天自动进入 Memex，而无需手动导出：

1. 在终端中启动本地 HTTP 服务器：

   uv run memex serve
   

   默认监听 127.0.0.1:5777。浏览 claude.ai 时，请保持服务器运行。启动时会打印一个访问令牌；扩展必须发送该令牌（仅靠回环 Origin 检查无法对其他本地进程进行身份验证）。随时运行 uv run memex token 可重新打印令牌。

2. 加载 Chrome 扩展：

   • 即将推出：从 Chrome 网上应用店 安装（Alpha 版正在审核中）。
   • 目前（加载未打包的扩展）：
     • 打开 chrome://extensions/
     • 启用开发者模式
     • 点击加载已解压的扩展程序 → 选择仓库中的 chrome-extension/
     • 点击 Memex 图标，并确认“Server”状态标签显示为正在响应（绿色）。

3. 将扩展与访问令牌配对。运行 uv run memex token，复制令牌值，将其粘贴到扩展弹出窗口的令牌字段中，然后点击保存令牌。每台机器只需设置一次（令牌仅对当前用户可见，并存放在数据库旁）。没有令牌时，数据导入请求会被拒绝并返回 401。

4. 导入完整历史记录（只需点击一次）。打开 claude.ai 标签页后，点击弹出窗口中的回填 claude.ai 历史记录。扩展会遍历完整的聊天列表，并将每段对话导入 Memex，跳过已建立索引且未更改的对话（因此再次运行很快；如果关闭了标签页，下次点击时会接着处理）。进度会显示在弹出窗口中。这样全新安装后无需手动导出即可搜索历史记录。

5. **之后只需使用 claude.ai。**你打开或创建的每段新聊天都会自动导入。运行 memex stats，或通过 Claude Code 调用 search_chats 进行验证。

详情请参阅 chrome-extension/README.md。

自动启动（macOS + Windows + Linux）

这样你每次登录时就不必手动运行 memex serve（memex setup 也会为你完成此操作）：

memex install-service          # default action: install
memex install-service status   # check current state
memex install-service uninstall

CLI 会根据你的操作系统调用相应的安装程序：

• macOS：为 serve 和每 15 分钟运行一次的 Claude Code 数据导入备用任务写入 launchd 代理，并通过 launchctl load 加载它们。日志位于数据目录中（从克隆仓库安装时为 <repo>/data/serve.log，从 PyPI 安装时为 ~/Library/Application Support/memex/com.memex.serve.log）。添加 --remote 也可运行 claude.ai 连接器（需要 MEMEX_REMOTE_* 配置）。请参阅持续运行。
• Windows：注册一个在登录时运行 memex serve 的计划任务（MemexServe）。无需管理员权限，不会弹出控制台窗口，关闭 VS Code 后仍会运行。日志位于 %LOCALAPPDATA%\memex\serve.log。如果服务退出，最多会自动重启 3 次。
• Linux：在 ~/.config/systemd/user/memex-serve.service 写入 systemd 用户单元，启用并立即启动。日志位于 ~/.local/share/memex/serve.log。如需在注销后继续运行：loginctl enable-linger $USER。查看状态：systemctl --user status memex-serve。

从 pip/pipx 安装（未克隆仓库）时，memex install-service 在 macOS、Linux 和 Windows 上都可使用：它会生成一个独立的代理（launchd / systemd / 登录时运行的计划任务），直接运行已安装的 memex serve，并将数据库存放在你的个人用户数据目录中。请使用 pipx（而非临时运行的 uvx），这样服务在启动时就有稳定的解释器可用。

让 Claude 主动使用 Memex

默认情况下，大模型使用工具时比较谨慎：它们倾向于先询问，再调用任何工具。如果你说 “还记得我们聊过 X 吗？”，Claude 往往会回答 “我不记得了”，而不是进行搜索。

4 个工具的文档字符串中已包含“主动使用”说明，但你可以将以下片段添加到 CLAUDE.md 中来强化这一点（为所有会话设置全局文件 ~/.claude/CLAUDE.md，或为特定项目设置本地文件 <project>/CLAUDE.md）：

## Memex: persistent memory of Claude.ai chats

There is an MCP server `memex` with 4 tools: `search_chats`, `get_chat`, `list_recent_chats`, `find_related`.
They index ALL of the user's Claude.ai history, reachable via hybrid search
(semantic + lexical FTS5).

**Operational rule:** before answering "I have no record", "I don't remember", "this is
the first time I hear about this", or anything equivalent, call `mcp__memex__search_chats`
with the relevant query. Claude Code's native memory starts clean every session; Memex
is the only path into the user's real history.

Typical triggers: "remember when...", "did I tell you about...", "we already talked about...",
"the other day we discussed...", or any reference to a project / person / decision that might
live in history.

路线图

阶段、完成标准和当前状态请参阅 ROADMAP.md（内容为西班牙语，是内部日志）。

开发日志

请参阅 DEVLOG.md，了解决策、阻碍和进展记录（西班牙语）。

灵感与参考资料

• 官方功能请求：anthropics/claude-code#12858
• Claude Historian、claude-conversation-extractor：用于 Claude Code / Desktop 历史记录的 MCP 服务，可作为工具结构的参考。
• claude-conversation-export：采用相同捕获策略的 Claude.ai 导出工具，可用于补录历史记录。
• SyncChat 项目的衍生项目。

许可证

MIT。