OpenGradient Docs

Appearance

MemSync ​

MemSync is a long-term memory layer for AI built on top of OpenGradient's verifiable inference and embeddings infrastructure. It provides a REST API for long-term context management and AI personalization, enabling you to build AI applications that remember user context and provide personalized experiences.

Overview ​

MemSync automatically extracts meaningful memories from conversations, organizes them intelligently, and makes them searchable through semantic search. This allows your AI applications to maintain context across sessions and provide truly personalized interactions.

Resources ​

For comprehensive documentation and detailed API reference, see:

  • MemSync Guide - Complete guide with detailed examples and advanced features
  • API Documentation - Interactive API reference with all endpoints and parameters

Key Features ​

  • Automatic Memory Extraction: Automatically extracts meaningful facts and memories from conversations
  • Semantic Search: Search across personal memories using semantic similarity for relevant context retrieval
  • Memory Types: Intelligently classifies memories as semantic (lasting facts) or episodic (time-bound events)
  • User Profiles: Auto-generates user profiles with bios and insights from stored memories
  • Memory Categories: Organizes memories into categories like career, interests, relationships, and more
  • REST API: Simple REST API for easy integration into any application

Quick Start ​

Prerequisites ​

  • A MemSync account and API key
  • Basic knowledge of REST APIs
  • Your preferred programming language setup (Python, JavaScript, curl, etc.)

Authentication ​

MemSync uses API key-based authentication for all API requests. Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Note: OAuth 2.0 authentication will be available soon for enhanced security.

Step 1: Store Your First Memory ​

Store a conversation that MemSync will process to extract meaningful memories:

python
import requests

url = "https://api.memchat.io/v1/memories"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "messages": [
        {
            "role": "user", 
            "content": "I'm a software engineer at Google working on machine learning projects. I love hiking and photography in my free time."
        },
        {
            "role": "assistant", 
            "content": "That's great! It sounds like you have a nice balance between your technical work and creative hobbies."
        }
    ],
    "agent_id": "my-chatbot",
    "thread_id": "conversation-123",
    "source": "chat"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Step 2: Search for Relevant Memories ​

Search for memories related to user interests:

python
import requests

url = "https://api.memchat.io/v1/memories/search"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "query": "What does the user do for work?",
    "limit": 5,
    "rerank": True
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

print("User Bio:", result['user_bio'])
print("Relevant Memories:")
for memory in result['memories']:
    print(f"- {memory['memory']}")

Step 3: Get User Profile ​

Retrieve the user's complete profile with auto-generated bio and insights:

python
import requests

url = "https://api.memchat.io/v1/users/profile"
headers = {
    "X-API-Key": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
profile = response.json()

print("User Bio:", profile['user_bio'])
print("Profiles:", profile['profiles'])
print("Insights:", profile['insights'])

Memory Types ​

MemSync uses two distinct types of memories to capture different kinds of information:

Semantic Memories ​

Semantic memories represent stable, lasting facts that are not tied to a specific time or place. These are core truths about a user that remain relatively constant over time.

Characteristics:

  • Persistent: Don't change frequently
  • Context-independent: True regardless of when or where they were mentioned
  • Factual: Represent established knowledge about the user
  • Searchable: Highly valuable for providing relevant context

Examples:

  • Identity: "User is a software engineer at Google"
  • Skills: "Experienced in Python and machine learning"
  • Preferences: "Prefers working in collaborative environments"
  • Interests: "Passionate about hiking and photography"

Episodic Memories ​

Episodic memories relate to current situations, goals, or projects that might change over time. They are tied to specific moments and could evolve or become outdated.

Characteristics:

  • Time-bound: Relevant to a specific period or context
  • Dynamic: May change, complete, or become irrelevant over time
  • Situational: Tied to particular circumstances or goals
  • Contextual: Provide important background for current interactions

Examples:

  • Current Projects: "Currently working on a new iOS app"
  • Active Goals: "Learning how to cook new recipes"
  • Recent Events: "Just moved to a new apartment last week"
  • Temporary States: "Currently traveling in Europe for 2 weeks"

Memory Classification ​

MemSync automatically classifies memories during extraction using advanced language models. The system analyzes:

  • Temporal indicators (words like "currently", "recently", "always")
  • Context and content analysis
  • Conversation patterns

Understanding Search Results ​

When you search for memories, MemSync returns:

json
{
  "user_bio": "Software engineer at Google specializing in machine learning with interests in hiking and photography",
  "memories": [
    {
      "id": "mem_123",
      "memory": "Works as a software engineer at Google focusing on machine learning projects",
      "categories": ["career"],
      "type": "semantic",
      "vector_distance": 0.15,
      "rerank_score": 0.92,
      "source": "chat",
      "created_at": "2024-03-20T10:00:00Z"
    }
  ]
}

Key Fields:

  • user_bio: Auto-generated summary of the user
  • memory: The extracted fact or memory
  • categories: Organized tags (career, interests, etc.)
  • type: semantic (lasting facts) or episodic (time-bound events)
  • vector_distance: Similarity score for search relevance
  • rerank_score: Enhanced relevance score when reranking is enabled

Use Cases ​

MemSync is ideal for building:

  • Personalized Chatbots: Chatbots that remember user preferences and context across conversations
  • AI Assistants: Virtual assistants that learn about users over time
  • Context-Aware Applications: Applications that adapt based on user history and preferences
  • Memory-Enhanced LLM Apps: LLM applications that maintain long-term context beyond token limits

Best Practices ​

Memory Extraction ​

  • Provide rich conversation context to help MemSync understand what information is important
  • Include relevant details that help classify memories correctly
  • Use consistent terminology for better memory organization

Search Strategy ​

  • Use broad queries to find semantic memories (e.g., "What does the user do for work?")
  • Use specific queries to find episodic memories (e.g., "What is the user currently working on?")
  • Combine both types in search results for comprehensive context
  • Enable reranking for better relevance when needed

Memory Lifecycle ​

  • Semantic memories typically have longer relevance
  • Episodic memories may need periodic updates or cleanup
  • Monitor memory relevance over time and update as needed

API Base URL ​

All MemSync API endpoints are available at:

https://api.memchat.io/v1

Common Issues ​

401 Unauthorized Error: Make sure your API key is valid and included in the X-API-Key header.

No memories returned: It may take a few seconds for memories to be processed and indexed. Try searching again, or check that your conversation contained meaningful information.

Rate limiting: MemSync has rate limits to ensure service quality. If you hit limits, implement exponential backoff in your retry logic.