# Echo Memory

> A temporal, causal-typed memory graph for AI agents — built to keep working after months of accumulated history, not just on day one.

Echo Memory stores facts as typed, directed edges between entity nodes instead of flat vector
rows, so retrieval cost stays bounded by what's currently relevant instead of growing with
everything that's ever been written. Extraction happens in the calling agent, never on the
server, so the write path makes zero LLM calls — the agent already identified the entities to
answer the user, and hands them over rather than paying a second model to re-derive them. Runs
on Postgres with pgvector and Apache AGE. Apache-2.0 licensed.
Source: https://github.com/echo-mem/echo-mem

## Implementing against the hosted API

If you are a coding agent asked to integrate Echo Memory, read this and you
have everything: the endpoint, the MCP handshake, the four tool schemas, the
traps, and complete Node and Python clients.

https://echo-mem.com/docs/integration.md

Endpoint https://api.echo-mem.com/mcp, `Authorization: Bearer <key>`, MCP over
streamable HTTP. Three POSTs: initialize, notifications/initialized, then
tools/call with the Mcp-Session-Id the first response returned. The Accept
header must list BOTH application/json and text/event-stream.

## MCP tools

Four, over stdio:

- `write_episode(scope, session_id, entities, facts)` — record entities and the typed facts
  between them. The caller supplies both; the server validates, embeds, resolves entities
  against what already exists, and stores. Never reads free text to decide what is in it.
- `query_memory(scope, query, top_k, digest)` — hybrid retrieval, pgvector and Postgres
  full-text fused by reciprocal rank. Every result carries provenance: the agent that wrote it,
  the session, the project, and a `fact_id`.
- `record_recall_save(scope, fact_id, note)` — record that a recalled fact saved re-explaining
  something. Takes a `fact_id` rather than an author name: the server derives who wrote it from
  that edge, so the number cannot be asserted by the agent being measured.
- `get_audit_log(scope, since)` — every mutation, with what changed and why.

## CLI

`echo-memory adopt` wires every MCP client on the machine, each under its own agent id, showing
a diff before it writes anything. `echo-memory health` scores the graph and names what needs
attention. `echo-memory why <fact_id>` shows a fact's full audit trail. Also `status`,
`init-db`, `install`, `skill`, `dashboard --serve`, `graph`, `export`, `benchmark`, `bootstrap`,
`pending`, `recall`, `analyse`, `trial`.

## Install

```
git clone https://github.com/echo-mem/echo-mem.git && cd echo-mem
docker compose up -d
pip install echo-mem
export ECHO_MEMORY_DATABASE_URL="postgresql://postgres:postgres@localhost:5433/echo_memory"
echo-memory init-db
claude mcp add --scope user echo-memory \
  -e ECHO_MEMORY_USER_ID=your-user-id \
  -e ECHO_MEMORY_AGENT_ID=claude-code \
  -e ECHO_MEMORY_DATABASE_URL="$ECHO_MEMORY_DATABASE_URL" \
  -- python -m echo_memory.server
```

The PyPI distribution is `echo-mem`, not `echo-memory` — that name belongs to an unrelated
product. The Python import path is `echo_memory` either way.

## Pages

- [Homepage](https://www.echo-mem.com/): product overview, architecture (Postgres + pgvector +
  Apache AGE), the interactive causal-typing demo, pricing, roadmap (v1a built, v1b gated on v1a
  proving recall first, v1.1 planned), and full setup instructions.
- [Blog index](https://www.echo-mem.com/blog/): all posts below, human-readable.

## Blog

- [Why Echo Memory Uses a Graph, Not a Vector Store](https://www.echo-mem.com/blog/why-a-graph-not-a-vector-store) — [markdown](https://www.echo-mem.com/blog/why-a-graph-not-a-vector-store.md): the structural argument against flat vector stores at long horizons, and where the argument stops (v1a ships hybrid retrieval; multi-hop PageRank is v1b).
- [Causal Typing: How Echo Memory Tracks Why, Not Just What](https://www.echo-mem.com/blog/causal-typing-explained) — [markdown](https://www.echo-mem.com/blog/causal-typing-explained.md): the optional `causal_hint` field (caused_by, led_to, enabled_by, blocked_by, contradicts), set by the writing agent's judgment rather than inferred statistically, and the audit trail behind every edge. Distinct from `relation_type`, which is free text the agent chooses. Surfacing contradictions is v1b and gated on an evaluation set that does not exist yet.
- [Installing Echo Memory with Claude Code](https://www.echo-mem.com/blog/install-echo-memory-with-claude-code) — [markdown](https://www.echo-mem.com/blog/install-echo-memory-with-claude-code.md): the five-step setup end to end, including the echo-mem vs echo-memory naming collision on PyPI.
- [The Architecture Behind Echo Memory](https://www.echo-mem.com/blog/architecture-postgres-pgvector-apache-age) — [markdown](https://www.echo-mem.com/blog/architecture-postgres-pgvector-apache-age.md): storage, retrieval, and interface layers, real measured write/query latency, and the staged v1a/v1b/v1.1 roadmap.

## Reference

- [robots.txt](https://www.echo-mem.com/robots.txt)
- [sitemap.xml](https://www.echo-mem.com/sitemap.xml)
- [Source repository](https://github.com/echo-mem/echo-mem)
- [License (Business Source License 1.1)](https://github.com/echo-mem/echo-mem/blob/main/LICENSE)