context-manager

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

# 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

{
  "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
# Linux/macOS: ~/.claude-memories/decisions/{uuid}.md
# Windows: %USERPROFILE%\.claude-memories\decisions\{uuid}.md
~/.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 ~/.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:

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

*