ConversationSession Memory Metadata Integration

[ngduyanhece]

Title

Integrate Custom Metadata Support in ConversationSession

Description

Extend ConversationSession to accept and propagate custom metadata to the memory extraction process, enabling
session-level metadata defaults and user-provided metadata overrides.

Background

The ConversationSession is a key integration point where memory operations are initiated. We need to extend it
to support custom metadata that can be passed down to memory tools for proper history tracking and multi-tenant
support.

Requirements

• Support for custom metadata in session run method
• Automatic session-level metadata extraction
• Proper metadata merging (user-provided > session-level > defaults)
• Backward compatibility with existing session calls
• Context override capabilities

Implementation Details

Files to Modify

• src/core/session/conversation-session.ts

1. Extend ConversationSession.run() Method

Add options parameter:
public async run(
input: string,
imageDataInput?: { image: string; mimeType: string },
stream?: boolean,
options?: {
memoryMetadata?: Record<string, any>;
contextOverrides?: Record<string, any>;
historyTracking?: boolean; // Enable/disable history tracking
}
): Promise

2. Update Memory Extraction Call

const memoryResult = await this.services.unifiedToolManager.executeTool(
'cipher_extract_and_operate_memory',
{
interaction: comprehensiveInteractionData,
context: {
sessionId: this.id,
conversationTopic: 'Interactive CLI session',
recentMessages: comprehensiveInteractionData,
...options?.contextOverrides // Allow context overrides
},
memoryMetadata: {
// Session-level defaults
...this.getSessionMetadata(),
// User-provided metadata takes precedence
...options?.memoryMetadata
},
options: {
similarityThreshold: 0.7,
maxSimilarResults: 5,
useLLMDecisions: true,
confidenceThreshold: 0.4,
enableDeleteOperations: true,
historyTracking: options?.historyTracking ?? true
}
}
);

3. Add Session Metadata Extraction

private getSessionMetadata(customMetadata?: Record<string, any>): Record<string, any> {
return {
sessionId: this.id,
source: 'conversation-session',
timestamp: new Date().toISOString(),
environment: process.env.NODE_ENV || 'development',
...this.getSessionContext(),
...customMetadata
};
}

Acceptance Criteria

• ConversationSession.run() accepts optional metadata parameter
• Session-level defaults are properly extracted
• Metadata merging follows correct precedence
• Backward compatibility maintained for existing calls
• Proper error handling for invalid metadata
• Context overrides work as expected
• History tracking can be enabled/disabled per session

Testing Requirements

• Unit tests for metadata parameter handling
• Integration tests with memory extraction
• Test metadata merging behavior with different precedence
• Test error scenarios with invalid metadata
• Backward compatibility tests