---
title: "Search & retrieval"
description: "Query the knowledge graph — chat-identical context blocks, raw ranked facts, and cache warming."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & retrieval

Two endpoints read a user's memory, at different levels of processing — plus a cache-warming call to make the first read of a session fast. For which to use when, see [Choosing an endpoint](/memory/overview/#choosing-an-endpoint).

## Retrieve Memory Context

Returns exactly what Truememory injects into the LLM during a chat turn — the same pipeline as `POST /v1/chat/completions`: cached session context, low-information gating, and a per-message graph search. Use this when you run your **own** LLM and want Truememory's memory as a ready-made context block with identical recall to Truememory's automatic injection.

```bash
POST https://your-tie-host/memories/retrieve
Authorization: Bearer $TOKEN
Content-Type: application/json
```

**Request body:**

```json
{
  "query": "what should I eat for breakfast?",
  "agent_id": "chatbot",
  "display_name": "Alice Chen",
  "email": "alice@example.com"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | The user message to retrieve memories for (max 5,000 characters) |
| `agent_id` | string | Yes | Determines [memory scope](/memory/overview/#memory-scoping) |
| `display_name` | string | No | User display name rendered into the context prompt — pass it for parity with chat, where Truememory uses the authenticated user's name |
| `email` | string | No | User email rendered into the context prompt |
| `graph_ids` | string[] | No | Up to 4 [graph namespaces](/memory/graph-namespacing/) to blend into the per-message retrieval |

**Response:**

```json
{
  "query": "what should I eat for breakfast?",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "__shared__",
  "elapsed_seconds": 0.42,
  "context": {
    "data": { "entities": [...], "facts": [...] },
    "prompt": "## Known Entities\n...\n## Known Facts\n...",
    "cache_hit": true,
    "cache_age_seconds": 12.5,
    "source": "cache"
  },
  "retrieval": {
    "results": [
      {
        "id": "edge-uuid",
        "name": "PREFERS",
        "content": "User prefers a high-protein breakfast",
        "created_at": "2026-05-01T08:00:00Z",
        "valid_at": "2026-05-01T08:00:00Z",
        "source_name": "User",
        "target_name": "High-protein breakfast"
      }
    ],
    "prompt": "## Relevant memories for this message\n...",
    "low_info_skipped": false,
    "result_count": 1
  }
}
```

The response has two halves, mirroring the two memory fetches Truememory runs concurrently on every chat turn:

- **`context`** — the session-level block ("Known Entities / Known Facts"), cached for 5 minutes per user. `cache_hit` and `source` tell you whether it came from the hot cache or a database fallback.
- **`retrieval`** — facts found by a hybrid graph search against `query`. Skipped entirely for low-information messages (greetings, fillers) — indicated by `low_info_skipped: true`.

Both halves include a `prompt` string rendered with the same templates Truememory's own agents use. To replicate automatic injection, append `context.prompt` and `retrieval.prompt` to your system prompt as-is.

## Search Memory

Raw ranked facts from the knowledge graph — hybrid retrieval (BM25 + cosine similarity + graph traversal + cross-encoder reranking). Returns only the per-message search half, with no cached context block and no rendered prompts. Use [Retrieve Memory Context](#retrieve-memory-context) instead when you want the chat-identical payload.

```bash
POST https://your-tie-host/memories/search
Authorization: Bearer $TOKEN
Content-Type: application/json
```

**Request body:**

```json
{
  "query": "breakfast preferences",
  "agent_id": "chatbot",
  "max_results": 10
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query (max 5,000 characters) |
| `agent_id` | string | Yes | Determines [memory scope](/memory/overview/#memory-scoping) |
| `max_results` | integer | No | 1–50, default 10 |
| `created_after` | ISO 8601 datetime | No | Only return memories created after this time |
| `created_before` | ISO 8601 datetime | No | Only return memories created before this time |
| `graph_ids` | string[] | No | Up to 4 [graph namespaces](/memory/graph-namespacing/) to blend into the search |

**Response** — an array of fact edges, most relevant first:

```json
[
  {
    "id": "edge-uuid",
    "name": "PREFERS",
    "content": "User prefers a high-protein breakfast",
    "created_at": "2026-05-01T08:00:00Z",
    "valid_at": "2026-05-01T08:00:00Z",
    "source_name": "User",
    "target_name": "High-protein breakfast",
    "source_labels": ["Entity", "User"],
    "target_labels": ["Entity", "Object"],
    "source_descriptions": ["episode-source"],
    "scope": "user",
    "graph_id": null
  }
]
```

Each result carries a `scope` (`"user"` or `"graph"`) and, for namespace hits, the `graph_id` it came from — see [Graph Namespacing](/memory/graph-namespacing/).

## Warming the User Cache

Truememory uses a multi-tier retrieval architecture for memory. The fastest retrieval happens from a hot in-memory cache. After several minutes of inactivity, user data transitions to a slower tier — the next request falls back to a direct database query while a background job repopulates the cache.

You can signal to Truememory that a user is about to start chatting, prompting the system to proactively load their knowledge graph into cache before the first request arrives. The best time to do this is **when the user logs in or opens your app**.

```bash
POST https://your-tie-host/memories/graph/{user_id}/warm
Authorization: Bearer $TOKEN
```

| Parameter | In | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | path | Yes | The user's UUID |
| `agent_id` | query | No | Agent whose memory scope to warm. Defaults to the shared graph, which covers most agents. Only needed for agent-scoped memory (e.g. `rag-assistant`). |

With a user token, `user_id` must be your own — warming another user's cache returns `403 AUTH_SUBJECT_FORBIDDEN`. A service token may name any user, but if it also sends `X-On-Behalf-Of` or `X-External-User-Id` the two must agree, or the call returns `400 AUTH_SUBJECT_CONFLICT`.

**Response:**

```json
{
  "entities": [
    { "name": "Project Atlas", "summary": "A migration project the user is leading" },
    { "name": "Bruno", "summary": "Backend developer on the Finerminds team" }
  ],
  "facts": [
    "User is working on Truememory Auth integration",
    "Staging deployment target is April 1st"
  ]
}
```

The result is cached for **5 minutes**. Subsequent chat requests during that window return instantly from cache. If the cache has expired by the time a chat request arrives, Truememory uses a fast database query while triggering a background refresh. Calling this endpoint again performs a full search and re-populates the cache.

:::note[Deprecated path]
The previous endpoint `POST /context/{agent_id}` still works but is deprecated. Migrate to `/memories/graph/{user_id}/warm` when convenient.
:::

Source: https://truememory-docs.mvstg.com/memory/retrieval/index.mdx