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

```bash
# 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):

```json
{
  "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

Always Check First: Before initializing, check if configuration exists
- Prevents overwriting user customizations
- Respects existing project setup
Use toon Mode by Default: 95% token savings
- Switch to full mode only when detailed instructions needed
- Compact mode for balanced approach
Version Your Memory: Include version in memory file
- Enables migration when format changes
- Backward compatibility support
Session History Rotation: Keep last 50 sessions
- Prevents unbounded growth
- Maintains useful context
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}

project-init-memory