By default the whole directory sits in ~/.memory. It can be moved with the MEMORY_HOME variable or the persistent memory config set-home setting.

Why Markdown is a sound foundation

Every session file is an ordinary Markdown document with metadata in YAML. That means memory is not locked inside a proprietary database: it can be read, searched, edited, versioned in Git, or opened as an Obsidian vault.

A record roughly contains fields like these:

An important difference from a plain folder of notes: Markdown here is the human-friendly storage form, but in parallel EchoVault maintains an index, metadata, vectors, archive state, supersessions and retrieval statistics.

Why SQLite as well, then

Reading dozens or hundreds of files on every request is awkward, so a local index lives alongside. In the current code it holds a table of records with identifiers and metadata, separate details, a full-text search virtual table, a sqlite-vec table when embeddings are enabled, an active-or-archived status, a link to the superseding record, confidence, validity dates, commit, branch and links, plus local counters of how often results were used.

So Markdown makes memory portable and inspectable, while SQLite makes it fast enough for an agent.

The interface is deliberately tiny

This is a good decision. Instead of twenty tools the agent needs to understand three verbs: load context, search deeper, save something new. And the tool descriptions themselves instruct the agent: do not save typos and obvious things, write memory for a future agent with zero current context.

Installation

On macOS and Linux the README offers an installer:

It prefers uv or pipx, and if neither is present it creates a separate virtual environment in ~/.local/share/echovault. The installer does not touch the system Python.

The manual route:

One trap the README warns about separately: do not simply run pip install echovault - that name on PyPI belongs to a different project. Install from the full Git URL.

Connecting agents, and shared memory

The integration can be installed for the current project only:

Importantly, all four use the same memory directory, so a decision saved by one agent is found by another in the next session:

That beats a separate proprietary store per tool: you can change agents without losing the project's history.

Your first proper memory

Every field here does work. The title is a short name for search and the context pack. "What" is what actually changed or was discovered. "Why" is the reason for the decision, and a month later that is often more important than the outcome. "Impact" is what a future agent must now take into account. Related files tie the memory to parts of the code, and the source shows which agent created the record.

Details are best laid out as: context, options considered, decision, tradeoffs, follow-up. That turns a note into a small architectural decision record.

Ten categories of memory

Living memory and a record's provenance

In version 0.5.0 EchoVault stopped treating every old record as equally useful. Memory gained fields that tell you how much to trust it, when it was current, in which branch and commit it appeared, when it was last verified, which other records it supersedes or links to, and whether any follow-ups remain open.

The idea is simple: long-term memory without a lifecycle eventually becomes a graveyard of old decisions. Living memory stores not only what was said but whether it can still be believed. In practice it looks like this:

For memory about code that is especially valuable: "it worked once" and "verified against current main yesterday" are entirely different levels of trust.

Playbook: memory that can be executed

An ordinary record states a fact. A playbook stores a procedure:

A playbook can hold triggers, prerequisites, steps, verification, follow-ups, constraints, rejected alternatives and open questions. Instead of "last time we released it somehow", a future agent gets an almost executable runbook: when to apply it, what to check first, which steps to run and how to confirm the result.

The context pack, a token budget, and how to switch it off

EchoVault assembles context for a specific request rather than handing over the last ten records. The tool description explicitly suggests the agent call it before feature development, planning, debugging and architecture work. The response may include relevant decisions, constraints, project state, active work, known fixes, playbooks, provenance and an approximate cost of the context in tokens.

The interesting part is how the volume is bounded:

Instead of "always return twenty memories" the system works to an approximate context budget. The most relevant results go in first, then constraints, project state, active work, known fixes, playbooks, decisions and useful recent records. The practical point: a memory system's goal is not to show the agent as much of the past as possible but to give the most useful context within a limited number of tokens.

Automatic context injection can be switched off without switching memory off. The policy works at three levels: the MEMORY_CONTEXT variable for the current process, a per-agent setting, and the overall mode in the configuration.

Search and save keep working: proactive injection is gone, while memory stays available on explicit request.

Search: words first, vectors when they help

If embeddings are configured, EchoVault merges FTS5 keyword search with vector similarity through sqlite-vec. In the current code the standard merge uses weights of 0.3 for the full-text part and 0.7 for the vector part, and with certain discrepancies between a single lexical hit and a strong semantic one the vector weight can go higher still. Temporary diagnostic and test records are also demoted in the ranking unless the query asks for them specifically.

But embeddings are not called without need - the pipeline is full-text-first:

That cuts latency and is especially useful with a remote embeddings API: a search for an exact function name or technology often finishes locally.

There is a second kind of saving too - on the depth of each result. The README describes search results as compact pointers: a short summary of a few dozen tokens plus an identifier and a flag that details are available.

The result is two-stage retrieval: cheaply pick the right records first, and read the large body only for one that genuinely matters.

Ollama or OpenAI, a local loop, and enrichment

The cloud variant:

The OpenAI-style provider also lets you point at your own address - for a local vLLM or a compatible gateway, for instance. After changing the embedding model the index has to be rebuilt:

Fully local and free is possible. The arrangement looks like this:

With the ollama provider the embeddings stay local, and if enrichment is off or uses a local endpoint, EchoVault sends nothing outside. But local-first does not automatically mean local-only: pick the OpenAI provider and the text being embedded or enriched goes to an external API.

Enrichment itself is an optional model-driven step before saving: it can improve the summary or add tags.

The separation matters. For its core work EchoVault need not run every memory through a model: you can save the structure the agent prepared as it is and use a model only for retrieval.

Three layers of secret protection

Before writing, a redaction pipeline runs: explicit <redacted>...</redacted> markers, regular expressions for known secret formats, and your project rules from .memoryignore.

The current code has patterns for Stripe keys, GitHub personal access tokens, AWS access identifiers, Slack bot tokens, private key headers, JWTs and fields such as password, secret, api_key. If the memory text said:

what lands on disk is:

This guards against accidents rather than being a full data-loss prevention system: regular expressions cannot be guaranteed to catch every secret. The project rule should still be simple - do not save credentials into memory.

Obsidian and the terminal dashboard

Since session files are valid Markdown, nothing stops you from opening ~/.memory/vault/ in Obsidian or any other editor. That is handy for a manual audit: you literally see what the agent considers important long-term memory instead of browsing opaque vector records. If the Markdown was edited by hand, there are import and reindex commands to bring the search layer back in sync.

Since version 0.4.0 the dashboard has been rewritten in Rust with ratatui and crossterm: it runs as a separate binary of about three megabytes, starts instantly and needs no Python UI runtime. From it you can search and filter records, view details, open a record in $EDITOR as a YAML file, archive and restore, browse duplicate candidates and merge them, and see statistics. Duplicate detection runs on a background thread, so the interface does not freeze during the quadratic comparison. Import and reindex, though, are not performed inside the dashboard - it only points you at the corresponding memory import and memory reindex commands.

Navigation is done in the spirit of k9s: the digits one to four switch panels, j, k, g and G move the cursor vim-style, the slash opens search, the colon a command palette, the question mark the help overlay.

Retrieval quality is meant to be measured

This is a rare trait among memory projects. Instead of "we have semantic search, so all is well", EchoVault lets you assemble a set of real questions with expected answers:

The report includes recall and precision at k, mean reciprocal rank, normalised discounted ranking quality, false positives on negative queries, latency and an approximate cost of context tokens.

From this grows a warning worth remembering: you cannot simply set similarity to 0.8. Different embedding models have entirely different similarity distributions, and the README gives a convincing example - on their benchmark with the nomic-embed-text model relevant values landed roughly in the 0.05-0.07 range, so a threshold of 0.55 would discard every semantic candidate. That is exactly why the configuration has two distinct parameters: min_relevance governs the quality of the final ranked result, while min_vector_similarity is the floor for a vector candidate specifically. Calibration numbers should not be copied blindly: the README itself advises repeating calibration for each model and your own vault.

Feedback, review and the doctor

Feedback is stored locally as aggregate counters, and the project notes specifically that the prompts themselves are not saved. The review command looks for candidates to consolidate and sort out: duplicates, contradictions, stale context, superseded records, completed follow-ups and overly broad session dumps. An important safety detail - review proposes changes but does not mutate the vault itself: a human or an agent sees the candidate first.

There is a separate health check:

It looks at the state of the vault and index, vectors, references, lifecycle issues, growth, latency and risky settings. This is a mature thought: long-term memory is infrastructure. If the index lags behind the Markdown, the embeddings were built by an old model, or references point at archived records, answer quality drops even with an excellent model.

Limitations and real tradeoffs

The main specialisation is agents working with code. The record structure, project detection, related files, Git provenance and playbooks are clearly aimed at software development; for a personal assistant a Mem0- or Memanto-style model will feel more natural.

Markdown and the index have to be kept in sync. A human can edit files by hand - a plus for inspectability, but precisely why import, reindex and the health check earn their place.

Vector search still depends on the model. Ollama makes the decision local but does not guarantee quality, and thresholds have to be calibrated per model.

Local retrieval does not mean the agent itself is local. EchoVault can store and index memory entirely on your machine, but Claude Code or Codex have their own model infrastructure - a separate privacy question.

And finally, the system moves fast: the main branch already carries unreleased installer and setup changes, so for a reproducible environment it is better to pin a release tag than always install from main.

Among the other projects, and when it is your choice

The most distinctive thing here is the combination of a simple file-based foundation with fairly serious engineering around retrieval quality and record lifecycle.

EchoVault is especially good if you work constantly with Claude Code, Codex or Cursor on the same projects; do not want to hand project decisions to a separate cloud service; want to see memory as ordinary Markdown files; need local semantic search through Ollama; care about playbooks and known fixes rather than only facts about a user; want to measure retrieval quality against your own real tasks; need one memory to serve several agents at once; would rather not keep a daemon permanently running.

It will be redundant in one-off sessions; when memory is needed by your service's end users rather than the developer; when a centralised multi-tenant cloud service is required; when you want a fully managed API with no local files and no index maintenance.

The project began with a simple idea - keep an agent's decisions locally. Version 0.5.0 makes it considerably more interesting: this is no longer a Markdown folder with vector search but a small operations system for memory. Memory stays readable rather than an opaque database. Search is fast: words first, vectors only when they help. Context is selective: bounded by relevance and a token budget. And memory is maintainable: there is measurement, feedback, review, a health check and provenance. The project's central thought is that an agent's memory should not merely be persistent - it should be local, readable, measurable and maintainable, or in a few months long-term memory turns into long-term rubbish.

Sources

This article was checked on 9 August 2026 against the current main branch, release v0.5.0, the README, the changelog and the code of the MCP server, search, the database layer and secret redaction. The main branch already carries separate unreleased installer changes, so a production install is best pinned to a release tag. Supplemented on 14 August 2026 against a fresh clone: import and reindex removed from the dashboard's capabilities, since it does not perform them, and the binary size, background duplicate detection and key bindings added.

• GitHub: mraza007/echovault
• README.md
• CHANGELOG.md
• Release v0.5.0
• pyproject.toml
• MCP server implementation
• Hybrid search implementation
• SQLite / FTS5 / sqlite-vec layer
• Memory data model
• Secret redaction pipeline
• MIT License