Memory API v1

Manage Memory

Store and retrieve memories for MCP integration and personal memory management. Simple APIs to save context, preferences, and interactions.

Get StartedAPI Reference

Quick Start Guide

Get up and running with the Memory API in under 5 minutes

1

Get Your API Key

Sign up and generate your API key from the user dashboard

2

Create Memories

Store user context, preferences, and interactions

3

Search & Retrieve

Query memories with semantic or keyword search

Why Use Memory API?

Simple user memory management for MCP servers and personal AI assistants

Fast Semantic Search

Retrieve relevant memories instantly with semantic and keyword matching

MCP Integration

Perfect for Model Context Protocol servers that need persistent user memory

Private & Secure

User memories are encrypted and isolated with complete privacy

Simple REST API

Two endpoints: create and search. That's all you need to manage memories

API Reference

Complete reference for all Memory API endpoints

Base URL

https://api.arkios.ai

Authentication

All API requests require authentication using an API key in the x-api-key header. You can generate your API key from the user dashboard.

x-api-key: YOUR_API_KEY
POST/api/knowledge-base/v1/user/memory/create

Create Memory

Store a new memory for the authenticated user. Memories are automatically embedded and made searchable for later retrieval.

Request Body

contentstringrequired

The memory content to store. Cannot be empty.

namespacestringoptional

Optional namespace to organize memories (e.g., 'preferences', 'history')

explicit_savebooleanoptionaldefault: false

Mark this memory as explicitly saved by the user

metadataobjectoptional

Additional metadata to attach to the memory

tagsarrayoptional

Tags for categorizing and filtering memories

Request Example

fetch('https://api.arkios.ai/api/knowledge-base/v1/user/memory/create', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'User prefers dark mode and minimal UI design',
    namespace: 'preferences',
    explicit_save: true,
    metadata: {
      category: 'ui_preferences',
      importance: 'high'
    },
    tags: ['preferences', 'ui', 'theme']
  })
});

Response Example

{
  "success": true,
  "data": {
    "memory_id": "73b407d3-3444-492b-ad45-ec6fc5ee5c53"
  },
  "message": "Memory created successfully"
}
POST/api/knowledge-base/v1/user/memory/search

Search Memories

Search through the authenticated user's stored memories. Supports semantic search for natural language queries and keyword search for exact matches.

Request Body

querystringrequired

The search query. Cannot be empty.

modestringoptionaldefault: semantic

Search mode: 'semantic' (meaning-based), 'keyword' (exact matches), or 'hybrid' (both)

namespacestringoptional

Filter results by namespace

agent_idstringoptional

Filter memories by specific agent

limitnumberoptionaldefault: 20

Maximum number of results (max: 50)

min_scorenumberoptionaldefault: 0.3

Minimum relevance score (0.0 - 1.0)

date_fromstringoptional

Filter memories created after this date (ISO 8601)

date_tostringoptional

Filter memories created before this date (ISO 8601)

include_archivedbooleanoptionaldefault: false

Include archived memories in results

search_scopestringoptionaldefault: all

Scope of search: 'all', 'user_only', 'agent_only', or 'specific_agent'

Request Example

fetch('https://api.arkios.ai/api/knowledge-base/v1/user/memory/search', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'user interface preferences',
    mode: 'semantic',
    namespace: 'preferences',
    limit: 10,
    min_score: 0.5,
    search_scope: 'user_only'
  })
});

Response Example

{
  "success": true,
  "data": [
    {
      "memory_id": "dc7d9e96-05fa-4cb3-846e-b42117e86418",
      "content": "User prefers dark mode and minimal UI design",
      "score": 0.87,
      "chunk_info": {
        "chunk_index": 0,
        "chunk_count": 1,
        "chunk_start": 0,
        "chunk_end": 45,
        "collection_source": "mem_7638fbae_74e8_4b8c_b9c8_8c74f4c4e90a"
      },
      "namespace": "preferences",
      "agent_id": "user-created",
      "created_at": "2025-11-03T18:18:24.459Z",
      "importance_score": 0.8,
      "access_count": 3,
      "metadata": {
        "category": "ui_preferences",
        "importance": "high",
        "tags": ["preferences", "ui", "theme"]
      },
      "match_type": "semantic",
      "collection_source": "mem_7638fbae_74e8_4b8c_b9c8_8c74f4c4e90a",
      "retrieval_info": {
        "mode": "whole",
        "is_partial": false,
        "total_chunks": 1,
        "returned_chunks": [0],
        "content_size_words": 8
      },
      "highlights": [
        "User prefers dark mode and minimal UI design"
      ]
    }
  ],
  "stats": {
    "total_results": 1,
    "semantic_results": 1,
    "keyword_results": 0,
    "search_time_ms": 145,
    "search_scope": "user_only",
    "collections_searched": [
      "mem_7638fbae_74e8_4b8c_b9c8_8c74f4c4e90a"
    ]
  },
  "cached": false
}

HTTP Status Codes

CodeDescription
200OK - Request successful
201Created - Memory created successfully
400Bad Request - Invalid input or missing required fields
401Unauthorized - Invalid or missing API key
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong on our end

Best Practices

1

Use Semantic Search for Natural Language

When users ask questions in natural language, semantic search provides the most relevant results based on meaning.

2

Leverage Namespaces for Organization

Group related memories using namespaces (e.g., 'preferences', 'history', 'tasks') for better organization.

3

Set Appropriate Min Scores

Use min_score to filter out low-relevance results. Start with 0.5 for high precision, 0.3 for higher recall.

4

Add Rich Metadata

Include relevant metadata and tags to enable advanced filtering and better context understanding.

5

Handle Rate Limits Gracefully

Implement exponential backoff when you receive 429 responses to avoid overwhelming the API.

6

Cache Frequently Accessed Memories

For commonly accessed memories, implement client-side caching to reduce API calls and improve performance.

Start Using Memory API

Get your API key from the dashboard and start storing user memories for your MCP servers and AI assistants.

Get Started FreeJoin Community