Chapter 14

The Contract for Writing and Reading Memory

Chapter 13 said the concept system is open in two places. In that open space a person fills the gaps from context. A system cannot. It has to know explicitly what kind a Node is, which fields are required, and which relations are allowed. That explicit statement is this chapter's contract.

1. A Fragment is the unit of writing

Whoever wants to write into the graph, usually an AI assistant in the middle of a conversation, sends a Fragment. A Fragment is one bundle holding a list of Nodes, a list of Edges, which theme's vocabulary to read them with, and whose they are. On an account graph the account decides both.

Fragment
 ├─ theme_id
 ├─ nodes[]   id, type, title, domain, tags, props
 ├─ edges[]   from, type, to
 └─ owner

The server merges it on exact identifiers only. A Node with a matching id updates the existing Node; without one, it is created. An Edge is the same Edge only when both endpoints have matched first and from, relation and to are all equal. relates_to alone counts the reverse direction as the same Edge. No judgment of similarity is made. The moment the server started making one, the principle of Chapter 12 would fall.

The type is read against the theme's vocabulary. The five kinds of Chapter 10 go to their own places, any other name lands on Entity, and a name the vocabulary has not seen is folded in as proposed and reported in the response. Nothing is dropped for being unknown.

A Fragment is the format that carries memory between systems. The Graph is the structure memory lives in. A Fragment is not the memory itself.

2. Errors are not silently erased

The second clause of the contract is about what the system does not do.

It does not fill a missing value with a plausible one. An Episode or Record without a title keeps an empty title and gains a warning. The identifier is never put in the title's place; that would make a lookalike that reads fine in a list and hands you a key the moment you look for the name. A date in the wrong format is not stored; a warning comes back and the existing value is kept. An empty value means “unknown”. It does not mean “today”.

It does not silently store what is not allowed. Send an Edge whose pair is not in Chapter 11's table and that Edge is skipped and a warning attached. The warning opens with a token naming its kind: a relation name outside the vocabulary altogether is one error, a valid name used between two kinds that do not support it is another, and they are fixed differently.

It does not discard the unknown. What gets skipped is only what is malformed: no identifier, no kind, an Entity with no title, or an Edge whose endpoint was itself skipped and so has nowhere to stand. A collision with someone else's identifier is reported separately, because identifiers are global and retrying will not help; a different name has to be chosen.

If anything at all was skipped, the response sets partial. That is a warning not to trust the merge counts as proof that everything landed. The point of validation is not to reject data. It is to keep clear what the system knows and what it does not.

3. Writing and reading must speak the same grammar

A strict writing contract is no use on its own. If what was written is not read back the same way, two readers look at the same Graph and interpret different memories.

So the response to a write hands back the stored Nodes read back from the graph, so the writer can compare what was sent with what was kept. A field a kind does not have is absent from the response, and a domain comes back in its normalized form. The table of allowed pairs is held by server and tool byte for byte, and a test fails the moment they part. Ownership scope is applied by the same rule on reads and on writes. When a document is read, the losslessness check of Chapter 12 comes back with it.

This contract is what lets the system grow. A new Agent, a new client, a new host can all connect to the same memory as long as they speak the same contract. The desktop, the web and MCP stand on the same graph because all three speak the same contract. The desktop sidecar and the hub serve the same route table, and the web uses only the part its proxy allows.

The contract does not stand in for meaning. It fixes what the system reads and writes, and how. Meaning is made from a Node's content and relations, from documents and evidence. The contract is the boundary between memory and the environment that runs on it.

The next chapter follows one document through this contract from beginning to end.

Continue with Chapter 15, How a Document Becomes Nodes.