EchoVault Memory
Local-first memory for coding agents; stores decisions, bugs, and context across sessions.
Open source Open in the app JSON README (API)
About
Local-first memory for coding agents; stores decisions, bugs, and context across sessions.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- go-ports
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.3
- Stars
- 4
- Open pull requests
- 6
- Last push
- 2026-09-07T09:15:29Z
- Repository state
- ativo
- Language
- Go
- License
- MIT
- Added
- 2026-08-29 03:02:51
- Updated
- 2026-08-29 03:02:51
- Origin id
io.github.go-ports/echovault
README
<p align="center"> <img src="assets/echovault-gopher-icon.svg" width="120" height="120" alt="EchoVault" /> </p> <h1 align="center">EchoVault — Go</h1> <p align="center"> Local memory for coding agents. Your agent remembers decisions, bugs, and context across sessions — no cloud, no API keys, no cost. </p> <p align="center"> <a href="#install">Install</a> · <a href="#features">Features</a> · <a href="#how-it-works">How it works</a> · <a href="#commands">Commands</a> </p> --- This is the **Go port** of [EchoVault](https://github.com/mraza007/echovault). It is a single static binary with no Python runtime dependency. The vault format and MCP interface are fully compatible with the Python version — you can switch between them without losing any memories. ## Features **Works with 4 agents** — Claude Code, Cursor, Codex, OpenCode. One command sets up MCP config for your agent. **MCP native** — Runs as an MCP server exposing `memory_save`, `memory_search`, and `memory_context` as tools. Agents call them directly — no shell hooks needed. **Local-first** — Everything stays on your machine. Memories are stored as Markdown in `~/.memory/vault/`, readable in Obsidian or any editor. **Zero idle cost** — No background processes, no daemon, no RAM overhead. The MCP server only runs when the agent starts it. **Hybrid search** — FTS5 keyword search works out of the box. Add Ollama or OpenAI for semantic vector search. **Secret redaction** — 3-layer redaction strips API keys, passwords, and credentials before anything hits disk. Supports explicit `<redacted>` tags, pattern detection, and custom `.memoryignore` rules. **Cross-agent** — Memories saved by Claude Code are searchable in Cursor, Codex, and OpenCode. One vault, many agents. **Obsidian-compatible** — Session files are valid Markdown with YAML frontmatter. Point Obsidian at `~/.memory/vault/` and browse your agent's memory visually. ## Install ### Pre-built binary Download the latest release for your platform from the [releases page](https://github.com/go-ports/echovault/releases) and place the binary somewhere on your `$PATH`. ### Build from source ```bash git clone https://github.com/go-ports/echovault.git cd echovault make build # produces ./bin/memory sudo cp bin/memory /usr/local/bin/ ``` > **CGO required.** The binary links against `go-sqlite3` and `sqlite-vec`, so a C compiler (gcc/clang) must be present. On macOS: `xcode-select --install`. On Debian/Ubuntu: `apt install build-essential`. ### First run ```bash memory init memory setup claude-code # or: cursor, codex, opencode ``` That's it. `memory setup` installs the MCP server config automatically. By default the config is installed globally. To install for a specific project: ```bash 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 ``` ### Configure embeddings (optional) Embeddings enable semantic search. Without them, you still get fast keyword search via FTS5. Generate a starter config: ```bash memory config init ``` This creates `~/.memory/config.yaml` with sensible defaults: ```yaml embedding: provider: ollama # ollama | openai | openrouter model: nomic-embed-text context: semantic: auto # auto | always | never topup_recent: true ``` **What each section does:** - **`embedding`** — How memories get turned into vectors for semantic search. `ollama` runs locally; `openai` and `openrouter` call cloud APIs. `nomic-embed-text` is a good local model for Ollama. - **`context`** — Controls how memories are retrieved at session start. `auto` uses vector search when embeddings are available, falls back to keywords. `topup_recent` also includes recent memories so the agent has fresh context. For cloud providers, add `api_key` under the provider section. API keys are redacted in `memory config` output. ### Configure memory location By default, EchoVault stores data in `~/.memory`. You can change that in two ways: - `MEMORY_HOME=/path/to/memory` (highest priority, per-shell/per-process) - `memory config set-home /path/to/memory` (persistent default) Useful commands: ```bash memory config set-home /path/to/memory memory config clear-home memory config ``` `memory config` shows both `memory_home` and `memory_home_source` (`env`, `config`, or `default`). The `--memory-home` global flag overrides everything for a single invocation: ```bash memory --memory-home /tmp/test-vault search "authentication" ``` ## Usage Once set up, your agent uses memory via MCP tools: - **Session start** — agent calls `memory_context` to load prior decisions and context - **During work** — agent calls `memory_search` to find relevant memories - **Session end** — agent calls `memory_save` to persist decisions, bugs, and learnings The MCP tool descriptions instruct agents to save and retrieve automatically. No manual prompting needed in most cases. You can also use the CLI directly: ```bash 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 ``` For long details, use `--details-file notes.md`. To scaffold structured details automatically, use `--details-template`. ## How it works ``` ~/.memory/ ├── vault/ # Obsidian-compatible Markdown │ └── my-project/ │ └── 2026-02-01-session.md ├── index.db # SQLite: FTS5 + sqlite-vec └── config.yaml # Embedding provider config ``` - **Markdown vault** — one file per session per project, with YAML frontmatter - **SQLite index** — FTS5 for keywords, sqlite-vec for semantic vectors - **Compact pointers** — search returns ~50-token summaries; full details fetched on demand - **3-layer redaction** — explicit tags, pattern matching, and `.memoryignore` rules ## Supported agents | Agent | Setup command | What gets installed | |-------|---------------|---------------------| | Claude Code | `memory setup claude-code` | MCP server in `.mcp.json` (project) or `~/.claude.json` (global) | | Cursor | `memory setup cursor` | MCP server in `.cursor/mcp.json` | | Codex | `memory setup codex` | MCP server in `.codex/config.toml` + `AGENTS.md` fallback | | OpenCode | `memory setup opencode` | MCP server in `opencode.json` (project) or `~/.config/opencode/opencode.json` (global) | All agents share the same memory vault at your effective `memory_home` path (default `~/.memory/`). A memory saved by Claude Code is searchable from Cursor, Codex, or OpenCode. ## Commands | Command | Description | |---------|-------------| | `memory init` | Create vault at effective memory home | | `memory setup <agent>` | Install MCP server config for an agent | | `memory uninstall <agent>` | Remove MCP server config for an agent | | `memory save ...` | Save a memory (`--details-file` and `--details-template` supported) | | `memory search "query"` | Hybrid FTS + semantic search | | `memory details <id>` | Full details for a memory | | `memory delete <id>` | Delete a memory by ID or prefix | | `memory context --project` | List memories for current project | | `memory sessions` | List session files | | `memory config` | Show effective config | | `memory config init` | Generate a starter config.yaml | | `memory config set-home <path>` | Persist default memory location | | `memory config clear-home` | Remove persisted memory location | | `memory reindex` | Rebuild vectors after changing provider | | `memory mcp` | Start the MCP server (stdio transport) | ### Global flags | Flag | Description | |------|-------------| | `--memory-home <path>` | Override memory home for this invocation | | `--help` | Show help for any command | ## Uninstall ```bash memory uninstall claude-code # or: cursor, codex, opencode rm /usr/local/bin/memory ``` To also remove all stored memories: `rm -rf ~/.memory/` ## Privacy Everything stays local by default. If you configure OpenAI or OpenRouter for embeddings, those API calls go to their servers. Use Ollama for fully local operation. ## License MIT — see [LICENSE](../LICENSE).