Metadata-Version: 2.4
Name: spark-memory
Version: 0.1.2
Summary: High-performance MCP memory server powered by Redis Stack and LangGraph
Author-email: Jason <jaesun23@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Jaesun23/spark-memory
Project-URL: Documentation, https://github.com/Jaesun23/spark-memory/blob/main/README.md
Project-URL: Repository, https://github.com/Jaesun23/spark-memory.git
Project-URL: Issues, https://github.com/Jaesun23/spark-memory/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: redis[hiredis]>=5.0.0
Requires-Dist: fastmcp>=2.5.1
Requires-Dist: langgraph>=0.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Dynamic: license-file

# Spark Memory ✨

High-performance MCP (Model Context Protocol) memory server powered by Redis Stack and LangGraph.

## Features

- ⚡ **Lightning Fast**: Redis Stack-based with millisecond response times
- 🧠 **Intelligent Memory**: Vector search and semantic consolidation
- 🔒 **Enterprise Security**: Field-level encryption, RBAC, audit logging
- 📈 **Scalable**: Distributed environment support
- 🎯 **Easy Deployment**: One-line execution via uvx

## Installation

### Requirements

- Python 3.11+
- Redis Stack 7.2.0+ (with JSON, Search, TimeSeries modules)

### Install via pip

```bash
pip install spark-memory
```

### Install Redis Stack

**macOS:**
```bash
brew tap redis-stack/redis-stack
brew install redis-stack
brew services start redis-stack
```

**Ubuntu/Debian:**
```bash
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt-get update
sudo apt-get install redis-stack
```

**Docker:**
```bash
docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest
```

## Quick Start

### 1. Run as MCP Server

```bash
# Using uvx (recommended)
uvx spark-memory

# Or with Python
python -m spark_memory
```

### 2. Configure with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "spark-memory": {
      "command": "uvx",
      "args": ["spark-memory"]
    }
  }
}
```

### 3. Use in Claude

Once configured, you can use these commands in Claude:

- `m_memory`: Save, search, and manage memories
- `m_state`: Checkpoint and state management
- `m_admin`: System administration
- `m_assistant`: Natural language memory commands

## Architecture

Spark Memory uses a layered architecture:

1. **MCP Server Layer**: FastMCP server exposing tools via Model Context Protocol
2. **Memory Engine Layer**: Core business logic for memory operations
3. **Redis Client Layer**: Redis Stack wrapper with connection pooling
4. **Security Layer**: Encryption, access control, and audit logging

## Memory Operations

### Save Memory
```python
# In Claude, you can say:
# "Save this conversation about Python optimization"
# "Remember that the meeting is at 3pm tomorrow"
```

### Search Memory
```python
# "What did we discuss about Redis?"
# "Find all memories from last week"
```

### State Management
```python
# "Create a checkpoint for the current project"
# "Restore the previous state"
```

## Configuration

Environment variables:
- `REDIS_HOST`: Redis server host (default: localhost)
- `REDIS_PORT`: Redis server port (default: 6379)
- `REDIS_PASSWORD`: Redis password (optional)
- `LOG_LEVEL`: Logging level (default: INFO)

## Development

```bash
# Clone the repository
git clone https://github.com/Jaesun23/spark-memory
cd spark-memory

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with debug logging
LOG_LEVEL=DEBUG python -m spark_memory
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

- Issues: [GitHub Issues](https://github.com/Jaesun23/spark-memory/issues)
- Discussions: [GitHub Discussions](https://github.com/Jaesun23/spark-memory/discussions)

---

Made with ❤️ by Jason and 1호
