API Usage Guide

API Usage Guide

This document provides detailed instructions on how to use MemSys API interfaces to store and retrieve memory data.

📋 Table of Contents

• API Overview
• Memory Storage APIs
  • V1 Memory API
  • V1 Memory API
  • API Selection Guide
• Group Chat Data Format
• Using Scripts to Store Memories
• API Call Examples

🔍 API Overview

MemSys provides two standardized API interfaces for storing memories:

Available APIs

API Comparison

Important Note: Both APIs use identical storage formats, so you can choose based on your needs. If you need retrieval functionality, we recommend using V1 Memory API for complete feature support.

🚀 Memory Storage APIs

V1 Memory API

Recommended for scenarios requiring complete functionality (storage + retrieval).

Endpoint

POST /api/v1/memories

Features

• ✅ Simple direct single message format
• ✅ Supports lightweight retrieval (RRF fusion)
• ✅ Supports Agentic intelligent retrieval (LLM-assisted)
• ✅ Supports session metadata management

For detailed documentation, see: Memory API Documentation

V1 Memory API

Recommended for simple scenarios requiring only storage functionality.

Endpoint

POST /api/v1/memories

Features

• ✅ Simple direct single message format
• ✅ Focused on memory storage
• ✅ Supports session metadata management (with PATCH partial updates)

For detailed documentation, see: Memory API Documentation

API Selection Guide

Use V1 Memory API (/api/v1/memories) if:

• ✅ You need intelligent retrieval functionality
• ✅ You need to build a complete memory system (storage + retrieval)
• ✅ You want to use lightweight or Agentic retrieval modes

Use V1 Memory API (/api/v1/memories) if:

• ✅ You only need to store memories without retrieval
• ✅ You have your own retrieval solution
• ✅ You prefer a more concise dedicated storage interface

Note: Both APIs use identical data formats and underlying storage mechanisms. The main difference is that V1 API provides additional retrieval functionality.

📝 Memorize API Details

Request Format (Common to Both APIs)

Both APIs use the same simple direct single message format:

{
  "message_id": "msg_001",
  "create_time": "2025-02-01T10:00:00+00:00",
  "sender": "user_103",
  "sender_name": "Chen",
  "content": "Message content",
  "refer_list": [],
  "group_id": "group_001",
  "group_name": "Project Discussion Group"
}

Field Descriptions

Response Format

{
  "code": 0,
  "message": "success",
  "result": {
    "count": 2,
    "saved_memories": [
      {
        "memory_id": "mem_001",
        "type": "episode",
        "content": "Extracted memory content"
      }
    ]
  }
}

Call Examples

cURL

curl -X POST http://localhost:1995/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_001",
    "create_time": "2025-02-01T10:00:00+00:00",
    "sender": "user_103",
    "sender_name": "Chen",
    "content": "We need to complete the product design this week",
    "group_id": "group_001",
    "group_name": "Project Discussion Group"
  }'

Python

import httpx
import asyncio

async def store_memory():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:1995/api/v1/memories",
            json={
                "message_id": "msg_001",
                "create_time": "2025-02-01T10:00:00+00:00",
                "sender": "user_103",
                "sender_name": "Chen",
                "content": "We need to complete the product design this week",
                "group_id": "group_001",
                "group_name": "Project Discussion Group"
            }
        )
        print(response.json())

asyncio.run(store_memory())

JavaScript

fetch('http://localhost:1995/api/v1/memories', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message_id: 'msg_001',
    create_time: '2025-02-01T10:00:00+00:00',
    sender: 'user_103',
    sender_name: 'Chen',
    content: 'We need to complete the product design this week',
    group_id: 'group_001',
    group_name: 'Project Discussion Group'
  })
})
.then(response => response.json())
.then(data => console.log(data));

Using V1 Memory API:

fetch('http://localhost:1995/api/v1/memories', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message_id: 'msg_001',
    create_time: '2025-02-01T10:00:00+00:00',
    sender: 'user_103',
    sender_name: 'Chen',
    content: 'We need to complete the product design this week',
    group_id: 'group_001',
    group_name: 'Project Discussion Group'
  })
})
.then(response => response.json())
.then(data => console.log(data));

📁 Group Chat Data Format

MemSys defines a standardized group chat data format GroupChatFormat for storing and exchanging group chat conversation data.

Format Overview

{
  "version": "1.0.0",
  "conversation_meta": {
    "group_id": "group_001",
    "name": "Project Discussion Group",
    "default_timezone": "+00:00",
    "user_details": {
      "user_101": {
        "full_name": "Alex",
        "role": "Technical Lead",
        "department": "Engineering"
      }
    }
  },
  "conversation_list": [
    {
      "message_id": "msg_001",
      "create_time": "2025-02-01T10:00:00+00:00",
      "sender": "user_101",
      "sender_name": "Alex",
      "type": "text",
      "content": "Good morning everyone",
      "refer_list": []
    }
  ]
}

Core Features

1. Separated Metadata and Message List

   • conversation_meta: Group chat metadata
   • conversation_list: Message list

2. Centralized User Details

   • All user information stored in user_details
   • Messages only need to reference user IDs

3. Timezone-aware Timestamps

   • Uses ISO 8601 format
   • Supports timezone information

4. Flexible Message References

   • Supports string references (message_id only)
   • Supports object references (complete message information)

Detailed Documentation

For complete format specification, see: Group Chat Format Specification

🔧 Using Scripts to Store Memories

MemSys provides the run_memorize.py script for batch storing group chat data into the system. The script supports both API interfaces.

Script Location

src/run_memorize.py

Basic Usage

Run using the Bootstrap script with V1 API:

Using V1 Memory API (Recommended, supports retrieval):

uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --api-url http://localhost:1995/api/v1/memories

Using V1 Memory API (Storage only):

uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --api-url http://localhost:1995/api/v1/memories

Command Line Arguments

Usage Examples

1. Store Memories

Using V1 Memory API:

# Basic usage
uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --api-url http://localhost:1995/api/v1/memories

# Using relative path
uv run python src/bootstrap.py src/run_memorize.py \
  --input ../my_data/chat_history.json \
  --api-url http://localhost:1995/api/v1/memories

# Specifying remote server
uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --api-url http://api.example.com/api/v1/memories

Using V1 Memory API:

# Basic usage
uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --api-url http://localhost:1995/api/v1/memories

# Using relative path
uv run python src/bootstrap.py src/run_memorize.py \
  --input ../my_data/chat_history.json \
  --api-url http://localhost:1995/api/v1/memories

2. Validate File Format

Validate file format before storing:

uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --validate-only

Script Workflow

1. Validate Input File

   • Check if JSON format is correct
   • Verify compliance with GroupChatFormat specification
   • Output data statistics

2. Process Messages One by One

   • Read each message from group chat file
   • Call API to store each message
   • Display processing progress and results

3. Output Processing Results

   • Number of successfully processed messages
   • Number of saved memories
   • Failed messages (if any)

Output Example

🚀 Group Chat Memory Storage Script
======================================================================
📄 Input File: /path/to/data/group_chat.json
🔍 Validation Mode: No
🌐 API Address: http://localhost:1995/api/v1/memories
======================================================================

======================================================================
Validating Input File Format
======================================================================
Reading file: /path/to/data/group_chat.json
Validating GroupChatFormat...
✓ Format validation passed!

=== Data Statistics ===
Format Version: 1.0.0
Group Name: Project Discussion Group
Group ID: group_001
User Count: 5
Message Count: 20
Time Range: 2025-02-01T10:00:00+00:00 ~ 2025-02-01T18:30:00+00:00

======================================================================
Starting to Call Memorize API for Each Message
======================================================================
Group Name: Project Discussion Group
Group ID: group_001
Message Count: 20
API Address: http://localhost:1995/api/v1/memories

--- Processing Message 1/20 ---
  ✓ Successfully saved 2 memories

--- Processing Message 2/20 ---
  ✓ Successfully saved 1 memory

...

======================================================================
Processing Complete
======================================================================
✓ Successfully Processed: 20/20 messages
✓ Total Saved: 35 memories

📝 API Call Examples

Complete Workflow

1. Prepare Data File

Create a JSON file conforming to GroupChatFormat:

{
  "version": "1.0.0",
  "conversation_meta": {
    "group_id": "project_team_001",
    "name": "Product Development Team",
    "default_timezone": "+00:00",
    "user_details": {
      "alice": {
        "full_name": "Alice Wang",
        "role": "Product Manager",
        "department": "Product"
      },
      "bob": {
        "full_name": "Bob Chen",
        "role": "Technical Lead",
        "department": "Engineering"
      }
    }
  },
  "conversation_list": [
    {
      "message_id": "msg_20250201_001",
      "create_time": "2025-02-01T09:00:00+00:00",
      "sender": "alice",
      "sender_name": "Alice Wang",
      "type": "text",
      "content": "Good morning! Let's discuss the new feature requirements today",
      "refer_list": []
    },
    {
      "message_id": "msg_20250201_002",
      "create_time": "2025-02-01T09:02:00+00:00",
      "sender": "bob",
      "sender_name": "Bob Chen",
      "type": "text",
      "content": "Sure, I've prepared some technical solutions",
      "refer_list": ["msg_20250201_001"]
    }
  ]
}

Save as my_chat_data.json.

2. Validate File Format

uv run python src/bootstrap.py src/run_memorize.py \
  --input my_chat_data.json \
  --validate-only

3. Start Service

Ensure MemSys service is running:

uv run python src/run.py

After service starts, visit http://localhost:1995/docs to verify API documentation is accessible.

4. Store Memories

Option A: Using V1 Memory API (Recommended)

uv run python src/bootstrap.py src/run_memorize.py \
  --input my_chat_data.json \
  --api-url http://localhost:1995/api/v1/memories

Option B: Using V1 Memory API

uv run python src/bootstrap.py src/run_memorize.py \
  --input my_chat_data.json \
  --api-url http://localhost:1995/api/v1/memories

5. Verify Storage Results

If using V1 Memory API, you can query stored memories through the retrieval interface (see Memory API Documentation for specific query APIs).

Error Handling

Format Validation Failed

✗ Format validation failed!
Please ensure input file conforms to GroupChatFormat specification

Solution:

• Check if JSON format is correct
• Refer to Group Chat Format Specification
• Ensure all required fields are filled

API Call Failed

✗ API call failed: 500
Response content: {"error": "Internal server error"}

Solution:

• Check if service is running normally
• View service logs to troubleshoot
• Verify API address is correct

Connection Timeout

✗ Processing failed: ReadTimeout

Solution:

• Check network connection
• Verify service address and port are correct
• Check firewall settings

🔗 Related Documentation

API Documentation

• Memory API Documentation - Complete V1 API documentation (storage + retrieval)
• Memory API Documentation - Complete V1 Memory API documentation (focused on storage)

Other Documentation

• Group Chat Format Specification - Detailed GroupChatFormat specification
• Getting Started Guide - Environment setup and service startup
• Agentic Retrieval Guide - Intelligent retrieval features explained

💡 Best Practices

1. Data Preparation

   • Use standard GroupChatFormat
   • Ensure timestamps include timezone information
   • Provide complete user details

2. Batch Processing

   • For large number of messages, use script to process one by one
   • Add appropriate delays to avoid server pressure
   • Monitor processing progress and errors

3. Error Recovery

   • Log failed messages
   • Support resume from checkpoint
   • Regularly verify storage results

4. Performance Optimization

   • Set reasonable concurrency levels
   • Use batch interfaces (if available)
   • Monitor API response times

For questions, please refer to FAQ or submit an issue.