# memory-validator

> Validates memory keys against the namespace schema before operations

- Author: z
- Repository: tktk4751/superspec
- Version: 20260127050940
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/tktk4751/superspec
- Web: https://mule.run/skillshub/@@tktk4751/superspec~memory-validator:20260127050940

---

---
name: memory-validator
description: Validates memory keys against the namespace schema before operations
version: 2.0.0
schema: ../schemas/memory-namespace.yaml
implementation: src/superspec/core/memory.py
requirements:
  - REQ-MCP-006
test_requirements:
  - TR-MCP-002
  - TR-MCP-003
---

# Memory Validator Skill

## Purpose

Validate all memory keys against the namespace schema (REQ-MCP-006) to ensure consistent, organized storage and prevent invalid keys from polluting the memory system.

## When to Use

- Before any `write_memory()` operation
- Before any `read_memory()` operation
- When migrating legacy keys to new namespace format
- When suggesting corrections for invalid keys

## Input

```yaml
key: string          # The memory key to validate
operation: string    # "read" | "write" | "delete"
suggest: boolean     # Whether to provide suggestions for invalid keys (default: true)
```

## Output

```yaml
valid: boolean
namespace: string | null        # Identified namespace if valid
segments: string[]              # Parsed path segments
error:
  code: string                  # Error code if invalid (MEM-001 to MEM-005)
  message: string               # Human-readable error message
  suggestion: string | null     # Suggested correction if available
```

## Validation Rules

### 1. Namespace Check (MEM-001)

The key MUST start with a valid namespace:
- `session/` - Ephemeral session state (eviction priority: 1)
- `plan/` - Planning artifacts (eviction priority: 3)
- `execution/` - Execution logs (eviction priority: 2)
- `evaluation/` - Evaluation results (eviction priority: 3)
- `learning/` - Cross-session learnings (eviction priority: 5, preserved longest)
- `project/` - Project-wide config (eviction priority: 4)

### 2. Key Format Check (MEM-002)

Keys MUST match pattern: `namespace/segment(/segment)*`
- Segments start with lowercase letter `[a-z]`
- Contain lowercase letters, numbers, hyphens `[a-z0-9-]`
- No trailing hyphens
- No consecutive slashes
- Date-based segments allowed: `2026-01-25-type-error`

### 3. Depth Check (MEM-003)

Keys MUST NOT exceed namespace-specific max depth:
- `session/` - max 3 segments
- `plan/` - max 3 segments
- `execution/` - max 3 segments
- `evaluation/` - max 3 segments
- `learning/` - max 3 segments
- `project/` - max 2 segments

### 4. Reserved Words (MEM-005)

Segments MUST NOT use reserved words:
- `null`
- `undefined`
- `true`
- `false`

## Python Implementation

```python
from superspec.core.memory import (
    validate_memory_key,
    MemoryKeyError,
    MemoryEntry,
    Namespace,
    get_namespace_config,
)

# Validate a key
try:
    validated_key = validate_memory_key("session/context")
    print(f"Valid key: {validated_key}")
except MemoryKeyError as e:
    print(f"Error [{e.code}]: {e.message}")
    if e.suggestion:
        print(f"Suggestion: {e.suggestion}")

# Create a memory entry
from datetime import datetime
entry = MemoryEntry(
    key="session/context",
    value={"state": "active"},
    timestamp=datetime.now(),
    namespace="session",
)

# Get namespace configuration
config = get_namespace_config("learning")
print(f"Max depth: {config.max_depth}")  # 3
print(f"Eviction priority: {config.eviction_priority}")  # 5
```

## Procedure

1. **Parse Key**
   - Split key by `/`
   - Extract namespace (first segment)
   - Extract subpath (remaining segments)

2. **Validate Namespace**
   - Check if namespace is in valid_namespaces list
   - If invalid, return MEM-001 error

3. **Validate Format**
   - Check key has at least namespace + one segment
   - Check each segment matches SEGMENT_PATTERN or DATE_SEGMENT_PATTERN
   - Check no reserved words used
   - If invalid, return MEM-002 or MEM-005 error

4. **Validate Depth**
   - Count segments (excluding namespace)
   - Compare against namespace-specific max_depth
   - If exceeds, return MEM-003 error

5. **Return Result**
   - If valid: return validated key
   - If invalid: raise MemoryKeyError with code, message, suggestion

## Examples

### Valid Key

```yaml
Input:
  key: "learning/patterns/auth-flow"
  operation: "write"

Output:
  valid: true
  namespace: "learning"
  segments: ["patterns", "auth-flow"]
  error: null
```

### Invalid Key - Missing Namespace (MEM-001)

```yaml
Input:
  key: "random_key_without_namespace"
  operation: "write"

Output:
  valid: false
  namespace: null
  segments: []
  error:
    code: "MEM-001"
    message: "Invalid namespace 'random_key_without_namespace'. Valid namespaces: session, plan, execution, evaluation, learning, project"
    suggestion: null
```

### Invalid Key - Underscore in Key (MEM-002)

```yaml
Input:
  key: "session/my_context"
  operation: "write"

Output:
  valid: false
  namespace: "session"
  segments: []
  error:
    code: "MEM-002"
    message: "Invalid key format 'session/my_context'. Keys must match pattern: namespace/segment/..."
    suggestion: "Example: session/my-key"
```

### Invalid Key - Too Deep (MEM-003)

```yaml
Input:
  key: "project/a/b/c"
  operation: "write"

Output:
  valid: false
  namespace: "project"
  segments: ["a", "b", "c"]
  error:
    code: "MEM-003"
    message: "Key 'project/a/b/c' exceeds maximum depth of 2 for namespace 'project'"
    suggestion: "Reduce path depth or use a different namespace"
```

### Invalid Key - Reserved Word (MEM-005)

```yaml
Input:
  key: "session/null"
  operation: "write"

Output:
  valid: false
  namespace: "session"
  segments: ["null"]
  error:
    code: "MEM-005"
    message: "Segment 'null' is a reserved word and cannot be used in keys"
    suggestion: "Use a different segment name"
```

## Integration

### Pre-Write Hook

```yaml
# In command frontmatter
hooks:
  pre-write-memory:
    skill: memory-validator
    on-failure: block
```

### In-Command Usage

```markdown
Before calling write_memory():
1. Validate key using memory-validator skill
2. If invalid, show error and suggestion
3. If valid, proceed with write operation
```

## Migration Support

When `suggest: true` and a legacy key is detected:

1. Check if key matches legacy_key_mapping in schema
2. If match found, return:
   - `valid: true` (accept legacy key during migration)
   - `migration_hint: "Consider updating to new format: {new_key}"`
3. Dual-write to both old and new keys (if migration.dual_write enabled)

## Error Codes

| Code | Description |
|------|-------------|
| MEM-001 | Key does not start with valid namespace |
| MEM-002 | Key contains invalid characters or format |
| MEM-003 | Key exceeds maximum depth for namespace |
| MEM-004 | Value exceeds maximum size for namespace |
| MEM-005 | Key contains reserved word as segment |

## Related

- Schema: `superspec/schemas/memory-namespace.yaml`
- Implementation: `src/superspec/core/memory.py`
- Requirement: REQ-MCP-006
- Test Requirements: TR-MCP-002, TR-MCP-003