Metadata-Version: 2.4
Name: q-mem-mcp-server
Version: 1.0.0
Summary: Amazon Q CLI용 대화 기억 및 세션 관리 MCP 서버 - ChromaDB 기반 실시간 동기화
Project-URL: Homepage, https://github.com/jikjeong/q-mem-mcp-server
Project-URL: Repository, https://github.com/jikjeong/q-mem-mcp-server
Project-URL: Documentation, https://github.com/jikjeong/q-mem-mcp-server/blob/main/README.md
Project-URL: Issues, https://github.com/jikjeong/q-mem-mcp-server/issues
Author-email: jikjeong <jikjeong@amazon.com>
License: MIT
License-File: LICENSE
Keywords: amazon-q,chromadb,conversation-memory,embedding-search,mcp,sqlite-sync
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: chromadb>=0.4.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Q Memory MCP Server

A Model Context Protocol (MCP) server that provides conversation memory and session management for Amazon Q CLI.

## 🎯 **Key Features**

- **Automatic Conversation Saving**: Real-time sync of Q CLI conversations to ChromaDB
- **Session Management**: Organize conversations by topics/sessions
- **Context Restoration**: Resume previous conversations with full context memory
- **Semantic Search**: Search through conversation history using natural language

## 🚀 **Quick Start**

### 1. Installation
```bash
cd /path/to/q-mem-mcp-server
pip install -e .
```

### 2. MCP Configuration
Add to `~/.config/q/mcp_config.json`:
```json
{
  "mcpServers": {
    "q-mem": {
      "command": "python",
      "args": ["-m", "q_mem_mcp.server"],
      "env": {}
    }
  }
}
```

### 3. Usage
```bash
# Start Q CLI
q chat

# Start a new session
start_session(description="Python Learning")

# Chat normally (automatically saved)
# ... have conversations ...

# List sessions
list_sessions()

# Resume session (loads full context)
resume_session(session_id="Python_Learning_0709_1234")
```

## 🛠️ **Available Commands**

| Command | Description |
|---------|-------------|
| `start_session(description)` | Start a new session |
| `list_sessions()` | List all sessions |
| `resume_session(session_id)` | Resume session with full context |
| `search_memory_by_session_id(session_id, query)` | Search previous conversations |
| `delete_session(session_id, confirm=true)` | Delete a session |
| `get_storage_stats()` | Check storage status |

## 🔧 **Technology Stack**

- **ChromaDB**: Vector database for conversation storage and search
- **SQLite WAL**: Real-time sync with Q CLI database
- **Sentence Transformers**: Semantic search embeddings
- **MCP Protocol**: Communication with Amazon Q

## 📁 **Data Storage**

- **ChromaDB**: `~/.Q_mem/chroma_db/`
- **Sync State**: `~/.Q_mem/sync_state.json`
- **Logs**: `~/.Q_mem/q_mem.log`

## 🔄 **Auto-Sync Features**

Q CLI conversations are automatically saved to ChromaDB in real-time:

- **Real-time Detection**: Checks for new conversations every 2 seconds
- **Partial Failure Handling**: Saves successful conversations even if some fail
- **Auto Recovery**: Automatically recovers from consecutive failures
- **State Restoration**: Restores sync state after restart

## 💡 **Usage Tips**

1. **Session Organization**: Separate conversations by topics
2. **Semantic Search**: Use natural language rather than exact keywords
3. **Context Utilization**: Use `resume_session` for complete conversation restoration
4. **Regular Cleanup**: Delete unnecessary sessions with `delete_session`

## 🐛 **Troubleshooting**

### Q CLI Sync Issues
```bash
# Set environment variable
export Q_CLI_DB_PATH="/path/to/q/cli/database"

# Or check auto-detection
get_storage_stats()
```

### ChromaDB Errors
```bash
# Recreate database
rm -rf ~/.Q_mem/chroma_db/
# Run start_session again
```

### Memory Issues
```bash
# Clean up old sessions
cleanup_old_sessions(days=30, confirm=true)
```

## 📄 **License**

MIT License
