Conversation Memory Deep Dive

NeurosLink AI's Conversation Memory feature enables AI models to maintain context across multiple turns within a session, creating more natural and coherent conversations.

🧠 Overview

The conversation memory system provides:

• Session-based memory: Each conversation session maintains its own context

• Turn-by-turn persistence: AI remembers previous messages within a session

• Automatic cleanup: Configurable limits to prevent memory bloat

• Session isolation: Different sessions don't interfere with each other

• In-memory storage: Fast, lightweight storage for conversation history

• Universal Method Support: Works seamlessly with both generate() and stream() methods

• Stream Integration: Full conversation memory support for streaming responses

⚙️ Configuration

Environment Variables

# Enable/disable conversation memory
NEUROLINK_MEMORY_ENABLED=true

# Maximum number of sessions to keep in memory
NEUROLINK_MEMORY_MAX_SESSIONS=50

# Maximum number of turns per session
NEUROLINK_MEMORY_MAX_TURNS_PER_SESSION=50

Programmatic Configuration

import { NeurosLink AI } from "neurolink";

const neurolink = new NeurosLink AI({
  conversationMemory: {
    enabled: true,
    maxSessions: 10,
    maxTurnsPerSession: 20,
  },
});

🚀 Usage Examples

Basic Usage with Session ID

import { NeurosLink AI } from "neurolink";

const neurolink = new NeurosLink AI({
  conversationMemory: { enabled: true },
});

// First message in session
const response1 = await neurolink.generate({
  prompt: "My name is Alice and I love reading books",
  context: {
    sessionId: "user-123",
    userId: "alice",
  },
});

// Follow-up message - AI will remember previous context
const response2 = await neurolink.generate({
  prompt: "What is my favorite hobby?",
  context: {
    sessionId: "user-123",
    userId: "alice",
  },
});
// Response: "Based on what you told me, your favorite hobby is reading books!"

Streaming Support

The conversation memory system now fully supports streaming responses with the same memory persistence:

import { NeurosLink AI } from "neurolink";

const neurolink = new NeurosLink AI({
  conversationMemory: { enabled: true },
});

// Stream a response - memory is AUTOMATICALLY captured in background!
const streamResult = await neurolink.stream({
  input: { text: "My favorite hobby is photography" },
  provider: "vertex",
  context: {
    sessionId: "photo-session",
    userId: "photographer",
  },
});

// OPTIONAL: Consume the stream for real-time display
// Memory is saved automatically regardless of whether you consume the stream
let response = "";
for await (const chunk of streamResult.stream) {
  response += chunk.content;
  process.stdout.write(chunk.content); // Real-time display
}

// Memory works even without consuming the stream!
// Both user input AND AI response are automatically stored

// Follow-up message will remember the streamed conversation
const followUp = await neurolink.generate({
  input: { text: "What hobby did I mention?" },
  provider: "vertex",
  context: {
    sessionId: "photo-session", // Same session
    userId: "photographer",
  },
});
// Response: "You mentioned that your favorite hobby is photography!"

Mixed Generate/Stream Conversations

You can seamlessly mix generate() and stream() calls within the same conversation:

// Start with generate
await neurolink.generate({
  input: { text: "I work as a software engineer" },
  context: { sessionId: "career-chat" },
});

// Continue with stream
const streamResult = await neurolink.stream({
  input: { text: "I specialize in AI development" },
  context: { sessionId: "career-chat" },
});

// Back to generate - AI remembers both previous messages
const summary = await neurolink.generate({
  input: { text: "Summarize what you know about my career" },
  context: { sessionId: "career-chat" },
});
// Response includes both software engineering and AI development details

Session Isolation Example

// Session 1
await neurolink.generate({
  prompt: "My favorite color is blue",
  context: { sessionId: "session-1" },
});

// Session 2 - completely isolated
await neurolink.generate({
  prompt: "What is my favorite color?",
  context: { sessionId: "session-2" },
});
// Response: "I don't have information about your favorite color..."

📊 Memory Management

Turn Limits

When the number of conversation turns exceeds maxTurnsPerSession, older messages are automatically removed:

// With maxTurnsPerSession: 3
// Turn 1: User + AI response (2 messages)
// Turn 2: User + AI response (4 messages total)
// Turn 3: User + AI response (6 messages total)
// Turn 4: User + AI response (6 messages - oldest turn removed)

Session Limits

When the number of active sessions exceeds maxSessions, the least recently used sessions are removed:

// With maxSessions: 2
// Session 1: Active
// Session 2: Active
// Session 3: Created -> Session 1 (least recent) is removed

🔌 API Reference

Memory Statistics

// Get memory usage statistics
const stats = await neurolink.getConversationStats();
console.log(stats);
// Output: { totalSessions: 3, totalTurns: 15 }

Session Management

// Clear specific session
const cleared = await neurolink.clearConversationSession("session-123");
console.log(cleared); // true if session existed and was cleared

// Clear all conversations
await neurolink.clearAllConversations();

🧪 Test Results

The conversation memory system has been thoroughly tested and validated:

✅ Test Suite Results

Test Case	Status	Description
Basic Memory	✅ PASS	AI correctly remembers information across turns
Session Isolation	✅ PASS	Sessions remain completely separate
Turn Limits	✅ PASS	Automatic cleanup when limits exceeded
Session Limits	✅ PASS	LRU eviction of old sessions
API Functions	✅ PASS	Clear operations work correctly

Example Test Output

🧪 NeurosLink AI Conversation Memory - Quick Test

📋 TEST 1: Basic Memory Functionality
----------------------------------------
👤 User: My name is Alice
🤖 AI: Hello Alice! It's nice to meet you. How can I help you today?

👤 User: What is my name?
🤖 AI: Your name is Alice! You introduced yourself to me in your previous message.
✅ Memory Test: PASS - Remembers name correctly

📋 TEST 2: Session Isolation
----------------------------------------
👤 User (different session): Do you know Alice?
🤖 AI: I don't know a specific person named Alice...
✅ Isolation Test: PASS - Sessions properly isolated

🎉 OVERALL: ✅ ALL TESTS PASSED

💡 Best Practices

1. Session ID Strategy

// Use consistent session IDs for the same conversation
const sessionId = `user-${userId}-${conversationId}`;

// Include user ID for better tracking
const context = {
  sessionId: sessionId,
  userId: userId,
};

2. Memory Limits

// For chat applications
const chatConfig = {
  maxSessions: 100, // Support many users
  maxTurnsPerSession: 50, // Long conversations
};

// For short interactions
const quickConfig = {
  maxSessions: 20, // Fewer concurrent users
  maxTurnsPerSession: 10, // Brief exchanges
};

3. Error Handling

try {
  const response = await neurolink.generate({
    prompt: "Hello",
    context: { sessionId: "test-session" },
  });
} catch (error) {
  console.error("Generation failed:", error);
  // Memory operations are designed to fail gracefully
  // Generation will continue without memory if needed
}

🔧 Technical Implementation

Architecture

┌─────────────────────┐
│   NeurosLink AI SDK     │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│ ConversationMemory  │
│     Manager         │
└─────────┬───────────┘
          │
┌─────────▼───────────┐
│   In-Memory Store   │
│  (Map<Session, []>) │
└─────────────────────┘

Message Format

interface ChatMessage {
  role: "user" | "assistant" | "system";
  content: string;
}

// Internal storage format
interface SessionMemory {
  sessionId: string;
  userId?: string;
  messages: ChatMessage[];
  createdAt: number;
  lastActivity: number;
}

🔍 Troubleshooting

Common Issues

Memory not persisting between calls

• Ensure sessionId is consistent across calls

• Verify conversationMemory.enabled is true

• Check that sessionId is a valid string

Performance issues with large conversations

• Reduce maxTurnsPerSession limit

• Implement session cleanup strategies

• Monitor memory usage statistics

Session isolation not working

• Verify different sessionId values are being used

• Check for session ID conflicts or duplicates

Debug Logging

// Enable debug logging to see memory operations
const neurolink = new NeurosLink AI({
  conversationMemory: { enabled: true },
  debug: true, // Enables detailed logging
});

🔗 Related Documentation

• Redis Conversation Export - Export session history as JSON for analytics (Q4 2025)

• API Reference - Complete SDK documentation

• Configuration - Environment setup guide

• Examples - More usage examples

• Testing Guide - How to test conversation memory

📈 Performance Characteristics

• Memory Usage: ~1KB per conversation turn

• Lookup Time: O(1) for session retrieval

• Cleanup Time: O(n) for session limit enforcement

• Concurrency: Thread-safe in-memory operations

The conversation memory system is designed for production use with efficient memory management and robust error handling.