Metadata-Version: 2.4
Name: q-mem-mcp-server
Version: 1.0.1
Summary: Conversation memory and session management MCP server for Amazon Q CLI with ChromaDB real-time sync
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

# AWS Q CLI 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 (PyPI Installation)**

### 1. MCP Configuration
Add to `~/.config/amazon-q/mcp_config.json`:
```json
{
  "mcpServers": {
    "q-mem-mcp-server": {
      "command": "uvx",
      "args": ["q-mem-mcp-server@latest"],
      "env": {
        "Q_CLI_DB_PATH": "~/Library/Application Support/amazon-q/data.sqlite3",
        "Q_MEM_VERBOSE": "true"
      },
      "disabled": false,
      "autoApprove": [
        "start_session",
        "resume_session", 
        "search_memory_by_session_id",
        "get_storage_stats",
        "list_sessions"
      ]
    }
  }
}
```

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

# Start a new session
start_session(description="backendDev")
or 
session start "backendDev" 
# Chat normally (automatically saved)
# ... have conversations ...

# List sessions
list_sessions()

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

## 🛠️ **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`
 

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

## 📦 **Installation Methods**

###  PyPI  
```json
{
  "mcpServers": {
    "q-mem-mcp-server": {
      "command": "uvx",
      "args": ["q-mem-mcp-server@latest"],
      "env": {
        "Q_CLI_DB_PATH": "~/Library/Application Support/amazon-q/data.sqlite3",
        "Q_MEM_VERBOSE": "true"
      }
    }
  }
}
```
  

## 📄 **License**

MIT License

## 🔗 **Links**

- **PyPI**: https://pypi.org/project/q-mem-mcp-server/
- **GitHub**: https://github.com/jikjeong/q-mem-mcp-server
- **Issues**: https://github.com/jikjeong/q-mem-mcp-server/issues
