Verified Examples

Complete the four-step path

1. 1
   Configure a trusted server client

   Load the API key from a server-side environment variable. Choose a project and a stable opaque ID for the end user your server represents.

   PythonNode.jscURL

   import os
   from memorysync import MemorySyncClient
   
   client = MemorySyncClient(
       api_key=os.environ["MEMORYSYNC_API_KEY"],
       base_url="https://api.memorysync.io",
       project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
       end_user_id="user-123",
   )

2. 2
   Add one useful memory

   Write a confirmed preference with a source, stable tag, and small non-secret metadata object. Branch on created versus skipped.

   PythonNode.jscURL

   import os
   from memorysync import MemorySyncClient
   
   client = MemorySyncClient(
       api_key=os.environ["MEMORYSYNC_API_KEY"],
       base_url="https://api.memorysync.io",
       project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
       end_user_id="user-123",
   )
   
   result = client.add(
       "The user prefers concise answers.",
       source="profile",
       tags=["preference"],
       importance=0.7,
       metadata={"setting_id": "response-style"},
   )
   
   if getattr(result, "status", None) == "skipped":
       print("Not stored:", result.reason)
   else:
       print("Created:", result.id)

3. 3
   Retrieve it for a later task

   Ask for the context needed by the task and use the same project and end-user scope. This example narrows candidates with the verified tag shape.

   PythonNode.jscURL

   import os
   from memorysync import MemorySyncClient
   
   client = MemorySyncClient(
       api_key=os.environ["MEMORYSYNC_API_KEY"],
       base_url="https://api.memorysync.io",
       project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
       end_user_id="user-123",
   )
   
   result = client.query(
       "How should I format the answer?",
       k=5,
       filters={"tags": ["preference"]},
   )
   
   for memory in result.memories:
       print(memory.text)

4. 4
   Authorize and use the result

   An empty array is valid. For returned candidates, apply application authorization, select useful records, and delimit them as untrusted context before sending anything to a model.

   Memory found

   Use only the fields your task needs.

   • •Check application access.
   • •Select relevant candidates.
   • •Keep memory separate from instructions.

   Nothing found

   Continue safely without durable context.

   • •Use a product fallback.
   • •Avoid inventing remembered facts.
   • •Do not retry an unchanged query in a loop.

Expected checkpoints

Before moving beyond the example

• Replace user-123 with a stable opaque ID selected after your own authorization check.
• Choose tags and metadata names from a small application-owned vocabulary.
• Add bounded handling for rate limits, server errors, timeouts, and ambiguous write outcomes.
• Connect forget operations to account deletion, consent, and support workflows.
• Evaluate retrieval with representative questions and expected facts from your own product.

Go deeper by task