Standardize Redis Key and Index Naming to Use Consistent Dash (-) Convention [BREAKING CHANGE - Major Version Required]

[abrookins]

Problem

The codebase has inconsistent usage of dashes (-) vs underscores (_) in Redis keys and index names, which conflicts with RedisVL conventions and reduces maintainability.

Current inconsistencies:

• Index name: "memory_records" (underscore) vs RedisVL convention of dashes
• Key patterns: Mixed usage of working_memory, auth_token vs dash convention
• Configuration: redisvl_index_prefix: str = "memory_idx" should be "memory-idx"

Files affected: agent_memory_server/config.py:72,96, agent_memory_server/utils/keys.py

Proposed Solution

Standardize to dash (-) convention aligning with RedisVL best practices:

• redisvl_index_name: "memory-records"
• working-memory:*, auth-token:* key patterns

⚠️ Migration Complexity

This is a breaking change requiring careful migration:

1. Index Migration: Need to export/re-index all documents from memory_records → memory-records
2. Key Migration: Rename existing keys using SCAN/RENAME operations
3. Data Safety: Risk of data loss without proper backup/rollback

Required migration components:

• Redis backup before migration
• Atomic key renaming script using SCAN/RENAME
• Index recreation with document preservation
• Rollback capability
• CLI command: uv run agent-memory migrate-redis-naming
• Configuration flag for gradual rollout

Risk Level: HIGH - Could break existing installations

Version Impact

Requires Major Version Bump (v0.x → v1.0)

This is a breaking change that requires existing installations to run migration scripts. Following semantic versioning, this justifies a major version increment.

Version Strategy:

• Current: v0.x → v1.0 (first major release with dash convention)
• Include migration tooling in v1.0 release
• Deprecation notice in final v0.x release
• Clear upgrade documentation with migration steps

Release Notes Requirements:

## v1.0.0 - BREAKING CHANGES

### Redis Key Naming Convention Change
- All Redis keys now use dash (-) convention instead of underscore (_)
- Index name changed: `memory_records` → `memory-records`
- Key patterns changed: `working_memory:*` → `working-memory:*`

### Migration Required
Run before upgrading:
```bash
# Backup your Redis data first\!
redis-cli BGSAVE

# Run migration (with dry-run first)
uv run agent-memory migrate-redis-naming --dry-run
uv run agent-memory migrate-redis-naming

Rollback Available

If issues occur:

uv run agent-memory rollback-redis-naming

## Implementation Approach
1. Create migration script with dry-run capability
2. Add backward compatibility layer during transition
3. Comprehensive testing on non-production data
4. Documentation for manual migration steps

This should be implemented as part of the v1.0 major release due to its breaking nature.