Engram

Engram

engram 是一种假设的记忆在神经组织中的物理痕迹——编码我们所学内容的生化变化。

本地优先的认知记忆系统，可将原始大模型对话历史转化为结构化、整合后的知识。与传统的对话搜索（将会话视为待检索文档）不同，Engram 模仿人类记忆架构：情景记忆会被捕获，并在“梦境状态”处理中整合为语义知识；通过图分析浮现的新兴联系——这很像 Zettelkasten 的反向链接揭示出内容地图，而这些地图并非任何单条笔记事先预料到的。

专为 Claude Code 和其他大模型 Agent 设计的 MCP 服务，并提供 CLI 和 Web 可视化界面。

安装与首次运行

先决条件

• Node.js 22 或更高版本（node --version）
• macOS、Linux 或 Windows，适用于 CLI、MCP 服务和 Web 可视化工具。计划任务式后台整合均提供各自平台的安装程序（launchd、systemd 用户计时器、Task Scheduler）；请参阅下方的平台对照表。
• 如果希望 engram sync 从 ~/.claude/projects 导入对话历史，则需要 Claude Code
• 至少配置一个用于提取和梦境整合的大模型提供商（请参阅配置）。搜索、remember 和 Web 可视化工具无需配置大模型提供商即可使用。

快速开始——三个命令

npx @devinmlowe/engram preflight    # is this node/platform/arch/libc covered by prebuilt native modules? (fix per OS if not)
npm install -g @devinmlowe/engram   # puts `engram` on your PATH; the postinstall hook runs the same preflight
engram setup                        # doctor → init → sync (asked) → register every host present → install the three services → doctor --fix → one real extraction → summary

engram setup 会引导全新安装完成配置并开始运行，最后告知本次提取使用了哪个大模型层级（extraction smoke: tier=ollama memories=3）。每一步都会说明执行了什么以及对应的手动命令，因此一切操作都清晰可见。默认情况下，它会安装全部三项服务——MCP HTTP 守护进程、夜间梦境计时器和 Web 可视化工具（端口 3001，回环地址）（决策 #62）；使用 --no-daemons 或 --daemons=mcp,dream 可缩小范围，使用 --host claude 可缩小主机注册范围，使用 --no-sync / --sync 可跳过或强制索引，使用 --no-smoke 可跳过提取，使用 --yes 可自动回答脚本所需的所有问题（但不会自动确认 Linux loginctl enable-linger 提示），使用 --json 可打印结果。如果未配置大模型提供商，梦境计时器仍会安装，设置流程结束时会显示 [warn] dream timer installed but no LLM tier is reachable … 并指出需要设置的变量——退出码为 0；只有必需的 doctor 检查失败（或 init 失败）时才会以退出码 1 结束。之后，engram doctor --fix 会修复所有异常项——服务环境变量文件、node_modules 内的模型缓存、缺失的 Ollama 模型（会先询问）、已停止的 MCP 守护进程、未注册的主机——并打印每项操作对应的手动执行方式；再次运行时会提示 nothing to fix。请参阅 CLI 和 docs/api-reference.md。

手动执行相同步骤

engram mcp install claude           # registers engram with Claude Code (codex | cursor | hermes | --all); restart the host

engram mcp install <host> 会自动修改主机自身的配置文件——~/.claude.json（--project：.mcp.json）、~/.codex/config.toml、~/.cursor/mcp.json，或部署 Hermes 插件——整个过程是原子操作，修改前的内容会保存在 <file>.bak 中，不会影响其他服务，重复运行也不会产生变化。如果 HTTP 守护进程的 GET /health 有响应，它会优先使用该守护进程（http://127.0.0.1:9907/mcp），否则会回退到 stdio（node …/dist/interfaces/cli/index.js mcp，守护进程启动后会自动桥接至该守护进程），并说明所用方式及原因；--transport http|stdio 可覆盖默认选择，--dry-run 可显示路径和差异。守护进程令牌会通过环境变量引用（${ENGRAM_MCP_TOKEN} / bearer_token_env_var / ${env:ENGRAM_MCP_TOKEN}），绝不会写入配置；engram mcp status 会报告每个主机的状态、其是否指向此安装、守护进程是否有响应，以及相应变量是否已解析。请参阅下文的注册主机。 从源码安装

git clone https://github.com/devinmlowe/engram.git
cd engram
node scripts/preflight.cjs   # optional: the native-dependency verdict before anything is installed
npm install          # runs the same preflight as postinstall, then builds via the "prepare" script
npm link             # puts `engram` on your PATH (or run `node dist/interfaces/cli/index.js` directly)

无论哪种方式，都请继续执行 engram setup——也可以逐步操作：

engram preflight     # prebuilt / compiled locally / unsupported per native module, with the fix for this OS
engram doctor        # node, platform/arch, native modules, model cache, ollama tier, llm providers, data dir, env file, install path, mcp daemon, hosts, extraction smoke — all [ok]?
engram doctor --fix  # apply the known remediations (env file, durable model cache, ollama pull with confirmation, start a stopped daemon, register a host) and re-check
engram init          # creates engram.db in the data dir (default ~/.local/share/engram; see Configuration) and downloads the embedding model
engram sync          # index conversations from ~/.claude/projects (optional)
engram search "what did I decide about caching"
engram mcp install --all   # from a checkout: register every host present (~/.claude, ~/.codex, ~/.cursor, ~/.hermes)
scripts/install-mcp-daemon.sh install; scripts/install-daemon.sh install; scripts/install-visualizer.sh install   # the three services (what setup runs)

engram doctor 最后会显示一行 extraction smoke：在 60 s 的预算和受限输入下，对最近一次对话进行一次真实提取（如果尚未建立索引，则使用内置 fixture），并报告 tier=<ollama|openai|openrouter|anthropic> memories=N；如果没有任何层级响应，则报告每个层级的原因。从真实对话中提取的记忆会像其他记忆一样写入，并标记为 source=smoke（使用 engram memories list 查找，使用 forget 删除）；fixture 永远不会写入。--no-smoke 会跳过此操作；--strict 会在任何一行不是 [ok] 时以状态码 1 退出（CI）。

首次运行时会下载模型一次。 engram init（或首次搜索）会将数百 MB 的模型权重下载到 ~/.local/share/engram/models（或 $ENGRAM_MODEL_CACHE_DIR / $HF_HOME/hub），重新安装和升级后仍会保留；请参阅模型缓存。 设置 ENGRAM_RERANK_ENABLED=false 可跳过重排序模型。

安装为 Claude Code 插件（推荐）

无需克隆，也无需绝对路径。在 Claude Code 中：

/plugin marketplace add devinmlowe/engram
/plugin install engram@engram

此仓库本身就是一个市场（.claude-plugin/marketplace.json）；该插件（.claude-plugin/plugin.json）会将已发布的 npm 包作为 stdio MCP 服务运行—— npx -y @devinmlowe/engram@<version> mcp，版本固定为对应的发布版本——并添加 /engram:recall、/engram:remember、/engram:explore-graph、/engram:reflect 和 /engram:engram-connect 命令（打包自 commands/；其工具为 mcp__plugin_engram_engram__<tool>）。/mcp 应列出包含 16 个工具的 engram；首次 recall 会下载一次嵌入模型（见上方说明）。插件通过市场更新（发布后执行 /plugin update engram@engram）；engram update 仍负责处理 CLI、守护进程和 Hermes 插件。

首次启动会很慢。 首次运行 npx 会将软件包及其预构建的原生模块安装到 npm 缓存中——每个固定版本只需安装一次，之后便会命中缓存。如果 Claude Code 在安装期间提示服务超时，请增大其启动超时时间（毫秒）： MCP_TIMEOUT=120000 claude。有两种预热方式：先运行 npm install -g @devinmlowe/engram，这样软件包（以及 engram doctor/engram init）就已安装在本机；或者运行 HTTP 守护进程（见下文的 scripts/install-mcp-daemon.sh install）——此时 engram mcp 会桥接到该守护进程，宿主进程不会打开数据库或加载模型（请参阅传输方式）。

注册宿主（engram mcp install）

engram mcp install claude            # ~/.claude.json  (--project: ./.mcp.json)
engram mcp install codex             # ~/.codex/config.toml  (--project: ./.codex/config.toml)
engram mcp install cursor            # ~/.cursor/mcp.json  (--project: ./.cursor/mcp.json)
engram mcp install hermes            # deploys interfaces/hermes-plugin to ~/.hermes (+ profiles that already have it)
engram mcp install --all --dry-run   # every host whose config dir exists; print path + unified diff, write nothing
engram mcp status                    # registered? this install? daemon answering? ENGRAM_MCP_TOKEN resolving?
engram mcp uninstall codex           # removes only the engram entry; <file>.bak keeps the previous content

决策逻辑：如果守护进程响应 /health，则使用 HTTP；否则使用 stdio（#51）；令牌通过环境变量引用，除非传入 --inline-token，否则绝不会写入文件（#52）。安装了 Claude Code 插件后，mcp install claude 会跳过用户级配置项（否则会重复注册该服务），除非使用 --force；mcp status 会将插件列为已注册的 Claude 宿主。通过 GUI 启动的宿主不会继承 fish/zsh 登录 shell，因此当守护进程需要令牌时，mcp status 会显示对应平台的修复方法（macOS 上的 launchctl setenv ENGRAM_MCP_TOKEN …、Linux 上的 ~/.config/environment.d/、Windows 上的 setx）。不会重启任何宿主进程，且该命令除回环探测外不需要网络连接。

手动配置（如果你更愿意自行编辑文件）

将服务添加到 Claude Code MCP 配置（~/.claude.json，或项目级 .mcp.json）中。 从 npm 安装：

{
  "mcpServers": {
    "engram": { "command": "npx", "args": ["-y", "@devinmlowe/engram", "mcp"] }
  }
}

或者，如果是源码检出，则使用绝对路径指向编译后的服务：

{
  "mcpServers": {
    "engram": {
      "command": "node",
      "args": ["/absolute/path/to/engram/dist/interfaces/mcp/server.js"],
      "env": {}
    }
  }
}

此仓库随附的 .mcp.json 使用相同配置，但采用仓库相对路径；在 Claude Code 中打开 engram 检出目录时会自动加载（它用于开发 engram；插件不会使用它）。

可选：后台整合与可视化

./scripts/install-mcp-daemon.sh install  # MCP HTTP daemon on 127.0.0.1:9907 via launchd (what the Hermes plugin talks to)
./scripts/install-daemon.sh install      # nightly `engram dream` at 02:00 via launchd
./scripts/install-visualizer.sh install  # macOS launchd visualizer

在 Linux 上，同一组脚本会检测 uname -s，并改为安装 systemd 用户单元 （无需 root；如果希望它们在注销后继续运行，请执行 loginctl enable-linger $USER）：

./scripts/install-mcp-daemon.sh install  # renders systemd/engram-mcp.service, enables it (Restart=always)
./scripts/install-mcp-daemon.sh status   # unit state, GET /health, effective data dir, last log lines
./scripts/install-daemon.sh install      # renders systemd/engram-dream.{service,timer}, enables engram-dream.timer
./scripts/install-daemon.sh status       # systemctl --user list-timers + last log lines
./scripts/install-daemon.sh run-now      # systemctl --user start engram-dream.service

macOS/Linux：MCP HTTP 守护进程生命周期

scripts/install-mcp-daemon.sh 与 Windows 版本的六个动词相同 （install、uninstall、start、stop、restart、status）。它会根据 当前运行目录中的代码库生成 launchd/com.engram.mcp.plist（macOS）或 systemd/engram-mcp.service（Linux），构建 dist/，并等待 GET /health 返回后再报告成功。该服务运行 scripts/run-mcp-daemon.sh，后者会加载 ~/.config/engram/env（在 install 时创建，权限模式为 600），因此 ENGRAM_DATA_DIR、ENGRAM_MODEL_CACHE_DIR、ENGRAM_HTTP_WORKERS 和 ENGRAM_MCP_PORT 均可更改，而无需重新生成任何文件。安装程序解析出的 数据目录也会写入服务配置，因此守护进程和 CLI 不会打开不同的数据库； status 会显示该目录，并在旧路径下存在第二个 engram.db 时发出警告。 install 会停止占用端口的非托管进程，并停用 0.1.x 文档中的手写 ai.hermes.engram-mcp LaunchAgent（文件会重命名为 *.retired-by-engram，不会删除）。 engram doctor 会将相同的 /health 探测作为其 mcp daemon 检查项报告。

在 Windows 上，请使用内置的按用户配置的任务计划程序适配器：

.\scripts\install-daemon.ps1 install -PersistEnv   # daily 02:00 task running the compiled CLI with the resolved node.exe
.\scripts\install-daemon.ps1 status
.\scripts\install-visualizer.ps1 install
.\scripts\install-visualizer.ps1 status
.\scripts\install-mcp-daemon.ps1 install           # per-user Task Scheduler task for the MCP HTTP daemon (loopback only)
.\scripts\install-mcp-daemon.ps1 status

Windows：MCP HTTP 守护进程生命周期

scripts/install-mcp-daemon.ps1 会注册一个按用户配置的任务计划程序任务 \Engram\MCP，该任务在登录时启动，并使用 node.exe 和编译后的 dist\interfaces\mcp\server.js 的绝对路径运行 scripts/run-mcp-daemon.ps1。 服务器按设计绑定到 127.0.0.1:9907——它没有身份验证，也绝不会绑定到 其他地址，因此该任务不会将 MCP 端口暴露到网络。

六个动词，与其他安装程序的形式相同：install、uninstall、 start、stop、restart、status。status 会同时报告任务 计划程序状态，以及对守护进程执行的实时 GET /health 检查。

进程清理：运行器会将自身的 PID 和子进程 node.exe 的 PID 写入数据目录下的 文件；stop 和 uninstall 会使用 taskkill.exe 结束这些 PID 对应的进程树， 然后按命令行扫描并清理任何残留的 node.exe 或 run-mcp-daemon.ps1 进程， 因此即使 PID 文件过期或缺失，也不会留下孤立进程。

故障后重启在两个层面都有上限：运行器会在 600 秒内重启 5 次后放弃并以状态码 1 退出；任务计划程序本身则会以 1 分钟为间隔重试失败的任务 3 次，然后停止—— 因此，损坏的安装不会无限循环重启。服务器正常退出（状态码 0）会被视为主动停止， 不会重启。任务会继承你的用户范围环境变量（包括 API 密钥）；任务定义中不会 复制任何内容，也不会将任何内容提交到代码库。

重启冒烟测试步骤（按顺序复制并粘贴每个代码块）：

1. 安装并确认运行正常：

   .\scripts\install-mcp-daemon.ps1 install
   .\scripts\install-mcp-daemon.ps1 status   # taskState Running, healthy True
   

2. 重启 Windows 并重新登录——不要手动启动任何程序。
3. 确认任务已自行恢复运行：

   .\scripts\install-mcp-daemon.ps1 status   # taskState Running, healthy True
   curl.exe http://127.0.0.1:9907/health     # { "status": "ok", ... }
   

4. 确认 MCP 握手正常——先执行 initialize，再发送 initialized 通知，然后调用 tools/list，并在每次调用中传递 Mcp-Session-Id 响应 标头：

   curl.exe -s -D headers.txt -o init.json http://127.0.0.1:9907/mcp `
     -H "Content-Type: application/json" `
     -H "Accept: application/json, text/event-stream" `
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0"}}}'
   $sid = (Select-String -Path headers.txt -Pattern '^Mcp-Session-Id:\s*(\S+)').Matches.Groups[1].Value
   
   curl.exe -s http://127.0.0.1:9907/mcp `
     -H "Content-Type: application/json" `
     -H "Accept: application/json, text/event-stream" `
     -H "Mcp-Session-Id: $sid" `
     -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
   
   curl.exe -s http://127.0.0.1:9907/mcp `
     -H "Content-Type: application/json" `
     -H "Accept: application/json, text/event-stream" `
     -H "Mcp-Session-Id: $sid" `
     -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
   

5. 确认 Codex/Claude Code 无需手动启动 Node，就能通过同一 服务执行 recall 和 remember。
6. 停止服务并确认没有 MCP 进程残留：

   .\scripts\install-mcp-daemon.ps1 stop
   Get-CimInstance Win32_Process -Filter "Name = 'node.exe'" | Where-Object CommandLine -like '*mcp\server.js*'   # empty
   

7. 卸载并确认只剩下可视化工具任务：

   .\scripts\install-mcp-daemon.ps1 uninstall
   Get-ScheduledTask -TaskPath '\Engram\'   # lists Visualizer, not MCP
   

所有可视化工具路径都会在环回地址 http://127.0.0.1:3001 上运行同一个编译后的 Node 服务器， 并将日志写入 engram 数据目录；所有 dream 路径都会运行 node dist/interfaces/cli/index.js dream，并将日志写入 <data dir>/logs/dream.log。 安装脚本会根据你运行脚本时所在的检出目录渲染 launchd/*.plist（macOS）或 systemd/engram-{mcp,dream}.service（Linux），无论该目录位于何处；并使用找到的任意 node（fnm、Homebrew、nvm 或系统版本）。dream 守护进程从 ~/.config/engram/env 读取 API 密钥（权限模式为 600，由安装脚本创建并附带注释模板；支持 $XDG_CONFIG_HOME）——plist 本身绝不包含密钥。 如果你在该文件创建之前就已安装，请将密钥移至该文件并重新运行 install；具体步骤请参阅 scripts/README.md。

每个脚本都会预先检查所需的外部工具，并指出需要安装哪些工具。可视化工具的安装脚本会使用 node（或通过 /api/health 使用 curl）探测端口；只有在已安装 lsof 时才会将其用作可选的快速检查；Claude Code 压缩后钩子 （scripts/compact-dream.sh）和 Hermes 心跳摘要（scripts/commitments-surface.sh） 只需要 node；该钩子支持 ENGRAM_DATA_DIR / ENGRAM_LOGS_DIR。没有脚本需要 jq 或 python3。

支持的平台

组件	macOS	Linux	Windows
CLI（engram init/sync/search/dream）	支持	支持	支持
MCP 服务（stdio + HTTP）	支持	支持	支持
Web 可视化工具（node dist/interfaces/web/server.js）	支持	支持	支持
可视化工具常驻服务	launchd（scripts/install-visualizer.sh）	使用你自己的监督程序运行（systemd 用户单元、pm2）	任务计划程序（scripts/install-visualizer.ps1）
每晚 dream 守护进程	launchd（scripts/install-daemon.sh）	systemd 用户定时器 engram-dream.timer（scripts/install-daemon.sh）	任务计划程序（scripts/install-daemon.ps1）
MCP HTTP 守护进程常驻服务（--http --port 9907）	使用你自己的监督程序运行（launchd Agent、KeepAlive）	使用你自己的监督程序运行（systemd 用户单元）	任务计划程序（scripts/install-mcp-daemon.ps1）
Claude Code 钩子（scripts/*.sh）	支持	支持（bash、node）	仅限 WSL 或 Git Bash

支持的平台／架构组合

Engram 依赖三个原生／预编译链：better-sqlite3、sqlite-vec（alpha；仅提供平台软件包）和 onnxruntime-node（由 @xenova/transformers 引入）。只有当这三者都为你的 process.platform、process.arch 和 libc（Linux 上的 glibc 或 musl）提供预编译二进制文件时，Engram 才能运行；自 better-sqlite3 13 起，所有链都采用 N-API，因此只要 Node 版本 ≥ 22，主版本便不再重要。 下表由 scripts/preflight.cjs 生成，preflight 和 engram doctor 都会查询同一张表；当两者不一致时，测试会失败：

目标	设备	better-sqlite3	sqlite-vec	onnxruntime-node	Engram
darwin-arm64	Apple 芯片 Mac	预编译	预编译	预编译	支持（CI：macos-latest）
darwin-x64	Intel Mac	预编译	预编译	预编译	支持
linux-arm64	64 位 ARM Linux（glibc）：Graviton、Raspberry Pi OS 64 位版、Apple 芯片虚拟机	预编译	预编译	预编译	支持（CI：ubuntu-24.04-arm）
linux-x64	x86-64 Linux（glibc：Debian、Ubuntu、Fedora 等）	预编译	预编译	预编译	支持（CI：ubuntu-latest）
linuxmusl-arm64	64 位 ARM Alpine / musl	预编译	—	—	不支持
linuxmusl-x64	x86-64 Alpine / musl（node:*-alpine 镜像）	预编译	—	—	不支持（CI：node:22-alpine 容器会验证此结论）
win32-arm64	ARM 版 Windows（Snapdragon、运行 Windows 11 ARM 的 Apple 芯片虚拟机）	预编译	—	预编译	不支持（CI：windows-11-arm 会验证此结论）
win32-x64	x86-64 Windows 10/11	预编译	预编译	预编译	支持（CI：windows-latest，实验性支持）
其他任意目标	FreeBSD、32 位 x86 等	编译	—	—	不支持
每个原生依赖（better-sqlite3、sqlite-vec、onnxruntime-node）都与 N-API / Node 版本无关：同一组二进制文件适用于所有 Node 主版本 ≥ 22，包括奇数（非 LTS）主版本。由 scripts/preflight.cjs 生成，命令为 node scripts/supported-platforms.cjs --write；测试套件会运行 --check。

有三种方式可以了解当前情况：

• npx @devinmlowe/engram preflight（安装后也可运行 engram preflight；在代码库检出目录中则运行 node scripts/preflight.cjs）会为每个原生模块打印一行状态——[ok] prebuilt、[warn] compiled locally / will compile (needs python3 + C++ toolchain)、[FAIL] unsupported、[--] unknown (<reason>)——随后给出适用于你操作系统的确切修复方法（xcode-select --install、sudo apt install build-essential python3、sudo dnf install gcc-c++ make python3、apk add build-base python3、安装包含 "Desktop development with C++" 工作负载的 Visual Studio Build Tools）。判定结果来自静态目标平台表（所有原生模块都使用 N-API，因此 Node 主版本无关）；安装后，该命令还会确认已发布的二进制文件确实位于 node_modules 中（若看到 build/Release/better_sqlite3.node 而非捆绑的 prebuilds/<target>.node，则说明 node-gyp 已在本地编译）。--json 会输出结构化结果；--strict 遇到任何 [FAIL] 时会以状态码 1 退出；--expect prebuilt（或 --expect better-sqlite3=prebuilt,sqlite-vec=unsupported）会在判定结果不匹配时以状态码 1 退出，CI 正是借此检测依赖升级是否移除了预构建二进制文件。npm_config_platform / npm_config_arch / npm_config_target_arch / npm_config_libc 可用于覆盖目标平台。
• npm install 会将该预检作为非致命的 postinstall hook 运行（设置 ENGRAM_SKIP_PREFLIGHT=1 可关闭）。它绝不会导致安装失败：package.json 特意没有声明强制的 os / cpu 字段，否则会拒绝在未列出的目标平台上、但具备可用工具链的用户安装。
• engram doctor 会运行完整的构建后检查；其 better-sqlite3 和 sqlite-vec 状态行会以 prebuilt — … 或 compiled locally — … 结尾。这能区分升级时静默回退到 node-gyp 编译的情况，以及使用了预构建二进制文件的情况（通常是离线或代理安装，或设置了 npm_config_build_from_source 所致）。

注意事项：Windows ARM、armv7 和 Alpine/musl。 sqlite-vec 不为 win32-arm64 或 linux-arm（armv7）发布二进制文件；它的 Linux 构建（与 onnxruntime-node 一样）仅支持 glibc（需要 ld-linux，即使安装了 gcompat，也无法在 musl 上加载）。better-sqlite3 本身为 win32-arm64 和 musl 提供预构建二进制文件（13.x 移除了 32 位 linux-arm 预构建版本，因此 armv7 会从源代码编译），所以 npm install 会成功，但随后 engram init 会在加载 sqlite-vec 时失败；预检会提前报告 [FAIL] sqlite-vec: unsupported。在 Windows ARM 上，实用的解决办法是安装 x64 版 Node.js：Windows 11 会通过仿真运行该版本，并可加载 win32-x64 预构建二进制文件（速度较慢，CI 未覆盖）。在 armv7 开发板上，请使用 64 位操作系统镜像（linux-arm64）。在 Alpine 上，请使用 glibc 镜像（node:22-bookworm-slim）。 npm 10 仍会为 better-sqlite3 13 运行 node-gyp。 该软件包内置了二进制文件，但锁文件没有包含其 gypfile: false，因此 npm 10（Node 22 自带的 npm）仍会在安装时隐式运行 node-gyp rebuild。当内置预编译文件匹配时，binding.gyp 不会编译任何内容，但 node-gyp configure 仍需要 Python 3 和 Node 头文件——每个 Node 版本都会从 nodejs.org 下载一次（缓存于 ~/.cache/node-gyp），因此离线或使用代理的安装可能会在目标已有预编译文件时失败。在 Windows 上，这意味着安装 Node 22 需要 node-gyp 能识别的 Visual Studio（2019/2022 Build Tools，并安装 C++ 工作负载）以及 Python 3，因为 node-gyp configure 会在读取 binding.gyp 之前报错 could not find a version of Visual Studio 2017 or newer——CI 的 windows-latest, node 22 作业就展示了这一点。npm 11（Node 24，或在 Node 22 上运行 npm install -g npm@11）会跳过该脚本，因此这是最简单的解决方法。无论哪种情况，预检都会报告 [ok] better-sqlite3: prebuilt — prebuilds/<target>.node is bundled in the package。

其他情况下所需的工具链。 如果目标平台（不在表格中的平台，例如 armv7 或 FreeBSD）没有 better-sqlite3 的预编译文件，npm install 会使用 node-gyp 从源代码编译，这需要 C++ 工具链和 Python 3：

• Windows：安装 Visual Studio 2022 Build Tools，并选择“使用 C++ 的桌面开发”工作负载（MSVC 编译器 + Windows SDK）以及 Python 3。node-gyp 会自动找到它们；如果它选错了 Visual Studio，请运行 npm config set msvs_version 2022。
• Linux：需要 gcc/g++、make 和 python3——Debian/Ubuntu 使用 sudo apt install build-essential python3；Fedora 使用 sudo dnf install gcc-c++ make python3；Alpine 使用 apk add build-base python3。
• macOS：Xcode Command Line Tools（xcode-select --install）。

CI 会在 Node 22 和 24 上为 x64 Linux、arm64 Linux（ubuntu-24.04-arm）、arm64 macOS 和 x64 Windows（实验性）运行 lint 和完整测试套件；还会在每个平台上运行 preflight --strict --expect prebuilt，确保依赖升级导致预编译文件缺失时，问题会在 CI 中而非用户的机器上暴露；并会在 windows-11-arm 和 node:22-alpine（musl）容器中验证文档所述的不支持结论。Dependabot 会将原生模块升级分别分组，并为其添加 native-dep 标签，以便人工审查预编译文件。

核心原则

记忆不是搜索

Engram 是一个认知系统——它会提取含义、归纳模式、检测矛盾，并呈现涌现出的关联。原始对话是输入，而非输出。

Token 纪律

记忆注入必须精准。检索到的记忆会限制在调用方指定的 token 预算内，按首因位置格式化，并通过渐进式披露交付——先提供指针，仅在请求时提供完整内容。

涌现式发现

如同 Zettelkasten，价值在于连接。机会式双向链接、随着图密度增长而涌现的内容地图，以及充当图书管理员的梦境状态守护进程，都会发现整个集合中的模式。

本地优先，支持离线

所有处理都在本地运行。除用于提取/摘要的可选 API 调用外，不依赖云服务（可替换为通过 Ollama 运行的本地模型，以实现真正的离线运行）。

架构

四个领域共用核心基础设施：

• episodic/ — 对话档案的导入、索引和情景搜索
• semantic/ — 知识提取、归纳和语义搜索
• graph/ — 实体/关系图、主题簇、文件结构索引和图遍历
• dream/ — 自主归纳流水线（导入 → 提取 → 归纳 → 反思 → 剪枝）
• interfaces/ — CLI、MCP 服务和 Web 可视化
• _core/ — 共享基础设施（配置、db、类型、嵌入、搜索、llm、缓存）
• decisions/ — 架构决策记录

MCP 服务

用于大模型 Agent 记忆操作的 16 个工具：

工具	用途
recall	混合搜索（向量 + FTS5 + 图谱），支持令牌预算；强化返回的记忆（FSRS 记录，reinforce: false 可关闭），并接受每次调用的 scope / read_scopes
remember	存储单条记忆（事实、决策、模式等）
show	检索完整对话或记忆上下文
explore	从某个实体开始进行固定深度的图遍历；遵循每次调用的 scope / read_scopes（#25）
reflect	图分析——社群、桥接关系、时间模式
recall_session	带会话跟踪和预算的有状态迭代搜索
recall_drill	深入检索特定搜索结果，并扣减预算
explore_selective	由模型指定并带相关性筛选的选择性图遍历；遵循 read_scopes
remember_batch	批量记忆导入，并进行实体关联和去重
fetch_snippets	获取多个范围的文件片段（最多 20 个范围）
index_file_structure	将文件结构解析为图实体（支持多种语言）
scan_file	基于正则表达式扫描文件，并检测函数上下文
commitments	列出跟踪中的承诺（他人做出的承诺、意向、待跟进事项）——逾期事项优先；遵循 read_scopes
commitments_update	将承诺标记为已完成、已放弃或已被取代
ingest_turn	记录外部 Agent 会话中的一轮用户/助手对话（session_id、turn_index、scope、user_text、assistant_text）——幂等地更新插入到情景层；提取的记忆继承该范围
forget	删除用户指出有误或过时的记忆（#55）：memory_id（每个返回的 <semantic> 上的 id）可在一次调用中直接执行；query 会返回带 ID 的候选项，只有在设置 confirm: true 且匹配项明确唯一时才会执行。软删除保留 ENGRAM_FORGET_RETENTION_DAYS 指定的天数（立即移除向量/FTS 行，以客户端名称记录变更日志，不会被 dream 重新提取）；hard: true 会直接删除；遵循 read_scopes；只有在服务器环境未固定读取范围时，scope: "global" 才会覆盖该设置（#109）

传输方式：stdio（默认）和 HTTP

dist/interfaces/mcp/server.js（以及插件运行的 engram mcp）默认使用 stdio，这也是“安装与首次运行”中的 .mcp.json 示例所使用的方式。使用 --http 启动即可改用 Streamable HTTP：

node dist/interfaces/mcp/server.js --http            # http://127.0.0.1:9907/mcp
node dist/interfaces/mcp/server.js --http --port 9910

HTTP 模式会开放 POST /mcp（每个客户端对应一个 MCP 会话，通过 Mcp-Session-Id 标头路由）以及返回 JSON 的 GET /health。它只绑定到 127.0.0.1。将任何支持 Streamable HTTP 的客户端指向该服务：

{ "mcpServers": { "engram": { "type": "http", "url": "http://127.0.0.1:9907/mcp" } } }

（当守护进程响应 /health 时，engram mcp install <host> 会准确写入这些内容；如果配置了令牌，还会写入令牌标头引用。）

在 HTTP 模式下，每次工具调用都在 node:worker_threads 池中运行，因此耗时数秒的 recall 不会阻塞 /health、握手或其他客户端。 每个工作线程都有自己的 SQLite 连接和嵌入模型。stdio 模式 不会启动工作线程。

stdio 会桥接到正在运行的守护进程。 启动 stdio（engram mcp、插件的 npx 命令、node dist/interfaces/mcp/server.js）时，会先探测 GET http://127.0.0.1:<port>/health（依次使用 --port、ENGRAM_MCP_PORT，否则为 9907， 超时时间为 1.5 秒）。如果 engram 守护进程有响应，该进程会作为轻量代理运行——它既是连接守护进程 /mcp 的 MCP 客户端，也是通过 stdio 转发 tools/list、tools/call 和 ping 的 MCP 服务——且不会打开数据库或加载 嵌入模型；因此所有主机都会共用一个已预热的守护进程。stderr 会输出一行说明运行方式：

Engram MCP: bridging stdio to http://127.0.0.1:9907/mcp (daemon healthy)
Engram MCP: running inline (no daemon on :9907 (ECONNREFUSED))

engram mcp --standalone（或在服务的环境中设置 ENGRAM_MCP_STANDALONE=1） 会强制以内联模式运行；在该环境中设置 ENGRAM_SCOPE / ENGRAM_READ_SCOPES 也会如此（它们限定的是此进程的范围；守护进程会忽略它们，#87）。设置了 ENGRAM_DB_PATH 时，只有守护进程的 /health 报告相同的 dbPath，才会使用桥接。守护进程需要令牌时，桥接会转发其自身环境中的 Authorization: Bearer $ENGRAM_MCP_TOKEN，并以宿主的 clientInfo 重新打开其守护进程会话（因此 forget 仍会记录真实操作者）；守护进程重启（engram update）后，桥接也能通过一次重连恢复运行。

变量	默认值	用途
ENGRAM_HTTP_WORKERS	2	HTTP 模式下的工作线程数（0 = 在主线程中内联运行工具调用）
ENGRAM_WORKER_TIMEOUT_MS	8000	每次调用的超时时间；remember、remember_batch、index_file_structure 和 reflect --refresh 的超时下限更高。工作线程在超时时间的 2 倍内仍无响应时，会被终止并重新启动
ENGRAM_MCP_TOKEN	—	设置后，/mcp 需要 Authorization: Bearer <token>（否则返回 401）；/health 仍向监管程序开放。守护进程只能在绑定到回环地址时运行；要绑定其他地址，必须设置此变量
ENGRAM_MCP_HOST	127.0.0.1	绑定地址。除非设置了 ENGRAM_MCP_TOKEN，否则拒绝绑定到任何非回环地址
ENGRAM_MCP_STANDALONE	—	设为 1 后，即使守护进程运行正常，通过 stdio 启动也会以内联模式运行（与 --standalone 相同）

身份验证。 默认情况下，两个 HTTP 服务都依靠绑定到回环地址来控制访问： 任何可以访问 127.0.0.1 的人（其他本地用户、反向代理）都拥有对记忆存储的完整读写权限。设置 ENGRAM_MCP_TOKEN（受监管的守护进程需在 ~/.config/engram/env 中设置） 即可要求提供 Bearer 令牌；Streamable-HTTP 客户端会通过标头发送令牌，例如： { "type": "http", "url": "http://127.0.0.1:9907/mcp", "headers": { "Authorization": "Bearer <token>" } }， Hermes 插件则从 engram.json 中的 token 读取令牌。engram mcp install 不会写入令牌的实际值，而是引用变量（Claude Code 使用 Bearer ${ENGRAM_MCP_TOKEN}， Codex 使用 bearer_token_env_var，Cursor 使用 Bearer ${env:ENGRAM_MCP_TOKEN}），因此密钥会保留在 ~/.config/engram/env 中——如果宿主环境未解析该变量，engram mcp status 会提示你。令牌采用恒定时间比较，且绝不会写入日志。可视化工具使用 ENGRAM_WEB_TOKEN（若未设置，则使用 ENGRAM_MCP_TOKEN）； 请参阅Web 可视化。

有关工作线程池的内部实现（worker-pool.ts、dispatch.ts、worker.ts），请参阅 CLAUDE.md 中的“MCP Server Transports”一节。

集成其他 Agent（Codex CLI、Cursor、自定义宿主）

engram mcp install codex / cursor 会注册 MCP 工具（参见 注册宿主）；运行 engram mcp install codex && engram mcp install cursor 后，两个宿主会使用同一个 engram.db，因此在 Codex 中执行的 remember，也可以从 Cursor 中通过 recall 获取。有关自动回忆钩子和指令块， docs/integrate-your-agent.md 旨在交给运行在你要连接的宿主中的 AI Agent 使用。该文档说明了公开约定（端点、握手、工具、范围限定），以及要实现的三种行为（每轮对话前自动回忆、显式 MCP 工具、通过 remember 捕获信息），并提供验证步骤和一个完整的 Codex CLI 示例。interfaces/hermes-plugin/ 中的 Hermes Agent 提供程序是参考实现。

更新现有安装

你的数据位于仓库之外（engram doctor 会打印实际使用的数据目录和数据库），数据库每次打开时都会运行增量式架构迁移，而 engram update 会完成其余工作——每个平台只需一条命令：

engram update --check   # current vs available (git tag or npm dist-tag), nothing else; cached 24 h
engram update --plan    # read-only: install kind, every dir holding an engram.db, model cache,
                        # every service and how it will be restarted, plugin deploy targets
engram update           # the controlled upgrade (asks once; --yes for scripts, --no-backup to skip the backup)
engram update --rollback            # undo the last update: previous code back, services restarted, verified
engram update --rollback --restore-data   # …and put the pre-update backup of the data dir back

engram update --plan    # identical on Windows (Task Scheduler tasks under \Engram\)
engram update --yes

每次运行会依次执行以下操作（--plan 输出的就是此列表，其中会填入你机器上的路径）：

1. 备份 数据目录（engram.db、-wal/-shm 和 archive/），先检查点处理 WAL，再备份到同级目录 <data dir>.backup-<timestamp>。
2. 停止 通过监管程序运行的所有 engram 服务：先停止 dream，再停止 MCP HTTP 守护进程，然后停止可视化工具（launchd / systemd 用户单元 / Task Scheduler）。如果某个守护进程能在其端口上响应，却没有监管程序，则会阻止更新：请手动停止它，或先安装监管程序。
3. 快照 记录行数（engram stats --json）。
4. 模型缓存：如果旧版 0.4.0 之前的缓存仍位于 node_modules/@xenova/transformers/.cache，请在 npm 操作 node_modules 之前，将其移到解析后的缓存目录（默认为 <data dir>/models）。models/ 不会备份（可重新下载）；如果回滚时缓存缺失，会重新下载。
5. 代码：对于检出版本，运行 git pull --ff-only + npm ci（工作树有未提交更改会阻止更新）；对于 npm 安装，运行 npm install -g @devinmlowe/engram@<version>。
6. 迁移：如果旧版 0.2.0 之前的数据目录中有唯一的数据库，则将该目录移到解析后的目录中（如果两个目录中都有数据库，则拒绝迁移）；然后用新构建版本打开一次数据库，以运行架构迁移。
7. 重启 MCP 守护进程，然后重启可视化工具，并逐个等待 /health 响应；重新启用 dream 计划任务；将 Hermes 插件（interfaces/hermes-plugin/deploy.sh）重新部署到每个安装了该插件的配置文件——这会重启各网关。（Claude Code 插件不会受影响：它会通过 marketplace 和 /plugin update engram@engram 更新；与旧守护进程通信的 stdio 桥接程序会重新连接到新守护进程。）
8. 验证：运行 engram doctor，检查 /health，并确认 engram stats 的行数没有减少。如果代码切换后的某一步失败，运行会提供下方的回滚操作：使用 --yes 会执行回滚；在终端中会提示 Roll back to <previous>? [y/N]；脚本若未使用 --yes，则会显示要运行的确切命令。无论发生什么，服务都会重新启动。

回滚

在进行任何更改之前，engram update 会在 <data dir>/updates/<stamp>.json 记录回滚计划（保留最近 10 份； engram update --list-rollbacks 会列出这些计划）：先前的版本和 git sha、安装类型和根目录、备份目录、正在运行的服务及其启动命令、 插件部署目标、目标版本、数据库的架构版本、更新前的行数，以及一个 每完成一步都会推进的 progress 标记——因此，即使更新在第 1 步中止，该文件也会存在，回滚也能知道更新进行到了哪一步。

engram update --rollback                  # the most recent plan; --rollback <stamp> for an older one
engram update --rollback --restore-data   # also restore the backup (everything written since is discarded)

默认情况下，回滚仅回退代码（决策 #66）：停止服务 → git checkout <previous sha> && npm ci 或 npm install -g @devinmlowe/engram@<previous> → 在子进程中使用已恢复的构建执行 engram migrate schema → 重启之前正在运行的服务 → 执行相同的验证（版本、doctor、/health、 行数不少于快照）。engram.db 会保留更新后写入的所有内容：架构迁移只会添加内容，因此先前的构建能够读取较新的数据库，并忽略自己不认识的列和表（会打印这一注意事项）。只有使用 --restore-data 时才会恢复备份；或者，当触发回滚的验证失败显示行数低于更新前的快照时，会自动恢复——绝不会悄无声息地恢复。--restore-data 会还原 engram.db + WAL + archive/（合并 archive，以备份为准）；如果更新时使用了 --no-backup，则会拒绝此操作。每次回滚都会打印所执行的模式，并说明备份不包含 models/（#54）。如果某个版本发布了旧版构建无法读取的迁移（src/_core/db/schema.ts 中的 BREAKING_MIGRATIONS，目前为空），则会拒绝跨越该迁移进行仅回退代码的回滚，并说明原因；仍可使用 --restore-data。

哪个 engram 会运行？

两个全局目录树——Homebrew 的 node 和 nvm 的 node 各自都有一个 bin/engram——意味着 npm i -g 升级其中一个时，你的 shell 仍在运行另一个。 engram doctor 有一项 install path 检查，会列出 PATH 中的每个 engram，并在存在多个，或第一个不是 engram update 会升级的那个安装时发出警告（[--]，不会判定为失败），同时给出修复方法（使用另一个目录树的 npm 执行 npm uninstall -g @devinmlowe/engram，或调整 PATH 顺序）。engram update --plan 也会打印相同的警告。

每日版本通知

engram update --check 会将检查结果缓存 24 小时，存储在 <data dir>/cache/update-check.json 中。已知有新版本时，engram doctor、health、stats、 search、sync 和 reflect 会在 stderr 上输出一行 — engram 0.4.0 available (you have 0.3.0) — engram update — 每天最多刷新一次缓存（不会在使用 --json 时刷新，也不会从 MCP 服务中刷新），守护进程的 /health JSON 也会从同一缓存中附带 update: {current, available, checkedAt}。程序绝不会自动更新；ENGRAM_NO_UPDATE_CHECK=1 会禁用自动检查和通知（显式运行 engram update --check 仍会发起检查，并继续复用未过期的缓存条目）。

engram migrate [data-dir|model-cache|schema] [--dry-run] 会单独、幂等地运行第 4 步和第 6 步，适用于手动更新的安装（默认设置生效且没有遗留内容需要迁移后，model-cache 不会执行任何操作）。

请阅读 CHANGELOG.md 了解此版本的说明 — 例如，0.2.0 会在首次运行 dream 时重新提取每段对话一次（可通过 ENGRAM_DREAM_MAX_CONVERSATIONS 限制数量）。

手动更新。 如果你更愿意自行运行，可按相同步骤操作：

git fetch origin && git status --short   # resolve any local changes first
git pull origin main
npm ci                                   # exact dependencies; rebuilds via "prepare", runs the install preflight
engram migrate                           # data dir + model cache + schema (see --dry-run first)

对于 npm 安装：运行 npm install -g @devinmlowe/engram@latest，然后运行 engram migrate。

然后重启负责管理运行中进程的服务，使其加载新的 dist/ 输出（并重新部署插件 + 重启 Hermes 网关）：

平台	MCP HTTP 守护进程	Dream 守护进程	可视化工具
macOS (launchd)	./scripts/install-mcp-daemon.sh restart	launchctl kickstart -k gui/$(id -u)/com.engram.dreamstate	./scripts/install-visualizer.sh restart
Windows (Task Scheduler)	.\scripts\install-mcp-daemon.ps1 restart	.\scripts\install-daemon.ps1 restart	.\scripts\install-visualizer.ps1 restart
Linux (systemd)	./scripts/install-mcp-daemon.sh restart (systemctl --user restart engram-mcp)	systemctl --user restart engram-dream	使用你自己的服务管理器运行

只重启实际已安装的服务（每个安装脚本的 status 会显示安装状态）；手动启动的 node dist/interfaces/mcp/server.js --http 不受服务管理器管理，必须手动停止并启动，或改用 install-mcp-daemon.sh install 安装。

重启后验证：

engram doctor      # node, native modules, model cache, ollama tier, effective data dir, env file, install path, mcp daemon /health, registered hosts, extraction smoke
engram health      # database, embedding model, MCP entry point
engram stats       # counts must match the pre-update numbers
engram search "smoke test"   # end-to-end recall through the new build

Windows：安全更新和数据目录迁移

0.2.0 将 Windows 上的默认数据目录从 %USERPROFILE%\.local\share\engram 更改为 %LOCALAPPDATA%\engram。此前安装的版本会将数据库保留在旧路径；升级后，如果不迁移数据或设置 ENGRAM_DATA_DIR，每个 engram 命令和 MCP 守护进程都会在新路径打开一个全新且为空的数据库。engram update 会处理此问题（步骤 6）；如果手动更新，请先进行预检：

engram doctor --json          # "data dir" check: which engram.db this process uses, and a warning
                              # if a populated legacy database exists that it would ignore
Test-Path "$env:USERPROFILE\.local\share\engram\engram.db"   # legacy location
Test-Path "$env:LOCALAPPDATA\engram\engram.db"               # 0.2.0+ default
engram stats                  # write these counts down; they must match after the update

• 升级期间绝不要运行 engram init——它会在生效路径创建一个全新的数据库。只有在全新安装时才运行它。
• 将数据移至 %LOCALAPPDATA%\engram（使用 engram migrate data-dir，或手动移动：engram.db、 engram.db-wal、engram.db-shm、archive\、logs\），或使用用户范围环境变量将数据保留在原处：setx ENGRAM_DATA_DIR "$env:USERPROFILE\.local\share\engram" （若只指定数据库文件，则使用 ENGRAM_DB_PATH）。用户范围很重要：任务计划程序任务会继承该变量，而不是你用于安装的 shell。
• 在进行任何其他操作之前，备份活动数据目录 （Copy-Item -Recurse $dataDir "$dataDir.backup-$(Get-Date -Format yyyyMMdd-HHmm)"）。
• 默认情况下，模型权重位于 %LOCALAPPDATA%\engram\models（或 ENGRAM_MODEL_CACHE_DIR 指向的位置），因此 npm ci 永远不会删除它们。

安装与重启。 每个安装程序中的 restart 都假定对应任务已存在；较旧的安装可能有可视化工具任务但没有 MCP 任务，也可能仍在运行手动启动的 MCP 进程。请先检查并选择相应动词：

.\scripts\install-mcp-daemon.ps1 status    # installed / taskState / healthy / dataDir / dbPath / legacyDbPath
.\scripts\install-mcp-daemon.ps1 install   # no task yet (re-runnable; re-registers with the current paths)
.\scripts\install-mcp-daemon.ps1 restart   # task exists
Get-ScheduledTask -TaskPath '\Engram\'     # which of MCP, Dream, Visualizer are actually installed

只重启已安装的组件。安装程序默认使用与 CLI 解析出的相同数据目录（%LOCALAPPDATA%\engram 或 ENGRAM_DATA_DIR），并接受 -DataDir / -DbPath 显式指定路径——请传入与 CLI 和钩子相同的目录；status 会显示任务注册时使用的目录。

端口上存在过期进程。 如果 status 显示任务正在重启，或显示 healthy False，但 9907 端口仍有响应，则说明有一个监督器不负责管理的进程占用了该端口：

Get-NetTCPConnection -LocalPort 9907 -State Listen | Select-Object OwningProcess
Get-Process -Id <pid> | Select-Object Id, ProcessName, Path, CommandLine
Stop-Process -Id <pid>                                # only if it is an engram node.exe you started by hand
.\scripts\install-mcp-daemon.ps1 restart              # the task's own runner now binds the port

uninstall 和 stop 也会根据命令行扫描并清理残留的 node.exe / run-mcp-daemon.ps1 进程，因此过期的 pid 文件不会留下孤立进程。

更新后验证（证明数据已保留且服务可用）：

engram doctor                 # every check [ok]; "data dir" names the populated database
engram health
engram stats                  # counts equal the pre-update numbers
engram search "smoke test"
.\scripts\install-mcp-daemon.ps1 status    # taskState Running, healthy True
Invoke-RestMethod http://127.0.0.1:9907/health
# MCP handshake + tool listing through the daemon:
$init = @{ jsonrpc='2.0'; id=1; method='initialize'; params=@{ protocolVersion='2025-03-26'; capabilities=@{}; clientInfo=@{ name='check'; version='0' } } } | ConvertTo-Json -Depth 5
$r = Invoke-WebRequest http://127.0.0.1:9907/mcp -Method Post -ContentType 'application/json' -Headers @{ Accept='application/json, text/event-stream' } -Body $init
$sid = $r.Headers['Mcp-Session-Id']
Invoke-WebRequest http://127.0.0.1:9907/mcp -Method Post -ContentType 'application/json' -Headers @{ Accept='application/json, text/event-stream'; 'Mcp-Session-Id'="$sid" } -Body '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | Select-Object -ExpandProperty Content

如果已安装可视化工具，请运行：.\scripts\install-visualizer.ps1 status 和 Invoke-RestMethod http://127.0.0.1:3001/api/health。

CLI

engram init            # Initialize database + download embedding model
engram sync            # Ingest conversations from Claude Code projects
engram search <query>  # Hybrid search across all memory layers
engram remember <text> # Store a memory
engram extract         # LLM-based fact extraction from a conversation
engram dream           # Run autonomous consolidation pipeline (--force re-extracts unchanged conversations)
engram reflect         # Show emergent graph patterns
engram explore <name>  # Explore entity connections
engram entities        # List/search entities
engram relationships   # Show relationships for an entity
engram stats           # Database statistics (--json: the row counts `engram update` compares before/after)
engram health          # System health check (database, model, Ollama, MCP entry point)
engram doctor          # Runtime diagnostics: node, platform/arch, better-sqlite3, sqlite-vec, model cache, ollama tier, llm providers, data dir, env file, install path, mcp daemon, hosts, extraction smoke (--json, --fix [--yes], --strict, --no-smoke)
engram setup           # First run in one command: doctor → init → sync → mcp install → all three services → doctor --fix → extraction smoke → summary (--yes, --no-sync/--sync, --no-daemons/--daemons=<ids>, --host <id...>, --no-smoke, --json)
engram update          # Controlled self-update: backup, stop services, pull/npm install, migrate, restart, verify (--check, --plan, --yes, --no-backup, --rollback [stamp], --restore-data, --list-rollbacks)
engram migrate [topic] # Install/data migration: data-dir | model-cache | schema | all; idempotent, --dry-run lists every action
engram memories list|show|edit|delete|restore|purge|log  # Inspect and curate memories: provenance, edit, forget (soft delete + retention), restore, purge a conversation, change log
engram validate [--fix]  # Store integrity (embeddings, FTS, no vector/FTS rows for forgotten memories; --fix repairs)
engram backfill-event-ts  # Backfill event-time timestamps (temporal recall)
engram commitments [status]        # List tracked commitments (same XML as the MCP tool)
engram commitment-done <id>        # Mark a commitment done (--status dropped|superseded)
engram commitments-extract <conv>  # Re-scan one conversation (no checkpoint; proves dedupe)
engram export [--out f] [--scope s...] [--include-inactive] [--kinds ...]  # JSONL v1 of memories/entities/relationships/commitments (no embeddings)
engram import <file> [--scope override] [--dry-run]  # Idempotent by id (newer wins); vectors + FTS regenerated from content
engram mcp             # Start the MCP server (stdio; see Transports section)
engram mcp install <host> [--all] [--project] [--transport http|stdio] [--dry-run] [--force] [--inline-token] [--json]  # Register with claude | codex | cursor | hermes
engram mcp uninstall <host> [--project]   # Remove the engram entry (previous content in <file>.bak)
engram mcp status [--json]                # Every host: registered, this install?, daemon /health, ENGRAM_MCP_TOKEN resolves?

Web 可视化

在 localhost:3001 提供交互式知识图谱可视化：

力导向图（/graph）	深度视图（/graph/depth）
灵感来自 Obsidian 的 Canvas 2D 力导向图。节点大小按提及次数缩放（平方根比例），按实体类型着色，亮度则取决于度数。边以可配置的中心渐暗渐变效果渲染。包含提及阈值滑块、类型筛选标签、支持突出显示邻居的文本搜索、点击聚焦和拖动节点功能。	Three.js 3D 图，其中纵轴表示相关性——综合近期程度（30%）、提及频率（25%）、桥接得分（20%）、创建时间（10%）和度数（15%）加权计算。较早且连接较少的节点会沉至底部，活跃枢纽则会上升至顶部。包含将卫星节点拉向其枢纽的重力迭代，以及从第一个节点到当前状态重放图谱历史的生长动画。
星系视图（/graph/galaxy）	词云（/words）
枢纽节点（高 degree、高桥接得分和高提及次数）会成为引力中心，每个中心在 3D 空间中定义一个独特的轨道平面。卫星节点根据吸积强度（边权重）围绕其枢纽运行，并根据与邻居的 Jaccard 相似度确定位置角度。六种自定义力——枢纽排斥、卫星吸引、圆盘扁平化、轨道对齐、桥接牵引和标准斥力——共同营造出动态的太阳系隐喻。可配置枢纽阈值、圆盘平坦度和星系间距。	根据情景记忆中的用户消息构建的 D3 词云。词语大小按平方根缩放的频率设定，并通过丰富的停用词列表和十六进制哈希检测器进行过滤。采用 Catppuccin Mocha 12 色调色板、阿基米德螺旋排布和混合旋转方式（65% 水平、20% 垂直、15% 倾斜）。悬停可显示提及次数；实时轮询每 10 秒刷新一次，并在内容变化时播放脉冲动画。

• 梦境控制 — 实时跟踪流水线阶段并显示进度条（页面会轮询 /graph/api/dream/status）
• 实时更新 — 每个视图每 1.5 秒轮询一次各自的 api/diff 路由；WAL 监视器会在数据库发生变化时重置服务端缓存

启动：npx tsx src/interfaces/web/server.ts

身份验证。 默认仅限环回地址访问，且无需身份验证。设置 ENGRAM_WEB_TOKEN （或 ENGRAM_MCP_TOKEN）后，除 /api/health 外的所有路由都需要提供令牌：API 客户端需通过 Authorization: Bearer <token> 传递；也可以使用 ?token=<token> 打开任意页面一次， 服务端会为该页面的 API 调用设置 HttpOnly Cookie。若未设置令牌却将 ENGRAM_BIND 绑定到非环回地址，服务将在启动时拒绝运行。

要在 Windows 上进行持久化安装，请使用 scripts/install-visualizer.ps1。macOS 的 launchd 安装方式仍为 scripts/install-visualizer.sh。

搜索

结合三种来源并使用倒数排名融合的混合搜索：

• 向量 — 通过 nomic-embed-text（384 维）实现语义相似度，MiniLM 作为备用方案
• FTS5 — 对交流记录、记忆和实体进行 SQLite 全文搜索
• 图谱 — 实体遍历及结合关系的上下文扩展

所有搜索响应都会遵守调用方指定的令牌预算。有状态会话支持迭代优化，并跟踪预算。

Dream Pipeline

模拟人类记忆综合过程的自主整合：

flowchart LR
    subgraph dream["Dream Daemon"]
        direction LR
        I[Ingest] --> E[Extract] --> C[Consolidate] --> R[Reflect] --> P[Prune]
    end

    subgraph episodic["Episodic"]
        sync[sync]
        store[store]
    end

    subgraph semantic["Semantic"]
        extractor[extractor]
        consolidator[consolidator]
        decay[decay]
    end

    subgraph graph["Graph"]
        gextractor[extractor]
        reflection[reflection]
    end

    subgraph core["_core"]
        llm[llm]
        db[db]
        embeddings[embeddings]
    end

    I -- "discover & index\nconversations" --> sync
    sync -- "persist\nexchanges" --> store
    E -- "extract facts" --> extractor
    E -- "extract entities\n& relationships" --> gextractor
    C -- "dedup, merge,\nconflict detect" --> consolidator
    R -- "communities, bridges,\ntemporal patterns" --> reflection
    P -- "FSRS decay,\nlow-value removal" --> decay

    extractor --> llm
    gextractor --> llm
    reflection --> llm
    store --> db
    consolidator --> embeddings
    extractor --> embeddings

1. 摄取 — 通过 episodic 层同步新的对话存档
2. 提取 — 基于 LLM 提取事实（semantic），并提取实体/关系（graph）
3. 整合 — 通过 semantic 整合器和嵌入相似度去重、合并并解决冲突
4. 反思 — 通过 graph 反思检测社区、桥接实体和时间模式
5. 修剪 — 使用受 FSRS 启发的可检索性评分衰减并移除低价值记忆（semantic 衰减）

所有阶段都使用 _core 基础设施：llm 用于 LLM 调用，db 用于持久化，embeddings 用于相似度计算。

可通过 engram dream、Web UI 的 dream 按钮，或使用 scripts/install-daemon.sh（macOS 上的 launchd、Linux 上的 engram-dream.timer）/ scripts/install-daemon.ps1（Windows 任务计划程序）在每晚 02:00 运行。

技术

组件	技术
运行时	Node.js ≥ 22（TypeScript）
数据库	SQLite + WAL 模式（单文件、本地优先）
向量搜索	sqlite-vec
全文搜索	SQLite FTS5（Porter 词干提取）
嵌入	通过 @xenova/transformers 使用 nomic-embed-text
图分析	graphology（Louvain 社区、介数中心性）
LLM 提供商	Anthropic、OpenRouter、Ollama（分层级联）
MCP 服务	@modelcontextprotocol/sdk
守护进程	launchd（macOS）、systemd 用户定时器（Linux）、任务计划程序（Windows）— scripts/install-daemon.sh / .ps1

开发

npm run build        # TypeScript compilation
npm run test:run     # Run tests (vitest, 131 test files)
npm run mcp          # Start MCP server
npm run dev          # Dev CLI via tsx
npm run dream        # Run dream consolidation
npm run lint         # Type-check without emit

模型缓存

@xenova/transformers 首次使用时会下载 ONNX 模型权重（嵌入模型 nomic-ai/nomic-embed-text-v1.5、重排序模型 Xenova/bge-reranker-base，以及整合过程使用的 NLI 模型）。Engram 会将它们保存在持久目录中，目录按以下顺序确定：

1. ENGRAM_MODEL_CACHE_DIR — 任意绝对路径（共享网络卷也可以；只读路径可用于已下载的模型，但新下载会失败）
2. $HF_HOME/hub — 设置了 HF_HOME 时，使用 Hugging Face hub 缓存位置
3. <data dir>/models — 默认位置：~/.local/share/engram/models （Windows 上为 %LOCALAPPDATA%\engram\models），与 engram.db 同级

不会使用该库自身的默认目录 node_modules/@xenova/transformers/.cache/：每次 npm install、npm ci 或全局升级都会清除该目录。从会将缓存写入此目录的构建版本升级的安装，在首次加载模型时（或运行 engram init / engram migrate model-cache 时）会将权重移至确定的目录，并记录一行日志 — 不会重新下载。engram doctor 会显示正在使用的目录、该目录是否可写、durable: yes|no（仅当显式指定的路径位于 node_modules 内时才会显示 no），以及选择该目录的层级。engram update 不会备份 models/；如果缓存缺失，回滚时会重新下载。CI 会将 ENGRAM_MODEL_CACHE_DIR 固定为运行器临时目录，并在运行之间缓存该目录。

配置

所有设置都通过环境变量配置；CLI 和 MCP 服务不会读取任何配置文件。唯一的例外是 launchd dream 守护进程，其启动脚本（scripts/run-dream.sh）会加载 ~/.config/engram/env，以便 API 密钥不必写入 plist — 下方列出的任何变量都可以在该文件中设置。

变量	默认值	用途
ANTHROPIC_API_KEY	—	启用 Anthropic 提供商（大模型级联的最后一层）
OPENROUTER_API_KEY	—	启用 OpenRouter 提供商
ENGRAM_OPENAI_BASE_URL	https://api.openai.com/v1	通用 OpenAI 兼容路由：OpenAI、LiteLLM 网关（http://localhost:4000）、可自托管服务。若仅提供源站地址，则会追加 /v1
ENGRAM_OPENAI_MODEL	—	该路由提供的模型；设置后会启用 openai 层
ENGRAM_OPENAI_API_KEY_ENV	OPENAI_API_KEY	保存该路由凭据的环境变量名称。Engram 会在调用时读取该变量，绝不会存储、打印或提交其值
ENGRAM_OPENAI_TEMPERATURE	—	仅在设置后发送；通用路由默认省略 temperature，因为许多网关和推理模型不接受该参数
ENGRAM_LLM_PROVIDERS	ollama,openai,openrouter,anthropic	层级顺序，以逗号分隔。未列出的层级不会尝试；未知名称会被忽略并显示警告
ENGRAM_LLM_TIMEOUT_MS	120000	每个层级的单次请求超时时间。对于运行缓慢的本地模型，请调高此值——Apple Silicon 上的 27B 模型每次提取提示词需要 2–4 分钟；extraction smoke 的预算会相应增加
OLLAMA_HOST	http://localhost:11434	Ollama 端点；若可连接则优先使用
ENGRAM_LOCAL_MODEL	qwen2.5:7b	Ollama 模型名称（必须已在 Ollama 主机上拉取）
ENGRAM_LOCAL_MODEL_FALLBACKS	—	以逗号分隔的 Ollama 模型列表；当未拉取 ENGRAM_LOCAL_MODEL 时，按顺序尝试这些模型（例如 llama3.1:8b,qwen3:8b）
ENGRAM_OPENROUTER_MODEL	google/gemini-2.5-flash-lite	OpenRouter 模型名称
ENGRAM_DATA_DIR	平台默认值（见下文）	数据库、归档和日志的根目录
ENGRAM_DB_PATH	$ENGRAM_DATA_DIR/engram.db	SQLite 数据库位置
ENGRAM_ARCHIVE_DIR	$ENGRAM_DATA_DIR/archive	对话归档目录
ENGRAM_LOGS_DIR	$ENGRAM_DATA_DIR/logs	日志目录
ENGRAM_CLAUDE_PROJECTS_DIR	~/.claude/projects	engram sync 查找 Claude Code 对话的位置
ENGRAM_EMBEDDING_DIMS	256	Matryoshka 嵌入维度（必须与现有数据库匹配）
ENGRAM_RERANK_ENABLED	true	设置为 false 或 0 以禁用交叉编码器重排序器
ENGRAM_MODEL_CACHE_DIR	$ENGRAM_DATA_DIR/models（设置 HF_HOME 时为 $HF_HOME/hub）	模型权重的下载和缓存位置；绝不会放在 node_modules 内（见 模型缓存）
ENGRAM_SKIP_PREFLIGHT	—	设置为 1 以静默跳过 npm install 平台预检
ENGRAM_NO_UPDATE_CHECK	—	设置为 1 以禁用每日自动版本检查和“有更新版本可用”提示；engram update --check 仍会检查（见 每日版本提示）
ENGRAM_FORGET_RETENTION_DAYS	30	忘却的记忆在被彻底删除前保留的天数（不会参与召回，可恢复）；梦境清理阶段会将其彻底删除。设为 0 则在下次运行时清除。forget hard: true / engram memories delete --hard / purge --hard 可绕过此设置
ENGRAM_BIND	127.0.0.1	Web 可视化工具的绑定地址（设为 0.0.0.0 可在网络上公开访问；需要 ENGRAM_WEB_TOKEN）
ENGRAM_WEB_TOKEN	ENGRAM_MCP_TOKEN	可视化工具所需的 Bearer 令牌 / ?token=（除 /api/health 外的所有路由）
ENGRAM_MCP_TOKEN	—	MCP 守护进程的 /mcp 所需的 Bearer 令牌；见 MCP 服务
ENGRAM_MCP_HOST	127.0.0.1	MCP 守护进程的绑定地址（非环回地址需要 ENGRAM_MCP_TOKEN）
PORT	3001	Web 可视化工具端口
数据目录。 未设置 ENGRAM_DATA_DIR 时，Linux/macOS 上的默认路径为 $XDG_DATA_HOME/engram，Windows 上为 %LOCALAPPDATA%\engram；如果该变量也未设置或为空，engram 会在所有平台上回退到 ~/.local/share/engram，因此现有安装不会迁移（在通常未设置 XDG_DATA_HOME 的 macOS 上，默认路径仍为 ~/.local/share/engram）。每个组件（CLI、MCP 服务、dream 守护进程、Web 可视化工具）都遵循这条规则解析路径。

大模型提供方。 信息提取和 dream 工作流会按层级依次尝试，默认顺序为 Ollama（如果 OLLAMA_HOST 有响应，且 ENGRAM_LOCAL_MODEL 或 ENGRAM_LOCAL_MODEL_FALLBACKS 中的某个模型已拉取到该主机；否则会跳过本地层级，并仅发出一次警告，列出该主机已有的模型），然后是通用的 OpenAI 兼容 路由（如果设置了 ENGRAM_OPENAI_MODEL：OpenAI、LiteLLM 或其他网关、可自托管服务；凭据从 ENGRAM_OPENAI_API_KEY_ENV 指定的环境变量中读取），接着是 OpenRouter（如果设置了 OPENROUTER_API_KEY），最后是 Anthropic（如果设置了 ANTHROPIC_API_KEY）。ENGRAM_LLM_PROVIDERS 可调整层级顺序或限制层级，例如 openai,anthropic。engram doctor 会显示顺序、每个层级的端点/模型及其密钥对应的环境变量（绝不显示密钥），以及 Ollama 层级解析出的本地模型。

通用路由的安全边界：告知 Engram 的是一个变量名，而不是密钥。每个部署都会在仓库之外将自己的凭据映射到该变量（通过 shell 配置文件、服务环境文件 ~/.config/engram/env、包装脚本或监管进程的环境）；令牌绝不会写入配置、日志或 --plan 输出。OpenRouter 和通用路由共用一个 OpenAI-wire 客户端，因此请求兼容性修复会同时适用于两者。 engram extract 和 engram dream 至少需要配置一个提供方；search、remember、remember_batch 和 Web 可视化工具不需要大模型。

参考资料

• SPEC.md — 完整的系统规范，包含需求和接口约定
• CHANGELOG.md — 发布说明及各版本的升级步骤
• docs/history/SPEC-legacy.md — 原始愿景文档，包含详细的设计依据（已归档）
• plans/ — 实施计划（阶段 1–4、阶段 6 RLM、阶段 7 扩展）
• decisions/ — 架构决策记录