MaximemSynap Python SDK

Python client library for the MaximemSynap context management system.

Installation

pip install maximem-synap

Quick Start

from maximem_synap import MaximemSynapSDK, ContextType, CompactionLevel

# Initialize SDK (reads SYNAP_API_KEY from your environment)
sdk = MaximemSynapSDK()

# Fetch conversation context
context = sdk.conversation.fetch(
    conversation_id="conv-123",
    search_query="user preferences",
    max_results=10,
    types=[ContextType.FACTS, ContextType.PREFERENCES]
)

# Access context items
for item in context.items:
    print(f"{item.context_type}: {item.content}")

# Compact conversation context
compacted = sdk.conversation.compact(
    conversation_id="conv-123",
    compaction_level=CompactionLevel.BALANCED
)

# Fetch user context
user_context = sdk.user.fetch(
    user_id="user-456",
    conversation_id="conv-123",  # Optional
    max_results=20
)

# Listen for real-time updates
sdk.instance.listen()
# ... your application logic ...
sdk.instance.stop()

# Cleanup
sdk.shutdown()

Configuration

from maximem_synap import CacheConfig, TimeoutConfig

# Configure caching
cache_config = CacheConfig(
    enabled=True,
    ttl_seconds=300,
    max_entries=1000
)

# Configure timeouts
timeout_config = TimeoutConfig(
    connect_timeout_ms=5000,
    read_timeout_ms=30000,
    total_timeout_ms=60000
)

# Apply configuration
sdk.configure(
    cache=cache_config,
    log_level="DEBUG",
    timeouts=timeout_config
)

Environment Variables

SYNAP_API_KEY: Your Synap API key

Context Controllers

Conversation Context

# Fetch conversation context
context = sdk.conversation.fetch(
    conversation_id="conv-123",
    search_query="optional search",
    max_results=10,
    types=[ContextType.FACTS]
)

# Compact conversation context
compacted = sdk.conversation.compact(
    conversation_id="conv-123",
    compaction_level=CompactionLevel.ADAPTIVE
)

User Context

context = sdk.user.fetch(
    user_id="user-456",
    conversation_id="conv-123",  # Optional
    types=[ContextType.PREFERENCES, ContextType.EMOTIONS]
)

Customer Context

context = sdk.customer.fetch(
    customer_id="cust-789",
    conversation_id="conv-123"  # Optional
)

Client Context

context = sdk.client.fetch(
    client_id="client-abc",
    conversation_id="conv-123"  # Optional
)

Error Handling

from maximem_synap import (
    SDKError,
    AgentUnavailableError,
    ContextNotFoundError,
    AuthenticationError
)

try:
    context = sdk.conversation.fetch(conversation_id="conv-123")
except AgentUnavailableError as e:
    # Retryable error
    print(f"Agent unavailable: {e}")
except ContextNotFoundError as e:
    # Non-retryable error
    print(f"Context not found: {e}")
except AuthenticationError as e:
    # Authentication failed
    print(f"Auth error: {e}")
except SDKError as e:
    # Base exception
    print(f"SDK error: {e}, retryable: {e.retryable}")

Context Types

ContextType.FACTS: Factual information
ContextType.PREFERENCES: User preferences
ContextType.EPISODES: Conversation episodes
ContextType.EMOTIONS: Emotional context
ContextType.TEMPORAL: Time-based context
ContextType.ALL: All context types

Compaction Levels

CompactionLevel.AGGRESSIVE: Maximum compression
CompactionLevel.BALANCED: Balanced approach
CompactionLevel.CONSERVATIVE: Minimal compression
CompactionLevel.ADAPTIVE: Adaptive based on context

License

MIT

Development Status
- 3 - Alpha
Intended Audience
- Developers
Programming Language

Metadata

Development Status
- 3 - Alpha
Intended Audience
- Developers
Programming Language

Release files for maximem-synap 0.5.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maximem-synap 0.5.5
File	Size	Uploaded
maximem_synap-0.5.5.tar.gz	170.0 kB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for maximem-synap 0.5.5
File	Interpreter	ABI	Platform	Reset
maximem_synap-0.5.5-py3-none-any.whl 176.1 kB Oct 7, 2026	Python 3	none	any	Details

Total release size: 346.1 kB

Release files / maximem_synap-0.5.5.tar.gz

Download URL	maximem_synap-0.5.5.tar.gz
Size	170.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`acfc5d4130ac2ab8b23e3cd52d3d44ff92395b15ac489212c62f00d19c64f8a9`
BLAKE2b-256 checksum How to use checksums	`dbb4b50fc4240936c4d110f9e16dd5ff2db9a8c8ccc75d0e9e7a778ee9846880`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`

Release files / maximem_synap-0.5.5-py3-none-any.whl

Download URL	maximem_synap-0.5.5-py3-none-any.whl
Size	176.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0a20574cee400bdc83b07e8697459b2df04b0e4b3055c925916c8ff7b9bceb9c`
BLAKE2b-256 checksum How to use checksums	`82370feca43d0512d95458e0339a4a03c64c3509c8ee78bb60f5ef576c794238`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.2`