friendlist API Documentation

Store and retrieve user information with intelligent memory processing. Our enhanced API automatically organizes information to help you build more personalized and understanding applications.

Getting Started

What is friendlist?

friendlist is an intelligent memory system for applications. Instead of just storing data, it understands and organizes information to help you build better user experiences.

🧠 Smart Memory Processing

Automatically organize and categorize user information for better recall.

🔍 Intelligent Retrieval

Find relevant information quickly with semantic search capabilities.

Quick Start

Get started with friendlist in 4 simple steps:

Install

# Node.js / npm npm install @friendlist/node # or Browser CDN <script src="https://cdn.friendlist.ai/v1/friendlist.js"></script>

Initialize

friendlist.init('YOUR_API_KEY');

Remember

friendlist.remember(userId, 'User prefers dark mode');

Recall

const memory = await friendlist.recall('customer@example.com');

🎉 That's it. Your app now has memory.

friendlist organizes information and helps you build better user experiences.

Installation Examples

Store Different Types of Information

# Simple text friendlist.remember(userId, 'allergic to peanuts'); # Structured data friendlist.remember(userId, { purchase: 'shoes', size: 10, brand: 'Nike' }); # Conversations friendlist.remember(userId, [ { text: 'Hi there!' }, { text: 'How can I help?' } ]);

Retrieve with Context

# Get everything const all = await friendlist.recall('customer@example.com'); # Get shopping memories only const shopping = await friendlist.recall('customer@example.com', { domain: 'shopping' }); # Search for specific content const shoes = await friendlist.recall(userId, { query: 'shoe size' });

💡 Pro Tip

Start simple with basic remember() and recall(). Add advanced options only when you need fine-grained control.

How It Works

Deep dive into friendlist's API endpoints and parameters

Core Endpoints

POST /api/remember

Purpose: Store information about a user with automatic content analysis and classification

# Basic Usage friendlist.remember(userId, content); # Advanced Usage with Optional Parameters friendlist.remember(userId, content, { // Domain hint for categorization domain: 'shopping', // Content category category: 'preference', // Memory importance (0-100) strength: 75, // Time-based behavior temporal: 'permanent', // Usage context context: 'checkout' });

GET /api/recall

Purpose: Retrieve stored information about a user with intelligent filtering and ranking

# Basic Usage const memory = await friendlist.recall('customer@example.com'); # Advanced Usage with Filters const memory = await friendlist.recall('customer@example.com', { // Context filtering context: 'checkout', // Domain filtering domain: 'shopping', // Text search query: 'shoe size', // Result limit limit: 5 });

Parameters Reference

Domain Detection

Automatic categorization into:

  • shopping: Products, prices, brands, sizes
  • health: Medical terms, symptoms, medications
  • work: Projects, meetings, deadlines
  • education: Learning, courses, topics
  • social: Relationships, interactions
  • finance: Money, payments, budgets
  • travel: Locations, bookings, trips
  • food: Meals, restaurants, dietary
  • general: Everything else

Temporal Detection

Content analysis determines lifespan:

  • Time-specific phrases ("tomorrow", "3pm") → Fast decay
  • Search queries ("looking for") → Normal decay
  • Stated preferences ("I prefer") → Slow decay
  • Critical info (allergies) → Never decay

Strength Calculation

Automatic importance scoring:

  • Critical keywords (allergy, emergency) → 100
  • Preferences ("I love", "I hate") → 70-90
  • Actions (purchased, subscribed) → 50-70
  • Browsing (viewed, clicked) → 20-40

Privacy Zones

Automatic privacy classification:

  • Private: Medical, financial, passwords
  • Protected: Work, family, personal
  • Public: General preferences, activities

💡 Best Practice

Start with simple remember(userId, content) calls and only add advanced parameters when you need specific control over classification or behavior.

API Reference

Authentication

Include your API key in the X-API-Key header with every request.

curl -H "X-API-Key: your_api_key" https://friendlist.ai/api/remember

Get your API keys from the dashboard after creating an account.

POST /api/remember

Store information about a user with intelligent processing and categorization.

userId required
string - Unique identifier for the user
content required
string | object | array - Information to store:
  • "allergic to peanuts"
  • { purchase: "shoes", size: 10, brand: "Nike" }
  • [ { text: "Hi there!" }, { text: "How can I help?" } ]
curl -X POST https://friendlist.ai/api/remember \ -H "Content-Type: application/json" \ -H "X-API-Key: your_api_key" \ -d '{ "userId": "user123", "content": "allergic to peanuts" }'

Response

{ "success": true, "memoryId": "mem_abc123", "strength": 85, "category": "preferences", "domain": "food", "sessionId": "session_xyz789", "metadata": { "processing_time_ms": 245, "session_memory_count": 3, "user_profile_completeness": 42.3, "contextual_tags": ["dietary", "allergies"], "auto_captured_metadata": 8 } }

GET /api/recall

Retrieve stored information about a user.

userId required
string - User to get information for
query optional
string - Search for specific content
limit optional
number - Number of results to return (default: 10)
curl -X GET "https://friendlist.ai/api/recall?userId=user123" \ -H "X-API-Key: your_api_key"

Response

{ "success": true, "memories": [ { "id": "mem_abc123", "content": "allergic to peanuts", "timestamp": "2023-12-01T10:00:00Z" } ], "count": 1 }

Use Cases

Real-world examples of how to integrate friendlist into your applications

Customer Support 🎧

"Support tickets that solve themselves"

Understanding interaction patterns across all touchpoints, not just ticket logs.

What you could build:

  • Pattern detection across disconnected channels
  • Solution effectiveness scoring from outcomes
  • Emotional context preservation between agents
// Store support interaction friendlist.remember(userId, { issue: "payment failed", sentiment: "frustrated", channel: "chat", resolution: "updated payment method", satisfaction: 8 });

Healthcare ⚕️

"Medical apps that never forget critical information"

Living medical memory that understands relationships between symptoms, treatments, and outcomes.

What you could build:

  • Allergy detection from conversation patterns
  • Anxiety indicators from appointment behaviors
  • Treatment effectiveness from subtle feedback
// Store patient interaction friendlist.remember(patientId, { symptoms: ["headache", "nausea"], medication: "ibuprofen 400mg", response: "symptoms improved after 2 hours", sideEffects: "mild drowsiness" });

Education 🎓

"Learning that adapts to each student's mind"

Understanding learning patterns across subjects and time from interaction behaviors.

What you could build:

  • Confidence tracking without test scores
  • Learning style detection from interaction patterns
  • Knowledge gap identification from hesitation patterns
// Store learning interaction friendlist.remember(studentId, { lesson: "quadratic equations", attempts: 3, hesitationTime: 12000, // ms score: 0.85, struggledWith: "factoring" });

E-commerce 🛒

"Stores where nothing is ever lost"

Understanding intent, hesitation, and decision patterns across fragmented shopping interactions.

What you could build:

  • Intent understanding from browse patterns
  • Hesitation detection at micro-moments
  • Size confidence from return patterns
// Store shopping behavior friendlist.remember(userId, { product: "running shoes", timeSpent: 180, // seconds sizePreference: "size 10", action: "added_to_cart", hesitation: "compared 3 brands" });

Chat Apps 💬

"Conversations that continue forever without storing messages"

Preserving understanding and context while messages vanish - perfect memory without storage.

What you could build:

  • Context continuity without message history
  • Expertise tracking from discussion patterns
  • Relationship depth from interaction quality
// Store conversation context (not content) friendlist.remember(userId, { topics: ["machine learning", "career advice"], expertise: "senior developer", interactionQuality: "helpful and detailed", relationship: "mentoring" });

Social Platforms 👥

"Social apps that understand relationships, not just connections"

Understanding relationship dynamics and authentic engagement from behavior patterns.

What you could build:

  • Relationship strength from interaction patterns
  • Content relevance from engagement quality
  • Notification timing from response behaviors
// Store social interaction friendlist.remember(userId, { engagementType: "meaningful_comment", contentCategory: "family_photos", responseTime: 300, // seconds interactionDepth: "asked follow-up questions" });