Record something worth remembering later: a decision, a correction, a stated preference, or context that would otherwise have to be re-explained to a different tool or a future session. Call this proactively and immediately when you notice one of these - don't wait to be asked, and don't batch it up for later in the conversation. The cost of a missed memory (re-explaining something later) is higher than the cost of one extra call.

You (the calling agent) extract entities/facts yourself - this server never calls an LLM. Exact shape, every key required unless marked optional:

entities: [{"name": "Postgres", "type": "tool"}, ...]

• name: non-empty string, unique per entity in this call

• type: any short string describing what kind of thing this is (e.g. "tool", "person", "decision", "preference") - your choice, not a fixed enum

facts: [{"source": "Decision", "target": "Postgres", "relation_type": "uses", "fact": "decided to use Postgres for storage", "confidence": "extracted"}, ...]

• source/target: must each exactly match a "name" in entities above

• relation_type: any short string describing the relationship (e.g. "uses", "prefers", "caused_by") - your choice, not a fixed enum

• fact: the actual sentence to remember, plain text

• confidence: MUST be exactly one of "extracted" (directly stated), "inferred" (you deduced it), or "ambiguous" (uncertain) - any other value, including numbers or omitting it, is rejected

entity_resolutions (optional): only needed when a previous call returned ambiguous_entities and you're now confirming which candidate a mention refers to, or that it's new: {"mention name": {"resolved_to": "" | "new"}}. Omit entirely on a call with no prior ambiguity to resolve.

Example call: write_episode(scope="solo", session_id="sess-1", entities=[{"name": "Postgres", "type": "tool"}, {"name": "Decision", "type": "decision"}], facts=[{"source": "Decision", "target": "Postgres", "relation_type": "uses", "fact": "decided to use Postgres for storage", "confidence": "extracted"}])

Recall prior facts relevant to query, from this agent's own memory (scope="solo") or the pool shared across this user's agents (scope="shared"). Call this at session start, and any other time recalling prior context would save the user from re-explaining something - check here before asking them to repeat themselves or guessing at context you don't have.

digest=True ignores query and returns the most recently written active facts instead, as an opt-in "catch me up" convenience; call it explicitly at session start if you want one, it's never automatic.

A pending_ingest field appears when memory files have been written that the graph hasn't heard about yet. Read each listed file and call write_episode with the entities and facts it states, then mark it done with echo-memory pending --done <path>. The queue exists because extraction needs a model and this server never calls one.

Record that a fact you recalled from memory saved the user from re-explaining something to you.

Call this IN THE SAME TURN, the moment it happens. The trigger is concrete: you called query_memory (or read a memory-derived fact), it answered something the user would otherwise have had to tell you again, and the fact was originally written by a DIFFERENT tool or a past session.

That last part is the whole point, and it is why this takes fact_id rather than a written_by string. Pass the fact_id of the fact that helped - every query_memory result carries one. The server reads that edge's own agent_id and uses it as written_by; the caller does not get to assert who wrote a fact.

Until 2026-08-29 written_by was free text supplied by the caller. Nothing checked the fact existed, so the number gating v1a was a string typed by the model being graded. A fact_id is checkable, so the reading is admissible.

recalled_by is you, defaulting to this server's own agent id. If the fact's author and you are the same tool, the save is still recorded but does not count toward the trial's bar - recalling your own note from ten minutes ago is not the thing being measured.

note should be one sentence naming what it saved re-explaining, written so it still makes sense read cold in six months. Recording the identical note twice is a no-op, so a retry after an error is safe.

Do NOT call this speculatively, for a fact you wrote this session, or because a recall was merely interesting. It is evidence for a gate that decides real build work; an inflated count is worse than an empty one.

Human-readable audit trail: what was written, invalidated, superseded, or resolved, and why. since is an ISO8601 timestamp; entries at or after it, chronologically ordered.