# OpenViking Chat with Memory

Interactive chat interface with memory that persists across sessions using OpenViking's Session API.

<img height="888" alt="image" src="https://github.com/user-attachments/assets/c028f40a-3040-457d-a88c-8220e55973b5" />


## Features

- 🔄 **Multi-turn conversations**
- 💾 **Persistent memory**
- ✨ **Memory extraction**
- 📚 **Source attribution**
- 🎨 **Rich UI**
- 🛡️ **Graceful exit**

## Quick Start

```bash
# 0. Setup
cd examples/chatmem
uv sync

# 1. Configure (copy from query example or create new)
vi ./ov.conf
# Edit ov.conf with your API keys

# 2. Start chatting
uv run chatmem.py
```

## How Memory Works

### Session Storage

Every conversation is saved with a session ID:
- **Default:** `chat-interactive`
- **Custom:** Use `--session-id my-project`

Sessions are stored in `data/session/{session-id}/`:
```
data/session/chat-interactive/
├── messages.jsonl          # All conversation messages
├── history/                # Archived message history
│   └── archive_001/        # Compressed archives
│       ├── messages.jsonl
│       ├── .abstract.md
│       └── .overview.md
└── .abstract.md            # Session summary
```

### Memory Extraction

When you exit (Ctrl-C or /exit), the session:
1. **Commits** current messages to storage
2. **Extracts** long-term memories from conversation
3. **Archives** older messages for compression
4. **Persists** everything to disk

### Resuming Sessions

Next time you run with the same session ID:
```bash
uv run chatmem.py --session-id my-project
```

You'll see:
```
📝 Continuing from previous session: 5 turns, 10 messages
```

The AI remembers your previous conversation context!

## Usage

### Basic Chat

```bash
uv run chatmem.py
```

**First run:**
```
🚀 OpenViking Chat with Memory

You: What is prompt engineering?
[Answer with sources]

You: /exit
💾 Saving session...
👋 Goodbye!
```

**Second run:**
```
📝 Continuing from previous session: 1 turns, 2 messages

You: Can you give me more examples?
[Remembers previous context!]
```

### Commands

- `/help` - Show available commands
- `/clear` - Clear screen (keeps memory)
- `/exit` or `/quit` - Save and exit
- `Ctrl-C` - Save and exit gracefully
- `Ctrl-D` - Exit

#### /time - Performance Timing

Display performance metrics for your queries:

```bash
You: /time what is retrieval augmented generation?

✅ Roger That
...answer...

📚 Sources (3 documents)
...sources...

⏱️  Performance
┌─────────────────┬─────────┐
│ Search          │  0.234s │
│ LLM Generation  │  1.567s │
│ Total           │  1.801s │
└─────────────────┴─────────┘
```

#### /add_resource - Add Documents During Chat

Add documents or URLs to your database without exiting:

```bash
You: /add_resource ~/Downloads/paper.pdf

📂 Adding resource: /Users/you/Downloads/paper.pdf
✓ Resource added
⏳ Processing and indexing...
✓ Processing complete!
🎉 Resource is now searchable!

You: what does the paper say about transformers?
```

Supports:
- Local files: `/add_resource ~/docs/file.pdf`
- URLs: `/add_resource https://example.com/doc.md`
- Directories: `/add_resource ~/research/`

### Session Management

```bash
# Use default session
uv run chatmem.py

# Use project-specific session
uv run chatmem.py --session-id my-project

# Use date-based session
uv run chatmem.py --session-id $(date +%Y-%m-%d)
```

### Debug Mode

```bash
OV_DEBUG=1 uv run chatmem.py
```

## Configuration

Edit `./ov.conf`:

```json
{
  "embedding": {
    "provider": "volcengine",
    "model": "doubao-embedding",
    "api_key": "your-key"
  },
  "vlm": {
    "provider": "volcengine",
    "model": "doubao-pro-32k",
    "api_key": "your-key",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3"
  }
}
```

## Architecture

### Components

- **ChatREPL** - Interactive interface with command handling
- **OpenViking Session** - Persistent conversation memory
- **Recipe** - RAG pipeline (from query example)
- **TextPart** - Message content wrapper

### Memory Flow

```
User Input
    ↓
session.add_message("user", [TextPart(question)])
    ↓
Recipe.query() → LLM Response
    ↓
session.add_message("assistant", [TextPart(answer)])
    ↓
Display Answer + Sources
    ↓
On Exit: session.commit()
    ↓
Memories Extracted & Persisted
```

## Troubleshooting

**"Error initializing"**
- Check `./ov.conf` has valid API keys
- Ensure `data/` directory is writable

**"No relevant sources found"**
- Add documents using `/add_resource`
- Lower `--score-threshold` value
- Try rephrasing your question

**Session not loading**
- Verify session ID matches previous run
- Check `data/session/{session-id}/` exists
- Look for `messages.jsonl` in session directory

**High memory usage**
- Sessions accumulate messages - use different session IDs for different topics
- Check `data/session/` directory size
- Old sessions can be deleted if not needed

## Advanced

### List All Sessions

```bash
ls data/session/
```

### View Session Messages

```bash
cat data/session/chat-interactive/messages.jsonl
```

### Check Extracted Memories

```bash
# Look in memory storage
ls data/memory/
```

### Backup Sessions

```bash
tar -czf sessions-backup-$(date +%Y%m%d).tar.gz data/session/
```

