# Enhanced Memory System for Chat Agents

## Overview

The enhanced memory system solves the context window problem in long conversations by implementing smart forgetting and automatic memory storage. It maintains conversation continuity while keeping the active context window small and efficient.

## Key Features

### 1. **Automatic Tool Response Storage**
- All non-memory tool responses are automatically stored in memory
- Tool results are only kept in conversation history for the immediate next LLM turn
- After that, they're moved to memory and removed from active conversation

### 2. **End-of-Turn Memory Calls**
- Memory tool calls can be included at the end of responses
- These don't trigger additional LLM turns
- Allows agents to store context without conversation overhead

### 3. **Smart Conversation Trimming**
- Keeps only recent messages in active conversation (configurable, default: 20 messages)
- Older messages are summarized and stored in memory
- System messages are always preserved

### 4. **Tool Response Lifecycle Management**
- **Active Phase**: Tool responses available to next LLM turn
- **Memory Phase**: Stored in memory, removed from conversation
- **Archived Phase**: Summarized if memory gets too full

### 5. **Memory Integration in System Prompts**
- Recent memory entries are automatically included in system prompts
- Provides context continuity without bloating conversation history

## Architecture

### Core Components

1. **MemoryTool**: Handles memory operations (read, append, update, clear, summarize)
2. **MemoryManager**: Orchestrates memory lifecycle and conversation management
3. **Enhanced ChatService**: Integrates memory management into conversation flow

### Memory Storage Format

```
[2024-01-15 10:30:15] TOOL_RESULT: write_file - SUCCESS - create file test.txt
[2024-01-15 10:31:22] User working on screenplay agent project
[2024-01-15 10:32:45] CONVERSATION_SUMMARY: Conversation (10:25:00 to 10:30:00): Topics: testing, files. Actions: creation, analysis. (8 messages)
```

## Configuration

### MemoryConfig Options

```typescript
interface MemoryConfig {
  maxConversationHistory: number;  // Max messages in active conversation (default: 20)
  maxToolResponseAge: number;      // Max turns to keep tool responses active (default: 1)
  autoStoreToolResults: boolean;   // Auto-store non-memory tool results (default: true)
  enableEndOfTurnMemory: boolean;  // Allow end-of-turn memory calls (default: true)
}
```

### Customizing Memory Behavior

```javascript
// Get memory manager from chat service
const memoryManager = chatService.getMemoryManager();

// Update configuration
memoryManager.updateConfig({
  maxConversationHistory: 30,  // Keep more messages
  autoStoreToolResults: false  // Disable automatic storage
});
```

## Usage Examples

### Basic Memory Operations

```xml
<!-- Read current memory -->
<tool_call name="memory" id="1">
  <operation>read</operation>
</tool_call>

<!-- Store information -->
<tool_call name="memory" id="2">
  <operation>append</operation>
  <content>User completed screenplay project setup with character profiles and scene outlines</content>
</tool_call>

<!-- End-of-turn memory (no additional LLM turn) -->
I've completed your request. 

<tool_call name="memory" id="3">
  <operation>append</operation>
  <content>Successfully created project structure with 5 scene files and character database</content>
</tool_call>
```

### Automatic Tool Response Storage

When you execute any non-memory tool:

```xml
<tool_call name="write_file" id="1">
  <operation_type>create</operation_type>
  <file_path>story.md</file_path>
  <content>Once upon a time...</content>
</tool_call>
```

This automatically creates a memory entry:
```
[2024-01-15 10:30:15] TOOL_RESULT: write_file - SUCCESS - create file story.md
```

## Memory Lifecycle

### 1. Tool Execution
- Tool calls are executed normally
- Non-memory tool results are automatically stored in memory
- Tool responses are added to conversation for next LLM turn

### 2. Next LLM Turn
- LLM sees tool responses in conversation
- Generates response based on tool results
- Tool responses are marked for cleanup

### 3. Cleanup Phase
- Old tool responses are removed from conversation
- Conversation history is trimmed if too long
- Old messages are summarized and stored in memory

### 4. System Prompt Integration
- Recent memory entries are included in system prompts
- Provides context for future conversations
- Memory content is automatically formatted

## Benefits

### Context Window Efficiency
- **Before**: All tool responses and messages kept in conversation
- **After**: Only recent messages + memory summary in context
- **Result**: 70-90% reduction in context window usage

### Conversation Continuity
- Important information preserved in memory
- Automatic summarization prevents information loss
- Context available across long conversations

### Developer Experience
- Automatic memory management (no manual intervention needed)
- Configurable behavior for different use cases
- Debug tools for monitoring memory usage

## Testing

### Run Memory System Tests

```bash
# Basic memory test
node test_memory.js

# Test with specific configuration
node -e "
import('./dist/services/chatService.js').then(({ ChatService }) => {
  const service = new ChatService();
  const memoryManager = service.getMemoryManager();
  memoryManager.updateConfig({ maxConversationHistory: 10 });
  console.log('Memory config:', memoryManager.getConfig());
});
"
```

### Memory Statistics

```javascript
const memoryStats = await memoryManager.getMemoryStats();
console.log('Memory stats:', memoryStats);
// Output: { totalEntries: 15, memoryFile: '.chat_memory.txt', config: {...} }
```

## Best Practices

### For Agents
1. **Use end-of-turn memory** for storing outcomes without additional turns
2. **Keep memory entries concise** but informative
3. **Focus on actionable information** that will be useful later
4. **Let automatic storage handle tool results** - don't duplicate

### For Developers
1. **Monitor memory growth** in long-running applications
2. **Adjust configuration** based on use case requirements
3. **Use memory statistics** for debugging and optimization
4. **Test conversation trimming** with realistic message volumes

## Troubleshooting

### Common Issues

**Memory file not found**: Normal for new conversations, file is created on first memory operation

**Context window still large**: Check if conversation history limit is too high or memory summarization is working

**Missing context**: Verify memory entries are being created and included in system prompts

### Debug Commands

```javascript
// Check memory content
const memoryTool = toolManager.getTool('memory');
const result = await memoryTool.execute({ operation: 'read' });

// Check conversation length
console.log('Messages in conversation:', session.messages.length);

// Check memory configuration
console.log('Memory config:', memoryManager.getConfig());
```

## Future Enhancements

- **Semantic memory search**: Find relevant memories based on content similarity
- **Memory categories**: Organize memories by type (tool results, conversations, facts)
- **Memory expiration**: Automatic cleanup of very old memories
- **Cross-session memory**: Share memories across different chat sessions
- **Memory compression**: Advanced summarization for long-term storage