Retrieve

Query memory for relevant context to use in your agent's prompt.

POST /retrieve

Request Body

{
  "appId": string,           // Required: Your app identifier
  "userId": string,          // Required: User to retrieve memories for
  "query": string,           // Required: Query to find relevant memories
  "maxTokens"?: number,      // Optional: Max tokens in response (default: 2000)
  "includeGraph"?: boolean,  // Optional: Include graph context (default: true)
  "categories"?: string[],   // Optional: Limit to specific categories
  "timeDecayDays"?: number,  // Optional: Time decay period (default: 30)
  "minConfidence"?: number   // Optional: Minimum confidence threshold (default: 0.6)
}

Example Request

curl -X POST https://api.magneteco.io/v1/retrieve \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "tanda",
    "userId": "user-123",
    "query": "What do I know about Acme Corp?",
    "maxTokens": 1500,
    "includeGraph": true
  }'

const context = await memory.retrieve({
  userId: 'user-123',
  query: 'What do I know about Acme Corp?',
  maxTokens: 1500,
  includeGraph: true,
});

// Use in your agent's prompt
const prompt = `${memory.formatForPrompt(context)}\n\nUser: ${userMessage}`;

response = requests.post(
    'https://api.magneteco.io/v1/retrieve',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'appId': 'tanda',
        'userId': 'user-123',
        'query': 'What do I know about Acme Corp?',
        'maxTokens': 1500,
        'includeGraph': True,
    }
)

Response

{
  "summaries": {
    "client_preferences": "Acme Corp prefers weekly status updates...",
    "project_context": "Working on NetSuite implementation..."
  },
  "relevantItems": [
    {
      "id": "item-001",
      "content": "User mentioned they prefer weekly status updates",
      "category": "client_preferences",
      "confidence": 0.92,
      "score": 0.87,           // After time decay
      "createdAt": "2024-01-10T14:30:00Z"
    }
  ],
  "graphContext": [
    {
      "name": "Acme Corp",
      "type": "Client",
      "properties": {
        "industry": "Manufacturing"
      },
      "relationships": [
        { "type": "OWNS", "target": "NetSuite Implementation" }
      ]
    }
  ],
  "tokenCount": 847,
  "processingTime": 423        // Milliseconds
}

Status Codes

Code	Description
200	Success
400	Invalid request body
401	Unauthorized
404	No memories found (returns empty context)

Get Context

Get all category summaries for a user.

GET /context/:appId/:userId

Example Request

curl https://api.magneteco.io/v1/context/tanda/user-123 \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "summaries": {
    "client_preferences": "User prefers weekly updates...",
    "project_context": "Working on NetSuite implementation...",
    "risk_factors": "Previous scope creep issues noted..."
  },
  "lastUpdated": "2024-01-15T14:30:00Z"
}

Get available categories for an app with content status.

GET /categories/:appId/:userId

Example Request

curl https://api.magneteco.io/v1/categories/tanda/user-123 \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "categories": [
    {
      "name": "client_preferences",
      "description": "How clients like to work...",
      "hasContent": true,
      "itemCount": 12,
      "lastUpdated": "2024-01-15T14:30:00Z"
    },
    {
      "name": "project_context",
      "description": "Background on projects...",
      "hasContent": true,
      "itemCount": 8,
      "lastUpdated": "2024-01-14T10:00:00Z"
    }
  ]
}

Retrieve

On this page