Skip to content

PROJECT_INTERVIEW_GUIDE.md

Latest commit

 

History

History
1212 lines (954 loc) · 42.3 KB

PROJECT_INTERVIEW_GUIDE.md

File metadata and controls

1212 lines (954 loc) · 42.3 KB

Wake Intelligence - Interview Preparation Guide

Wake Intelligence: 5-Layer Temporal Intelligence for AI Agents MCP server implementing Past (causality), Present (memory), Future (prediction), Adaptive (meta-learning), Personality (temporal postures) Reference implementation of Semantic Intent patterns and Hexagonal Architecture

🎯 Table of Contents

  1. Project Overview - The 30-Second Elevator Pitch
  2. Technical Architecture
  3. Key Design Decisions & Trade-offs
  4. Implementation Highlights
  5. Testing Strategy
  6. Challenges & Solutions
  7. Interview Q&A by Theme
  8. Connection to Other Projects

1. Project Overview - The 30-Second Elevator Pitch

What is Wake Intelligence?

Wake Intelligence is an MCP server implementing a 5-layer temporal intelligence brain for AI agents: Past (causality tracking), Present (memory management), Future (predictive pre-fetching), Adaptive (meta-learning), and Personality (temporal postures shaping how context is surfaced).

Why it matters:

  • Enables AI agents to learn from history, optimize current context, and predict future needs
  • 231 passing tests demonstrate comprehensive coverage
  • Deploys to Cloudflare Workers (edge computing)
  • Reference implementation of semantic intent + hexagonal architecture

Business value:

  • AI agents remember WHY decisions were made (causality)
  • Automatic memory optimization with 4-tier LRU system
  • Proactive pre-fetching based on composite prediction scoring
  • Production-ready with deterministic, explainable algorithms

Tech stack: TypeScript, Cloudflare Workers, D1 Database, Workers AI, MCP SDK, Vitest

2. Technical Architecture

2.1 The 5-Layer Temporal Intelligence Brain

┌─────────────────────────────────────────────────────────────┐
│                   WAKE INTELLIGENCE BRAIN                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  LAYER 5: PERSONALITY MODES (Presentation - HOW SURFACED)  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • historian — newest-first, timestamps, causality   │    │
│  │ • prophet   — ranked by Layer 4 prediction score    │    │
│  │ • archaeologist — most-dormant contexts first       │    │
│  │ • minimalist — raw summaries, no framing            │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 4: META-LEARNING (Adaptive - HOW WELL)              │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Tunes HOW WELL predictions work per project       │    │
│  │ • Records prediction outcomes (actual vs predicted) │    │
│  │ • Adjusts weights: temporal/causal/frequency blend  │    │
│  │ • Clamped [0.1, 0.6] — activates after 20 outcomes  │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 3: PROPAGATION ENGINE (Future - WHAT)                │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Predicts WHAT will be needed next                 │    │
│  │ • Composite scoring (40% temporal + 30% causal +    │    │
│  │   30% frequency)                                    │    │
│  │ • Pre-fetching optimization                         │    │
│  │ • Pattern-based next access estimation              │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 2: MEMORY MANAGER (Present - HOW)                    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Tracks HOW relevant contexts are NOW              │    │
│  │ • 4-tier memory classification                      │    │
│  │   (ACTIVE/RECENT/ARCHIVED/EXPIRED)                  │    │
│  │ • LRU tracking + automatic tier updates             │    │
│  │ • Expired context pruning                           │    │
│  └─────────────────────────────────────────────────────┘    │
│                            ▲                                  │
│  LAYER 1: CAUSALITY ENGINE (Past - WHY)                     │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ • Tracks WHY contexts were created                  │    │
│  │ • Causal chain tracking                             │    │
│  │ • Dependency auto-detection                         │    │
│  │ • Reasoning reconstruction                          │    │
│  │ • Action type taxonomy                              │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Why 5 layers?

  1. Past (Causality) - Understand decision history → informs predictions
  2. Present (Memory) - Optimize current relevance → informs access patterns
  3. Future (Propagation) - Predict what's needed → proactive optimization
  4. Adaptive (Meta-Learning) - Tune HOW WELL predictions work → self-improving accuracy
  5. Personality (Postures) - Shape HOW context is surfaced → historian/prophet/archaeologist/minimalist

2.2 Hexagonal Architecture

┌────────────────────────────────────────────┐
│      Presentation Layer (MCPRouter)        │
│        HTTP Request Routing                │
└─────────────────┬──────────────────────────┘
                  │
┌─────────────────▼──────────────────────────┐
│        Application Layer                   │
│   • ToolExecutionHandler                   │
│   • MCPProtocolHandler                     │
└─────────────────┬──────────────────────────┘
                  │
┌─────────────────▼──────────────────────────┐
│           Domain Layer                     │
│   • MetaLearningService (Layer 4)         │
│   • PropagationService (Layer 3)          │
│   • MemoryManagerService (Layer 2)        │
│   • CausalityService (Layer 1)            │
│   • ContextService (Orchestrator)         │
│   • ContextSnapshot (Entity)              │
└─────────────────┬──────────────────────────┘
                  │ (Ports: Interfaces)
┌─────────────────▼──────────────────────────┐
│      Infrastructure Layer                  │
│   • D1ContextRepository                    │
│   • CloudflareAIProvider                   │
│   • CORSMiddleware                         │
└────────────────────────────────────────────┘

2.3 Directory Structure

src/
├── domain/                    # Pure business logic (20 tests)
│   ├── models/                # ContextSnapshot entity
│   └── services/              # 5 services (Context, Causality, Memory, Propagation, MetaLearning)
├── application/               # Orchestration (10 tests)
│   └── handlers/              # ToolExecutionHandler, MCPProtocolHandler
├── infrastructure/            # External adapters (20 tests)
│   └── adapters/              # D1Repository, CloudflareAIProvider
├── presentation/              # HTTP routing (12 tests)
│   └── routes/                # MCPRouter
└── index.ts                   # Composition root (74 lines!)

3. Key Design Decisions & Trade-offs

3.1 Why 5-Layer Brain vs Traditional Context Management?

Decision: Temporal intelligence with Past/Present/Future layers

Rationale:

  • Causality (Past) - Understand WHY contexts exist (decision history)
  • Memory (Present) - HOW relevant is it NOW (LRU + tiers)
  • Propagation (Future) - WHAT will be needed next (predictive)

Trade-off:

  • ✅ Rich temporal understanding
  • ✅ Proactive optimization
  • ✅ Explainable predictions
  • ❌ More complex than simple key-value storage
  • ❌ Additional database columns

Code reference: ARCHITECTURE.md:25-363

3.2 Why Composite Prediction Scoring?

Decision: 40% temporal + 30% causal + 30% frequency

Rationale:

predictionScore =
  0.4 * temporalScore +      // Recency (exponential decay)
  0.3 * causalStrength +     // Position in causal chains
  0.3 * frequencyScore       // Access frequency (log scale)

Why these weights?

  • 40% temporal - Recency is strongest signal (most recent = most likely next)
  • 30% causal - Causal roots often re-accessed (important contexts)
  • 30% frequency - High-use contexts likely needed again

Trade-off:

  • ✅ Balanced multi-factor prediction
  • ✅ Deterministic (not black-box ML)
  • ✅ Each component is explainable
  • ✅ Layer 4 Meta-Learning now tunes weights per project based on observed outcomes

Code reference: PropagationService.ts:60-115

3.3 Why 4-Tier Memory System?

Decision: ACTIVE (< 1hr) / RECENT (1-24hr) / ARCHIVED (1-30d) / EXPIRED (> 30d)

Rationale:

  • Observable tiers based on time since last access
  • Auto-recalculation as contexts age
  • Pruning candidates (EXPIRED tier)
  • Search prioritization (ACTIVE/RECENT ranked higher)

Trade-off:

  • ✅ Simple, observable logic
  • ✅ Automatic memory optimization
  • ✅ Prevents database bloat
  • ❌ Time thresholds are fixed (could be configurable)

Code reference: MemoryManagerService.ts:15-85

3.4 Why Cloudflare Workers vs Traditional Server?

Decision: Deploy to Cloudflare Workers (edge computing)

Rationale:

  • Global edge deployment - Low latency worldwide
  • Serverless - No servers to manage
  • D1 + Workers AI integration - Native Cloudflare ecosystem
  • Auto-scaling - Handles traffic spikes

Trade-off:

  • ✅ Fast (edge-deployed)
  • ✅ Scalable (auto-scale)
  • ✅ Cheap (pay-per-use)
  • ❌ Platform lock-in (Cloudflare-specific)
  • ❌ Cold start latency (first request)

3.5 Why Hexagonal Architecture for MCP Server?

Decision: Full hexagonal architecture with ports & adapters

Rationale:

  • Testability - Domain logic has zero infrastructure dependencies
  • Flexibility - Could swap D1 for PostgreSQL
  • Clarity - Clear layer boundaries
  • Reference implementation - Demonstrates patterns

Trade-off:

  • ✅ Highly maintainable
  • ✅ Easy to test (231 tests!)
  • ✅ Composition root is only 74 lines (down from 483 - 90% reduction)
  • ❌ More files/abstractions upfront

4. Implementation Highlights

4.1 Composition Root (Dependency Injection)

Location: src/index.ts

What it does: Wires all dependencies in 74 lines (90% reduction from monolithic version)

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Infrastructure
    const repository = new D1ContextRepository(env.DB);
    const aiProvider = new CloudflareAIProvider(env.AI);
    const metaLearningRepository = new D1MetaLearningRepository(env.DB);

    // Domain services (5-layer brain)
    const causalityService = new CausalityService(repository);
    const memoryService = new MemoryManagerService(repository);
    const propagationService = new PropagationService(
      repository,
      causalityService
    );
    const metaLearningService = new MetaLearningService(
      metaLearningRepository
    );

    // Orchestrator
    const contextService = new ContextService(
      repository,
      aiProvider,
      causalityService,
      memoryService,
      propagationService
    );

    // Application
    const toolHandler = new ToolExecutionHandler(contextService);
    const protocolHandler = new MCPProtocolHandler(toolHandler);

    // Presentation
    const router = new MCPRouter(protocolHandler);
    return router.handle(request);
  }
};

Why this matters:

  • Single source of truth for dependency graph
  • 90% reduction from previous monolithic approach
  • Explicit dependencies make testing easy

4.2 Layer 1: Causality Engine

Location: CausalityService.ts

Auto-dependency detection:

async detectDependencies(project: string): Promise<string[]> {
  // Find contexts created in last 24 hours
  const recent = await this.repository.findRecent(project, 5, 24);

  // Auto-detect dependencies from temporal proximity
  return recent
    .filter(ctx => {
      const hoursSince = (Date.now() - new Date(ctx.timestamp).getTime()) / 3600000;
      return hoursSince < 1;  // Created within last hour
    })
    .map(ctx => ctx.id);
}

Causal chain building:

async buildCausalChain(targetId: string): Promise<ContextSnapshot[]> {
  const chain: ContextSnapshot[] = [];
  let current = await this.repository.findById(targetId);

  while (current.causality?.causedBy) {
    chain.unshift(current);
    current = await this.repository.findById(current.causality.causedBy);
  }

  chain.unshift(current);  // Add root
  return chain;
}

Why this matters:

  • Temporal proximity heuristic for dependency detection
  • Reconstruct decision history for "Why did I do this?"
  • Observable causal relationships

4.3 Layer 2: Memory Manager

Location: MemoryManagerService.ts

Tier calculation:

calculateMemoryTier(lastAccessed: string | null, timestamp: string): MemoryTier {
  const referenceTime = lastAccessed || timestamp;
  const hoursSince = (Date.now() - new Date(referenceTime).getTime()) / 3600000;

  if (hoursSince < 1) return MemoryTier.ACTIVE;
  if (hoursSince < 24) return MemoryTier.RECENT;
  if (hoursSince < 720) return MemoryTier.ARCHIVED;  // 30 days
  return MemoryTier.EXPIRED;
}

LRU tracking:

async trackAccess(contextId: string): Promise<void> {
  const context = await this.repository.findById(contextId);
  const newTier = this.calculateMemoryTier(new Date().toISOString(), context.timestamp);

  await this.repository.updateAccessTracking(contextId, {
    lastAccessed: new Date().toISOString(),
    accessCount: context.accessCount + 1,
    memoryTier: newTier
  });
}

Why this matters:

  • Observable time-based tiers
  • Fire-and-forget access tracking (don't block responses)
  • Automatic tier recalculation

4.4 Layer 3: Propagation Engine

Location: PropagationService.ts

Composite scoring:

calculatePropagationScore(context: ContextSnapshot, causalStrength: number): number {
  const temporal = this.calculateTemporalScore(context);
  const frequency = this.calculateFrequencyScore(context);

  return 0.4 * temporal + 0.3 * causalStrength + 0.3 * frequency;
}

Temporal score (exponential decay):

private calculateTemporalScore(context: ContextSnapshot): number {
  if (!context.lastAccessed) {
    // Never accessed - use tier-based default
    return context.memoryTier === 'ACTIVE' ? 0.3 :
           context.memoryTier === 'RECENT' ? 0.2 :
           context.memoryTier === 'ARCHIVED' ? 0.1 : 0.0;
  }

  const hoursSince = (Date.now() - new Date(context.lastAccessed).getTime()) / 3600000;
  return Math.exp(-hoursSince / 24);  // Half-life of 24 hours
}

Why this matters:

  • Explainable predictions (not black-box ML)
  • Deterministic algorithm (same inputs = same outputs)
  • Composite multi-factor scoring

4.5 Cloudflare AI Provider with Fallbacks

Location: CloudflareAIProvider.ts

Graceful degradation:

async generateSummary(content: string): Promise<string> {
  if (content.length <= 200) {
    return content;  // Already concise
  }

  try {
    const response = await this.ai.run('@cf/meta/llama-2-7b-chat-int8', {
      messages: [{ role: 'user', content: `Summarize: ${content}` }]
    });
    return response.response;
  } catch (error) {
    console.error('AI summary generation failed:', error);
    // Fallback: Simple truncation
    return content.substring(0, 200) + '...';
  }
}

Why this matters:

  • Graceful degradation if AI unavailable
  • No critical dependency on AI (fallback works)
  • Simple fallback (truncation) is predictable

5. Testing Strategy

Test Distribution

Total: 231 tests (all passing ✅)

Layer Tests Strategy
Domain 20 Pure logic, no mocks
Application 10 Mock domain services
Infrastructure 20 Mock D1/AI
Presentation 12 HTTP routing tests
Integration 13 End-to-end flows
Causality Service 20 Layer 1 algorithms
Context Service 13 Orchestration
Meta-Learning 47 Layer 4 adaptive weights
Other 1 Config/utils

Testing Each Layer

Domain Layer (No Mocks Needed):

describe('CausalityService', () => {
  it('should detect dependencies from temporal proximity', async () => {
    const recentContexts = [
      { id: 'ctx-1', timestamp: '2024-01-01T10:00:00Z' },
      { id: 'ctx-2', timestamp: '2024-01-01T10:30:00Z' }
    ];

    const deps = await causalityService.detectDependencies('project-1');
    expect(deps).toContain('ctx-2');  // Created within 1 hour
  });
});

Infrastructure Layer (Mock External Services):

describe('CloudflareAIProvider', () => {
  it('should use fallback when AI throws error', async () => {
    const mockAI = {
      run: vi.fn().mockRejectedValue(new Error('AI unavailable'))
    };

    const provider = new CloudflareAIProvider(mockAI);
    const summary = await provider.generateSummary(longContent);

    expect(summary).toHaveLength(203);  // Truncated to 200 + '...'
  });
});

Test Commands

npm test              # Run all 231 tests
npm run test:watch    # TDD mode
npm run test:ui       # Visual test runner
npm run test:coverage # Coverage report

6. Challenges & Solutions

6.1 Challenge: Temporal Proximity Dependency Detection

Problem: How to auto-detect which contexts are related without explicit user input?

Solution: Temporal proximity heuristic

// Contexts created within 1 hour of each other are likely related
const hoursSince = (now - context.timestamp) / 3600000;
if (hoursSince < 1) {
  dependencies.push(context.id);
}

Why this works:

  • Observable signal (time is measurable)
  • Reasonable assumption (recent contexts likely related)
  • Simple heuristic (no complex inference)

Trade-offs:

  • ✅ Works without user input
  • ✅ Simple, deterministic
  • ❌ May miss long-running projects
  • ❌ May create false positives

Improvement path: Could add semantic similarity later

6.2 Challenge: Prediction Weight Tuning

Problem: How to balance temporal, causal, and frequency scores?

Solution: Start with heuristic weights (40/30/30), plan for tuning

Current approach:

const score = 0.4 * temporal + 0.3 * causal + 0.3 * frequency;

Rationale:

  • Temporal dominant (40%) - Recency is strongest signal
  • Causal + Frequency balanced (30% each)
  • Simple starting point for validation

Shipped in v3.2.0:

// Layer 4: Meta-Learning — shipped in v3.2.0
// After 20+ outcomes, weights adapt automatically per project
const weights = await metaLearningService.getWeights(project);
// e.g. { temporal: 0.52, causal: 0.28, frequency: 0.20 }
const score = propagationService.calculateScore(context, weights);

6.3 Challenge: Fire-and-Forget Access Tracking

Problem: Don't want to slow down context retrieval with access tracking

Solution: Fire-and-forget pattern

async loadContext(project: string): Promise<ContextSnapshot[]> {
  const contexts = await repository.findByProject(project);

  // Fire-and-forget access tracking (don't await!)
  contexts.forEach(ctx => {
    memoryManager.trackAccess(ctx.id).catch(err => {
      console.error(`Failed to track access for ${ctx.id}:`, err);
    });
  });

  return contexts;
}

Why this matters:

  • Fast responses (don't block on tracking)
  • Best-effort tracking (log errors, continue)
  • Acceptable trade-off (tracking is optimization, not critical)

6.4 Challenge: Cloudflare Workers Environment Constraints

Problem: Workers have execution time limits, no persistent memory

Solution: Design for edge constraints

Approaches:

  • Lazy prediction refresh - Only recalculate when stale
  • Batch operations - Update multiple predictions in single request
  • D1 for persistence - No reliance on Worker memory
  • Stateless design - Each request is independent

Code:

// Only refresh if stale (default: 24 hours)
const hoursSincePrediction = (now - lastPredicted) / 3600000;
if (hoursSincePrediction > staleThreshold) {
  await propagation.refreshPrediction(context);
}

7. Interview Q&A by Theme

Theme A: Architecture & Design

Q1: Explain the 5-layer Wake Intelligence brain. Why Past/Present/Future/Adaptive/Personality?

A: The brain is structured around temporal understanding:

Layer 1: Causality (Past - WHY)

  • Tracks WHY contexts were created
  • Builds causal chains (what led to what)
  • Enables reasoning reconstruction
  • Example: "Why did I make this decision?"

Layer 2: Memory (Present - HOW)

  • Manages HOW relevant contexts are NOW
  • 4-tier system (ACTIVE → RECENT → ARCHIVED → EXPIRED)
  • LRU tracking + auto-tier recalculation
  • Example: "What's actively being worked on?"

Layer 3: Propagation (Future - WHAT)

  • Predicts WHAT will be needed next
  • Composite scoring (temporal + causal + frequency)
  • Pre-fetching optimization
  • Example: "What contexts should we load ahead of time?"

Layer 4: Meta-Learning (Adaptive - HOW WELL)

  • Tunes HOW WELL Layer 3 predictions work
  • Records outcomes (predicted vs actually accessed)
  • Adjusts weights per project after 20+ outcomes
  • Clamped at [0.1, 0.6] — no signal dominates entirely
  • Example: "Are my predictions getting more accurate over time?"

Why this structure?

  • Progressive enhancement - Each layer builds on previous
  • Temporal completeness - Past informs present, present informs future
  • Observable at each layer - No black-box predictions
  • Self-improving - Layer 4 closes the feedback loop

Code reference: ARCHITECTURE.md:25-363

Q2: Walk through the hexagonal architecture. How does it differ from traditional MCP servers?

A: Hexagonal architecture maintains strict layer separation:

Traditional MCP server:

// Monolithic - everything in one file
export default {
  async fetch(request, env) {
    const data = JSON.parse(await request.text());
    const result = await env.DB.query(...); // Direct DB access
    const summary = await env.AI.run(...);   // Direct AI access
    return new Response(JSON.stringify(result));
  }
}

Wake Intelligence hexagonal:

// Presentation → Application → Domain → Infrastructure
export default {
  async fetch(request, env) {
    // Infrastructure adapters
    const repository = new D1ContextRepository(env.DB);
    const aiProvider = new CloudflareAIProvider(env.AI);

    // Domain services (pure business logic)
    const contextService = new ContextService(repository, aiProvider);

    // Application handlers
    const toolHandler = new ToolExecutionHandler(contextService);

    // Presentation router
    const router = new MCPRouter(protocolHandler);
    return router.handle(request);
  }
}

Key differences:

Benefits:

  1. Testability - Domain has zero infrastructure dependencies
  2. Composition root - Only 74 lines (90% reduction from monolithic)
  3. Clear boundaries - Each layer has single responsibility
  4. Swappable infrastructure - Could replace D1 with PostgreSQL

Trade-offs:

  • ✅ Maintainable, testable (231 tests!)
  • ✅ Clear architecture for teams
  • ❌ More files (5 layers vs 1 file)

Q3: Explain the composite prediction scoring algorithm. Why these weights?

A: Prediction score combines 3 observable signals:

predictionScore =
  0.4 * temporalScore +      // 40% weight
  0.3 * causalStrength +     // 30% weight
  0.3 * frequencyScore       // 30% weight

1. Temporal Score (40%) - Exponential decay

hoursSince = (now - lastAccessed) / 3600000;
temporalScore = Math.exp(-hoursSince / 24);  // Half-life of 24 hours
  • Most recently accessed = highest score
  • Decays exponentially (24-hour half-life)
  • Why 40%? Recency is strongest predictor

2. Causal Strength (30%) - Position in chains

if (isRoot && hasDependents) return 0.5+;  // High importance
if (hasDependents) return 0.3+;            // Moderate
return 0.2;                                 // Leaf node
  • Causal roots score higher (foundational decisions)
  • Nodes with dependents are important
  • Why 30%? Causality indicates importance

3. Frequency Score (30%) - Logarithmic access count

frequencyScore = Math.log(accessCount + 1) / Math.log(101);
  • High-use contexts likely needed again
  • Logarithmic scaling (diminishing returns)
  • Why 30%? Frequency matters but shouldn't dominate

Why composite scoring?

  • Multi-factor - No single signal is perfect
  • Balanced - Weights tuned heuristically
  • Deterministic - Not black-box ML
  • Explainable - Each component traceable

Layer 4 (meta-learning) ships in v3.2.0 — weights now adapt per project based on observed outcomes. Use get_learning_stats to inspect.

Theme B: Implementation Details

Q4: How does dependency auto-detection work?

A: Temporal proximity heuristic - contexts created within 1 hour are likely related

Algorithm:

async detectDependencies(project: string): Promise<string[]> {
  // Find recent contexts (last 24 hours)
  const recent = await repository.findRecent(project, limit=5, hours=24);

  // Filter by temporal proximity (< 1 hour)
  const dependencies = recent
    .filter(ctx => {
      const hoursSince = (now - ctx.timestamp) / 3600000;
      return hoursSince < 1;
    })
    .map(ctx => ctx.id);

  return dependencies;
}

Why 1 hour threshold?

  • Observable - Time is measurable
  • Reasonable assumption - Developer likely working on related tasks
  • Simple heuristic - No complex inference needed

Example workflow:

10:00 AM - Save context: "Design database schema"
10:30 AM - Save context: "Implement schema migrations"
           → Auto-detected dependency: previous context

Trade-offs:

  • ✅ Works without user input
  • ✅ Simple, deterministic
  • ❌ May miss long-running projects (> 1 hour between saves)
  • ❌ May create false positives

Future improvement: Add semantic similarity (embeddings) to complement temporal proximity

Q5: How does the 4-tier memory system work?

A: Observable time-based classification with automatic recalculation

Tier calculation:

calculateMemoryTier(lastAccessed: string | null, timestamp: string): MemoryTier {
  const referenceTime = lastAccessed || timestamp;
  const hoursSince = (now - referenceTime) / 3600000;

  if (hoursSince < 1)    return ACTIVE;     // < 1 hour
  if (hoursSince < 24)   return RECENT;     // 1-24 hours
  if (hoursSince < 720)  return ARCHIVED;   // 1-30 days
  return EXPIRED;                            // > 30 days
}

Memory tier behaviors:

Tier Time Range Search Priority Auto-Actions
ACTIVE < 1 hr Highest Top of results
RECENT 1-24 hr High Include in searches
ARCHIVED 1-30 days Low De-prioritize
EXPIRED > 30 days Lowest Pruning candidate

Automatic tier updates:

async trackAccess(contextId: string): Promise<void> {
  const context = await repository.findById(contextId);
  const newTier = this.calculateMemoryTier(new Date().toISOString(), context.timestamp);

  await repository.update(contextId, {
    lastAccessed: new Date().toISOString(),
    accessCount: context.accessCount + 1,
    memoryTier: newTier  // Auto-update tier
  });
}

Pruning:

async pruneExpiredContexts(limit = 100): Promise<number> {
  const expired = await repository.findByTier(EXPIRED, limit);
  for (const ctx of expired) {
    await repository.delete(ctx.id);
  }
  return expired.length;
}

Benefits:

  • ✅ Self-optimizing memory
  • ✅ Automatic cleanup
  • ✅ Observable tier logic
  • ✅ Search prioritization

Theme C: Testing & Quality

Q6: You have 231 tests. Walk through your testing strategy.

A: Layer-specific strategies optimized for each architectural layer

Test distribution:

  • Domain: 20 tests (pure logic, no mocks)
  • Application: 10 tests (mock domain services)
  • Infrastructure: 20 tests (mock D1/AI)
  • Presentation: 12 tests (HTTP routing)
  • Integration: 13 tests (end-to-end)
  • Specialized: 33 tests (Causality, Context services)
  • Other: 1 test

Domain Layer - No Mocks:

describe('PropagationService', () => {
  it('should calculate temporal score with exponential decay', () => {
    const context = {
      lastAccessed: '2024-01-01T12:00:00Z',
      timestamp: '2024-01-01T10:00:00Z'
    };

    const score = propagation.calculateTemporalScore(context);
    expect(score).toBeCloseTo(0.92, 2);  // exp(-2/24)
  });
});

Why no mocks? Pure functions, no infrastructure

Infrastructure Layer - Mock External:

describe('D1ContextRepository', () => {
  it('should save context to D1', async () => {
    const mockDB = {
      prepare: vi.fn().mockReturnValue({
        bind: vi.fn().mockReturnValue({
          run: vi.fn().mockResolvedValue({ success: true })
        })
      })
    };

    const repo = new D1ContextRepository(mockDB);
    await repo.save(context);

    expect(mockDB.prepare).toHaveBeenCalledWith(
      expect.stringContaining('INSERT INTO context_snapshots')
    );
  });
});

Integration Tests - End-to-End:

describe('Integration: Save and Load Context', () => {
  it('should persist and retrieve context with all layers', async () => {
    // Save
    await contextService.saveContext({
      project: 'test',
      content: 'Integration test',
      actionType: 'testing'
    });

    // Load
    const contexts = await contextService.loadContext('test');
    expect(contexts).toHaveLength(1);
    expect(contexts[0].causality.actionType).toBe('testing');
  });
});

Test commands:

npm test              # All 231 tests
npm run test:watch    # TDD mode
npm run test:coverage # Coverage report

Theme D: Challenges & Problem-Solving

Q7: What was the hardest technical challenge in this project?

A: Balancing prediction accuracy with computational cost

The problem:

  • Prediction scoring requires multiple calculations per context
  • Workers have execution time limits
  • Can't recalculate predictions on every request (too slow)

Solution 1: Lazy refresh with staleness threshold

// Only refresh if stale (default: 24 hours)
const hoursSincePrediction = (now - lastPredicted) / 3600000;
if (hoursSincePrediction > staleThreshold) {
  await propagation.refreshPrediction(context);
}

Solution 2: Batch updates

async updateProjectPredictions(project: string, staleThreshold = 24) {
  const staleContexts = await repository.findStalePredictions(staleThreshold);
  const projectContexts = staleContexts.filter(c => c.project === project);

  // Batch update all stale predictions
  for (const context of projectContexts) {
    const score = this.calculatePropagationScore(context, causalStrength);
    await repository.updatePrediction(context.id, score);
  }
}

Solution 3: Pre-compute causal strength

// Store causal strength in DB, not recalculate every time
const causalStrength = this.calculateCausalStrength(context);
await repository.update(context.id, { causalStrength });

Results:

  • ✅ Fast requests (< 100ms typical)
  • ✅ Predictions stay reasonably fresh (24-hour staleness ok)
  • ✅ Batch updates efficient
  • ❌ Predictions can be stale for up to 24 hours (acceptable trade-off)

Lessons learned:

  • Caching matters in serverless environments
  • Staleness is acceptable for predictions (not real-time data)
  • Pre-computation beats on-demand calculation

Theme E: Business & Impact

Q8: Why build this? What problem does it solve?

A: AI agents have no memory of their past work

The problem:

Before Wake Intelligence:

Developer: "Why did I make this architectural decision 2 weeks ago?"
AI Agent: "I don't have that context. What were you working on?"
Developer: *manually searches old conversations*

After Wake Intelligence:

Developer: "Why did I make this architectural decision?"
AI Agent: [Uses build_causal_chain]
"You made that decision as part of a refactoring effort. Here's the chain:
1. Initial design (Dec 1) - Chose monolithic architecture
2. Performance issues (Dec 5) - Identified bottleneck
3. Decision to refactor (Dec 8) - Switched to microservices
4. This decision (Dec 10) - Implemented API gateway pattern

The rationale was: 'Need to isolate authentication logic for scaling'
Related contexts: [shows 3 linked decisions]"

Business value:

  1. Institutional knowledge - Never lose context of WHY decisions were made
  2. Onboarding - New team members understand decision history
  3. Efficiency - No manual searching for past contexts
  4. Proactive - Pre-fetches contexts you'll likely need

Real-world use cases:

Use case 1: Long-running projects

Month 1: Design database schema
Month 2: Implement business logic
Month 3: "Wait, why did we choose this schema?"
→ Layer 1 (Causality) reconstructs reasoning from Month 1

Use case 2: Context switching

Work on Project A (morning)
Work on Project B (afternoon)
Return to Project A (next day)
→ Layer 3 (Propagation) pre-fetches Project A contexts

Use case 3: Knowledge transfer

Senior dev leaves → Junior dev takes over
Junior: "Why is this architected this way?"
→ Causal chains show decision history with rationale

8. Connection to Other Projects

8.1 Relationship to Semantic Intent Portfolio

Wake Intelligence (this project) is part of a portfolio demonstrating semantic intent patterns:

PerchIQX (Database Intelligence)

  • Domain: Database introspection for Cloudflare D1
  • Connection: Both use hexagonal architecture + MCP
  • Shared patterns:
    • Semantic anchoring (observable properties)
    • Intent preservation
    • Hexagonal architecture
    • MCP protocol

Comparison:

Aspect Wake PerchIQX
Domain Temporal intelligence Database introspection
Tests 221 407
Layers 5-layer brain 4 architectural layers
Key entity ContextSnapshot TableInfo/DatabaseSchema
Deployment Cloudflare Workers Node.js (stdio)

Semantic Foragecast Engine (Video Pipeline)

  • Domain: Procedural animation pipeline
  • Connection: Config-driven systems, phased processing
  • Shared patterns:
    • Observable properties
    • Semantic anchoring
    • Deterministic algorithms

8.2 The "Semantic Intent" Thread

All projects demonstrate:

  1. Semantic Over Structural

    • Wake: Causality based on "action type" (why), not file size
    • PerchIQX: Index recommendations based on FK presence, not row counts

  2. Intent Preservation

    • Wake: Action type maintained through all transformations
    • PerchIQX: Environment semantic never overridden

  3. Observable Anchoring

    • Wake: Temporal proximity is measurable (time since creation)
    • PerchIQX: Foreign keys are directly observable in schema

8.3 How to Present in Interviews

Strategy: Show pattern consistency across domains

Opening: "Let me walk you through my temporal intelligence system for AI agents..."

Connect to portfolio: "I also built a database intelligence MCP server using similar patterns - hexagonal architecture, semantic anchoring, comprehensive testing..."

Unified narrative: "These projects demonstrate my approach to building maintainable AI-augmented systems. Whether it's temporal intelligence, database introspection, or multimedia pipelines, I focus on preserving semantic meaning through transformations."

📚 Additional Resources

Key Files to Reference

  1. README.md - Quick overview, brain architecture
  2. ARCHITECTURE.md - Complete design documentation (849 lines!)
  3. BRAIN-ARCHITECTURE-IMPLEMENTATION-PLAN.md - 5-layer implementation
  4. src/index.ts - Composition root (74 lines)
  5. src/domain/services/ - All 4 domain services

Commands to Know

# Development
npm run dev          # Start local Wrangler dev server
npm run deploy       # Deploy to Cloudflare Workers

# Testing
npm test             # Run all 231 tests
npm run test:watch   # TDD mode
npm run test:coverage # Coverage report

# Database
wrangler d1 create mcp-context              # Create D1 database
wrangler d1 execute mcp-context --file=...  # Run migrations

# Code quality
npm run lint         # Biome linting
npm run format       # Format code
npm run type-check   # TypeScript validation

Quick Stats to Memorize

  • 231 passing tests (all layers)
  • 5-layer brain (Past/Present/Future/Adaptive/Personality)
  • 4-tier memory (ACTIVE/RECENT/ARCHIVED/EXPIRED)
  • 74-line composition root (90% reduction)
  • Adaptive prediction (weights tune per project via Layer 4)
  • 15 MCP tools (Layer 1–4 + cross-project causality)
  • Deployed to edge (Cloudflare Workers)
  • TypeScript 5.8 with strict types

🎯 Interview Tips

Do's

✅ Start with the 5-layer brain - It's the unique differentiator ✅ Use specific numbers - "231 tests", "40/30/30 scoring", "4 tiers", "5 layers" ✅ Explain trade-offs - Every decision has pros/cons ✅ Connect layers - Show how Past informs Future ✅ Reference code - Point to specific files ✅ Show pattern consistency - Connect to PerchIQX

Don'ts

❌ Don't oversell ML - It's deterministic algorithms, not deep learning ❌ Don't skip the "why" - Always explain rationale ❌ Don't forget business value - Not just technical showcase ❌ Don't ignore alternatives - Show you evaluated options ❌ Don't memorize code - Understand the concepts

Practice Questions

Behavioral:

  • "Tell me about a system you designed from scratch" → Use Wake Intelligence 5-layer brain architecture

  • "Describe a time you optimized performance" → Use lazy prediction refresh + staleness threshold

Technical:

  • "How do you structure code for testability?" → Explain hexagonal architecture, 231 tests

  • "Explain a complex algorithm you've implemented" → Walk through composite prediction scoring

System Design:

  • "Design a context management system for AI agents" → Explain Wake Intelligence architecture

Good luck! This project demonstrates senior-level system design, temporal intelligence, and production-ready edge computing.

Remember: The 5-layer brain (Past/Present/Future/Adaptive/Personality) is your unique story - lead with that! 🧠