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.

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.

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

Request body:

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

Response:

{
  "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 instead when you want the chat-identical payload.

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

Request body:

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

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

[
  {
    "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.

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.

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

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:

{
  "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.