Memory API

Store and retrieve AI agent memory for persistent context.

Endpoints

POST/api/v1/memory/ingest

Store a user-agent interaction in memory

memory:write

POST/api/v1/memory/query

Retrieve relevant context for a query

memory:read

POST/api/v1/memory/flush

Force flush pending memory buffer

memory:write

Ingest Memory

Store user-agent interactions for later retrieval. Memory is buffered and processed asynchronously.

Request

POST /api/v1/memory/ingestbash

curl -X POST http://localhost:3000/api/v1/memory/ingest \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "conversation_id": "conv_xyz789",
    "user_message": "Remember that I prefer TypeScript over JavaScript",
    "agent_response": "Got it! I will use TypeScript for all code examples.",
    "metadata": {
      "intent": "preference_setting",
      "confidence": 0.95
    }
  }'

Parameters

Field	Type	Required	Description
`user_id`	string	Yes	The user ID this memory belongs to
`conversation_id`	string	Yes	The conversation context
`user_message`	string	Yes	The user's message
`agent_response`	string	Yes	The agent's response
`metadata`	object	No	Additional metadata about the interaction

Response

Response (201 Created)json

{
  "success": true,
  "interaction_id": "int_def456789",
  "buffered": true,
  "buffer_size": 3,
  "message": "Interaction queued for processing"
}

Query Memory

Retrieve relevant context based on a natural language query. Returns episodic memories and extracted facts.

Request

POST /api/v1/memory/querybash

curl -X POST http://localhost:3000/api/v1/memory/query \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "conversation_id": "conv_xyz789",
    "query": "What programming language does the user prefer?",
    "limit": 5,
    "include_facts": true
  }'

Parameters

Field	Type	Required	Description
`user_id`	string	Yes	The user to query memory for
`conversation_id`	string	No	Limit to specific conversation
`query`	string	Yes	Natural language query
`limit`	number	No	Max results (default: 10)
`include_facts`	boolean	No	Include extracted facts (default: true)

Response

Response (200 OK)json

{
  "context": [
    {
      "type": "episodic",
      "content": {
        "user_message": "Remember that I prefer TypeScript over JavaScript",
        "agent_response": "Got it! I will use TypeScript for all code examples."
      },
      "conversation_id": "conv_xyz789",
      "timestamp": "2024-01-15T10:40:00Z",
      "relevance_score": 0.95
    },
    {
      "type": "episodic",
      "content": {
        "user_message": "Can you show me how to create a React component?",
        "agent_response": "Here's a TypeScript React component example..."
      },
      "conversation_id": "conv_xyz789",
      "timestamp": "2024-01-15T10:45:00Z",
      "relevance_score": 0.78
    }
  ],
  "facts": [
    "User prefers TypeScript over JavaScript",
    "User is working with React components"
  ],
  "total_results": 2,
  "query_time_ms": 45
}

Flush Buffer

Force immediate processing of buffered memory. Useful before ending a session.

POST /api/v1/memory/flushbash

curl -X POST http://localhost:3000/api/v1/memory/flush \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "conversation_id": "conv_xyz789"
  }'

Response (200 OK)json

{
  "success": true,
  "flushed_count": 5,
  "blob_id": "blob_xxxxxxxxx",
  "message": "Buffer flushed and stored to Walrus"
}

Memory Types

Raven stores different types of memory for comprehensive context:

Episodic

Raw conversation history - user messages and agent responses with timestamps.

Semantic

Extracted facts, patterns, and summaries derived from conversations.

Embeddings

Vector representations for semantic search and similarity matching.

Related Endpoints

→Users API →Conversations API →Agent Integration Guide →Encryption Details