@maximem/synap-js-sdk 0.1.4 → 0.2.0

package/README.md

@@ -18,10 +18,10 @@ npm install @maximem/synap-js-sdk
 Install the Python runtime used by the wrapper:
 
 ```bash
-npx synap-js-sdk setup --sdk-version 0.1.1
+npx synap-js-sdk setup --sdk-version 0.2.0
 ```
 
-If you want the latest Python SDK version, omit `--sdk-version`.
+If you want the latest Python SDK version, omit `--sdk-version` and pass `--upgrade`.
 
 ## Verify Runtime
 
@@ -65,16 +65,27 @@ async function run() {
 
   await synap.addMemory({
     userId: 'user-123',
+    customerId: 'customer-456',
+    conversationId: 'conv-123',
     messages: [{ role: 'user', content: 'My name is Alex and I live in Austin.' }],
   });
 
-  const result = await synap.searchMemory({
+  const context = await synap.fetchUserContext({
     userId: 'user-123',
-    query: 'Where does the user live?',
+    customerId: 'customer-456',
+    conversationId: 'conv-123',
+    searchQuery: ['Where does the user live?'],
     maxResults: 10,
   });
 
-  console.log(result);
+  console.log(context.facts);
+
+  const promptContext = await synap.getContextForPrompt({
+    conversationId: 'conv-123',
+    style: 'structured',
+  });
+
+  console.log(promptContext.formattedContext);
   await synap.shutdown();
 }
 
@@ -97,9 +108,17 @@ This command can:
 ## Single-Flow Setup (JS + TS)
 
 ```bash
-npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version 0.1.1 && npx synap-js-sdk setup-ts
+npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version 0.2.0 && npx synap-js-sdk setup-ts
 ```
 
+## API Notes
+
+- `addMemory()` now requires `customerId` to match the Python SDK's explicit ingestion scope.
+- `fetchUserContext()`, `fetchCustomerContext()`, and `fetchClientContext()` expose the structured Python `ContextResponse` surface in JS/TS.
+- `getContextForPrompt()` exposes compacted context plus recent un-compacted messages.
+- `searchMemory()` and `getMemories()` remain convenience helpers built on top of user-scoped context fetches.
+- Temporal fields are exposed in JS/TS as `eventDate`, `validUntil`, `temporalCategory`, `temporalConfidence`, plus top-level `temporalEvents`.
+
 ## CLI Commands
 
 ```bash

package/bridge/synap_bridge.py

@@ -5,7 +5,9 @@ Protocol:
   stdin  -> {"id": 1, "method": "init", "params": {...}}\n
   stdout <- {"id": 1, "result": {...}, "error": null}\n
 Methods:
-  init, add_memory, search_memory, get_memories, delete_memory, shutdown
+  init, add_memory, search_memory, get_memories, fetch_user_context,
+  fetch_customer_context, fetch_client_context, get_context_for_prompt,
+  delete_memory, shutdown
 """
 
 import asyncio
@@ -51,6 +53,92 @@ def write_response(obj: dict) -> None:
     sys.stdout.flush()
 
 
+def tracking_key(user_id: str, customer_id: Optional[str]) -> str:
+    """Scope tracked memory IDs by both customer and user."""
+    return f"{customer_id or ''}::{user_id}"
+
+
+def serialize_context_response(context) -> dict:
+    """Serialize a Python ContextResponse for the JS bridge."""
+    payload = context.model_dump(mode="json")
+    payload["raw_response"] = context.raw if hasattr(context, "raw") else {}
+    return payload
+
+
+def serialize_context_for_prompt_response(response) -> dict:
+    """Serialize a Python ContextForPromptResponse for the JS bridge."""
+    return response.model_dump(mode="json")
+
+
+def flatten_context_items(context) -> List[dict]:
+    """Convert typed context collections into a flat memory list."""
+    items: List[dict] = []
+    for fact in context.facts:
+        items.append({
+            "id": fact.id,
+            "memory": fact.content,
+            "score": fact.confidence,
+            "source": fact.source,
+            "metadata": fact.metadata,
+            "context_type": "fact",
+            "event_date": str(fact.event_date) if getattr(fact, "event_date", None) else None,
+            "valid_until": str(fact.valid_until) if getattr(fact, "valid_until", None) else None,
+            "temporal_category": getattr(fact, "temporal_category", None),
+            "temporal_confidence": getattr(fact, "temporal_confidence", 0.0),
+        })
+    for preference in context.preferences:
+        items.append({
+            "id": preference.id,
+            "memory": preference.content,
+            "score": preference.strength,
+            "source": getattr(preference, "source", ""),
+            "metadata": preference.metadata,
+            "context_type": "preference",
+            "event_date": str(preference.event_date) if getattr(preference, "event_date", None) else None,
+            "valid_until": str(preference.valid_until) if getattr(preference, "valid_until", None) else None,
+            "temporal_category": getattr(preference, "temporal_category", None),
+            "temporal_confidence": getattr(preference, "temporal_confidence", 0.0),
+        })
+    for episode in context.episodes:
+        items.append({
+            "id": episode.id,
+            "memory": episode.summary,
+            "score": episode.significance,
+            "metadata": episode.metadata,
+            "context_type": "episode",
+            "event_date": str(episode.event_date) if getattr(episode, "event_date", None) else None,
+            "valid_until": str(episode.valid_until) if getattr(episode, "valid_until", None) else None,
+            "temporal_category": getattr(episode, "temporal_category", None),
+            "temporal_confidence": getattr(episode, "temporal_confidence", 0.0),
+        })
+    for emotion in context.emotions:
+        items.append({
+            "id": emotion.id,
+            "memory": emotion.context,
+            "score": emotion.intensity,
+            "metadata": emotion.metadata,
+            "context_type": "emotion",
+            "event_date": str(emotion.event_date) if getattr(emotion, "event_date", None) else None,
+            "valid_until": str(emotion.valid_until) if getattr(emotion, "valid_until", None) else None,
+            "temporal_category": getattr(emotion, "temporal_category", None),
+            "temporal_confidence": getattr(emotion, "temporal_confidence", 0.0),
+        })
+    for event in getattr(context, "temporal_events", []):
+        items.append({
+            "id": event.id,
+            "memory": event.content,
+            "score": event.temporal_confidence,
+            "source": event.source,
+            "metadata": event.metadata,
+            "context_type": "temporal_event",
+            "event_date": str(event.event_date) if event.event_date else None,
+            "valid_until": str(event.valid_until) if event.valid_until else None,
+            "temporal_category": event.temporal_category,
+            "temporal_confidence": event.temporal_confidence,
+        })
+    return items
+
+
 def messages_to_text(messages: List[dict]) -> str:
     lines: List[str] = []
     for message in messages:
@@ -147,7 +235,13 @@ async def handle_add_memory(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     messages = params["messages"]
+    conversation_id = params.get("conversation_id")
+    session_id = params.get("session_id")
+
+    if not customer_id:
+        raise ValueError("customer_id is required")
 
     step = time.perf_counter()
     transcript = messages_to_text(messages)
@@ -169,12 +263,26 @@ async def handle_add_memory(params: dict) -> dict:
 
     step = time.perf_counter()
     mode = params.get("mode", "long-range")
-    create_result = await sdk.memories.create(
-        document=transcript,
-        document_type="ai-chat-conversation",
-        user_id=user_id,
-        mode=mode,
-    )
+    document_type = params.get("document_type", "ai-chat-conversation")
+    document_id = params.get("document_id")
+    document_created_at = params.get("document_created_at")
+    metadata = params.get("metadata")
+
+    create_kwargs: dict = {
+        "document": transcript,
+        "document_type": document_type,
+        "user_id": user_id,
+        "customer_id": customer_id,
+        "mode": mode,
+    }
+    if document_id is not None:
+        create_kwargs["document_id"] = document_id
+    if document_created_at is not None:
+        create_kwargs["document_created_at"] = document_created_at
+    if metadata is not None:
+        create_kwargs["metadata"] = metadata
+
+    create_result = await sdk.memories.create(**create_kwargs)
     append_step(timings, "memories_create", step)
 
     ingestion_id = create_result.ingestion_id
@@ -186,10 +294,16 @@ async def handle_add_memory(params: dict) -> dict:
             if not content:
                 continue
             try:
+                role = message.get("role", "user")
                 await sdk.instance.send_message(
                     content=content,
-                    role=message.get("role", "user"),
+                    role=role,
+                    conversation_id=conversation_id,
                     user_id=user_id,
+                    customer_id=customer_id,
+                    session_id=session_id,
+                    event_type="assistant_message" if role == "assistant" else "user_message",
+                    metadata=message.get("metadata"),
                 )
             except Exception as exc:
                 logger.debug("gRPC send_message failed (non-fatal): %s", exc)
@@ -218,7 +332,7 @@ async def handle_add_memory(params: dict) -> dict:
 
     memory_ids = [str(memory_id) for memory_id in (final_status.memory_ids or [])]
     if memory_ids:
-        user_memory_ids.setdefault(user_id, []).extend(memory_ids)
+        user_memory_ids.setdefault(tracking_key(user_id, customer_id), []).extend(memory_ids)
 
     return {
         "success": final_status.status.value != "failed",
@@ -242,38 +356,29 @@ async def handle_search_memory(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     query = params["query"]
     max_results = params.get("max_results", 10)
     mode = params.get("mode", "fast")
+    conversation_id = params.get("conversation_id")
+    types = params.get("types", ["all"])
 
     start = time.perf_counter()
 
     step = time.perf_counter()
     context = await sdk.user.context.fetch(
         user_id=user_id,
+        customer_id=customer_id,
+        conversation_id=conversation_id,
         search_query=[query],
         max_results=max_results,
-        types=["all"],
+        types=types,
         mode=mode,
     )
     append_step(timings, "context_fetch", step)
 
     step = time.perf_counter()
-    results = []
-    for fact in context.facts:
-        results.append({"id": fact.id, "memory": fact.content, "score": fact.confidence})
-    for preference in context.preferences:
-        results.append(
-            {"id": preference.id, "memory": preference.content, "score": preference.strength}
-        )
-    for episode in context.episodes:
-        results.append(
-            {"id": episode.id, "memory": episode.summary, "score": episode.significance}
-        )
-    for emotion in context.emotions:
-        results.append(
-            {"id": emotion.id, "memory": emotion.context, "score": emotion.intensity}
-        )
+    results = flatten_context_items(context)
     append_step(timings, "map_context_results", step)
 
     return {
@@ -295,30 +400,28 @@ async def handle_get_memories(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     mode = params.get("mode", "fast")
+    conversation_id = params.get("conversation_id")
+    max_results = params.get("max_results", 100)
+    types = params.get("types", ["all"])
 
     start = time.perf_counter()
 
     step = time.perf_counter()
     context = await sdk.user.context.fetch(
         user_id=user_id,
+        customer_id=customer_id,
+        conversation_id=conversation_id,
         search_query=[],
-        max_results=100,
-        types=["all"],
+        max_results=max_results,
+        types=types,
         mode=mode,
     )
     append_step(timings, "context_fetch_all", step)
 
     step = time.perf_counter()
-    memories = []
-    for fact in context.facts:
-        memories.append({"id": fact.id, "memory": fact.content})
-    for preference in context.preferences:
-        memories.append({"id": preference.id, "memory": preference.content})
-    for episode in context.episodes:
-        memories.append({"id": episode.id, "memory": episode.summary})
-    for emotion in context.emotions:
-        memories.append({"id": emotion.id, "memory": emotion.context})
+    memories = flatten_context_items(context)
     append_step(timings, "map_memories", step)
 
     return {
@@ -326,7 +429,113 @@ async def handle_get_memories(params: dict) -> dict:
         "latencyMs": ms_since(start),
         "memories": memories,
         "memoriesCount": len(memories),
+        "totalCount": len(memories),
         "rawResponse": context.raw if hasattr(context, "raw") else {},
+        "source": context.metadata.source if context.metadata else "unknown",
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_fetch_user_context(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.user.context.fetch(
+        user_id=params["user_id"],
+        customer_id=params.get("customer_id"),
+        conversation_id=params.get("conversation_id"),
+        search_query=params.get("search_query"),
+        max_results=params.get("max_results", 10),
+        types=params.get("types"),
+        mode=params.get("mode", "fast"),
+    )
+    append_step(timings, "context_fetch", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context": serialize_context_response(context),
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_fetch_customer_context(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.customer.context.fetch(
+        customer_id=params["customer_id"],
+        conversation_id=params.get("conversation_id"),
+        search_query=params.get("search_query"),
+        max_results=params.get("max_results", 10),
+        types=params.get("types"),
+        mode=params.get("mode", "fast"),
+    )
+    append_step(timings, "context_fetch", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context": serialize_context_response(context),
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_fetch_client_context(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.client.context.fetch(
+        conversation_id=params.get("conversation_id"),
+        search_query=params.get("search_query"),
+        max_results=params.get("max_results", 10),
+        types=params.get("types"),
+        mode=params.get("mode", "fast"),
+    )
+    append_step(timings, "context_fetch", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context": serialize_context_response(context),
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_get_context_for_prompt(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    response = await sdk.conversation.get_context_for_prompt(
+        conversation_id=params["conversation_id"],
+        style=params.get("style", "structured"),
+    )
+    append_step(timings, "get_context_for_prompt", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context_for_prompt": serialize_context_for_prompt_response(response),
         "bridgeTiming": {
             "python_total_ms": ms_since(handler_start),
             "steps": timings,
@@ -339,6 +548,7 @@ async def handle_delete_memory(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     memory_id = params.get("memory_id")
 
     start = time.perf_counter()
@@ -350,6 +560,7 @@ async def handle_delete_memory(params: dict) -> dict:
         return {
             "success": True,
             "latencyMs": ms_since(start),
+            "deletedCount": 1,
             "rawResponse": {"deleted": 1},
             "bridgeTiming": {
                 "python_total_ms": ms_since(handler_start),
@@ -357,11 +568,15 @@ async def handle_delete_memory(params: dict) -> dict:
             },
         }
 
-    tracked_ids = user_memory_ids.get(user_id, [])
+    if not customer_id:
+        raise ValueError("customer_id is required when memory_id is not provided")
+
+    tracked_ids = user_memory_ids.get(tracking_key(user_id, customer_id), [])
     if not tracked_ids:
         return {
             "success": True,
             "latencyMs": 0,
+            "deletedCount": 0,
             "rawResponse": None,
             "note": "No tracked memory IDs for this user",
             "bridgeTiming": {
@@ -380,7 +595,7 @@ async def handle_delete_memory(params: dict) -> dict:
             last_error = str(exc)
     append_step(timings, "delete_tracked_memories", step)
 
-    user_memory_ids.pop(user_id, None)
+    user_memory_ids.pop(tracking_key(user_id, customer_id), None)
 
     if last_error:
         return {
@@ -396,6 +611,7 @@ async def handle_delete_memory(params: dict) -> dict:
     return {
         "success": True,
         "latencyMs": ms_since(start),
+        "deletedCount": len(tracked_ids),
         "rawResponse": {"deleted": len(tracked_ids)},
         "note": f"Deleted {len(tracked_ids)} memories",
         "bridgeTiming": {
@@ -434,6 +650,10 @@ HANDLERS = {
     "add_memory": handle_add_memory,
     "search_memory": handle_search_memory,
     "get_memories": handle_get_memories,
+    "fetch_user_context": handle_fetch_user_context,
+    "fetch_customer_context": handle_fetch_customer_context,
+    "fetch_client_context": handle_fetch_client_context,
+    "get_context_for_prompt": handle_get_context_for_prompt,
     "delete_memory": handle_delete_memory,
     "shutdown": handle_shutdown,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maximem/synap-js-sdk",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "JavaScript wrapper around the Synap Python SDK",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/setup-typescript.js

@@ -64,6 +64,10 @@ function getWrapperTemplate() {
   type AddMemoryInput,
   type SearchMemoryInput,
   type GetMemoriesInput,
+  type FetchUserContextInput,
+  type FetchCustomerContextInput,
+  type FetchClientContextInput,
+  type GetContextForPromptInput,
   type DeleteMemoryInput,
 } from '@maximem/synap-js-sdk';
 
@@ -90,6 +94,22 @@ export class SynapTsClient {
     return this.client.getMemories(input);
   }
 
+  fetchUserContext(input: FetchUserContextInput) {
+    return this.client.fetchUserContext(input);
+  }
+
+  fetchCustomerContext(input: FetchCustomerContextInput) {
+    return this.client.fetchCustomerContext(input);
+  }
+
+  fetchClientContext(input?: FetchClientContextInput) {
+    return this.client.fetchClientContext(input);
+  }
+
+  getContextForPrompt(input: GetContextForPromptInput) {
+    return this.client.getContextForPrompt(input);
+  }
+
   deleteMemory(input: DeleteMemoryInput) {
     return this.client.deleteMemory(input);
   }

package/src/synap-client.js

@@ -1,5 +1,200 @@
 const { BridgeManager } = require('./bridge-manager');
 
+function pickDefined(...values) {
+  for (const value of values) {
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function normalizeTemporalFields(item = {}) {
+  return {
+    eventDate: pickDefined(item.eventDate, item.event_date, null),
+    validUntil: pickDefined(item.validUntil, item.valid_until, null),
+    temporalCategory: pickDefined(item.temporalCategory, item.temporal_category, null),
+    temporalConfidence: pickDefined(item.temporalConfidence, item.temporal_confidence, 0),
+  };
+}
+
+function normalizeMemoryItem(item = {}) {
+  return {
+    id: item.id || '',
+    memory: pickDefined(item.memory, item.content, ''),
+    score: item.score,
+    source: item.source,
+    metadata: item.metadata || {},
+    contextType: pickDefined(item.contextType, item.context_type),
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeContextMetadata(metadata = {}) {
+  return {
+    correlationId: pickDefined(metadata.correlationId, metadata.correlation_id, ''),
+    ttlSeconds: pickDefined(metadata.ttlSeconds, metadata.ttl_seconds, 0),
+    source: metadata.source || 'unknown',
+    retrievedAt: pickDefined(metadata.retrievedAt, metadata.retrieved_at, null),
+    compactionApplied: pickDefined(metadata.compactionApplied, metadata.compaction_applied, null),
+  };
+}
+
+function normalizeConversationContext(value) {
+  if (!value) return null;
+  return {
+    summary: value.summary || null,
+    currentState: pickDefined(value.currentState, value.current_state, {}),
+    keyExtractions: pickDefined(value.keyExtractions, value.key_extractions, {}),
+    recentTurns: pickDefined(value.recentTurns, value.recent_turns, []),
+    compactionId: pickDefined(value.compactionId, value.compaction_id, null),
+    compactedAt: pickDefined(value.compactedAt, value.compacted_at, null),
+    conversationId: pickDefined(value.conversationId, value.conversation_id, null),
+  };
+}
+
+function normalizeFact(item = {}) {
+  return {
+    id: item.id || '',
+    content: item.content || '',
+    confidence: pickDefined(item.confidence, 0),
+    source: item.source || '',
+    extractedAt: pickDefined(item.extractedAt, item.extracted_at, null),
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizePreference(item = {}) {
+  return {
+    id: item.id || '',
+    category: item.category || '',
+    content: item.content || '',
+    strength: pickDefined(item.strength, item.confidence, 0),
+    source: item.source || '',
+    extractedAt: pickDefined(item.extractedAt, item.extracted_at, null),
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeEpisode(item = {}) {
+  return {
+    id: item.id || '',
+    summary: pickDefined(item.summary, item.content, ''),
+    occurredAt: pickDefined(item.occurredAt, item.occurred_at, null),
+    significance: pickDefined(item.significance, item.confidence, 0),
+    participants: item.participants || [],
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeEmotion(item = {}) {
+  return {
+    id: item.id || '',
+    emotionType: pickDefined(item.emotionType, item.emotion_type, ''),
+    intensity: pickDefined(item.intensity, item.confidence, 0),
+    detectedAt: pickDefined(item.detectedAt, item.detected_at, null),
+    context: item.context || '',
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeTemporalEvent(item = {}) {
+  return {
+    id: item.id || '',
+    content: item.content || '',
+    eventDate: pickDefined(item.eventDate, item.event_date, null),
+    validUntil: pickDefined(item.validUntil, item.valid_until, null),
+    temporalCategory: pickDefined(item.temporalCategory, item.temporal_category, ''),
+    temporalConfidence: pickDefined(item.temporalConfidence, item.temporal_confidence, 0),
+    confidence: pickDefined(item.confidence, 0),
+    source: item.source || '',
+    extractedAt: pickDefined(item.extractedAt, item.extracted_at, null),
+    metadata: item.metadata || {},
+  };
+}
+
+function normalizeContextResponse(result = {}) {
+  const context = result.context || result;
+  return {
+    facts: (context.facts || []).map(normalizeFact),
+    preferences: (context.preferences || []).map(normalizePreference),
+    episodes: (context.episodes || []).map(normalizeEpisode),
+    emotions: (context.emotions || []).map(normalizeEmotion),
+    temporalEvents: (pickDefined(context.temporalEvents, context.temporal_events, []) || []).map(normalizeTemporalEvent),
+    conversationContext: normalizeConversationContext(
+      pickDefined(context.conversationContext, context.conversation_context, null)
+    ),
+    metadata: normalizeContextMetadata(context.metadata || {}),
+    rawResponse: pickDefined(context.rawResponse, context.raw_response, {}),
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeRecentMessage(item = {}) {
+  return {
+    role: item.role || 'user',
+    content: item.content || '',
+    timestamp: item.timestamp || null,
+    messageId: pickDefined(item.messageId, item.message_id, ''),
+  };
+}
+
+function normalizeContextForPromptResult(result = {}) {
+  const payload = pickDefined(result.contextForPrompt, result.context_for_prompt, result);
+  return {
+    formattedContext: pickDefined(payload.formattedContext, payload.formatted_context, null),
+    available: !!payload.available,
+    isStale: !!pickDefined(payload.isStale, payload.is_stale, false),
+    compressionRatio: pickDefined(payload.compressionRatio, payload.compression_ratio, null),
+    validationScore: pickDefined(payload.validationScore, payload.validation_score, null),
+    compactionAgeSeconds: pickDefined(payload.compactionAgeSeconds, payload.compaction_age_seconds, null),
+    qualityWarning: !!pickDefined(payload.qualityWarning, payload.quality_warning, false),
+    recentMessages: (pickDefined(payload.recentMessages, payload.recent_messages, []) || []).map(normalizeRecentMessage),
+    recentMessageCount: pickDefined(payload.recentMessageCount, payload.recent_message_count, 0),
+    compactedMessageCount: pickDefined(payload.compactedMessageCount, payload.compacted_message_count, 0),
+    totalMessageCount: pickDefined(payload.totalMessageCount, payload.total_message_count, 0),
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeSearchMemoryResult(result = {}) {
+  return {
+    success: !!result.success,
+    latencyMs: result.latencyMs || 0,
+    results: (result.results || []).map(normalizeMemoryItem),
+    resultsCount: pickDefined(result.resultsCount, result.results?.length, 0),
+    rawResponse: result.rawResponse || {},
+    source: result.source,
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeGetMemoriesResult(result = {}) {
+  const memories = (result.memories || []).map(normalizeMemoryItem);
+  return {
+    success: !!result.success,
+    latencyMs: result.latencyMs || 0,
+    memories,
+    totalCount: pickDefined(result.totalCount, result.memoriesCount, memories.length, 0),
+    rawResponse: pickDefined(result.rawResponse, null),
+    source: result.source,
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeDeleteMemoryResult(result = {}) {
+  return {
+    success: !!result.success,
+    latencyMs: result.latencyMs || 0,
+    deletedCount: pickDefined(result.deletedCount, result.rawResponse?.deleted, 0),
+    rawResponse: pickDefined(result.rawResponse, null),
+    note: result.note,
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
 class SynapClient {
   constructor(options = {}) {
     this.bridge = new BridgeManager(options);
@@ -14,42 +209,122 @@ class SynapClient {
     await this.bridge.ensureStarted();
   }
 
-  async addMemory({ userId, messages, mode }) {
+  async addMemory({
+    userId,
+    customerId,
+    conversationId,
+    sessionId,
+    messages,
+    mode,
+    documentType,
+    documentId,
+    documentCreatedAt,
+    metadata,
+  }) {
     this.#assert(userId, 'userId is required');
+    this.#assert(customerId, 'customerId is required');
     this.#assert(Array.isArray(messages), 'messages must be an array');
 
     const params = { user_id: userId, messages };
+    params.customer_id = customerId;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (sessionId !== undefined) params.session_id = sessionId;
     if (mode !== undefined) params.mode = mode;
+    if (documentType !== undefined) params.document_type = documentType;
+    if (documentId !== undefined) params.document_id = documentId;
+    if (documentCreatedAt !== undefined) params.document_created_at = documentCreatedAt;
+    if (metadata !== undefined) params.metadata = metadata;
 
     return this.bridge.call('add_memory', params, this.options.ingestTimeoutMs);
   }
 
-  async searchMemory({ userId, query, maxResults = 10, mode }) {
+  async searchMemory({ userId, customerId, query, maxResults = 10, mode, conversationId, types }) {
     this.#assert(userId, 'userId is required');
     this.#assert(query, 'query is required');
+    this.#assertArray(types, 'types must be an array when provided');
 
     const params = { user_id: userId, query, max_results: maxResults };
+    if (customerId !== undefined) params.customer_id = customerId;
     if (mode !== undefined) params.mode = mode;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (types !== undefined) params.types = types;
 
-    return this.bridge.call('search_memory', params);
+    return normalizeSearchMemoryResult(await this.bridge.call('search_memory', params));
   }
 
-  async getMemories({ userId, mode }) {
+  async getMemories({ userId, customerId, mode, conversationId, maxResults, types }) {
     this.#assert(userId, 'userId is required');
+    this.#assertArray(types, 'types must be an array when provided');
 
     const params = { user_id: userId };
+    if (customerId !== undefined) params.customer_id = customerId;
     if (mode !== undefined) params.mode = mode;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (maxResults !== undefined) params.max_results = maxResults;
+    if (types !== undefined) params.types = types;
 
-    return this.bridge.call('get_memories', params);
+    return normalizeGetMemoriesResult(await this.bridge.call('get_memories', params));
   }
 
-  async deleteMemory({ userId, memoryId = null }) {
+  async fetchUserContext({ userId, customerId, conversationId, searchQuery, maxResults = 10, types, mode }) {
     this.#assert(userId, 'userId is required');
+    this.#assertArray(searchQuery, 'searchQuery must be an array when provided');
+    this.#assertArray(types, 'types must be an array when provided');
 
-    return this.bridge.call('delete_memory', {
-      user_id: userId,
-      memory_id: memoryId,
-    });
+    const params = { user_id: userId, max_results: maxResults };
+    if (customerId !== undefined) params.customer_id = customerId;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (searchQuery !== undefined) params.search_query = searchQuery;
+    if (types !== undefined) params.types = types;
+    if (mode !== undefined) params.mode = mode;
+
+    return normalizeContextResponse(await this.bridge.call('fetch_user_context', params));
+  }
+
+  async fetchCustomerContext({ customerId, conversationId, searchQuery, maxResults = 10, types, mode }) {
+    this.#assert(customerId, 'customerId is required');
+    this.#assertArray(searchQuery, 'searchQuery must be an array when provided');
+    this.#assertArray(types, 'types must be an array when provided');
+
+    const params = { customer_id: customerId, max_results: maxResults };
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (searchQuery !== undefined) params.search_query = searchQuery;
+    if (types !== undefined) params.types = types;
+    if (mode !== undefined) params.mode = mode;
+
+    return normalizeContextResponse(await this.bridge.call('fetch_customer_context', params));
+  }
+
+  async fetchClientContext({ conversationId, searchQuery, maxResults = 10, types, mode } = {}) {
+    this.#assertArray(searchQuery, 'searchQuery must be an array when provided');
+    this.#assertArray(types, 'types must be an array when provided');
+
+    const params = { max_results: maxResults };
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (searchQuery !== undefined) params.search_query = searchQuery;
+    if (types !== undefined) params.types = types;
+    if (mode !== undefined) params.mode = mode;
+
+    return normalizeContextResponse(await this.bridge.call('fetch_client_context', params));
+  }
+
+  async getContextForPrompt({ conversationId, style } = {}) {
+    this.#assert(conversationId, 'conversationId is required');
+
+    const params = { conversation_id: conversationId };
+    if (style !== undefined) params.style = style;
+
+    return normalizeContextForPromptResult(await this.bridge.call('get_context_for_prompt', params));
+  }
+
+  async deleteMemory({ userId, customerId, memoryId = null }) {
+    this.#assert(userId, 'userId is required');
+    if (memoryId == null) this.#assert(customerId, 'customerId is required when memoryId is not provided');
+
+    const params = { user_id: userId, memory_id: memoryId };
+    if (customerId !== undefined) params.customer_id = customerId;
+
+    return normalizeDeleteMemoryResult(await this.bridge.call('delete_memory', params));
   }
 
   async shutdown() {
@@ -60,6 +335,10 @@ class SynapClient {
     if (!value) throw new Error(message);
   }
 
+  #assertArray(value, message) {
+    if (value !== undefined && !Array.isArray(value)) throw new Error(message);
+  }
+
   #registerShutdownHooks() {
     const close = async () => {
       try {

package/types/index.d.ts

@@ -1,4 +1,28 @@
 export type LogLevel = 'debug' | 'error';
+export type RetrievalMode = 'fast' | 'accurate';
+export type IngestMode = 'fast' | 'long-range';
+export type PromptStyle = 'structured' | 'narrative' | 'bullet_points';
+export type ContextType =
+  | 'all'
+  | 'facts'
+  | 'preferences'
+  | 'episodes'
+  | 'emotions'
+  | 'temporal_events';
+export type FlattenedContextType =
+  | 'fact'
+  | 'preference'
+  | 'episode'
+  | 'emotion'
+  | 'temporal_event';
+export type DocumentType =
+  | 'ai-chat-conversation'
+  | 'document'
+  | 'email'
+  | 'pdf'
+  | 'image'
+  | 'audio'
+  | 'meeting-transcript';
 
 export interface BridgeLogHandler {
   (level: LogLevel, message: string): void;
@@ -31,30 +55,81 @@ export interface SynapClientOptions {
 }
 
 export interface ChatMessage {
-  role?: string;
+  role?: 'user' | 'assistant';
   content: string;
+  metadata?: Record<string, string>;
 }
 
 export interface AddMemoryInput {
   userId: string;
+  customerId: string;
+  conversationId?: string;
+  sessionId?: string;
   messages: ChatMessage[];
+  mode?: IngestMode;
+  documentType?: DocumentType;
+  documentId?: string;
+  documentCreatedAt?: string;
+  metadata?: Record<string, unknown>;
 }
 
 export interface SearchMemoryInput {
   userId: string;
+  customerId?: string;
   query: string;
   maxResults?: number;
+  mode?: RetrievalMode;
+  conversationId?: string;
+  types?: ContextType[];
 }
 
 export interface GetMemoriesInput {
   userId: string;
+  customerId?: string;
+  mode?: RetrievalMode;
+  conversationId?: string;
+  maxResults?: number;
+  types?: ContextType[];
 }
 
 export interface DeleteMemoryInput {
   userId: string;
+  customerId?: string;
   memoryId?: string | null;
 }
 
+export interface FetchUserContextInput {
+  userId: string;
+  customerId?: string;
+  conversationId?: string;
+  searchQuery?: string[];
+  maxResults?: number;
+  types?: ContextType[];
+  mode?: RetrievalMode;
+}
+
+export interface FetchCustomerContextInput {
+  customerId: string;
+  conversationId?: string;
+  searchQuery?: string[];
+  maxResults?: number;
+  types?: ContextType[];
+  mode?: RetrievalMode;
+}
+
+export interface FetchClientContextInput {
+  conversationId?: string;
+  searchQuery?: string[];
+  maxResults?: number;
+  types?: ContextType[];
+  mode?: RetrievalMode;
+}
+
+export interface GetContextForPromptInput {
+  conversationId: string;
+  style?: PromptStyle;
+}
+
 export interface BridgeStepTiming {
   step: string;
   ms: number;
@@ -65,6 +140,115 @@ export interface BridgeTiming {
   steps: BridgeStepTiming[];
 }
 
+export interface TemporalFields {
+  eventDate: string | null;
+  validUntil: string | null;
+  temporalCategory: string | null;
+  temporalConfidence: number;
+}
+
+export interface Fact extends TemporalFields {
+  id: string;
+  content: string;
+  confidence: number;
+  source: string;
+  extractedAt: string | null;
+  metadata: Record<string, unknown>;
+}
+
+export interface Preference extends TemporalFields {
+  id: string;
+  category: string;
+  content: string;
+  strength: number;
+  source: string;
+  extractedAt: string | null;
+  metadata: Record<string, unknown>;
+}
+
+export interface Episode extends TemporalFields {
+  id: string;
+  summary: string;
+  occurredAt: string | null;
+  significance: number;
+  participants: string[];
+  metadata: Record<string, unknown>;
+}
+
+export interface Emotion extends TemporalFields {
+  id: string;
+  emotionType: string;
+  intensity: number;
+  detectedAt: string | null;
+  context: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface TemporalEvent {
+  id: string;
+  content: string;
+  eventDate: string | null;
+  validUntil: string | null;
+  temporalCategory: string;
+  temporalConfidence: number;
+  confidence: number;
+  source: string;
+  extractedAt: string | null;
+  metadata: Record<string, unknown>;
+}
+
+export interface RecentMessage {
+  role: string;
+  content: string;
+  timestamp: string | null;
+  messageId: string;
+}
+
+export interface ContextResponseMetadata {
+  correlationId: string;
+  ttlSeconds: number;
+  source: string;
+  retrievedAt: string | null;
+  compactionApplied: string | null;
+}
+
+export interface ConversationContext {
+  summary: string | null;
+  currentState: Record<string, unknown>;
+  keyExtractions: Record<string, Array<Record<string, unknown>>>;
+  recentTurns: Array<Record<string, unknown>>;
+  compactionId: string | null;
+  compactedAt: string | null;
+  conversationId: string | null;
+}
+
+export interface ContextResponse {
+  facts: Fact[];
+  preferences: Preference[];
+  episodes: Episode[];
+  emotions: Emotion[];
+  temporalEvents: TemporalEvent[];
+  conversationContext: ConversationContext | null;
+  metadata: ContextResponseMetadata;
+  rawResponse: Record<string, unknown>;
+  bridgeTiming?: BridgeTiming;
+}
+
+export interface ContextForPromptResult {
+  formattedContext: string | null;
+  available: boolean;
+  isStale: boolean;
+  compressionRatio: number | null;
+  validationScore: number | null;
+  compactionAgeSeconds: number | null;
+  qualityWarning: boolean;
+  recentMessages: RecentMessage[];
+  recentMessageCount: number;
+  compactedMessageCount: number;
+  totalMessageCount: number;
+  bridgeTiming?: BridgeTiming;
+}
+
 export interface AddMemoryResult {
   success: boolean;
   latencyMs: number;
@@ -73,10 +257,13 @@ export interface AddMemoryResult {
   bridgeTiming?: BridgeTiming;
 }
 
-export interface SearchMemoryItem {
+export interface SearchMemoryItem extends TemporalFields {
   id: string;
   memory: string;
   score?: number;
+  source?: string;
+  metadata: Record<string, unknown>;
+  contextType?: FlattenedContextType;
 }
 
 export interface SearchMemoryResult {
@@ -89,22 +276,23 @@ export interface SearchMemoryResult {
   bridgeTiming?: BridgeTiming;
 }
 
-export interface MemoryItem {
-  id: string;
-  memory: string;
-}
+export interface MemoryItem extends SearchMemoryItem {}
 
 export interface GetMemoriesResult {
   success: boolean;
   latencyMs: number;
   memories: MemoryItem[];
   totalCount: number;
+  rawResponse: Record<string, unknown> | null;
+  source?: string;
   bridgeTiming?: BridgeTiming;
 }
 
 export interface DeleteMemoryResult {
   success: boolean;
+  latencyMs: number;
   deletedCount: number;
+  rawResponse: Record<string, unknown> | null;
   note?: string;
   bridgeTiming?: BridgeTiming;
 }
@@ -115,6 +303,10 @@ export class SynapClient {
   addMemory(input: AddMemoryInput): Promise<AddMemoryResult>;
   searchMemory(input: SearchMemoryInput): Promise<SearchMemoryResult>;
   getMemories(input: GetMemoriesInput): Promise<GetMemoriesResult>;
+  fetchUserContext(input: FetchUserContextInput): Promise<ContextResponse>;
+  fetchCustomerContext(input: FetchCustomerContextInput): Promise<ContextResponse>;
+  fetchClientContext(input?: FetchClientContextInput): Promise<ContextResponse>;
+  getContextForPrompt(input: GetContextForPromptInput): Promise<ContextForPromptResult>;
   deleteMemory(input: DeleteMemoryInput): Promise<DeleteMemoryResult>;
   shutdown(): Promise<void>;
 }