Memory API Documentation

Memory API Documentation

Home > Docs > API Docs > Memory API

Overview

The Memory API provides RESTful endpoints for storing, retrieving, searching, and managing conversational memories.

Base URL: http://localhost:1995/api/v1/memories

API Endpoints

POST /memories - Store Message

Store a single message into memory.

Request

{
  "message_id": "msg_001",
  "create_time": "2025-01-15T10:00:00+00:00",
  "sender": "user_001",
  "content": "Let's discuss the technical solution for the new feature today",
  "group_id": "group_123",
  "group_name": "Project Discussion Group",
  "sender_name": "John",
  "role": "user",
  "refer_list": ["msg_000"]
}

Request Fields

Group ID Behavior

When group_id and group_name are not provided (null), the API automatically creates a default group based on the sender field. This enables simpler use cases where correlated memories between multiple senders are not needed.

When to omit group_id:

• Knowledge base ingestion - Single-source content where sender correlation is not needed
• Persona/profile building - Building memories for a single user without multi-party context
• Simple chatbot interactions - 1:1 conversations where grouping is not required

When to provide group_id:

• Multi-user conversations - Group chats where multiple participants interact
• User + AI assistant - Conversations between a user and AI where context correlation matters
• Project/topic-based organization - When you want to query memories by logical groupings

Providing a group_id enables better episodic memory extraction by giving the system context about related messages across multiple senders. See the Group Chat Guide for detailed guidance.

Example

curl -X POST "http://localhost:1995/api/v1/memories" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_001",
    "create_time": "2025-01-15T10:00:00+00:00",
    "sender": "user_001",
    "sender_name": "John",
    "role": "user",
    "content": "Let us discuss the technical solution for the new feature today",
    "group_id": "group_123",
    "group_name": "Project Discussion Group",
    "refer_list": []
  }'

Response

Success (200) - Memory extracted (boundary triggered):

{
  "status": "ok",
  "message": "Extracted 1 memories",
  "result": {
    "saved_memories": [],
    "count": 1,
    "status_info": "extracted"
  }
}

Success (200) - Message queued (boundary not triggered):

{
  "status": "ok",
  "message": "Message queued, awaiting boundary detection",
  "result": {
    "saved_memories": [],
    "count": 0,
    "status_info": "accumulated"
  }
}

GET /memories - Fetch Memories

Retrieve memories by type with optional filters.

Request Parameters (Query String)

*At least one of user_id or group_id must be provided (cannot both be __all__).

Memory Types

Example

curl "http://localhost:1995/api/v1/memories?user_id=user_123&memory_type=episodic_memory&limit=20"

Response

{
  "status": "ok",
  "message": "Memory retrieval successful, retrieved 1 memories",
  "result": {
    "memories": [
      {
        "memory_type": "episodic_memory",
        "user_id": "user_123",
        "timestamp": "2024-01-15T10:30:00",
        "content": "User discussed coffee during the project sync",
        "summary": "Project sync coffee note"
      }
    ],
    "total_count": 100,
    "has_more": false,
    "metadata": {
      "source": "fetch_mem_service",
      "user_id": "user_123",
      "memory_type": "fetch"
    }
  }
}

GET /memories/search - Search Memories

Search memories using keyword, vector, or hybrid retrieval methods.

Request Body

{
  "query": "coffee preference",
  "user_id": "user_123",
  "group_id": "group_456",
  "retrieve_method": "keyword",
  "memory_types": ["episodic_memory"],
  "top_k": 10,
  "start_time": "2024-01-01T00:00:00",
  "end_time": "2024-12-31T23:59:59",
  "radius": 0.6,
  "include_metadata": true
}

Request Fields

*At least one of user_id or group_id must be provided (cannot both be __all__).

Note: profile memory type is not supported in the search interface.

Retrieve Methods

Example

curl -X GET "http://localhost:1995/api/v1/memories/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee preference",
    "user_id": "user_123",
    "retrieve_method": "keyword",
    "top_k": 10
  }'

Response

{
  "status": "ok",
  "message": "Memory search successful, retrieved 1 groups",
  "result": {
    "memories": [
      {
        "episodic_memory": [
          {
            "memory_type": "episodic_memory",
            "user_id": "user_123",
            "timestamp": "2024-01-15T10:30:00",
            "summary": "Discussed coffee choices",
            "group_id": "group_456"
          }
        ]
      }
    ],
    "scores": [{"episodic_memory": [0.95]}],
    "importance_scores": [0.85],
    "original_data": [],
    "total_count": 45,
    "has_more": false,
    "query_metadata": {
      "source": "episodic_memory_es_repository",
      "user_id": "user_123",
      "memory_type": "retrieve"
    },
    "metadata": {
      "source": "episodic_memory_es_repository",
      "user_id": "user_123",
      "memory_type": "retrieve"
    },
    "pending_messages": []
  }
}

Response Fields

GET /memories/conversation-meta - Get Metadata

Retrieve conversation metadata by group_id with fallback to default config.

Request Parameters

Example

curl "http://localhost:1995/api/v1/memories/conversation-meta?group_id=group_123"

Response

{
  "status": "ok",
  "message": "Conversation metadata retrieved successfully",
  "result": {
    "id": "...",
    "group_id": "group_123",
    "scene": "group_chat",
    "name": "Engineering Team",
    "user_details": {...},
    "is_default": false
  }
}

POST /memories/conversation-meta - Save Metadata

Save or update conversation metadata (upsert behavior).

Request Body

{
  "version": "1.0.0",
  "scene": "group_chat",
  "scene_desc": {
    "description": "Project discussion group chat",
    "type": "project_discussion"
  },
  "name": "Engineering Team",
  "description": "Backend team discussions",
  "group_id": "group_123",
  "created_at": "2025-01-15T10:00:00Z",
  "default_timezone": "America/New_York",
  "user_details": {
    "alice": {
      "full_name": "Alice Smith",
      "role": "user",
      "custom_role": "Tech Lead"
    }
  },
  "tags": ["engineering", "backend"]
}

Request Fields

User Details Fields

PATCH /memories/conversation-meta - Update Metadata

Partially update conversation metadata.

Request Body

{
  "group_id": "group_123",
  "name": "Updated Team Name",
  "tags": ["engineering", "python"]
}

Updatable Fields

Response

{
  "status": "ok",
  "message": "Conversation metadata updated successfully, 2 fields updated",
  "result": {
    "id": "...",
    "group_id": "group_123",
    "scene": "group_chat",
    "name": "Updated Team Name",
    "updated_fields": ["name", "tags"],
    "updated_at": "2025-01-15T12:00:00Z"
  }
}

DELETE /memories - Delete Memories

Soft delete memories based on filter criteria (AND logic).

Request Body

{
  "event_id": "evt_001",
  "user_id": "user_123",
  "group_id": "group_456"
}

Request Fields

At least one filter must be provided (not all __all__).

Example

# Delete all memories for a user in a group
curl -X DELETE "http://localhost:1995/api/v1/memories" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_123", "group_id": "group_456"}'

Response

{
  "status": "ok",
  "message": "Successfully deleted 10 memories",
  "result": {
    "filters": ["user_id", "group_id"],
    "count": 10
  }
}

Batch Processing with run_memorize.py

For batch processing GroupChatFormat JSON files:

# Process a group chat file
uv run python src/bootstrap.py src/run_memorize.py \
  --input data/group_chat.json \
  --scene group_chat \
  --api-url http://localhost:1995/api/v1/memories

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

Parameters

*Required unless using --validate-only.

Error Responses

All error responses follow this format:

{
  "status": "failed",
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "timestamp": "2025-01-15T10:30:00+00:00",
  "path": "/api/v1/memories"
}

Error Codes

See Also

• Group Chat Guide - Multi-participant conversations
• Metadata Control Guide - Conversation metadata management
• GroupChatFormat Specification - Data format reference