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 changed on disk and may not be recorded yet. Changed is not the same as missing: a past session may have written the facts and never marked the file done. Read each listed file, query_memory for its subject, and only call write_episode if what it states is genuinely absent — a duplicate fact costs more than a skipped one. Either way, 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"},
  ],
)