Query Memory

Query Session Memory

Session Memory recalls conversation Message input in the current Session, plus the Facts, Summary, and Topic entries formed from those messages. session_id must refer to an existing Session. The user identity comes from the Session binding.

Request

Node

const memory = await session.getMemory({
  query: "which city should be used for Europe or Americas team scheduling"
});

Python

memory = session.get_memory(
    query="which city should be used for Europe or Americas team scheduling",
)

bash

curl -G "http://localhost:8000/api/sessions/session_xxx/context" \
  -H "Authorization: Api-Key your_api_key" \
  --data-urlencode "query=which city should be used for Europe or Americas team scheduling" \
  --data-urlencode "details=false"

Response Content

Common fields include:

Field	Description
project_id	Project ID for the current Memory query.
user_id	User ID bound to the current Session.
session_id	Session ID for the current query.
history	Message list returned from the current Session.
facts	Facts related to the query.
summary	Summary from the current Session or user context that can be used for this recall.
formatted_context	Server-formatted context suitable for an Agent prompt.

If details is enabled, the response can include lower-level source information, such as matched Message, Facts, Summary, and scores. Use these fields for debugging. For normal integration, prefer formatted_context.

RecallConfig

You can pass recall config to adjust Session Memory recall scope.

Node

const memory = await session.getMemory({
  query: "which city should be used for Europe or Americas team scheduling",
  details: true,
  recallConfig: {
    MessageRecentLimit: 20,
    MetadataFilters: {
      ping: "pong"
    }
  }
});

Python

memory = session.get_memory(
    query="which city should be used for Europe or Americas team scheduling",
    details=True,
    recall_config={
        "MessageRecentLimit": 20,
        "MetadataFilters": {
            "ping": "pong",
        },
    },
)

bash

curl -X POST "http://localhost:8000/api/sessions/session_xxx/context?query=which city should be used for Europe or Americas team scheduling&details=true" \
  -H "Authorization: Api-Key your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recall_config": {
      "MessageRecentLimit": 20,
      "MetadataFilters": {
        "ping": "pong"
      }
    }
  }'

Parameter	Public meaning	Description
MessageRecentLimit	Recent Message count	Number of recent Message entries to include.
MetadataFilters	Exact metadata filters	A simple metadata key-value dictionary used to narrow recall scope.

MetadataFilters keys must be non-empty strings, and values must be strings, numbers, or booleans. GUMem applies these exact-match filters inside the Project, user, and Session recall scope.

Query Behavior Memory

Behavior Memory recalls searches, filters, clicks, saves, tool calls, and business events written through User Actions or behavior Message input. The public query entry point is still Session Memory recall. Pass a query that describes the current task, then use metadata to filter the behavior scope.

Request

curl -sS -X POST \
  "https://gumem.asix.inc/api/user/actions/profile/recall" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "query": "any query",
    "recall_config": {
      "topk": 10,
      "metadata_filters": {
        "workspace": "docs",
        "ping": "pong"
      }
    }
  }'

Response Content

Behavior Memory uses the same response shape as Session Memory. The difference is that matched content usually comes from behavior Message input or from Facts, Summary, and Topic entries extracted from behavior Message input.

Field	Description
short_term_context	Recent or directly related behavior Message context from the current Session.
mid_term_context	Facts related to the behavior query, such as page views, filters, saves, or tool outputs.
long_term_user_context	Long-term user Summary derived from behavior across Sessions.
long_term_session_context	Summary formed from behavior signals inside the current Session.
formatted_context	Server-formatted context suitable for an Agent prompt.

If details is enabled, the response can include matched sources, metadata, Facts, Summary, and scores. Exact fields depend on the deployed GUMem API version.

RecallConfig

Behavior Memory recall parameters are passed in recall_config. The common fields are topk and metadata_filters: topk controls the maximum number of returned memories, and metadata_filters narrows the behavior scope, such as a workspace, event source, business object, or tracking label.

Parameter	Public meaning	Description
topk	Result count	Maximum number of behavior memories to return.
metadata_filters	Exact metadata filters	A simple metadata key-value dictionary used to filter behavior memory.

metadata_filters is a simple key-value dictionary, such as { "workspace": "docs", "ping": "pong" }. It does not express nested queries, range queries, or complex boolean conditions.

Recall Order

Long-term recall works by layer:

Topic -> Summary -> Facts -> Message

1. GUMem decides whether the query needs long-term memory.
2. If needed, GUMem recalls related Topic entries.
3. GUMem recalls Summary under those Topic entries.
4. If Summary is insufficient, GUMem adds supporting Facts.
5. GUMem combines the result with recent Message context from the current Session.

Topic narrows the search area. Summary provides usable long-term context. Facts explain provenance and add evidence.

Debugging Recall

If the result is not what you expected, check:

• The query is specific enough.
• Related Message input has been written.
• Long-term processing has generated Summary and Topic.
• metadata_filters did not filter out the related Memory.
• The Session is bound to the correct user.

If the response is empty, the Agent should not pretend it knows the user's preference. Ask for missing information, then write the confirmed Message back to GUMem.

Next Step

Read Update Memory to handle user corrections.