Echo Memory

Echo Memory

Shared memory for AI agents, as a graph in your own database. What Claude Code learns, Cursor and Codex can recall. Every fact records who wrote it and when, and the server never calls a model to store one.

Every line above is real output, captured from these commands against a throwaway database. The transcript is at .github/branding/demo-transcript.txt.

Your agents start every session from zero. The usual fix is a notes file you paste into

context, which grows until it is mostly irrelevant to whatever you are asking. Echo

Memory is the other shape: facts connected to each other, and a query that returns the

few that matter. On the author's own 325 fact store that is 96.7% less context for

the same answer, with the answer still present 87.2% of the time across 1,190 queries

the harness derived from their own answers.

write_episode                          query_memory

billing ──uses──▸ Razorpay "how do we take payments" │ written by claude-code ▸ billing uses Razorpay, not Stripe │ supersedes ──▸ Stripe written by claude-code, 3 days ago └ no model invoked ▸ 1,372 tokens, not 41,838

Install

Requires: Python 3.11+ and Docker (for the database).

pipx install echo-mem

echo-memory quickstart

quickstart starts the database, applies the schema, and prints the claude mcp add line that registers it, filled in with the port it actually used. The Postgres image is published, so nothing compiles.

Or use the hosted service and run no database at all:

pipx install echo-mem

echo-memory connect # a key from https://app.echo-mem.com

Then once per machine, so an agent knows *when* to record and recall rather than only that the tools exist:

echo-memory install --global

Restart your client afterwards. An MCP server is a long lived process that holds

the code and config it started with, and an editable install does not change that.

The PyPI name is `echo-mem`, not `echo-memory`. That name belongs to an unrelated

hosted product. The import package and the CLI are both echo_memory / echo-memory;

only the distribution name differs.

Upgrading

pipx upgrade echo-mem

echo-memory init-db # apply any new migrations echo-memory reindex # rebuild what the new code derives

Both steps, in that order, and neither is optional on a store that predates the version you just installed.

Skipping `init-db` fails loudly. A read against a schema older than the code raises an undefined column, which is the good case: it stops rather than answering from something it half understands.

Skipping `reindex` fails silently, which is worse. Derived data that the new code reads differently is still the old data, and nothing errors. Concretely, on an upgrade to 0.5.3 the lexical corpus statistics are treated as stale until rebuilt, so BM25 stays off and your queries keep ranking by ts_rank while the setting reports as on. reindex rebuilds the embeddings and those statistics together. echo-memory health tells you afterwards.

Usage

echo-memory status                 # what each scope holds, and which agents have written

echo-memory health # a score, what is weak, and what to do about it echo-memory dashboard --serve # the graph, in a browser, localhost only

echo-memory why # the full audit trail for one fact echo-memory recall " " # query the store from a terminal echo-memory export # everything, as JSON

echo-memory install --for cursor # wire one client, project scoped echo-memory adopt # wire every MCP client on the machine, each with its own id

echo-memory infer-causal-hints # type the facts whose own sentence states a cause (dry run)

echo-memory eval # retrieval quality against your own store echo-memory eval --context # what a recall costs against injecting everything echo-memory eval --context --sweep # the same, as a curve across corpus size echo-memory eval-external locomo # LoCoMo, the corpus the published figures use echo-memory eval-external longmemeval # LongMemEval, the same echo-memory calibrate # is entity resolution trustworthy on your data echo-memory benchmark # write, query and digest latency

The seven MCP tools

What you get

A graph, not a list. Entities are nodes and a fact is an edge between two of them. Two sessions that never knew about each other resolve onto the same entity by name, so the second inherits what the first learned.

Bounded retrieval, designed but not built. The plan is that old, rarely read memory demotes into higher level summaries over time, with nothing discarded and every summary still edged back to the facts it came from. None of it exists yet: there is no tiering, no summarisation, and retrieval today walks every active fact in the scope. It is described in docs/designs/ and listed below as v1c, and this paragraph used to claim it in the present tense.

A ranked answer that says why each fact is in it. Every returned fact carries score, its cosine similarity to the query, rank, its position, and matched, the channels that found it. score is deliberately not the fusion number: reciprocal rank values are sums of 1/(k+rank) and mean nothing from one query to the next, while a similarity means the same thing every time, which is what a caller thresholding on it needs. It is computed for every fact returned, including the ones only full text search found, because which channel retrieved a fact is an implementation detail and has no business reaching a field callers read as relevance.

The full text channel ranks by BM25. Postgres's ts_rank counts term occurrences and nothing else: no inverse document frequency, so a word in every fact of a scope counts as much as one in three; no saturation, so repetition scales linearly; no length normalisation, so a long fact is punished for being long. On 324 real prompts the rank 3 and rank 4 scores were identical in 59% of them, and reciprocal rank fusion reads rank position and never the score underneath it, so a channel ordered by scan order handed the fusion a coin flip.

BM25 is computed in SQL rather than installed, so no extension is added to your database. Corpus statistics are rebuilt amortised on write inside the transaction that already holds the scope's lock, and by echo-memory reindex; a scope that has none falls back to ts_rank rather than ranking on statistics it does not have. ECHO_MEMORY_LEXICAL_BM25=0 returns to ts_rank everywhere.

Facts about an entity, which resemblance cannot express. query_memory takes about, one or two entity names, and returns only the facts recorded against them. One name gives the edges incident to that node; two give the edges between them in either direction, which is "both names in the same fact" without going near the fact text.

This is not a ranking improvement and it is not a substitute for one. A query about one team returns a semantically close fact about a different team because the wrong fact genuinely does resemble the question, and no amount of better ranking removes it. Identity is not similarity, and a fact is an edge between two nodes, so asking which entity a fact is about is structural and exact.

Name matching is exact and case insensitive, never a substring, because a short name is a substring of longer unrelated words. A name nothing is recorded under returns no facts rather than the nearest thing, and so does a pair with no fact joining them: that is real absence and it means nobody recorded this, not here is something adjacent. More than two names is refused rather than answered empty, because an edge has two endpoints and a fact about three entities is a question this model cannot express.

The history the store has always kept is readable. Every fact has carried t_valid and t_invalid since the first migration, and the read path had only ever asked whether a fact is current, so the store paid to keep the whole record of what a scope believed and could not answer the first question a post mortem asks. query_memory takes as_of in unix seconds and every channel honours it: vector, full text, the graph hop, the digest.

Supersession is what makes that more than a curiosity. Writing the same source, target and relation again with a changed claim does not edit the old fact, it ends it: the old edge takes a t_invalid and stays queryable. Nothing is ever rewritten, so the history is real rather than reconstructed, which is the property the memory reconsolidation literature gives up and the reason this project refuses that idea.

Restating an unchanged claim is not a change and no longer counts as one. If the fact text, the confidence and the causal hint all match the edge already there, the write is skipped and reported under restated. It used to create a second edge, end the first, and emit a supersession whose before_fact equalled its after_fact. That is the mechanism behind one customer edge carrying 47 versions of a single sentence, and behind 543 writes producing 112 facts while every one of them was billed. It also makes a retry safe: with no idempotency key, a caller retrying a write that had actually landed used to burn a version on it.

Every write answers whether it stored anything. write_episode can end with an empty edges_created four different ways, and from the caller's side they used to be indistinguishable without knowing which other key to inspect. Each one now reports stored: false and names itself in not_stored: refused (validation rejected it), deferred (an entity mention was close enough to an existing node to be worth asking about and not close enough to merge), unchanged (every fact already existed word for word) and no_facts (the episode asserted none). A refusal carries the same keys as a success, so one check works on every path, and retryable separates a database blip worth retrying from a validation error that will fail forever. A write that stored some of its facts and held the rest says partial.

The deferral is the one that cost real data, because it looks most like success: a well formed response, no error, isError false, and nothing written. A customer loading 26,633 facts read that as 26,633 success