MemoryStackMemoryStack/Documentation

    Quick Start

    Get up and running with Memorystack in 5 minutes. This guide will walk you through creating your first memory-enabled application.

    What you'll learn: How to authenticate, install the SDK, create memories from conversations, and retrieve them using semantic search.

    1

    Get Your API Key

    Your API key authenticates all requests to Memorystack. Each key is tied to your account and tracks usage for billing.

    Steps to generate:

    1. Navigate to your API Keys dashboard
    2. Click "Generate New Key" button
    3. Give your key a descriptive name (e.g., "Production", "Development")
    4. Copy and save your API key immediately—you won't be able to see it again

    ⚠️ Security Best Practices:

    • Store keys in environment variables, never in code
    • Never commit keys to version control (add .env to .gitignore)
    • Use different keys for development, staging, and production
    • Rotate keys regularly and immediately if compromised
    2

    Install the SDK

    Choose your preferred language. Both SDKs provide the same functionality with idiomatic APIs for each platform.

    Node.js / TypeScript

    Recommended for web apps

    Full TypeScript support with type definitions included. Works with Node.js 16+.

    npm install @memorystack/sdk

    Or use yarn add or pnpm add

    Python

    Great for data science

    Includes type hints for better IDE support. Compatible with Python 3.8+.

    pip install memorystack

    Or use poetry add memorystack

    3

    Initialize the Client

    Create a client instance with your API key. The client handles authentication, retries, and error handling automatically.

    Node.js / TypeScript

    import { MemoryStackClient } from '@memorystack/sdk';

// Initialize the client with your API key
// Always use environment variables for security
const client = new MemoryStackClient({
  apiKey: process.env.MEMORYSTACK_API_KEY
});

// Optional: Specify a custom base URL for self-hosted instances
// const client = new MemoryStackClient({
//   apiKey: process.env.MEMORYSTACK_API_KEY,
//   baseUrl: 'https://your-domain.com/api/v1'
// });

    💡 Tip: Create a .env file with MEMORYSTACK_API_KEY=your_key_here

    Python

    from memorystack import MemoryStackClient
import os

# Initialize the client with your API key
# Load from environment variable for security
client = MemoryStackClient(
    api_key=os.environ["MEMORYSTACK_API_KEY"]
)

# Optional: Specify a custom base URL
# client = MemoryStackClient(
#     api_key=os.environ["MEMORYSTACK_API_KEY"],
#     base_url="https://your-domain.com/api/v1"
# )

    💡 Tip: Use python-dotenv to load environment variables from a .env file

    4

    Create Your First Memory

    Send a conversation to Memorystack. The system will automatically extract semantic facts, preferences, and relationships from the dialogue.

    // Add a conversation to memory
// The first parameter is the user's message
// The second parameter is the assistant's response
const result = await client.addConversation(
  "I love TypeScript and prefer dark mode in my IDE",
  "Great choices! TypeScript is excellent for building scalable applications."
);

// The API returns how many memories were created
console.log(`Created ${result.memories_created} memories`);
// Output: Created 3 memories

// You can also see the IDs of created memories
console.log('Memory IDs:', result.memory_ids);
// Output: Memory IDs: ['uuid-1', 'uuid-2', 'uuid-3']

    🧠 What happens behind the scenes:

    • AI extracts: "User loves TypeScript" (preference)
    • AI extracts: "User prefers dark mode" (preference)
    • AI extracts: "TypeScript is good for scalable apps" (fact)
    • Each memory is embedded and stored with metadata
    5

    Retrieve Memories

    Fetch stored memories to provide context in your application. Memories are returned with confidence scores and metadata.

    // Get your personal memories (limit to 10 most recent)
const memories = await client.getPersonalMemories(10);

// Total count of memories
console.log(`Total memories: ${memories.count}`);

// Loop through and display each memory
memories.results.forEach(memory => {
  console.log(`[${memory.memory_type}] ${memory.content}`);
  console.log(`  Confidence: ${memory.confidence}`);
  console.log(`  Created: ${memory.created_at}`);
});

// Example Output:
// [preference] The user loves TypeScript.
//   Confidence: 0.95
//   Created: 2024-11-15T10:30:00Z
// [preference] The user prefers dark mode in their IDE.
//   Confidence: 0.92
//   Created: 2024-11-15T10:30:00Z
// [fact] TypeScript is excellent for building scalable applications.
//   Confidence: 0.88
//   Created: 2024-11-15T10:30:00Z

    🔍 Memory Types:

    • preference - User likes, dislikes, and choices
    • fact - Factual information and statements
    • experience - Past events and experiences
    • goal - Future intentions and objectives
    • relationship - Connections between entities

    🎉 You're all set!

    You've successfully created and retrieved your first memories. Ready to build something amazing?

    Next Steps

    Explore Node.js SDK

    Learn about all available methods and features

    Understanding Memories

    Learn how memories are extracted and stored

    Build a Chatbot

    Create a conversational AI with memory

    API Reference

    Complete API documentation

    Complete Working Example

    Here's a full example that demonstrates creating memories, retrieving them, and checking your usage stats.

    app.ts
    import { MemoryStackClient } from '@memorystack/sdk';

// Initialize the MemoryStack client
const client = new MemoryStackClient({
  apiKey: process.env.MEMORYSTACK_API_KEY
});

async function main() {
  try {
    // Step 1: Create memories from a conversation
    console.log('Creating memories...');
    const result = await client.addConversation(
      "I love TypeScript and prefer dark mode",
      "Great! TypeScript is excellent for scalable apps."
    );
    
    console.log(`✓ Created ${result.memories_created} memories`);
    console.log(`  Memory IDs: ${result.memory_ids.join(', ')}`);
    
    // Step 2: Retrieve all memories
    console.log('\nRetrieving memories...');
    const memories = await client.getPersonalMemories(10);
    
    console.log(`✓ Found ${memories.count} total memories:`);
    memories.results.forEach(m => {
      console.log(`  - [${m.memory_type}] ${m.content}`);
      console.log(`    Confidence: ${(m.confidence * 100).toFixed(0)}%`);
    });
    
    // Step 3: Check usage statistics
    console.log('\nChecking usage stats...');
    const stats = await client.getStats();
    console.log(`✓ Plan: ${stats.plan_tier}`);
    console.log(`  API Calls Used: ${stats.usage.api_calls_used}`);
    console.log(`  Total Memories: ${stats.totals.memories}`);
    
  } catch (error) {
    console.error('Error:', error.message);
  }
}

// Run the example
main();

    To run this example:

    1. Save the code as app.ts
    2. Set your API key: export MEMORYSTACK_API_KEY=your_key
    3. Run: npx tsx app.ts