project-init-memory（项目初始化内存）

Project Init Memory

When to use this skill

• New Project Setup: First time running Claude Code in a project
• Skillset Consistency: Ensure same skillset is loaded across sessions
• Team Onboarding: New team members get identical AI configuration
• Multi-Project Management: Maintain different skillsets per project
• Session Restoration: Resume work with previous context

Instructions

Step 1: Check for Existing Configuration

# Check if project already has skill configuration
ls -la .claude/ 2>/dev/null
cat .claude/settings.json 2>/dev/null
cat CLAUDE.md 2>/dev/null

If no configuration exists, proceed to Step 2.

Step 2: Detect Available Skills

# Check for .agent-skills directory
if [ -d ".agent-skills" ]; then
    echo "Found .agent-skills directory"
    ls -la .agent-skills/
fi

# Check for skills-template
if [ -d ".skills-template" ]; then
    echo "Found .skills-template"
    ls -la .skills-template/.agent-skills/
fi

Step 3: Initialize Project Memory

Create .claude/project-memory.json:

{
  "version": "1.0.0",
  "initialized": "2026-01-16T00:00:00Z",
  "skillset": {
    "source": ".skills-template/.agent-skills",
    "categories": ["backend", "frontend", "code-quality", "infrastructure"],
    "active_skills": [],
    "token_mode": "toon"
  },
  "environment": {
    "workflow_type": "full-multiagent",
    "mcp_servers": ["gemini-cli", "codex-cli"],
    "performance_preset": "balanced"
  },
  "project_context": {
    "name": "",
    "type": "",
    "primary_language": "",
    "frameworks": []
  },
  "session_history": []
}

Step 4: Generate CLAUDE.md with Memory

# Project: {project_name}

> Auto-generated by project-init-memory skill
> Last updated: {timestamp}

## Skillset Configuration

### Active Skills
- {list of active skills from memory}

### Token Mode
- Current: {toon|compact|full}
- Recommendation: toon (95% token savings)

## Project Context

### Technology Stack
- Language: {primary_language}
- Framework: {frameworks}
- Database: {database}

### Key Files
- Entry point: {entry_file}
- Config: {config_files}
- Tests: {test_directory}

## Session Notes

{Previous session notes if any}

## Quick Commands

Load skills

source .agent-skills/mcp-shell-config.sh

Query skill

skill-query "your query"

Check MCP status

mcp-status

Step 5: Auto-Load on Session Start

Add to .claude/commands.json (if supported):

{
  "on_session_start": [
    "read .claude/project-memory.json",
    "apply skillset configuration",
    "load project context"
  ]
}

Step 6: Update Memory on Changes

When skills are added/removed or configuration changes:

interface ProjectMemory {
  version: string;
  initialized: string;
  lastUpdated: string;
  skillset: {
    source: string;
    categories: string[];
    active_skills: string[];
    token_mode: 'toon' | 'compact' | 'full';
  };
  environment: {
    workflow_type: string;
    mcp_servers: string[];
    performance_preset: string;
  };
  project_context: {
    name: string;
    type: string;
    primary_language: string;
    frameworks: string[];
  };
  session_history: {
    timestamp: string;
    action: string;
    notes?: string;
  }[];
}

function updateMemory(memory: ProjectMemory, changes: Partial<ProjectMemory>): ProjectMemory {
  return {
    ...memory,
    ...changes,
    lastUpdated: new Date().toISOString(),
    session_history: [
      ...memory.session_history,
      {
        timestamp: new Date().toISOString(),
        action: 'configuration_update',
        notes: JSON.stringify(changes)
      }
    ]
  };
}

Examples

Example 1: First Time Project Init

# User opens project for first time
# AI Agent should:

# 1. Check for existing config
if [ ! -f ".claude/project-memory.json" ]; then
    echo "No existing configuration found. Initializing..."
    
    # 2. Detect project type
    if [ -f "package.json" ]; then
        PROJECT_TYPE="nodejs"
        PRIMARY_LANG="typescript"
    elif [ -f "requirements.txt" ]; then
        PROJECT_TYPE="python"
        PRIMARY_LANG="python"
    fi
    
    # 3. Setup skills
    if [ -d ".skills-template/.agent-skills" ]; then
        cd .skills-template/.agent-skills && ./setup.sh --silent
    fi
    
    # 4. Create memory file
    mkdir -p .claude
    cat > .claude/project-memory.json << 'EOF'
{
  "version": "1.0.0",
  "initialized": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "skillset": {
    "source": ".skills-template/.agent-skills",
    "token_mode": "toon"
  }
}
EOF
    
    echo "Project initialized!"
fi

Example 2: Session Restoration

# AI Agent detects existing memory
if [ -f ".claude/project-memory.json" ]; then
    echo "Found project memory. Restoring session..."
    
    # Read memory
    MEMORY=$(cat .claude/project-memory.json)
    
    # Extract skillset source
    SKILLSET_SOURCE=$(echo $MEMORY | jq -r '.skillset.source')
    
    # Load skills
    if [ -f "$SKILLSET_SOURCE/mcp-shell-config.sh" ]; then
        source "$SKILLSET_SOURCE/mcp-shell-config.sh"
    fi
    
    # Show session summary
    echo "=== Session Restored ==="
    echo "Skillset: $SKILLSET_SOURCE"
    echo "Token Mode: $(echo $MEMORY | jq -r '.skillset.token_mode')"
    echo "Last Updated: $(echo $MEMORY | jq -r '.lastUpdated')"
fi

Example 3: Multi-Project Switching

# When switching between projects, save current context
save_project_context() {
    local project_path="$1"
    
    # Save current session notes
    cat >> "$project_path/.claude/project-memory.json" << EOF
{
  "session_history": [{
    "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
    "action": "session_pause",
    "notes": "Switching to another project"
  }]
}
EOF
}

# When returning to project
restore_project_context() {
    local project_path="$1"
    
    if [ -f "$project_path/.claude/project-memory.json" ]; then
        echo "Welcome back! Restoring your previous context..."
        # Load and apply saved configuration
    fi
}

Best practices

1. Always Check First: Before initializing, check if configuration exists

- Prevents overwriting user customizations - Respects existing project setup

1. Use toon Mode by Default: 95% token savings

- Switch to full mode only when detailed instructions needed - Compact mode for balanced approach

1. Version Your Memory: Include version in memory file

- Enables migration when format changes - Backward compatibility support

1. Session History Rotation: Keep last 50 sessions

- Prevents unbounded growth - Maintains useful context

1. Sensitive Data Handling: Never store secrets in memory

- Use .gitignore for .claude/project-memory.json if contains local paths - Reference external secret managers

Common pitfalls

• Overwriting User Config: Always check before writing
• Stale Memory: Update timestamp on every session
• Missing Skillset: Gracefully handle when .agent-skills not found
• Permission Issues: Ensure .claude directory is writable

Troubleshooting

Issue 1: Memory File Not Loading

Symptoms: Skills not auto-loading, context lost between sessions Cause: Missing .claude directory or corrupted JSON Solution:

# Recreate memory
mkdir -p .claude
rm -f .claude/project-memory.json
# Re-run initialization

Issue 2: Wrong Skillset Loaded

Symptoms: Unexpected skills or missing expected skills Cause: skillset.source path changed or moved Solution:

# Update source path in memory
cat .claude/project-memory.json | jq '.skillset.source = ".agent-skills"' > tmp.json
mv tmp.json .claude/project-memory.json

Issue 3: Token Mode Not Applied

Symptoms: Full SKILL.md loaded instead of toon Cause: token_mode not being read correctly Solution:

# Verify token mode setting
cat .claude/project-memory.json | jq '.skillset.token_mode'
# Force update
cat .claude/project-memory.json | jq '.skillset.token_mode = "toon"' > tmp.json
mv tmp.json .claude/project-memory.json

Output format

Initialization Output

=== Project Init Memory ===
Status: Initialized
Project: {project_name}
Skillset: {source_path}
Token Mode: toon
MCP Servers: gemini-cli, codex-cli
Workflow: full-multiagent

Next Steps:
1. Run `source .agent-skills/mcp-shell-config.sh`
2. Use `skill-query` to find relevant skills
3. Configuration saved to .claude/project-memory.json

Session Restore Output

=== Session Restored ===
Project: {project_name}
Last Active: {timestamp}
Skills Loaded: {count} skills
Token Mode: toon
Session #: {session_number}

Recent Activity:
- {recent_action_1}
- {recent_action_2}

Constraints

MUST

1. Check for existing configuration before initializing
2. Preserve user customizations when updating
3. Use ISO 8601 timestamps
4. Include version number in memory file

MUST NOT

1. Store secrets or credentials in memory file
2. Overwrite without backup
3. Delete user's session history
4. Modify files outside .claude directory without explicit request

References

• Claude Code Documentation
• Agent Skills Specification
• MCP Protocol

Metadata

Version

• Current Version: 1.0.0
• Last Updated: 2026-01-16
• Compatible Platforms: Claude, ChatGPT, Gemini

Related Skills

• environment-setup
• skill-standardization
• mcp-codex-integration

Tags

#project-init #memory #skillset #configuration #automation #claude-code