5 minutesGetting Started

Quickstart Guide

Get your AI assistant remembering in 5 minutes. From zero to first memory in just 4 steps.

Key Concepts

userId

Required. Your end user's identifier. Use whatever ID system you have (database ID, email, UUID). All memories are scoped to this user.

tenantId

Optional. For multi-tenant SaaS apps. Isolates memories per customer organization. Learn more →

tags

Auto-extracted labels for filtering. Use filters.tags in recall to filter by topic.

1

Create Your Account

Sign up for free and get your API key from the dashboard.

Create a free account to get started. No credit card required.

Create Free Account

Once signed in, go to Settings > API Keys and create a new key:

hsmem_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep this key secure - it provides full access to your memories.

2

Store Your First Memory

Use the API to store a memory. Memories are automatically extracted and embedded.

Make a POST request to store a conversation as memories:

curl -X POST https://memory.hypersparkai.com//api/v1/memory/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "messages": [
      {
        "role": "user",
        "content": "My name is Alex and I work at Acme Corp as a software engineer."
      },
      {
        "role": "assistant",
        "content": "Nice to meet you, Alex! It sounds like you have an exciting role at Acme Corp."
      }
    ]
  }'

Success! HyperSpark automatically extracts facts like "Alex works at Acme Corp as a software engineer" and stores them with semantic embeddings.

3

Recall Your Memories

Search your memories using natural language. Results are ranked by relevance, importance, and recency.

Query your memories with semantic search:

curl -X POST https://memory.hypersparkai.com//api/v1/memory/recall \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "query": "Where does the user work?",
    "topK": 5
  }'

Response includes matched memories with relevance scores:

{
  "success": true,
  "memories": [
    {
      "id": "mem_abc123",
      "content": "Alex works at Acme Corp as a software engineer",
      "score": 0.92,
      "domain": "work",
      "ring": "semantic",
      "importance": 7,
      "tags": ["work", "identity", "acme-corp"],
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "userId": "user_123"
}

Response fields:

  • score - Relevance score (0-1), higher is more relevant
  • ring - Memory type: episodic (events), semantic (facts), procedural (patterns)
  • importance - Significance rating (1-10), auto-assigned by AI
  • domain - Life area: work, health, relationships, etc.
  • tags - Auto-extracted labels for filtering
4

Connect Claude Desktop

Add HyperSpark Memory to Claude Desktop using the Model Context Protocol (MCP).

Add this to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hyperspark-memory": {
      "url": "https://memory.hypersparkai.com//api/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

After restarting Claude Desktop, you'll have access to 15+ memory tools. Here are the essential ones:

Core Memory Tools

remember

Store important information from the current conversation.

Use when the user shares preferences, facts about themselves, or important decisions.

recall

Search memories by meaning, not just keywords.

Use when you need to find relevant memories. Query: "user's work preferences" finds memories about job, schedule, tools, etc.

get_context

Load user identity, preferences, and recent activity at conversation start.

Call this first in every new conversation to restore continuity. Returns a formatted context block.

Data Management

forget_preview

Preview what memories will be affected before deleting.

Always use this first when deleting data. Returns a plan showing which memories will be deleted, rewritten, or kept.

forget_confirm

Execute the deletion plan after user confirms.

Only call after showing forget_preview results and getting explicit user approval.

Decision Intelligence

log_decision

Track important decisions with full context and rationale.

Use when making significant choices. Records what was decided, why, and what informed it.

Plus: find_precedent, get_decision_context, update_decision_outcome, task management tools, and more.See all tools →

Building a Multi-Tenant App?

If you're building a SaaS where each of your customers needs isolated memories, just add tenantId to your requests:

// Same API - just add tenantId
{
  "userId": "user_123",
  "tenantId": "customer_acme",  // Isolates to this customer
  "messages": [...]
}

Auto-creation: Tenants are created on first use. No setup required.
Complete isolation: user_123 in tenant_A is completely separate from user_123 in tenant_B.

Read the Multi-Tenant Guide

Next Steps

MCP Tools Reference

Learn about all 15 MCP tools available for Claude Desktop and other AI assistants.

API Reference

Complete REST API documentation with endpoints, parameters, and examples.

Plans & Billing

Compare plans, understand usage limits, and add credit packs.

Best Practices

Learn when to use each tool and avoid common mistakes.

Need Help?

Join our community or reach out to support for assistance.

GitHub|support@hypersparkai.com