MemVaultDocumentation

Quick Start

Get started with MemVault in less than 5 minutes. This guide will walk you through storing your first memory and retrieving it.

Installation

MemVault is a REST API, so you can use it with any HTTP client. No SDK installation required.

# Example using curl
curl -X POST https://moderate-krystal-memvault-af80fe26.koyeb.app/api/memory/add \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "text": "User prefers dark mode and concise responses",
    "metadata": {
      "category": "preference",
      "timestamp": "2025-12-17T10:00:00Z"
    }
  }'

Basic Concepts

Memory

A memory is a piece of information stored in MemVault. Each memory contains:

  • Text: The main content of the memory
  • User ID: Identifies which user this memory belongs to
  • Agent ID: (Optional) Identifies which AI agent created this memory
  • Metadata: Additional structured data for filtering and context

Vector Embeddings

MemVault automatically converts your text into vector embeddings using state-of-the-art models. This enables semantic search where similar meanings are found, not just exact keyword matches.

Your First Memory

Step 1: Get Your API Key

  1. Sign up at memvault-demo.vercel.app
  2. Complete the checkout process
  3. Check your email for your API key (starts with sk_)

Step 2: Store a Memory

const response = await fetch('https://moderate-krystal-memvault-af80fe26.koyeb.app/api/memory/add', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'user-123',
    text: 'Customer requested a refund for order #12345 due to delayed shipping',
    metadata: {
      orderId: '12345',
      category: 'support',
      priority: 'high',
    },
  }),
})

const data = await response.json()
console.log('Memory stored:', data)

Step 3: Retrieve Memories

Use semantic search to find relevant memories:

const response = await fetch('https://moderate-krystal-memvault-af80fe26.koyeb.app/api/graphrag/retrieve', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 'user-123',
    query: 'shipping problems',
    limit: 5,
  }),
})

const data = await response.json()
console.log('Relevant memories:', data.memories)

Response Format

Store Memory Response

{
  "success": true,
  "memoryId": "mem_abc123xyz",
  "message": "Memory stored successfully"
}

Retrieve Memory Response

{
  "success": true,
  "memories": [
    {
      "id": "mem_abc123xyz",
      "text": "Customer requested a refund for order #12345 due to delayed shipping",
      "similarity": 0.92,
      "metadata": {
        "orderId": "12345",
        "category": "support",
        "priority": "high"
      },
      "createdAt": "2025-12-17T10:00:00Z"
    }
  ]
}

Common Patterns

Pattern 1: Contextual AI Responses

Store user conversations and retrieve relevant context before generating responses:

// Store conversation
await storeMemory({
  userId: 'user-123',
  text: 'User asked about pricing for the Pro plan',
  metadata: { category: 'conversation', topic: 'pricing' }
})

// Later, retrieve context
const memories = await retrieveMemories({
  userId: 'user-123',
  query: 'pricing questions',
  limit: 3
})

// Use memories to inform AI response
const aiResponse = await generateResponse(userQuery, memories)

Pattern 2: Knowledge Base

Build a searchable knowledge base with semantic understanding:

// Store knowledge articles
await storeMemory({
  userId: 'org-456',
  text: 'To reset your password, click the Forgot Password link and follow the email instructions',
  metadata: { category: 'knowledge', topic: 'account' }
})

// Retrieve relevant knowledge
const knowledge = await retrieveMemories({
  userId: 'org-456',
  query: 'how to change password',
  limit: 1
})

Pattern 3: Multi-Agent Systems

Different AI agents can share and access memories:

// Agent A stores a memory
await storeMemory({
  userId: 'user-123',
  agentId: 'support-agent',
  text: 'User reported a bug in the mobile app',
  metadata: { category: 'bug-report' }
})

// Agent B retrieves it later
const memories = await retrieveMemories({
  userId: 'user-123',
  query: 'mobile app issues',
  limit: 5
})

Next Steps