> ## 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`. With [MCP](https://gligabao.mintlify.site/guides/mcp.md) 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](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*. The question is also embedded and searched in the entity, edge, chunk and summary [vector indexes](https://gligabao.mintlify.site/guides/vectors.md#what-query-reads): similar entities (up to 10) join the seeds, similar facts are added with their entities, and the chunks of long texts that are close to the question become *passages*. If there are no seeds and no similar facts, the 25 most recently updated entities are used.

**2. Expand**

Every live edge touching a seed is added (newest first, up to 100) along with the entity at its other end: a one-hop subgraph. Facts that newer knowledge superseded are never retrieved (see [Facts over time](https://gligabao.mintlify.site/api-reference/query.md#facts-over-time-and-history)).

**3. Answer**

The subgraph and the passages (the best three with the text of the chunk) are rendered as text with IDs and sent to the LLM, which must answer only from them.

**4. Verify evidence**

Cited IDs are checked against what 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 there is nothing to answer from (no entity, fact or passage), 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.