API Reference

Complete reference documentation for the Nemo Memory API. All endpoints use RESTful conventions and return JSON responses.

Base URL
https://api.nemo.dev/v1

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header of every request.

Authorization: Bearer your_api_key_here Content-Type: application/json

Rate Limits

API requests are rate limited to ensure fair usage and system stability:

  • Free Tier: 1,000 requests per hour
  • Pro Tier: 10,000 requests per hour
  • Enterprise: Custom limits

Error Handling

The API uses conventional HTTP status codes and returns detailed error information in JSON format:

{ "error": { "code": "invalid_memory_type", "message": "Memory type 'invalid' is not supported", "details": { "supported_types": ["episodic", "semantic", "working", "procedural"] } } }

Memory Allocation

POST /memory/allocate
Allocates a new memory space with specified configuration. Returns a unique memory ID that can be used for subsequent operations.

Parameters

Parameter Type Required Description
size string Required Memory space size (e.g., "1GB", "500MB", "10TB")
type string Required Memory type: "episodic", "semantic", "working", "procedural"
persistence string Optional Persistence level: "session", "temporary", "persistent", "permanent"
name string Optional Human-readable name for the memory space
metadata object Optional Additional metadata for the memory space

Request Example

{ "size": "1GB", "type": "episodic", "persistence": "session", "name": "user_conversation_memory", "metadata": { "user_id": "user_123", "application": "chatbot", "version": "1.0" } }
Response
{ "memory_id": "mem_abc123def456", "size": "1GB", "type": "episodic", "persistence": "session", "name": "user_conversation_memory", "status": "allocated", "created_at": "2025-06-10T15:30:00Z", "expires_at": "2025-06-10T23:30:00Z" }
DELETE /memory/{memory_id}
Deallocates a memory space and permanently removes all stored data. This operation cannot be undone.

Path Parameters

Parameter Type Description
memory_id string Unique identifier of the memory space to deallocate
Response
{ "success": true, "memory_id": "mem_abc123def456", "deallocated_at": "2025-06-10T16:45:00Z", "data_removed": true }

Storage Operations

POST /memory/{memory_id}/store
Stores new data in the specified memory space with optional context, associations, and metadata.

Parameters

Parameter Type Required Description
data object Required The data to store (any valid JSON object)
context object Optional Contextual information about the memory
associations array Optional Array of strings representing memory associations
strength number Optional Association strength (0.0 to 1.0, default: 0.5)
timestamp string Optional ISO 8601 timestamp (defaults to current time)

Request Example

{ "data": { "content": "User asked about memory allocation limits", "response": "Explained that free tier allows 1GB per memory space", "satisfaction": "high" }, "context": { "conversation_id": "conv_789", "user_mood": "curious", "topic": "technical_support" }, "associations": ["support", "memory_limits", "free_tier", "satisfied"], "strength": 0.8, "timestamp": "2025-06-10T15:35:00Z" }
Response
{ "memory_item_id": "item_xyz789abc123", "memory_id": "mem_abc123def456", "stored_at": "2025-06-10T15:35:00Z", "associations_created": 4, "vector_embedding": true, "storage_size": "2.3KB" }
PUT /memory/{memory_id}/items/{item_id}
Updates an existing memory item with new data. Supports partial updates and different merge strategies.

Parameters

Parameter Type Required Description
data object Required Updated data for the memory item
merge_strategy string Optional "replace", "append", "merge" (default: "merge")
update_associations boolean Optional Whether to update associations (default: true)
Response
{ "memory_item_id": "item_xyz789abc123", "updated_at": "2025-06-10T16:20:00Z", "merge_strategy": "merge", "changes_applied": true, "new_associations": 2 }

Retrieval

POST /memory/{memory_id}/retrieve
Retrieves memories from the specified memory space using semantic similarity search, keyword matching, or contextual filtering.

Parameters

Parameter Type Required Description
query string Required Search query for semantic similarity matching
similarity_threshold number Optional Minimum similarity score (0.0 to 1.0, default: 0.7)
limit integer Optional Maximum number of results (default: 10, max: 100)
include_context boolean Optional Include contextual information (default: true)
time_range object Optional Filter by time range with "start" and "end" timestamps
associations array Optional Filter by specific associations

Request Example

{ "query": "technical support conversation", "similarity_threshold": 0.8, "limit": 5, "include_context": true, "time_range": { "start": "2025-06-10T00:00:00Z", "end": "2025-06-10T23:59:59Z" }, "associations": ["support", "satisfied"] }
Response
{ "results": [ { "memory_item_id": "item_xyz789abc123", "similarity": 0.92, "data": { "content": "User asked about memory allocation limits", "response": "Explained that free tier allows 1GB per memory space", "satisfaction": "high" }, "context": { "conversation_id": "conv_789", "user_mood": "curious", "topic": "technical_support" }, "associations": ["support", "memory_limits", "free_tier", "satisfied"], "timestamp": "2025-06-10T15:35:00Z", "strength": 0.8 } ], "total_results": 1, "query_time_ms": 23, "search_method": "semantic_similarity" }

Associations

POST /memory/{memory_id}/associations
Creates explicit associations between memory items or concepts, strengthening the connections for future retrieval.

Parameters

Parameter Type Required Description
item_a string Required First memory item ID or concept
item_b string Required Second memory item ID or concept
strength number Optional Association strength (0.0 to 1.0, default: 1.0)
type string Optional Association type: "causal", "temporal", "semantic", "contextual"
Response
{ "association_id": "assoc_def456ghi789", "item_a": "item_xyz789abc123", "item_b": "technical_support", "strength": 1.0, "type": "semantic", "created_at": "2025-06-10T16:30:00Z" }

Consolidation

POST /memory/{memory_id}/consolidate
Triggers memory consolidation to optimize storage, strengthen important associations, and improve retrieval performance.

Parameters

Parameter Type Required Description
strategy string Optional "temporal", "frequency", "importance", "adaptive" (default: "adaptive")
preserve_recent boolean Optional Preserve recent memories from consolidation (default: true)
min_strength number Optional Minimum association strength to preserve (default: 0.3)
Response
{ "consolidation_id": "cons_jkl012mno345", "memory_id": "mem_abc123def456", "strategy": "adaptive", "status": "completed", "started_at": "2025-06-10T17:00:00Z", "completed_at": "2025-06-10T17:02:15Z", "statistics": { "memories_processed": 1247, "associations_strengthened": 89, "storage_optimized": "15.2%", "retrieval_speed_improvement": "23%" } }