Skip to main content
For conversation-level context fetch and compaction during agent interactions, use the Python SDK which provides sdk.conversation.context.fetch() and sdk.conversation.context.compact() with automatic authentication, retries, and streaming support.

​
Fetch Client Context

Retrieve organizational context scoped to your application (client). Client-scoped memories are visible to all users across all customers. This is typically used for product knowledge, documentation, and announcements that were ingested via bootstrap ingestion. 
POST /v1/context/client/fetch

​
Request Body

​
search_query
string | string[]
One or more search queries to find relevant organizational memories. If omitted, returns the most recent and highest-confidence client-scoped memories.
​
max_results
integer
Maximum number of memory items to return. Defaults to 10. Maximum 50.
​
types
string[]
Filter results to specific memory types. If omitted, all types are included.
ValueDescription
factFactual information about your organization or product
preferenceOrganizational preferences and standards
episodeSignificant organizational events
temporal_eventTime-bound organizational events (launches, deadlines)
​
mode
string
Retrieval mode that controls the speed-quality tradeoff.
ValueDescription
fastVector search only. Lowest latency (~50-100ms).
accurateFull vector + graph + re-ranking. Highest quality (~200-500ms). Default.

​
Response

​
facts
array
Array of fact memories relevant to the query. Each includes content, confidence, entities, source, and relevance_score.
​
preferences
array
Array of preference memories.
​
episodes
array
Array of episode memories.
​
metadata
object
Response metadata including total_results, query_time_ms, tokens_used, scope, and mode.

​
Example

curl -X POST "https://api.synap.maximem.ai/v1/context/client/fetch" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "search_query": ["product features", "API rate limits"],
    "max_results": 5,
    "types": ["fact"],
    "mode": "accurate"
  }'
Response
{
  "facts": [
    {
      "id": "mem_org_a1b2c3d4",
      "content": "The API rate limit is 1000 requests per minute for Enterprise tier",
      "confidence": 0.97,
      "entities": [],
      "source": {
        "ingestion_id": "ing_bootstrap_001",
        "document_type": "knowledge-article",
        "document_created_at": "2025-01-10T00:00:00Z"
      },
      "relevance_score": 0.94
    },
    {
      "id": "mem_org_e5f67890",
      "content": "Platform supports SSO with SAML and OIDC protocols",
      "confidence": 0.95,
      "entities": [],
      "source": {
        "ingestion_id": "ing_bootstrap_002",
        "document_type": "document",
        "document_created_at": "2025-01-10T00:00:00Z"
      },
      "relevance_score": 0.87
    }
  ],
  "preferences": [],
  "episodes": [],
  "metadata": {
    "total_results": 2,
    "query_time_ms": 124,
    "tokens_used": 289,
    "scope": {
      "client_id": "cli_a1b2c3d4e5f67890"
    },
    "mode": "accurate"
  }
}
Client context is cached with a 30-minute TTL. Repeated queries within the TTL window are served from cache without re-querying the storage engines. New bootstrap ingestions automatically invalidate the cache.

​
Fetch Customer Context

Retrieve context scoped to a specific customer organization. Customer-scoped memories are visible to all users within that customer. This is useful for fetching shared organizational knowledge, company policies, and team-wide context. 
POST /v1/context/customer/fetch

​
Request Body

​
customer_id
string
required
The customer identifier to fetch context for.
​
search_query
string | string[]
One or more search queries to find relevant customer memories. If omitted, returns the most recent and highest-confidence customer-scoped memories.
​
max_results
integer
Maximum number of memory items to return. Defaults to 10. Maximum 50.
​
types
string[]
Filter results to specific memory types. If omitted, all types are included.
ValueDescription
factFactual information about the customer organization
preferenceCustomer organizational preferences
episodeSignificant events within the customer organization
emotionSentiment and emotional context within the organization
temporal_eventTime-bound events (project deadlines, fiscal year, etc.)
​
mode
string
Retrieval mode that controls the speed-quality tradeoff.
ValueDescription
fastVector search only. Lowest latency (~50-100ms).
accurateFull vector + graph + re-ranking. Highest quality (~200-500ms). Default.
​
include_client_context
boolean
Whether to also include client-scoped (organizational) context in the results. Defaults to true. When enabled, results merge customer-scoped and client-scoped memories, with customer-scoped memories taking priority.

​
Response

​
facts
array
Array of fact memories relevant to the query.
​
preferences
array
Array of preference memories.
​
episodes
array
Array of episode memories.
​
emotions
array
Array of emotion memories.
​
metadata
object
Response metadata including total_results, query_time_ms, tokens_used, scope, and mode.

​
Example

curl -X POST "https://api.synap.maximem.ai/v1/context/customer/fetch" \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_acme_corp",
    "search_query": ["project management tools", "engineering stack"],
    "max_results": 5,
    "types": ["fact", "preference"],
    "mode": "accurate",
    "include_client_context": true
  }'
Response
{
  "facts": [
    {
      "id": "mem_cust_f1a2b3c4",
      "content": "Acme Corp uses Jira for project management and Slack for communication",
      "confidence": 0.94,
      "entities": [
        { "canonical_name": "Acme Corp", "type": "organization", "entity_id": "ent_acme001" }
      ],
      "source": {
        "ingestion_id": "ing_cust_7a8b9c0d",
        "document_type": "ai-chat-conversation",
        "document_created_at": "2025-01-12T14:30:00Z"
      },
      "relevance_score": 0.92,
      "scope": "customer"
    },
    {
      "id": "mem_cust_d5e6f7a8",
      "content": "Engineering team uses Python 3.11 and PostgreSQL for all services",
      "confidence": 0.91,
      "entities": [
        { "canonical_name": "Acme Corp Engineering", "type": "team", "entity_id": "ent_acme_eng" }
      ],
      "source": {
        "ingestion_id": "ing_cust_0a9b8c7d",
        "document_type": "document",
        "document_created_at": "2025-01-08T09:00:00Z"
      },
      "relevance_score": 0.88,
      "scope": "customer"
    }
  ],
  "preferences": [
    {
      "id": "mem_cust_b9c0d1e2",
      "content": "Team prefers detailed code reviews over quick approvals",
      "confidence": 0.87,
      "entities": [],
      "source": {
        "ingestion_id": "ing_cust_7a8b9c0d",
        "document_type": "ai-chat-conversation",
        "document_created_at": "2025-01-12T14:30:00Z"
      },
      "relevance_score": 0.79,
      "scope": "customer"
    }
  ],
  "episodes": [],
  "emotions": [],
  "metadata": {
    "total_results": 3,
    "query_time_ms": 187,
    "tokens_used": 456,
    "scope": {
      "customer_id": "cust_acme_corp",
      "client_id": "cli_a1b2c3d4e5f67890"
    },
    "mode": "accurate"
  }
}
When include_client_context is true, memories from both customer and client scopes are merged and ranked together. Customer-scoped memories take priority over client-scoped memories when they cover the same topic, following the scope chain priority rules.