# Memory MCP - Redis Stack Backend

A drop-in replacement for `mcp-memory-duckdb` with full concurrent access support using Redis Stack.

## Features

- **Concurrent Access**: Multiple Claude sessions can read/write simultaneously
- **RediSearch**: Full-text search across entities and observations
- **ReJSON**: Native JSON document storage
- **Persistent Storage**: RDB snapshots + AOF for durability
- **Git-Friendly Export**: Auto-exports to JSONL after every change
- **API Compatible**: Same tools as mcp-memory-duckdb
- **Cross-Platform**: Works on macOS, Windows, and Linux

---

## Quick Install

### Windows (One-liner)

```powershell
# PowerShell (run as Administrator recommended)
irm https://raw.githubusercontent.com/BakeMark/mcp-memory-redis/main/install.ps1 | iex
```

Or download and run:
```cmd
curl -O https://raw.githubusercontent.com/BakeMark/mcp-memory-redis/main/install.bat
install.bat
```

### macOS

```bash
# Install Redis Stack
brew tap redis-stack/redis-stack
brew install redis-stack

# Clone and install
git clone https://github.com/BakeMark/mcp-memory-redis.git ~/.claude/mcp-memory-redis
cd ~/.claude/mcp-memory-redis
npm install

# Start Redis
redis-stack-server --daemonize yes
```

### Docker (Any Platform)

```bash
# Start Redis Stack
docker run -d --name redis-stack \
  -p 6379:6379 \
  -v redis-memory-data:/data \
  --restart unless-stopped \
  redis/redis-stack:latest

# Clone and install
git clone https://github.com/BakeMark/mcp-memory-redis.git
cd mcp-memory-redis
npm install
```

---

## Configuration

### Claude Code MCP Config

Add to `~/.claude/mcp-servers.json` (macOS/Linux) or `%USERPROFILE%\.claude\mcp-servers.json` (Windows):

#### macOS/Linux
```json
{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["~/.claude/mcp-memory-redis/src/index.js"],
      "env": {
        "REDIS_URL": "redis://localhost:6379",
        "MEMORY_DIR": "~/.claude/memory",
        "MEMORY_EXPORT_PATH": "~/.claude/memory/knowledge.jsonl"
      }
    }
  }
}
```

#### Windows
```json
{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["C:\\Users\\USERNAME\\.claude\\mcp-memory-redis\\src\\index.js"],
      "env": {
        "REDIS_URL": "redis://localhost:6379",
        "MEMORY_DIR": "C:\\Users\\USERNAME\\.claude\\memory",
        "MEMORY_EXPORT_PATH": "C:\\Users\\USERNAME\\.claude\\memory\\knowledge.jsonl"
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `REDIS_URL` | `redis://localhost:6379` | Redis connection URL |
| `REDIS_INDEX_NAME` | `memory_idx` | RediSearch index name |
| `MEMORY_DIR` | `~/.claude/memory` | Directory for exports |
| `MEMORY_EXPORT_PATH` | `~/.claude/memory/knowledge.jsonl` | JSONL export path |

---

## Windows Requirements

The install script handles these automatically:

| Requirement | Install Method |
|-------------|----------------|
| **Node.js 18+** | `winget install OpenJS.NodeJS.LTS` |
| **Docker Desktop** | [docker.com/desktop](https://docker.com/products/docker-desktop) |

Alternative to Docker: [Memurai](https://www.memurai.com/) (Windows-native Redis)

---

## CLI Usage

```bash
# Export knowledge graph
node src/cli.js export ~/backup.jsonl

# Import knowledge (merge with existing)
node src/cli.js import ~/backup.jsonl --merge

# Import knowledge (skip existing entities)
node src/cli.js import ~/backup.jsonl --skip

# Search the graph
node src/cli.js search "database"

# Show statistics
node src/cli.js stats

# Clear all data
node src/cli.js clear
```

---

## API Tools

The MCP server exposes these tools:

| Tool | Description |
|------|-------------|
| `create_entities` | Create new entities with observations |
| `create_relations` | Create relationships between entities |
| `add_observations` | Add observations to existing entities |
| `search_nodes` | Full-text search across entities |
| `open_nodes` | Retrieve specific entities by name |
| `read_graph` | Get entire knowledge graph |
| `delete_entities` | Delete entities (cascades) |
| `delete_observations` | Delete specific observations |
| `delete_relations` | Delete relationships |
| `export_knowledge` | Export to JSONL |
| `import_knowledge` | Import from JSONL |

---

## Migration from DuckDB

Import your existing knowledge:

```bash
# Export from current DuckDB (if needed)
node /path/to/mcp-memory-duckdb/src/cli.js export /tmp/backup.jsonl

# Import to Redis
node src/cli.js import /tmp/backup.jsonl --merge
```

---

## Concurrent Access

Unlike DuckDB which only allows single-writer access, Redis Stack supports:

- Multiple concurrent readers
- Multiple concurrent writers
- Atomic transactions via MULTI/EXEC
- No file locking issues

This means you can run multiple Claude Code sessions simultaneously, all accessing the same knowledge graph.

---

## Data Schema

Entities are stored as JSON documents with the key prefix `entity:`:

```json
{
  "name": "EntityName",
  "entityType": "Type",
  "observations": ["obs1", "obs2"],
  "createdAt": "2026-01-30T12:00:00.000Z",
  "updatedAt": "2026-01-30T12:00:00.000Z"
}
```

Relations are stored with the key prefix `rel:`:

```json
{
  "from": "EntityA",
  "to": "EntityB",
  "relationType": "relates_to",
  "createdAt": "2026-01-30T12:00:00.000Z"
}
```

---

## Troubleshooting

### Windows: Docker not starting

```powershell
# Start Docker Desktop manually, then retry
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"
```

### Redis Connection Failed

```bash
# Check if Redis is running
redis-cli ping

# Docker: check container
docker ps | grep redis-stack
docker logs redis-stack

# Restart container
docker restart redis-stack
```

### Search Index Issues

The search index is created automatically on first startup. If issues persist:

```bash
redis-cli
> FT._LIST
> FT.INFO memory_idx
```

### Windows: Uninstall

```powershell
.\uninstall.ps1
```

---

## License

MIT