> ## Documentation Index
> Fetch the complete documentation index at: https://gligabao.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How it works

> Remember, query, and the bi-temporal knowledge graph underneath.

## Remember

`POST /v1/gb/remember` with `{"user_id": "u1", "text": "Alice works at Acme and lives in Paris."}` stores the text as an [artifact](https://gligabao.mintlify.site/concepts/artifacts.md) 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](https://gligabao.mintlify.site/concepts/temporal.md).

**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](https://gligabao.mintlify.site/concepts/sessions.md)).

### 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](https://gligabao.mintlify.site/guides/chunking.md), images go through the [image pipeline](https://gligabao.mintlify.site/guides/images.md), and `web_search` can [enrich the graph](https://gligabao.mintlify.site/guides/web-search.md) with recent world events. With [geo](https://gligabao.mintlify.site/guides/geo.md) turned on, the entities that are places get coordinates, stored in `gb_entity_geo`.

### 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](https://gligabao.mintlify.site/api-reference/remember.md#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](https://gligabao.mintlify.site/api-reference/query.md).

## 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](https://gligabao.mintlify.site/concepts/temporal.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.