Organizational context is knowledge stored at the CLIENT scope — the broadest application-level scope in Synap’s hierarchy. It represents your product’s documentation, feature announcements, domain knowledge, and any other information that should be accessible to every user across every customer organization. When your AI agent needs to answer questions about your product or domain, organizational context is where that knowledge lives.
Think of organizational context as the “product brain” — the universal knowledge base that every user benefits from, regardless of which customer organization they belong to. It is the shared floor of knowledge beneath all customer-specific and user-specific memories.
Organizational context is created by ingesting documents without specifying user_id or customer_id. This causes Synap to store the resulting memories at the Client scope.
from synap import Synapsdk = Synap(api_key="your_api_key")# Ingest a single product documentawait sdk.memories.create( document=""" # Synap API Rate Limits All API endpoints are subject to rate limiting to ensure fair usage: - Free tier: 100 requests per minute - Pro tier: 1,000 requests per minute - Enterprise tier: 10,000 requests per minute Rate limit headers are included in every response: - X-RateLimit-Limit: maximum requests per window - X-RateLimit-Remaining: requests remaining in current window - X-RateLimit-Reset: seconds until the window resets When rate limited, the API returns HTTP 429 with a Retry-After header. """, document_type="document" # No user_id or customer_id -- stored at CLIENT scope)
Batch ingestion is the recommended approach for loading product documentation. It is more efficient than individual calls and ensures all documents are processed as a cohesive set for better entity resolution across documents.
More commonly, organizational context surfaces automatically during user conversations. When you retrieve context for a specific user and customer, Synap searches the full scope chain and includes relevant Client-scoped memories alongside user-specific and customer-specific ones:
# User asks about rate limits during a conversationcontext = await sdk.user.context.fetch( user_id="user_alice", customer_id="acme_corp", search_query=["what are the API rate limits"])# Results may include memories from all scopes:# USER scope: "Alice has exceeded rate limits twice this month" (highest priority)# CUSTOMER scope: "Acme Corp is on the Enterprise tier" (high priority)# CLIENT scope: "Enterprise tier: 10,000 requests per minute" (medium priority)
In this example, the agent can combine all three scopes to give a complete answer: “Your Enterprise plan allows 10,000 requests per minute. I notice you have hit rate limits twice this month — would you like to review your usage patterns?”
Organizational context is cached with a 30-minute TTL (time to live). This caching exists because organizational knowledge changes infrequently — product documentation is updated periodically, not on every request. The 30-minute TTL provides a balance between freshness and retrieval performance.
Aspect
Detail
Cache TTL
30 minutes
Cache scope
Per-Instance
Cache invalidation
Automatic on TTL expiry; manual via API if needed
Why cache
Organizational context is read-heavy, write-infrequent
If you update product documentation and need the changes to be reflected immediately, you can invalidate the cache manually. For most use cases, the 30-minute TTL is sufficient — new ingestions will be visible within 30 minutes of processing completion.
How organizational context merges with other scopes
During retrieval, organizational context is merged with customer-scoped and user-scoped memories following the scope chain priority rules. The merge process handles conflicts and redundancy:
Scenario
Resolution
Same fact at multiple scopes
Narrower scope wins (user > customer > client)
Complementary facts
All are included, ranked by relevance
Contradicting facts
Narrower scope takes priority; broader scope may be included with lower rank
Budget exceeded
Narrower-scope memories are preserved first; organizational context is trimmed if necessary
This means that organizational context serves as a knowledge baseline that can be overridden by more specific customer or user context. For example:
Client scope: “Default support hours are 9am-5pm EST”
Customer scope: “Acme Corp has 24/7 premium support”
When Alice at Acme Corp asks about support hours, the customer-scoped memory takes priority, and the agent correctly responds with “24/7 premium support.”
A common pattern is to load your product documentation into organizational context when your application starts, and then update it whenever documentation changes:
from synap import Synapimport globsdk = Synap(api_key="your_api_key")async def load_product_docs(): """Load all product documentation into organizational context.""" doc_files = glob.glob("docs/**/*.md", recursive=True) documents = [] for filepath in doc_files: with open(filepath, "r") as f: documents.append({ "document": f.read(), "document_type": "document", }) # Batch ingest at CLIENT scope result = await sdk.memories.batch_create(documents=documents) print(f"Loaded {len(documents)} documents, created {result.memory_count} memories")async def handle_user_question(user_id: str, customer_id: str, question: str): """Handle a user question, drawing on organizational + personal context.""" context = await sdk.user.context.fetch( user_id=user_id, customer_id=customer_id, search_query=[question] ) # Build prompt with retrieved context prompt = f"""You are a helpful support agent.Context from memory:- Facts: {context.facts}- Preferences: {context.preferences}User question: {question}""" # Pass prompt to your LLM...
