echo-memory

Echo Memory

Memory that survives the session. Facts are edges between entities in a graph, scoped to this user and attributed to this project, readable by any other tool pointed at the same store.

Recall before you ask

Call query_memory at session start, and before asking the user anything they plausibly already told a past session or another tool. Checking costs one call; making them re-explain costs their patience and is the entire problem this exists to solve.

query_memory(scope="shared", query="why is the deploy branch master")
query_memory(scope="shared", digest=True)   # "catch me up", ignores query

If the response carries a pending_ingest field, memory files were written that the graph hasn't heard about. Read each listed file, call write_episode with what it states, then close it:

echo-memory pending --done <path>

Write the moment it happens

Call write_episode in the same turn, not batched at the end, whenever:

• the user states a decision — "we're using X", "X only deploys from branch Y"
• the user corrects you — "actually, X not Y"
• the user states a preference or a standing rule
• the user says "remember this" / "for future reference" / "don't do that again"
• you discover something non-obvious that cost real time to learn

Skip genuinely throwaway exchanges: typo fixes, one-off questions with no lasting relevance. A missed memory costs more than one extra call.

The exact shape

The server never calls an LLM. You extract the entities and facts; it stores, resolves and retrieves them.

write_episode(
  scope="shared",
  session_id="<this session's id>",
  entities=[
    {"name": "Postgres", "type": "tool"},
    {"name": "storage decision", "type": "decision"},
  ],
  facts=[
    {"source": "storage decision", "target": "Postgres",
     "relation_type": "uses",
     "fact": "Switched from SQLite to Postgres for durability, 2026-08-20.",
     "confidence": "extracted"},
  ],
)

• entities[].name — non-empty, unique within the call. type is free text you choose ("tool", "person", "decision", "bug", "policy"), not a fixed enum.
• facts[].source / .target — must each match an entities[].name exactly.
• facts[].relation_type — free text ("uses", "caused_by", "blocked_by").
• facts[].fact — the sentence to remember. Write it so it still makes sense read cold in six months by a different tool: name the thing, don't say "it".
• facts[].confidence — exactly one of "extracted" (the user said it), "inferred" (you deduced it), "ambiguous" (uncertain). Not a number, not "high"/"low", never omitted. Anything else is rejected.