moai-foundation-memory by modu-ai/moai-adk

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:

Retrieve user_language for response language
Retrieve project_tech_stack for context
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:

Retrieve user preferences
Apply language and style settings
Load project context

During Interaction:

Store explicit user preferences
Learn from corrections
Update project context as needed

On Task Completion:

Store successful patterns
Update session state
Record milestones

Memory Key Reference

User Preferences

Key	Type	Description
`user_language`	string	Response language (ko, en, ja, etc.)
`user_coding_style`	string	Preferred style (descriptive, concise)
`user_naming_convention`	string	Naming style (camelCase, snake_case)
`user_comment_language`	string	Code comment language
`user_timezone`	string	User timezone
`user_expertise_level`	string	junior, mid, senior

Project Context

Key	Type	Description
`project_name`	string	Project name
`project_tech_stack`	JSON	Technologies and frameworks
`project_architecture`	string	Architecture pattern (monolith, microservices)
`project_test_framework`	string	Testing framework (pytest, jest)
`project_conventions`	JSON	Project-specific conventions

Learned Patterns

Key	Type	Description
`pattern_preferred_libraries`	JSON	User's preferred libraries
`pattern_error_resolutions`	JSON	Common error fixes
`pattern_code_templates`	JSON	Frequently used templates

Session State

Key	Type	Description
`session_last_spec`	string	Last worked SPEC ID
`session_active_branch`	string	Current git branch
`session_pending_tasks`	JSON	Incomplete tasks
`session_last_activity`	string	Timestamp of last activity

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

Category	Purpose	Stored By	Used By
`requirements`	SPEC requirements	manager-spec	All agents
`architecture`	Architecture decisions	manager-strategy	expert-*
`api`	API contracts	expert-backend	expert-frontend
`database`	Schema decisions	expert-backend	All agents
`decisions`	Key decisions log	All agents	manager-docs
`progress`	Workflow progress	All agents	Alfred

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