EchoVault Memory

<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. 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 and place the binary somewhere on your $PATH.

Build from source

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

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:

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:

memory config init

This creates ~/.memory/config.yaml with sensible defaults:

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:

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:

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:

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

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.