Complete API reference for managing agent memory with vector embeddings, semantic search, and bulk operations using MotteMB.
Store a new memory with automatic embedding generation.
{
"content": "Customer refund policy allows returns within 30 days for digital products and 60 days for physical products. Proof of purchase required.",
"metadata": {
"category": "policy",
"subcategory": "refunds",
"source": "handbook_v2.1",
"priority": "high",
"tags": ["refund", "policy", "customer-service", "returns"],
"effective_date": "2024-01-01",
"expires_at": null
}
}{
"memory_id": "mem_abc123",
"status": "stored",
"embedding_dimensions": 1536,
"processing_time": 0.8,
"created_at": "2024-01-15T10:30:00Z"
}Search memories using semantic similarity and optional filters.
{
"query": "What is our refund policy for digital products?",
"limit": 5,
"threshold": 0.7,
"filters": {
"category": ["policy", "faq"],
"priority": ["high", "medium"],
"tags": ["refund"]
},
"include_metadata": true,
"sort_by": "similarity"
}{
"query": "What is our refund policy for digital products?",
"results": [
{
"memory_id": "mem_abc123",
"content": "Customer refund policy allows returns within 30 days for digital products and 60 days for physical products. Proof of purchase required.",
"similarity_score": 0.94,
"metadata": {
"category": "policy",
"subcategory": "refunds",
"source": "handbook_v2.1",
"priority": "high",
"tags": ["refund", "policy", "customer-service", "returns"],
"created_at": "2024-01-15T10:30:00Z"
}
},
{
"memory_id": "mem_def456",
"content": "Digital product refunds are processed within 3-5 business days after approval. Customers receive email confirmation.",
"similarity_score": 0.87,
"metadata": {
"category": "process",
"subcategory": "refunds",
"priority": "medium",
"tags": ["refund", "digital", "processing-time"]
}
}
],
"total_results": 2,
"processing_time": 0.3
}Retrieve a specific memory by ID.
{
"memory_id": "mem_abc123",
"content": "Customer refund policy allows returns within 30 days for digital products and 60 days for physical products. Proof of purchase required.",
"embedding": [0.123, -0.456, 0.789, ...], // 1536 dimensions
"metadata": {
"category": "policy",
"subcategory": "refunds",
"source": "handbook_v2.1",
"priority": "high",
"tags": ["refund", "policy", "customer-service", "returns"],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"access_count": 42,
"last_accessed": "2024-01-15T14:20:00Z"
}
}Update memory content or metadata.
{
"content": "Updated customer refund policy allows returns within 30 days for digital products and 60 days for physical products. Proof of purchase and original payment method required.",
"metadata": {
"priority": "critical",
"tags": ["refund", "policy", "customer-service", "returns", "updated"],
"version": "2.2"
}
}{
"memory_id": "mem_abc123",
"status": "updated",
"embedding_regenerated": true,
"updated_at": "2024-01-15T15:30:00Z"
}Delete a memory permanently.
{
"memory_id": "mem_abc123",
"status": "deleted",
"deleted_at": "2024-01-15T16:00:00Z"
}Bulk import memories from various file formats.
Content-Type: multipart/form-data
file: [uploaded file]
format: "json" | "csv" | "txt" | "jsonl"
batch_size: 100 (optional)
auto_categorize: true (optional)
default_metadata: {
"source": "bulk_import_2024",
"priority": "medium"
} (optional){
"import_id": "import_ghi789",
"status": "processing",
"total_records": 1250,
"processed": 0,
"successful": 0,
"failed": 0,
"estimated_completion": "2024-01-15T17:30:00Z",
"status_url": "/api/memory/import/import_ghi789/status"
}Export memories in various formats with optional filters.
format=json&category=policy&limit=1000&include_embeddings=false
{
"export_id": "export_jkl012",
"status": "ready",
"download_url": "https://api.motte.ai/downloads/export_jkl012.json",
"file_size": "2.3 MB",
"record_count": 1250,
"expires_at": "2024-01-22T16:00:00Z"
}Get comprehensive statistics about your memory bank.
{
"total_memories": 1250,
"storage_size": "2.3 MB",
"index_size": "1.1 MB",
"categories": {
"policy": 45,
"faq": 120,
"procedures": 85,
"knowledge": 200,
"other": 800
},
"priority_distribution": {
"critical": 12,
"high": 89,
"medium": 456,
"low": 693
},
"recent_activity": {
"last_24h": {
"created": 15,
"updated": 8,
"deleted": 2,
"searches": 342
}
},
"performance": {
"avg_search_time": 0.3,
"cache_hit_rate": 0.78,
"index_efficiency": 0.94
},
"last_optimization": "2024-01-15T10:30:00Z"
}Optimize memory bank performance and remove duplicates.
{
"operations": [
"remove_duplicates",
"rebuild_indexes",
"compress_embeddings",
"cleanup_expired"
],
"duplicate_threshold": 0.95,
"compress_ratio": 0.75
}{
"optimization_id": "opt_mno345",
"status": "completed",
"results": {
"duplicates_removed": 23,
"indexes_rebuilt": true,
"compression_applied": true,
"expired_cleaned": 5
},
"performance_improvement": {
"search_time_reduction": 0.15,
"storage_saved": "0.8 MB",
"index_efficiency_gain": 0.12
},
"completed_at": "2024-01-15T17:45:00Z"
}List memories with pagination and filtering.
page=1&limit=50&category=policy&sort=created_at&order=desc&search=refund
{
"memories": [
{
"memory_id": "mem_abc123",
"content": "Customer refund policy allows returns within 30 days...",
"metadata": {...},
"created_at": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 1250,
"pages": 25,
"has_next": true,
"has_prev": false
}
}| Parameter | Type | Default | Description |
|---|---|---|---|
| query | string | required | Search query text |
| limit | number | 10 | Max results (1-100) |
| threshold | number | 0.7 | Similarity threshold (0-1) |
| filters | object | Metadata filters | |
| include_metadata | boolean | true | Include metadata in results |
The specified memory ID does not exist.
Failed to generate embeddings for the provided content.
Memory storage quota exceeded. Please upgrade your plan.
The search query is empty or contains invalid characters.