Memory API Documentation

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

Method	Endpoint	Description
POST	`/memories`	Store a single message
GET	`/memories`	Fetch memories by type
GET	`/memories/search`	Search memories
GET	`/memories/conversation-meta`	Get conversation metadata
POST	`/memories/conversation-meta`	Save conversation metadata
PATCH	`/memories/conversation-meta`	Partial update metadata
DELETE	`/memories`	Soft delete memories

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

Field	Type	Required	Description
`message_id`	string	Yes	Unique message identifier
`create_time`	string	Yes	ISO 8601 timestamp with timezone
`sender`	string	Yes	Sender user ID
`content`	string	Yes	Message content
`group_id`	string	No	Group identifier
`group_name`	string	No	Group display name
`sender_name`	string	No	Sender display name (defaults to `sender`)
`role`	string	No	`user` (human) or `assistant` (AI)
`refer_list`	array	No	Referenced message IDs

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)

Parameter	Type	Required	Default	Description
`user_id`	string	No*	-	User ID
`group_id`	string	No*	-	Group ID
`memory_type`	string	No	`episodic_memory`	Memory type
`limit`	integer	No	40	Max results (max: 500)
`offset`	integer	No	0	Pagination offset
`start_time`	string	No	-	Filter start time (ISO 8601)
`end_time`	string	No	-	Filter end time (ISO 8601)
`version_range`	array	No	-	Version range `[start, end]`

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

Memory Types

Type	Description
`profile`	User profile information
`episodic_memory`	Conversation episodes (default)
`foresight`	Prospective memory
`event_log`	Atomic facts

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

Field	Type	Required	Default	Description
`query`	string	No	-	Search query text
`user_id`	string	No*	-	User ID
`group_id`	string	No*	-	Group ID
`retrieve_method`	string	No	`keyword`	Retrieval method
`memory_types`	array	No	`[]` (defaults to `episodic_memory`)	Memory types to search
`top_k`	integer	No	40	Max results (max: 100)
`start_time`	string	No	-	Filter start time (ISO 8601)
`end_time`	string	No	-	Filter end time (ISO 8601)
`radius`	float	No	-	Cosine similarity threshold (0.0-1.0, for vector/hybrid only)
`include_metadata`	boolean	No	true	Include metadata in response
`current_time`	string	No	-	Current time for filtering foresight events

*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

Method	Description
`keyword`	BM25 keyword retrieval (default)
`vector`	Vector semantic retrieval
`hybrid`	Keyword + vector + rerank
`rrf`	RRF fusion (keyword + vector + RRF ranking)
`agentic`	LLM-guided multi-round intelligent retrieval

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

Field	Description
`memories`	List of memory groups, organized by memory type
`scores`	Relevance scores for each memory
`importance_scores`	Group importance scores for sorting
`original_data`	Original data associated with memories
`total_count`	Total number of memories found
`has_more`	Whether more results are available
`query_metadata`	Metadata about the query execution
`metadata`	Additional response metadata
`pending_messages`	Messages waiting for memory extraction

GET `/memories/conversation-meta` - Get Metadata

Retrieve conversation metadata by group_id with fallback to default config.

Request Parameters

Parameter	Type	Required	Description
`group_id`	string	No	Group ID (omit for default config)

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

Field	Type	Required	Description
`version`	string	Yes	Metadata version
`scene`	string	Yes	Scene identifier: `assistant` or `group_chat`
`scene_desc`	object	Yes	Scene description object
`name`	string	Yes	Conversation name
`description`	string	No	Conversation description
`group_id`	string	No	Group identifier (omit for default config)
`created_at`	string	Yes	Conversation creation time (ISO 8601 format)
`default_timezone`	string	No	Default timezone (defaults to system timezone)
`user_details`	object	No	Participant details, key is user ID
`tags`	array	No	Tag list

User Details Fields

Field	Type	Description
`full_name`	string	Display name
`role`	string	`user` or `assistant`
`custom_role`	string	Job title/position
`extra`	object	Additional metadata

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

Field	Description
`name`	Conversation name
`description`	Conversation description
`scene_desc`	Scene description
`tags`	Tag list
`user_details`	User details (replaces entire object)
`default_timezone`	Default timezone

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

Field	Type	Required	Default	Description
`event_id`	string	No	`__all__`	Filter by event ID
`user_id`	string	No	`__all__`	Filter by user ID
`group_id`	string	No	`__all__`	Filter by group ID

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

Parameter	Required	Description
`--input`	Yes	Path to GroupChatFormat JSON file
`--scene`	Yes	`group_chat` or `assistant`
`--api-url`	Yes*	Memory API endpoint
`--validate-only`	No	Only validate format, skip processing

*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

Code	HTTP Status	Description
`INVALID_PARAMETER`	400	Invalid or missing request parameters
`RESOURCE_NOT_FOUND`	404	Requested resource not found
`SYSTEM_ERROR`	500	Internal server error

FilesExpand file tree

memory_api.md

Latest commit

History

memory_api.md

File metadata and controls

Memory API Documentation

Overview

API Endpoints

POST /memories - Store Message

Request

Request Fields

Group ID Behavior

Example

Response

GET /memories - Fetch Memories

Request Parameters (Query String)

Memory Types

Example

Response

GET /memories/search - Search Memories

Request Body

Request Fields

Retrieve Methods

Example

Response

Response Fields

GET /memories/conversation-meta - Get Metadata

Request Parameters

Example

Response

POST /memories/conversation-meta - Save Metadata

Request Body

Request Fields

User Details Fields

PATCH /memories/conversation-meta - Update Metadata

Request Body

Updatable Fields

Response

DELETE /memories - Delete Memories

Request Body

Request Fields

Example

Response

Batch Processing with run_memorize.py

Parameters

Error Responses

Error Codes

See Also

POST `/memories` - Store Message

GET `/memories` - Fetch Memories

GET `/memories/search` - Search Memories

GET `/memories/conversation-meta` - Get Metadata

POST `/memories/conversation-meta` - Save Metadata

PATCH `/memories/conversation-meta` - Update Metadata

DELETE `/memories` - Delete Memories