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 servernever calls a model to store one.

Your agents start every session from zero. The usual fix is a notes file you paste intocontext, which grows until it is mostly irrelevant to whatever you are asking. EchoMemory is the other shape: facts connected to each other, and a query that returns thefew that matter. On the author's own store that is 96.7% less context for the sameanswer, with the answer still present 87.2% of the time across 1,190 questions.

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 addline that registers it, filled in with the port it actually used. The Postgres image ispublished, so nothing compiles.

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

pipx install echo-mem
echo-memory connect <key>          # a key from https://app.echo-mem.com

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

echo-memory install --global

Restart your client afterwards. An MCP server is a long lived process that holdsthe 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 unrelatedhosted product. The import package and the CLI are both echo_memory / echo-memory;only the distribution name differs.

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 <fact_id>          # the full audit trail for one fact
echo-memory recall "<question>"    # 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 eval                   # retrieval quality against your own store
echo-memory eval --context         # what a recall costs against injecting everything
echo-memory calibrate              # is entity resolution trustworthy on your data
echo-memory benchmark              # write, query and digest latency

The six 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, sothe second inherits what the first learned.

Bounded retrieval. Old, rarely read memory consolidates into higher level summariesover time. Nothing is discarded; what changes is how much a query has to walk.

Provenance on every fact. Who wrote it, which tool, which project, when, and whichreads returned it. A superseded fact is never deleted. It stops being drawn and staysreachable with its history.

Causal typing. Edges can be tagged caused_by, led_to, blocked_by,contradicts, set by the agent's own read of the conversation rather than inferredstatistically.

No inference on the write path. Extraction happens in the calling agent, so storinga memory invokes no model on the server. The cost moved rather than vanished: the agenthas to arrive with entities and facts already extracted, which is what thetool contract spells out. The comparison that makes this matter isZep/Graphiti, the closest architectural match, whose own description of ingestion is that"every episode triggers multiple LLM calls" and that "write cost scales with volume".

Any MCP client. A coding assistant, a chatbot, an ops agent, or something built inhouse. Coding agents are where this is proven, not what it is limited to.

Numbers, and how they were taken

Every figure comes from this repository or a live store, on a date, with the command thatreproduces it on yours. The corpus is small and the noise floor is stated, because adifference nobody sized is not a result.

That last row is the one that went the wrong way, and it is here on purpose. The intervalincludes chance, so the unattended merge is switched off: at the automatic bar precisionwas 50% over two reviewed pairs, and the audit log showed that path had fired once in thesystem's entire history. A near match is now offered for confirmation instead.

The context saving is measured against a specific baseline, stated so it cannot be readas more than it is. Not "no memory at all", which is however long a human spends reexplaining and is unmeasurable. It is the thing people do instead: keep the project'snotes in one file and paste the whole file. On that store the file is 325 facts, about41,838 tokens; a recall returned 1,372 on average. The hit rate belongs beside it, becausea recall that returned nothing would score 100%.

The graph

Memory is a graph, not a list of notes. Entities are nodes; a fact is an edge betweentwo of them. That is the whole data model, and everything else follows from it.

Three projects here. checkout-api, mobile-app and data-pipeline were recorded inseparate sessions and never told about each other, yet the picture already separates them,because separation is a property of the edges rather than a label anyone applied.

Clusters come from structure. Densely connected facts are grouped by label propagationover the edges, and each cluster is named after its most connected node. That is whydata-pipeline sits apart: nothing it knows touches payments. It is also whycheckout-api and mobile-app share a cluster despite being different codebases. Theygenuinely share an idea, and the graph found it rather than being told.

Components are the stronger claim. Two nodes in different components have no pathbetween them at all, which is the strongest statement this graph can make that twomemories are unrelated.

Click a node: everything it takes part in

idempotency keys is the largest node here and nobody made it large: seventeen facts fromseveral services resolved onto one entity by name. The panel lists every one, with whichagent wrote it and when.

Click a link: why memory believes it

Not a tooltip. Who wrote the fact, in which project, when, and how each of its entitiesresolved. echo-memory why <fact_id> prints the same trail in a terminal.

Seeing your own

echo-memory dashboard --serve --open

The images above come from a synthetic dataset (scripts/demo-seed.py) rather than a realstore, for the obvious reason: a real memory graph is full of hostnames, account numbersand client names.

Wiring more than one tool

Give each client its own ECHO_MEMORY_AGENT_ID. Cursor should say cursor, ClaudeDesktop claude-desktop. Memory is shared either way, but a fact records which toollearned it, and two tools claiming the same id makes cross tool recall impossible to seeafterwards.

echo-memory adopt                  # every MCP client on the machine, each with its own id
echo-memory install [path]         # one project: MCP config plus a skill, committed with the code

adopt shows the diff before writing anything. For an agent that does not speak MCP, seedocs/INTEGRATIONS.md.

Is the graph in good shape?

echo-memory health

A score, what is strong, what needs attention, and what to do about each, including whatrecall has cost: how often memory was read, how often a read returned anything, roughlyhow many tokens were injected, and how many saves those reads produced. Writes werecounted from the start; reads were not counted at all, so nothing could answer whetherrecall earns what it costs. It exists to be run when you have no question, because a storecan look healthy by every other number while most of its facts came from a bulk import,the last real write was a week ago, and only one of several wired agents has ever writtenanything. --json for machine readable output.

Nothing in it is gated. The paid plan sells hosting; diagnostics about your own data arenot a thing to withhold from the person whose data it is.

Architecture

Storage PostgreSQL with pgvector and Apache AGE, from a single local agent up to anorganisation wide shared graph, with no forced migration later. The novel work is thememory structure and the read/write algorithm on top of it, not a new database engine.

Retrieval Hybrid vector and full text search fused by reciprocal rank in v1a.Personalised PageRank via networkx lands in v1b for multi hop associative retrieval.

Interface Model Context Protocol, so any compliantagent reads and writes the same graph.

Status

Early and staged, on purpose. See docs/designs/ for the architectureand the v1a to v1b plan.

The validated wedge driving v1a is memory shared across coding agents, which is theauthor's own daily pain and the case with the most evidence behind it. Everything else isthe target this architecture is built toward.

Hosted

Running it yourself is free forever under Apache 2.0, with no account and no feature heldback. app.echo-mem.com runs the database for you at $99 amonth if you would rather not.

See CONTRIBUTING.md. Issues and pull requests welcome; please read thedesign docs first so proposals fit the staged build plan. A first pull request is asked tosign the Contributor License Agreement, once, in the PR thread.

The most useful contribution is a measurement that disagrees with one of the numbersabove. Run echo-memory eval, calibrate or benchmark on your own store and open anissue with the output.

License

Apache License 2.0. See LICENSE.

mcp-name: io.github.ayushcodes10/echo-mem