Skip to main content

​
Memory Operations

Store, retrieve, and manage memories via REST API.

​
Remember (Store Single)

Endpoint: 
POST /api/v2/agents/{agent_id}/remember
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Query Parameters:
  • memory_type (string) - Type: fact, preference, decision, etc.
  • content (string) - Memory text
  • title (string, optional) - Short title
  • confidence (float, optional) - 0-1 confidence (default: 1.0)
Response (201 Created): 
{
  "memory_id": "mem_abc123xyz",
  "agent_id": "my-agent",
  "type": "fact",
  "status": "queued"
}
Example: 
response = httpx.post(
    "http://localhost:8000/api/v2/agents/my-agent/remember",
    params={
        "memory_type": "fact",
        "content": "User prefers email",
        "confidence": 0.95
    },
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": token
    }
)
memory = response.json()

​
Batch Remember

Endpoint: 
POST /api/v2/agents/{agent_id}/batch-remember
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Content-Type: application/json
Request Body: 
{
  "memories": [
    {"content": "Alice", "type": "fact"},
    {"content": "Finance dept", "type": "fact"},
    {"content": "Prefers email", "type": "preference"}
  ]
}
Response (201 Created): 
{
  "memory_ids": ["mem_1", "mem_2", "mem_3"],
  "agent_id": "my-agent",
  "status": "queued"
}
Endpoint: 
GET /api/v2/agents/{agent_id}/recall
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Query Parameters:
  • query (string) - Search query
  • limit (int) - Max results (default: 5, max: 100)
  • memory_type (string, optional) - Filter by type
Response (200 OK): 
{
  "agent_id": "my-agent",
  "query": "user preferences",
  "memories": [
    {
      "id": "mem_abc123",
      "content": "Prefers email communication",
      "type": "preference",
      "confidence": 0.98,
      "created_at": "2025-03-26T09:00:00Z"
    }
  ]
}
Example: 
response = httpx.get(
    "http://localhost:8000/api/v2/agents/my-agent/recall",
    params={"query": "How does user prefer contact?", "limit": 10},
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": token
    }
)
memories = response.json()["memories"]

​
Answer (AI Question)

Endpoint: 
POST /api/v2/agents/{agent_id}/answer
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Query Parameters:
  • question (string) - Question to answer
Response (200 OK): 
{
  "agent_id": "my-agent",
  "question": "How should we contact the user?",
  "answer": "Based on stored preferences, the user prefers email communication. Send email during business hours.",
  "memory_references": ["mem_abc123"]
}

​
Validate Memory

Endpoint: 
POST /api/v2/agents/{agent_id}/validate/{memory_id}
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Response (200 OK): 
{
  "memory_id": "mem_abc123",
  "validated": true,
  "confidence": 1.0
}

​
Supersede Memory

Endpoint: 
POST /api/v2/agents/{agent_id}/supersede/{old_memory_id}
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Content-Type: application/json
Request Body: 
{
  "new_content": "User is now Director of Finance",
  "reason": "Promotion announced"
}
Response (200 OK): 
{
  "old_memory_id": "mem_old123",
  "new_memory_id": "mem_new456",
  "status": "superseded"
}

​
Mark Contradiction

Endpoint: 
POST /api/v2/agents/{agent_id}/contradict/{memory_id}
Headers: 
Authorization: Bearer mk_api_key
X-Session-Token: {session_token}
Response (200 OK): 
{
  "memory_id": "mem_abc123",
  "status": "marked_contradictory"
}

​
Workflow: Complete Memory Cycle

api_key = "mk_api_key"
token = "session_token"
agent = "my-agent"
base = "http://localhost:8000/api/v2"

headers = {
    "Authorization": f"Bearer {api_key}",
    "X-Session-Token": token
}

# Store
httpx.post(
    f"{base}/agents/{agent}/remember",
    params={"content": "User likes blue", "type": "preference"},
    headers=headers
)

# Recall
resp = httpx.get(
    f"{base}/agents/{agent}/recall",
    params={"query": "color preference"},
    headers=headers
)
memories = resp.json()["memories"]

# Answer
resp = httpx.post(
    f"{base}/agents/{agent}/answer",
    params={"question": "What's the user's favorite color?"},
    headers=headers
)
answer = resp.json()["answer"]

​
Next Steps