context-manager

What this skill does

# Context Manager

## Purpose

Permanent external memory system that compensates for SDAM (no episodic memory). Saves and recalls:
- **DECISION**: Architectural choices, tech stack selections, design decisions
- **BLOCKER**: Active obstacles preventing progress
- **CONTEXT**: Project background, requirements, constraints
- **PREFERENCE**: User preferences, coding style, patterns
- **PROCEDURE**: How-to guides, workflows, processes
- **NOTE**: General information, observations, reminders

**For SDAM users**: Complete external memory - never forget decisions or context.
**For ADHD users**: Eliminates decision fatigue - past choices automatically recalled.
**For dyschronometria**: All memories time-anchored with explicit timestamps.

## Activation Triggers

- User says: "remember", "save this", "don't forget"
- User asks: "what did we decide", "recall", "search for"
- User mentions: "decision", "blocker", "preference"
- Making important architectural decision (proactive save)
- Encountering obstacle (proactive blocker tracking)

## Core Workflow

### 1. Save Memory

When user says "remember [something]":

**Step 1**: Classify memory type
```
DECISION: "remember we're using PostgreSQL"
BLOCKER: "remember I can't access the API yet"
CONTEXT: "remember this is for BOOSTBOX project"
PREFERENCE: "remember I prefer functional components"
PROCEDURE: "remember how to deploy: npm run build then rsync"
NOTE: "remember to update docs after this feature"
```

**Step 2**: Extract metadata
- Content: The actual memory
- Tags: Auto-generate from keywords (e.g., "PostgreSQL" → ["database", "postgresql", "backend"])
- Project: Infer from current directory or explicit mention
- Timestamp: ISO 8601 format

**Step 3**: Read current index
```bash
# Cross-platform: Use $HOME (Linux/macOS) or %USERPROFILE% (Windows)
cat ~/.claude-memories/index.json
# Windows PowerShell alternative:
# Get-Content "$env:USERPROFILE\.claude-memories\index.json"
```

**Step 4**: Add to index
```json
{
  "version": "1.0.0",
  "created": "2025-10-17T17:45:00Z",
  "last_updated": "{current_timestamp}",
  "total_memories": N + 1,
  "memories_by_type": {
    "DECISION": X + 1,
    ...
  },
  "memories": [
    {
      "id": "{uuid}",
      "type": "DECISION",
      "content": "Using PostgreSQL as primary database",
      "timestamp": "{current_timestamp}",
      "tags": ["database", "postgresql", "backend"],
      "project": "boostbox",
      "context": {
        "file": "{current_file_if_relevant}",
        "conversation_id": "{if_available}"
      }
    },
    ...existing memories
  ],
  "tags_index": {
    "database": ["{uuid1}", "{uuid2}"],
    "postgresql": ["{uuid}"]
  },
  "project_index": {
    "boostbox": ["{uuid1}", "{uuid2}"],
    "toolhub": ["{uuid3}"]
  }
}
```

**Step 5**: Create detailed memory file
```bash
# Save to category-specific directory
# Linux/macOS: ~/.claude-memories/decisions/{uuid}.md
# Windows: %USERPROFILE%\.claude-memories\decisions\{uuid}.md
~/.claude-memories/decisions/{uuid}.md
```

```markdown
# DECISION: Using PostgreSQL

**Date**: 2025-10-17T17:45:00Z (2 hours ago)
**Project**: BOOSTBOX
**Tags**: database, postgresql, backend

## Decision

Using PostgreSQL as primary database instead of MongoDB.

## Rationale

{if provided by user or inferred from conversation}

## Context

{surrounding conversation context}

## Related Memories

{if any related memories found by tag/project match}

## Last Updated

2025-10-17T17:45:00Z
```

**Step 6**: Confirm to user
```
✅ Remembered: Using PostgreSQL as primary database
📁 Saved to: decisions/{uuid}.md
🏷️ Tags: database, postgresql, backend
📊 Total memories: {N+1}
```

### 2. Recall Memory

When user asks "what did we decide about [topic]":

**Step 1**: Parse query
- Extract keywords: "decide" → search DECISION type
- Extract topic: "database" → search tags/content

**Step 2**: Search index
```javascript
// Priority order:
1. Exact tag match in requested project
2. Exact tag match in any project
3. Partial content match in requested project
4. Partial content match in any project

// Sort by:
1. Relevance (exact match > partial)
2. Recency (newer > older)
3. Type priority (BLOCKER > DECISION > others)
```

**Step 3**: Load detailed memory files
```bash
# For each matching UUID
cat ~/.claude-memories/decisions/{uuid}.md
# Windows PowerShell:
# Get-Content "$env:USERPROFILE\.claude-memories\decisions\{uuid}.md"
```

**Step 4**: Present results
```
🔍 Found 3 memories about "database":

1. DECISION: Using PostgreSQL (2 days ago)
   📁 Project: BOOSTBOX
   💡 Using PostgreSQL as primary database instead of MongoDB
   🔗 decisions/abc-123.md

2. DECISION: Database schema design (5 days ago)
   📁 Project: BOOSTBOX
   💡 User table with UUID primary keys
   🔗 decisions/def-456.md

3. PREFERENCE: Prefer migrations over raw SQL (1 week ago)
   📁 All projects
   💡 Always use migration files, never direct SQL schema changes
   🔗 preferences/ghi-789.md

Would you like details on any of these?
```

### 3. Track Blockers

**Auto-detect blockers**:
- User says: "I can't", "it won't work", "stuck on"
- Error messages that can't be immediately fixed
- Missing credentials/access
- External dependencies not ready

**Proactive save**:
```
🚧 Detected blocker: API credentials not available

Saving as BLOCKER for tracking.

When this is resolved, say "blocker resolved: [brief description]"
```

**Blocker resolution**:
```
User: "blocker resolved: got API credentials"

✅ Blocker resolved: API credentials not available
📝 Updated memory with resolution timestamp
⏱️ Blocked for: 2 days 4 hours
```

### 4. Search Memories

Support rich queries:
- "search memories for auth" → Full-text search
- "show all blockers" → Filter by type
- "what did we decide this week" → Time-filtered DECISION
- "boostbox decisions" → Project + type filter
- "show preferences" → Type filter

**Search syntax**:
```
Basic: "search [topic]"
Type filter: "search decisions about [topic]"
Project filter: "search boostbox [topic]"
Time filter: "search [topic] this week|month|today"
Combined: "search boostbox decisions about database this week"
```

## Memory Types Deep Dive

### DECISION

**When to save**:
- Tech stack choices ("using React", "chose PostgreSQL")
- Architecture decisions ("microservices vs monolith")
- Design patterns ("using repository pattern")
- Library selections ("using Tailwind CSS")

**Structure**:
```markdown
# DECISION: {title}

## What we decided
{the decision}

## Why
{rationale - infer from conversation}

## Alternatives considered
{if discussed}

## Impact
{affected areas}
```

### BLOCKER

**When to save**:
- Can't access resource (API, database, server)
- Missing dependencies (libraries, services)
- External blockers (waiting on someone)
- Technical issues (bug preventing progress)

**Structure**:
```markdown
# BLOCKER: {title}

## Issue
{what's blocking}

## Impact
{what can't be done}

## Workarounds tried
{if any}

## Status
Active | Resolved | Bypassed

## Resolution (when resolved)
{how it was fixed}
{timestamp of resolution}
```

### CONTEXT

**When to save**:
- Project background ("this is for BOOSTBOX")
- Requirements ("must support offline mode")
- Constraints ("can't use paid services")
- Business rules ("users can't delete posts")

### PREFERENCE

**When to save**:
- Coding style ("prefer const over let")
- File organization ("components in src/components/")
- Testing approach ("always unit test utilities")
- Documentation style ("JSDoc for all public functions")

### PROCEDURE

**When to save**:
- Deployment process
- Build commands
- Testing workflows
- Release checklists

**Structure**:
```markdown
# PROCEDURE: {title}

## When to use
{triggering condition}

## Steps
1. {step 1}
2. {step 2}
3. {step 3}

## Expected outcome
{what success looks like}

## Troubleshooting
{common issues}
```

### NOTE

**When to save**:
- General observations
- Reminders
- Ideas for later
- Links to resources

## Time Anchoring (for Dyschronometria)