Technical Reference
A memory is an incrementally-editable graph. Writes are additive and atomic at the observation level; the entity and relationship graph is derived from those observations and maintained as they change. Retrieval is entity-primary and performs no language-model synthesis — the calling agent does that.
Data model
| Object | Fields | Notes |
|---|---|---|
| Observation | title, content, category, tags, observed-at, confidence, source | The unit of write, edit and delete. Identified by a stable slug |
| Entity | name, type, description, degree | Names are normalized, so the same name in two observations resolves to one entity |
| Relationship | source, type, target, description, weight | Directional — the authored order is preserved |
| Appendix file | path, filename, type, size, description, created-by | Stored per memory, referenced from observations by path |
Write contract
- Every entity requires a non-empty description. It is the primary retrieval signal; an entity without one is not retrievable and the write is rejected.
- Observations are soft-capped at roughly 2,000 characters. Longer content should be split into separate observations, with the source document placed in the appendix and referenced by path.
- Relationships are optional but strongly encouraged — they are what makes a recall return more than the note you already had.
- Entities may carry retrieval queries: a couple of questions the entity should answer, folded into how it is matched.
Repeated writes naming an existing entity merge into it rather than creating a duplicate. Write responses return the neighborhood of each touched entity, so a caller can reuse existing names and spot stale edges instead of duplicating them.
Recall
Two modes, both free of language-model calls.
| Mode | Trigger | Selection |
|---|---|---|
| Semantic | A query string | Ranks entities against the query, then returns their subgraph |
| Structural | No query | Filters observations by category, tags, time range or entity name |
Both return the same shape: a ranked entity list, the relationships among them, and one bounded snippet per source observation. The payload is capped — entities, relationships and observations each have a ceiling, and a note is included when results were truncated.
Snippets are short by design. An observation longer than the snippet is flagged truncated, and the full text is fetched on demand by slug. This keeps a recall well under the tool-response size limit while still grounding every entity in the note it came from.
Retrieval is entity-primary, not document-primary. A query matches entity descriptions first; observations come back because an entity in them ranked, not because the query matched their text. This is why recalling one person also surfaces the projects and organizations attached to them.
Edit and delete semantics
- The slug is stable identity. Changing an observation's title does not change its slug, so follow-up edits against a previously returned slug keep working. Title is display-only.
- Updates merge, they don't replace. Passing a partial entity list on an edit unions it with the observation's current graph; the caller wins on conflicts. Omitting an entity does not remove it — removal is explicit.
- A materially changed entity description triggers a review hint. The response lists that entity's existing relationships so their descriptions can be refreshed; nothing is rewritten automatically, because an edge description may still be correct after a node changes.
- Deleting an observation prunes orphans. Entities and relationships backed only by that observation are removed; anything referenced elsewhere survives.
Consolidation
Consolidation reviews a store and emits proposals — chiefly entity merges where the same real-world thing was recorded under variant names. Proposals are never applied automatically; each is accepted or rejected. Accepting a merge reassigns every relationship endpoint to the canonical entity, drops self-loops, and recomputes degrees.
Access tiers
Access is granted per agent-to-memory connection, not per agent.
| Tier | Adds |
|---|---|
read | Recall, inspect an entity, read an observation in full, list and read appendix files |
read_write | Add observations, store files, run consolidation — additive only |
full | Update and delete existing observations — corrective |
New connections default to read_write. The tiers are strictly nested; a tier grants everything below it.
Behavior and limits
- Writes are serialized per memory. Concurrent writes to one store queue rather than interleave; reads are never blocked.
- A store's retrieval configuration is fixed at creation and cannot be edited. Changing it would make existing and new entries mutually unsearchable, so it is a migration, not a setting.
- Ordering is not guaranteed across agents. Two agents writing in the same period may land in either order; observations are independent, so this does not corrupt the graph, but it does mean "latest wins" is not a safe assumption for contradictory facts. Correct contradictions with an explicit edit.
- Recall results are capped, and the response says so when results were dropped. Narrow with a category, tag or time filter rather than raising expectations of the cap.
- A memory shared at organization visibility is readable by the whole organization; the access tier still governs what any given agent may do with it.