context-manager

name	context-manager
description	Manages permanent memory storage for decisions, blockers, context, preferences, and procedures. Use when user says "remember", "save this decision", "what did we decide", "recall", "search memories", "any blockers", or when making important architectural decisions. Provides SDAM compensation through external memory.

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

cat /home/toowired/.claude-memories/index.json

Step 4: Add to index

{
  "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

# Save to category-specific directory
/home/toowired/.claude-memories/decisions/{uuid}.md

# 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

// 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

# For each matching UUID
cat /home/toowired/.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:

# 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:

# 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:

# 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)

Always provide:

1. Absolute timestamp: ISO 8601 format
2. Relative time: "2 hours ago", "3 days ago", "last Tuesday"
3. Context anchor: "Before we added authentication", "After the redesign"

Time utilities:

function relativeTime(timestamp) {
  const now = Date.now();
  const then = new Date(timestamp).getTime();
  const diff = now - then;

  const minutes = Math.floor(diff / 60000);
  const hours = Math.floor(diff / 3600000);
  const days = Math.floor(diff / 86400000);

  if (minutes < 60) return `${minutes} minutes ago`;
  if (hours < 24) return `${hours} hours ago`;
  if (days < 7) return `${days} days ago`;
  if (days < 30) return `${Math.floor(days/7)} weeks ago`;
  return `${Math.floor(days/30)} months ago`;
}

Memory Index Structure

Core Index File

/home/toowired/.claude-memories/index.json:

{
  "version": "1.0.0",
  "created": "ISO8601",
  "last_updated": "ISO8601",
  "total_memories": 0,
  "memories_by_type": {
    "DECISION": 0,
    "BLOCKER": 0,
    "CONTEXT": 0,
    "PREFERENCE": 0,
    "PROCEDURE": 0,
    "NOTE": 0
  },
  "memories": [
    {
      "id": "uuid",
      "type": "DECISION|BLOCKER|CONTEXT|PREFERENCE|PROCEDURE|NOTE",
      "content": "brief summary",
      "timestamp": "ISO8601",
      "tags": ["tag1", "tag2"],
      "project": "project-name",
      "status": "active|resolved|archived",
      "context": {
        "file": "optional-file-path",
        "line": "optional-line-number"
      }
    }
  ],
  "tags_index": {
    "tag-name": ["uuid1", "uuid2"]
  },
  "project_index": {
    "project-name": ["uuid1", "uuid2"]
  },
  "session_index": {
    "session-id": ["uuid1", "uuid2"]
  }
}

Directory Structure

/home/toowired/.claude-memories/
├── index.json                 # Master index
├── decisions/                 # Architecture decisions
│   ├── {uuid1}.md
│   └── {uuid2}.md
├── blockers/                  # Active/resolved blockers
│   ├── {uuid3}.md
│   └── {uuid4}.md
├── context/                   # Project context
│   ├── {uuid5}.md
│   └── {uuid6}.md
├── preferences/               # User preferences
│   ├── {uuid7}.md
│   └── {uuid8}.md
├── procedures/                # How-to procedures
│   ├── {uuid9}.md
│   └── {uuid10}.md
├── notes/                     # General notes
│   ├── {uuid11}.md
│   └── {uuid12}.md
├── sessions/                  # Session summaries
│   ├── 2025-10-17.md
│   └── 2025-10-16.md
└── backups/                   # Daily backups
    ├── index-2025-10-17.json
    └── index-2025-10-16.json

Integration with Other Skills

Session Launcher

Provides memories for session restoration:

• Recent decisions (last 7 days)
• Active blockers
• Project context
• Session summaries

Error Debugger

Searches memories for:

• Similar past errors
• Solutions that worked
• Known blockers
• Relevant procedures

Testing Builder

Recalls preferences:

• Testing style (unit/integration/E2E)
• Coverage requirements
• Test framework choices
• Mocking preferences

Deployment Orchestrator

Loads procedures:

• Deployment workflows
• Environment configurations
• Rollback procedures
• Checklist items

Proactive Memory Saving

Auto-save memories in these situations:

During architecture discussions:

User: "Let's use React for the frontend"
→ Auto-save as DECISION: Using React for frontend

When encountering blockers:

User: "Can't connect to the API"
→ Auto-save as BLOCKER: API connection failing

When establishing preferences:

User: "I prefer TypeScript over JavaScript"
→ Auto-save as PREFERENCE: Prefer TypeScript

When creating procedures:

User: "To deploy: run npm build then copy to server"
→ Auto-save as PROCEDURE: Deployment process

Always confirm:

💾 Saved as DECISION: Using React for frontend
(say "undo" within 30 seconds to cancel)

Backup Strategy

Daily backups:

# Every 24 hours, create backup
cp /home/toowired/.claude-memories/index.json \
   /home/toowired/.claude-memories/backups/index-$(date +%Y-%m-%d).json

# Keep last 30 days
find /home/toowired/.claude-memories/backups/ -name "index-*.json" -mtime +30 -delete

Corruption recovery:

# If index.json corrupted, restore from backup
cp /home/toowired/.claude-memories/backups/index-$(date -d yesterday +%Y-%m-%d).json \
   /home/toowired/.claude-memories/index.json

Quick Reference

Common Commands

User Says	Action
"remember we're using PostgreSQL"	Save as DECISION
"what did we decide about the database"	Search DECISIONs for "database"
"show all blockers"	List active BLOCKERs
"any blockers?"	Quick blocker check
"remember I prefer functional components"	Save as PREFERENCE
"search memories for authentication"	Full-text search
"blocker resolved: got API key"	Mark blocker as resolved

File Paths

• Index: /home/toowired/.claude-memories/index.json
• Decisions: /home/toowired/.claude-memories/decisions/{uuid}.md
• Blockers: /home/toowired/.claude-memories/blockers/{uuid}.md
• Backups: /home/toowired/.claude-memories/backups/

Memory Lifecycle

1. Create: User says "remember" or auto-detected
2. Store: Added to index + detailed file created
3. Recall: Searched by keywords/tags/type/project
4. Update: Can be edited if context changes
5. Archive: Old memories archived but never deleted

Success Criteria

✅ User never has to remember decisions ✅ "What did we decide?" is always answerable ✅ Blockers are tracked automatically ✅ All context is time-anchored ✅ Memory search returns relevant results in <1 second ✅ Zero reliance on user's biological memory