Skip to main content

​
REST API Overview

MEMANTO exposes a comprehensive REST API for programmatic memory management. All endpoints are accessed via HTTP with JSON request/response bodies.

​
Base URL

http://localhost:8000/api/v2
The /api/v2 prefix indicates API version 2 (current version).

​
Starting the Server

Before using the API, start the MEMANTO server: 
memanto serve

​
Authentication

All API requests require two headers:

​
1. Moorcheh API Key

Every request must include your Moorcheh API key: 
Authorization: Bearer mk_your_api_key_here

​
2. Session Token (for Memory Operations)

Memory operations also require a session token from agent activation: 
X-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Endpoint Structure

​
Agent Management

  • Create, list, delete agents
  • Manage agent lifecycle

​
Sessions

  • Activate agent sessions (get session token)
  • Deactivate sessions
  • Extend session duration
  • Check session status

​
Memory Operations

  • POST /{agent_id}/remember - Store single memory
  • POST /{agent_id}/batch-remember - Store multiple memories
  • GET /{agent_id}/recall - Semantic search
  • POST /{agent_id}/answer - AI-powered question answering

​
Temporal Queries

  • GET /{agent_id}/recall/as-of - Memories at specific time
  • GET /{agent_id}/recall/changed-since - Memories changed since date
  • GET /{agent_id}/recall/current - Only current (non-superseded) memories

​
Memory Management

  • Validate memories
  • Supersede outdated memories
  • Detect contradictions
  • Export memories

​
Context Summarization

  • Summarize memory scopes
  • Compress conversation history

​
Status Codes

CodeMeaningAction
200OKRequest succeeded
201CreatedResource created
204No ContentSuccessful deletion
400Bad RequestInvalid parameters
401UnauthorizedInvalid API key or session token
404Not FoundResource not found
422Validation ErrorInvalid request format
500Server ErrorInternal error

​
Common Response Format

​
Success Response

{
  "status": "success",
  "data": {
    // Response data
  },
  "timestamp": "2025-03-30T16:30:00Z"
}

​
Error Response

{
  "status": "error",
  "error": {
    "code": "INVALID_AGENT_ID",
    "message": "Agent 'xyz' not found"
  },
  "timestamp": "2025-03-30T16:30:00Z"
}

​
Rate Limiting

MEMANTO respects your Moorcheh free tier limits:
  • Free Tier: 500 credits/month (~100,000 operations)
  • Each operation: 1 credit
  • Rate Limit: No per-second limit, cumulative monthly limit

​
Pagination

List endpoints support pagination: 
GET /api/v2/agents?limit=10&offset=0
Parameters:
  • limit - Results per page (default: 10, max: 100)
  • offset - Skip first N results (default: 0)

​
Timestamps

All timestamps use ISO 8601 format with UTC timezone: 
2025-03-30T16:30:00Z

​
Error Handling

​
Invalid API Key

curl -X GET "http://localhost:8000/api/v2/agents" \
  -H "Authorization: Bearer invalid_key"
Response: 
{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key is invalid or expired"
  }
}

​
Missing Session Token

curl -X POST "http://localhost:8000/api/v2/agents/my-agent/remember" \
  -H "Authorization: Bearer mk_valid_key"
  # Missing X-Session-Token header
Response: 
{
  "status": "error",
  "error": {
    "code": "MISSING_SESSION_TOKEN",
    "message": "X-Session-Token header is required"
  }
}

​
API Documentation UI

MEMANTO provides interactive API documentation: Both show all endpoints with:
  • Parameter descriptions
  • Request/response examples
  • Interactive testing

​
Quick Start Example

import httpx

api_key = "mk_your_api_key"
agent_id = "my-agent"
base_url = "http://localhost:8000/api/v2"

# 1. Activate session
response = httpx.post(
    f"{base_url}/agents/{agent_id}/activate",
    headers={"Authorization": f"Bearer {api_key}"}
)
session_token = response.json()["session_token"]

# 2. Store memory
response = httpx.post(
    f"{base_url}/agents/{agent_id}/remember",
    params={
        "memory_type": "fact",
        "content": "Paris is the capital of France",
        "confidence": 1.0
    },
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": session_token
    }
)
memory_id = response.json()["memory_id"]

# 3. Recall memory
response = httpx.get(
    f"{base_url}/agents/{agent_id}/recall",
    params={"query": "What's the capital of France?"},
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": session_token
    }
)
memories = response.json()["memories"]
print(f"Found {len(memories)} memory")

​
API Endpoints Summary

​
Agent Management

  • POST /agents - Create agent
  • GET /agents - List agents
  • GET /agents/{agent_id} - Get agent details
  • DELETE /agents/{agent_id} - Delete agent

​
Sessions

  • POST /agents/{agent_id}/activate - Activate session
  • POST /agents/{agent_id}/deactivate - Deactivate session
  • GET /session/current - Check current session
  • POST /session/extend - Extend session

​
Memory Operations

  • POST /agents/{agent_id}/remember - Store memory
  • POST /agents/{agent_id}/batch-remember - Batch store
  • GET /agents/{agent_id}/recall - Semantic search
  • POST /agents/{agent_id}/answer - AI answer

​
Temporal Queries

  • GET /agents/{agent_id}/recall/as-of - As-of query
  • GET /agents/{agent_id}/recall/changed-since - Changed since
  • GET /agents/{agent_id}/recall/current - Current only

​
Memory Management

  • POST /agents/{agent_id}/validate/{memory_id} - Validate
  • POST /agents/{agent_id}/supersede/{memory_id} - Replace outdated
  • POST /agents/{agent_id}/contradict/{memory_id} - Mark contradiction

​
Context Operations

  • POST /context/summarize - Summarize scope
  • POST /context/summarize/custom - Summarize by IDs
  • POST /context/compress - Compress conversation

​
Detailed Endpoint Documentation

​
Common Patterns

​
Create Agent, Activate, Store Memory

import httpx

api_key = "mk_your_key"
base_url = "http://localhost:8000/api/v2"

# Create
httpx.post(f"{base_url}/agents",
    json={"agent_id": "my-agent"},
    headers={"Authorization": f"Bearer {api_key}"})

# Activate
resp = httpx.post(f"{base_url}/agents/my-agent/activate",
    headers={"Authorization": f"Bearer {api_key}"})
token = resp.json()["session_token"]

# Remember
httpx.post(f"{base_url}/agents/my-agent/remember",
    params={"content": "Hello", "type": "fact"},
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": token
    })

​
Batch Store Memories

memories = [
    {"content": "Alice", "type": "fact"},
    {"content": "Prefers email", "type": "preference"}
]

httpx.post(f"{base_url}/agents/my-agent/batch-remember",
    json={"memories": memories},
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": token
    })

​
Next Steps

The REST API is fully featured and production-ready. Use it to build custom integrations!