Query

Before querying data, make sure to configure the API key in your environment.

In the current version, memories are eventually consistent. Memories may not be available for querying for up to 5 minutes after adding them for the first time.

You can query a graph by using the query method.

  from circlemind import Circlemind

  # Initialize the client
  client = Circlemind()

  # Query the memories
  res = client.query(
    query="Where does Sophie like to hike?",
    graph_id="customer-id-123"
  )

  print(res.response)

The graph_id is an optional parameter. If not set, it defaults to the default graph.

The res.response will be a natural language response to your query.

​

Include references

Using the keyword with_references, it is possible to include the references to the sources used to generate an answer. These sources can then be formatted and injected into the answer with the function .format_references.

  from circlemind import Circlemind

  # Initialize the client
  client = Circlemind()

  # Query the memories
  res = client.query(
    query="Where does Sophie like to hike?",
    graph_id="customer-id-123",
    with_references=True
  )

  answer, references = res.format_references()
  print(answer)  # Sophie likes to hike on the Alps [1]
  print(references)  # {'1': {<metadata>}}
  

It is possible to provide custom formatting when injecting the references by passing a custom replacing function to .format_references (the default being lambda i, _: f"[{i}]"). For example, assuming each memory’s metadata contains a URL, we can provide markdown formatting with links to the sources used.

  answer, references = res.format_references(
    lambda i, metadata: f"[{i}]({metadata['url']})"
  )
  print(answer)  # Sophie likes to hike on the Alps [1](https://people/profiles/sophie/preferences)

where i is an incremental index automatically generated for each source used.

​

Only context

It is also possible to request only the context retrieved by Circlemind, skipping the answer generation step. This can be helpful if, for example, you want to control the style used to generate your answer or to use custom LLMs. To achieve this, it is simply necessary to specify the flag only_context=True when querying a graph. The context will be available via .context:

res = client.query(
    query="Where does Sophie like to hike?",
    graph_id="customer-id-123",
    only_context=True
  )

print(res.context)

​

Context length

By default, Circlemind reserves the following amount of tokens for each data source:

This behaviour can be customised by specifiying new values for each data source using the parameters entities_max_tokens, relations_max_tokens, chunks_max_tokens. For example:

res = client.query(
    query="Where does Sophie like to hike?",
    graph_id="customer-id-123",
    with_references=True,
    entities_max_tokens=-1,
    relations_max_tokens=-1,
    chunks_max_tokens=16000
  )

will return exclusively the chunk data.

Notes:

• when requesting a non-negative number of tokens, Circlemind will try to fill in any available token space from other sources (e.g., when reserving 100 tokens for entities and relations and 1000 for chunks, if the chunks only use 900 tokens, the remaining 100 available tokens will be distributed to entities and relations).
• use the special value “-1” to disable this behaviour and effectively reserve 0 tokens for the target data sources.