EchoVault Memory

EchoVault — Go

为编码 Agent 提供本地记忆。你的 Agent 会跨会话记住决策、Bug 和上下文——无需云服务、API 密钥或费用。

安装 · 功能 · 工作原理 · 命令

---

这是 EchoVault 的 Go 移植版。它是一个无需依赖 Python 运行时的静态二进制文件。保险库格式和 MCP 接口与 Python 版本完全兼容——你可以在两者之间切换，而不会丢失任何记忆。

功能

支持 4 种 Agent — Claude Code、Cursor、Codex、OpenCode。只需一条命令即可为你的 Agent 配置 MCP。

原生支持 MCP — 作为 MCP 服务运行，并将 memory_save、memory_search 和 memory_context 暴露为工具。Agent 可直接调用，无需 Shell 钩子。

本地优先 — 所有内容都保存在你的设备上。记忆以 Markdown 格式存储在 ~/.memory/vault/ 中，可用 Obsidian 或任何编辑器阅读。

空闲时零成本 — 没有后台进程、守护进程或 RAM 开销。只有 Agent 启动时才会运行 MCP 服务。

混合搜索 — FTS5 关键词搜索开箱即用。添加 Ollama 或 OpenAI 即可进行语义向量搜索。

机密信息脱敏 — 通过 3 层脱敏，在任何内容写入磁盘前移除 API 密钥、密码和凭据。支持显式 <redacted> 标签、模式检测和自定义 .memoryignore 规则。

跨 Agent 使用 — Claude Code 保存的记忆可在 Cursor、Codex 和 OpenCode 中搜索。一个保险库，多个 Agent。

兼容 Obsidian — 会话文件是包含 YAML frontmatter 的有效 Markdown。将 Obsidian 指向 ~/.memory/vault/，即可直观浏览 Agent 的记忆。

安装

预构建二进制文件

从发布页面下载适用于你平台的最新版本，并将二进制文件放到 $PATH 中的某个位置。

从源代码构建

git clone https://github.com/go-ports/echovault.git
cd echovault
make build          # produces ./bin/memory
sudo cp bin/memory /usr/local/bin/

需要 CGO。 该二进制文件链接了 go-sqlite3 和 sqlite-vec，因此必须安装 C 编译器（gcc/clang）。在 macOS 上：xcode-select --install。在 Debian/Ubuntu 上：apt install build-essential。

首次运行

memory init
memory setup claude-code   # or: cursor, codex, opencode

完成。memory setup 会自动安装 MCP 服务配置。

默认情况下，配置会全局安装。若要为特定项目安装：

cd ~/my-project
memory setup claude-code --project   # writes .mcp.json in project root
memory setup opencode --project      # writes opencode.json in project root
memory setup codex --project         # writes .codex/config.toml + AGENTS.md

配置嵌入（可选）

嵌入可启用语义搜索。即使不配置嵌入，你仍可通过 FTS5 进行快速关键词搜索。

生成初始配置：

memory config init

这会创建包含合理默认值的 ~/.memory/config.yaml：

embedding:
  provider: ollama              # ollama | openai | openrouter
  model: nomic-embed-text

context:
  semantic: auto                # auto | always | never
  topup_recent: true

各部分的作用：

• embedding — 控制如何将记忆转换为用于语义搜索的向量。ollama 在本地运行；openai 和 openrouter 会调用云 API。nomic-embed-text 是适用于 Ollama 的优质本地模型。
• context — 控制会话开始时如何检索记忆。auto 会在嵌入可用时使用向量搜索，否则回退到关键词搜索。topup_recent 还会包含近期记忆，让 Agent 获得新鲜的上下文。

对于云服务提供商，请在相应的服务提供商部分添加 api_key。memory config 输出中的 API 密钥会经过脱敏。

配置记忆位置

默认情况下，EchoVault 会将数据存储在 ~/.memory 中。

你可以通过以下两种方式更改该位置：

• MEMORY_HOME=/path/to/memory（优先级最高，按 Shell/进程设置）
• memory config set-home /path/to/memory（持久默认设置）

常用命令：

memory config set-home /path/to/memory
memory config clear-home
memory config

memory config 会显示 memory_home 和 memory_home_source（env、config 或 default）。

全局标志 --memory-home 可在单次调用时覆盖所有设置：

memory --memory-home /tmp/test-vault search "authentication"

用法

设置完成后，Agent 会通过 MCP 工具使用记忆：

• 会话开始 — Agent 调用 memory_context 加载之前的决策和上下文
• 工作期间 — Agent 调用 memory_search 查找相关记忆
• 会话结束 — Agent 调用 memory_save 持久化决策、错误和经验

MCP 工具说明会指导 Agent 自动保存和检索。大多数情况下，无需手动提示。

你也可以直接使用命令行：

memory save --title "Switched to JWT auth" \
  --what "Replaced session cookies with JWT" \
  --why "Needed stateless auth for API" \
  --impact "All endpoints now require Bearer token" \
  --tags "auth,jwt" --category "decision" \
  --details "Context:
Options considered:
- Keep session cookies
- Move to JWT
Decision:
Tradeoffs:
Follow-up:"

memory search "authentication"
memory details <id>
memory context --project

对于较长的详细内容，请使用 --details-file notes.md。若要自动生成结构化详细内容的模板，请使用 --details-template。

工作原理

~/.memory/
├── vault/                    # Obsidian-compatible Markdown
│   └── my-project/
│       └── 2026-02-01-session.md
├── index.db                  # SQLite: FTS5 + sqlite-vec
└── config.yaml               # Embedding provider config

• Markdown 知识库 — 每个项目的每个会话对应一个文件，包含 YAML 前置元数据
• SQLite 索引 — 使用 FTS5 搜索关键词，使用 sqlite-vec 存储语义向量
• 精简指针 — 搜索会返回约 50 个词元的摘要；需要时再获取完整详细内容
• 三层脱敏 — 显式标签、模式匹配和 .memoryignore 规则

支持的 Agent

Agent	设置命令	安装内容
Claude Code	memory setup claude-code	在 .mcp.json（项目级）或 ~/.claude.json（全局）中安装 MCP 服务
Cursor	memory setup cursor	在 .cursor/mcp.json 中安装 MCP 服务
Codex	memory setup codex	在 .codex/config.toml 中安装 MCP 服务，并提供 AGENTS.md 后备方案
OpenCode	memory setup opencode	在 opencode.json（项目级）或 ~/.config/opencode/opencode.json（全局）中安装 MCP 服务

所有 Agent 共用有效的 memory_home 路径（默认为 ~/.memory/）下的同一个记忆知识库。在 Claude Code 中保存的记忆也可以从 Cursor、Codex 或 OpenCode 中搜索。

命令

命令	说明
memory init	在有效的记忆主目录中创建知识库
memory setup <agent>	为 Agent 安装 MCP 服务配置
memory uninstall <agent>	移除 Agent 的 MCP 服务配置
memory save ...	保存记忆（支持 --details-file 和 --details-template）
memory search "query"	混合使用 FTS 和语义搜索
memory details <id>	获取记忆的完整详细内容
memory delete <id>	按 ID 或前缀删除记忆
memory context --project	列出当前项目的记忆
memory sessions	列出会话文件
memory config	显示有效配置
memory config init	生成初始版 config.yaml
memory config set-home <path>	保存默认记忆位置
memory config clear-home	移除已保存的记忆位置
memory reindex	更换提供方后重建向量
memory mcp	启动 MCP 服务（stdio 传输）

全局标志

标志	说明
--memory-home <path>	覆盖本次调用的记忆主目录
--help	显示任意命令的帮助信息

卸载

memory uninstall claude-code   # or: cursor, codex, opencode
rm /usr/local/bin/memory

若要同时移除所有已存储的记忆：rm -rf ~/.memory/

隐私

默认情况下，所有内容都保留在本地。如果你配置了 OpenAI 或 OpenRouter 来生成嵌入向量，相应的 API 调用会发送到它们的服务端。使用 Ollama 可完全在本地运行。

许可证

MIT — 请参阅 LICENSE。