Skip to main content

​
Remember

POST /v1/gb/remember with {"user_id": "u1", "text": "Alice works at Acme and lives in Paris."} stores the text as an artifact and adds the facts it states to the graph, with the time they became true.
1

Extract

The text is sent to an LLM (Anthropic, default claude-haiku-5-5), which returns JSON listing entities (name, type, description) and edges (source, target, relation, description, valid_at, invalid_at).
2

Normalize

Entity types are lowercased (empty becomes other), and relations are lowercased with spaces replaced by _.
3

Reconcile

New edges are compared with stored live edges that touch the same entities. See Temporal facts.
4

Store

In one transaction: the raw text goes into gb_artifacts, entities are upserted into gb_entities and linked to the artifact, and edges are inserted into gb_edges.
Optional inputs: kind (knowledge or episode), reference_time (RFC 3339, so relative dates can be resolved) and session_id (see Sessions).

​
Deduplication

  • Entities are unique on (normalized name, type). Re-submitting one only updates its description if the new one is non-empty.
  • A new edge that repeats a stored fact that is still true (same source, target, relation) is merged instead of inserted.
  • An edge that mentions an entity the LLM didn’t list creates that entity with type other.
  • Sending the same text twice adds a second artifact but no duplicate entities or edges.
Long texts are chunked, images go through the image pipeline, and web_search can enrich the graph with recent world events. With geo turned on, the entities that are places get coordinates, stored in gb_entity_geo. With MCP turned on, MCP clients can call remember and query as tools of an MCP server at /v1/gb/mcp.

​
Models per stage

Each LLM-invoking stage of remember can run on its own model through the optional models object (extract_graph, resolve_edges, web_search, resolve_series, detect_geo, extract_image). A stage you leave out uses the default. See Choosing the model of each stage.

​
Query

POST /v1/gb/query with {"user_id": "u1", "query": "Where does Alice work?"}.
1

Retrieve

The query is split into terms. Entities are scored by keyword match against names and descriptions; the top 10 become seeds. If nothing matches, the 25 most recently updated entities are used.
2

Expand

Every edge touching a seed is added (newest first, up to 100) along with the entity at its other end: a one-hop subgraph.
3

Answer

The subgraph is rendered as text with IDs and sent to the LLM, which must answer only from the graph.
4

Verify evidence

Cited IDs are checked against the subgraph that was actually sent, so hallucinated IDs are dropped. Each cited edge carries its artifact_id, so a fact can be traced back to the original text.
If the graph is empty, a fixed “I don’t have any information” answer is returned without calling the LLM. Details: Query.

​
The temporal model

Every edge has event time (valid_at, invalid_at: when the fact was true in the world) and system time (created_at, expired_at: when gligabao learned it and when newer knowledge superseded it). Contradicted facts are closed, never deleted, so history is preserved. See Temporal facts.