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
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 Type	Endpoint	Features	Recommended Use Case
V1 Memory API	`/api/v1/memories`	Memory Storage + Intelligent Retrieval	Complete application scenarios requiring retrieval features

API Comparison

Feature	V1 Memory API	V1 Memory API
Store Single Message	✅ Supported	✅ Supported
Message Format	Simple direct single message format	Simple direct single message format
Intelligent Retrieval	✅ Supported (Lightweight + Agentic)	❌ Not Supported
Session Metadata Management	✅ Supported	✅ Supported (with PATCH updates)
Use Case	Complete memory system (storage + retrieval)	Pure memory storage system

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

Field	Type	Required	Description
`message_id`	string	Yes	Unique message identifier
`create_time`	string	Yes	Message creation time (ISO 8601 format)
`sender`	string	Yes	Sender ID
`sender_name`	string	No	Sender name (for readability)
`content`	string	Yes	Message content
`refer_list`	array	No	List of referenced messages
`group_id`	string	No	Group ID
`group_name`	string	No	Group name

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

Separated Metadata and Message List
- conversation_meta: Group chat metadata
- conversation_list: Message list
Centralized User Details
- All user information stored in user_details
- Messages only need to reference user IDs
Timezone-aware Timestamps
- Uses ISO 8601 format
- Supports timezone information
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

Argument	Required	Description
`--input`	Yes	Input group chat JSON file path (GroupChatFormat)
`--api-url`	No*	Memorize API address (*unless using --validate-only)
`--validate-only`	No	Only validate input file format without storing

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

Validate Input File
- Check if JSON format is correct
- Verify compliance with GroupChatFormat specification
- Output data statistics
Process Messages One by One
- Read each message from group chat file
- Call API to store each message
- Display processing progress and results
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)

💡 Best Practices

Data Preparation
- Use standard GroupChatFormat
- Ensure timestamps include timezone information
- Provide complete user details
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
Error Recovery
- Log failed messages
- Support resume from checkpoint
- Regularly verify storage results
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.

FilesExpand file tree

api_usage_guide.md

Latest commit

History

api_usage_guide.md

File metadata and controls

API Usage Guide

📋 Table of Contents

🔍 API Overview

Available APIs

API Comparison

🚀 Memory Storage APIs

V1 Memory API

Endpoint

Features

V1 Memory API

Endpoint

Features

API Selection Guide

📝 Memorize API Details

Request Format (Common to Both APIs)

Field Descriptions

Response Format

Call Examples

cURL

Python

JavaScript

📁 Group Chat Data Format

Format Overview

Core Features

Detailed Documentation

🔧 Using Scripts to Store Memories

Script Location

Basic Usage

Command Line Arguments

Usage Examples

1. Store Memories

2. Validate File Format

Script Workflow

Output Example

📝 API Call Examples

Complete Workflow

1. Prepare Data File

2. Validate File Format

3. Start Service

4. Store Memories

5. Verify Storage Results

Error Handling

Format Validation Failed

API Call Failed

Connection Timeout

🔗 Related Documentation

API Documentation

Other Documentation

💡 Best Practices