Moai Foundation Memory

Quick Reference

Persistent Memory Management - MCP Memory Server integration for maintaining context across Claude Code sessions, storing user preferences, project-specific knowledge, and learned patterns.

Core Capabilities:

• Persistent key-value storage across sessions
• User preference management
• Project context preservation
• Learned pattern storage
• Session history tracking

When to Use:

• Store user preferences (language, coding style, naming conventions)
• Preserve project-specific decisions and rationale
• Remember frequently used commands and patterns
• Track project milestones and progress
• Store learned code patterns for reuse

Key Operations:

• mcp__memory__store: Store a key-value pair
• mcp__memory__retrieve: Retrieve a stored value
• mcp__memory__list: List all stored keys
• mcp__memory__delete: Delete a stored key

Implementation Guide

MCP Memory Server Setup

The memory server is configured in .mcp.json:

{
  "memory": {
    "command": "${SHELL:-/bin/bash}",
    "args": ["-l", "-c", "exec npx -y @modelcontextprotocol/server-memory"]
  }
}

Memory Categories

Organize stored data by category prefixes:

User Preferences (prefix: user_):

• user_language: Conversation language preference
• user_coding_style: Preferred coding conventions
• user_naming_convention: Variable/function naming style
• user_timezone: User's timezone for scheduling

Project Context (prefix: project_):

• project_tech_stack: Technologies used in project
• project_architecture: Architecture decisions
• project_conventions: Project-specific conventions
• project_dependencies: Key dependencies and versions

Learned Patterns (prefix: pattern_):

• pattern_error_fixes: Common error resolution patterns
• pattern_code_templates: Frequently used code templates
• pattern_workflow: User's preferred workflow

Session State (prefix: session_):

• session_last_spec: Last worked SPEC ID
• session_active_branch: Current git branch
• session_pending_tasks: Incomplete tasks

Usage Patterns

Pattern 1: Store User Preference

When user explicitly states a preference:

User: "I prefer Korean responses"
Action: Store using mcp__memory__store
Key: "user_language"
Value: "ko"

Pattern 2: Retrieve Context on Session Start

At session initialization:

1. Retrieve user_language for response language
2. Retrieve project_tech_stack for context
3. Retrieve session_last_spec for continuity

Pattern 3: Learn from User Behavior

When user corrects or adjusts output:

User: "Use camelCase not snake_case"
Action: Store pattern
Key: "user_naming_convention"
Value: "camelCase"

Pattern 4: Project Knowledge Base

Store important project decisions:

Key: "project_auth_decision"
Value: "JWT with refresh tokens, stored in httpOnly cookies"

Best Practices

Storage Guidelines:

• Use descriptive, categorized key names
• Keep values concise (under 1000 characters)
• Store JSON for complex data structures
• Include timestamps for time-sensitive data

Retrieval Guidelines:

• Check memory on session start
• Retrieve relevant context before tasks
• Use memory to avoid repeated questions

Privacy Considerations:

• Never store sensitive credentials
• Avoid storing personal identifiable information
• Store preferences, not personal data

Integration with Alfred

Alfred should proactively use memory:

On Session Start:

1. Retrieve user preferences
2. Apply language and style settings
3. Load project context

During Interaction:

1. Store explicit user preferences
2. Learn from corrections
3. Update project context as needed

On Task Completion:

1. Store successful patterns
2. Update session state
3. Record milestones

Memory Key Reference

User Preferences

Project Context

Learned Patterns

Session State

Agent-to-Agent Context Sharing

Overview

Memory MCP enables agents to share context during workflow execution. This reduces token overhead and ensures consistency across the Plan-Run-Sync cycle.

Handoff Key Schema

Handoff Data (prefix: handoff_):

handoff_{from_agent}_{to_agent}_{spec_id}

Example: handoff_manager-spec_manager-ddd_SPEC-001

Shared Context (prefix: context_):

context_{spec_id}_{category}

Categories: requirements, architecture, api, database, decisions

Workflow Integration

Plan Phase (manager-spec):

At SPEC completion, store:

Key: context_SPEC-001_requirements
Value: {
  "summary": "User authentication with JWT",
  "acceptance_criteria": ["AC1", "AC2", "AC3"],
  "tech_decisions": ["JWT", "Redis sessions"],
  "constraints": ["No external auth providers"]
}

Run Phase (manager-ddd, expert-backend, expert-frontend):

On task start, retrieve:

Key: context_SPEC-001_requirements
Action: Load requirements summary

On architecture decision, store:

Key: context_SPEC-001_architecture
Value: {
  "pattern": "Clean Architecture",
  "layers": ["domain", "application", "infrastructure"],
  "api_style": "REST with OpenAPI 3.0"
}

Sync Phase (manager-docs):

Retrieve all context for documentation:

Keys: context_SPEC-001_*
Action: Generate comprehensive documentation

Handoff Protocol

Step 1: Store handoff before agent completion

Key: handoff_manager-spec_manager-ddd_SPEC-001
Value: {
  "spec_id": "SPEC-001",
  "status": "approved",
  "key_requirements": [...],
  "tech_stack": [...],
  "priority_order": [...],
  "estimated_complexity": "medium"
}

Step 2: Retrieve handoff on agent start

Key: handoff_manager-spec_manager-ddd_SPEC-001
Action: Load context and continue workflow

Step 3: Update progress

Key: context_SPEC-001_progress
Value: {
  "completed_tasks": ["API design", "Database schema"],
  "in_progress": ["Authentication implementation"],
  "blocked": [],
  "completion_percentage": 60
}

Context Categories

Best Practices for Agent Sharing

Store Strategically:

• Store at workflow boundaries (phase completion)
• Store when making important decisions
• Store when context exceeds prompt capacity

Retrieve Efficiently:

• Retrieve at agent start
• Retrieve when context is needed
• Cache retrieved values in prompt context

Keep Values Structured:

• Use JSON for complex data
• Include timestamps for tracking
• Keep values under 2000 characters

Example: Full Workflow

1. manager-spec completes SPEC-001
   └─ Store: context_SPEC-001_requirements
   └─ Store: handoff_manager-spec_manager-ddd_SPEC-001

2. manager-ddd starts
   └─ Retrieve: handoff_manager-spec_manager-ddd_SPEC-001
   └─ Retrieve: context_SPEC-001_requirements

3. expert-backend implements API
   └─ Retrieve: context_SPEC-001_requirements
   └─ Store: context_SPEC-001_api
   └─ Store: context_SPEC-001_database

4. expert-frontend implements UI
   └─ Retrieve: context_SPEC-001_api
   └─ Store: context_SPEC-001_frontend

5. manager-docs generates documentation
   └─ Retrieve: context_SPEC-001_* (all)
   └─ Generate comprehensive docs

Works Well With

• moai-foundation-context - Token budget and session management
• moai-foundation-core - SPEC-First workflow integration
• moai-workflow-project - Project configuration persistence
• moai-foundation-claude - Claude Code patterns

Success Metrics

• Preference Persistence: User preferences maintained across sessions
• Context Continuity: Project context available without re-explanation
• Learning Efficiency: Reduced repetitive questions over time
• Session Recovery: Quick resumption with session state

Status: Production Ready MCP Integration: @modelcontextprotocol/server-memory Generated with: MoAI-ADK Skill Factory