project-init-memory skill

---
name: project-init-memory
description: Automatically remember and apply skillset configuration when first running a project. Use when initializing projects in .skills-template or any project requiring consistent AI agent setup. Handles CLAUDE.md generation, skill loading, and environment persistence.
tags: [project-init, memory, skillset, configuration, automation, claude-code]
platforms: [Claude, ChatGPT, Gemini]
allowed_tools: [Read, Write, Edit, Glob, Grep, Bash]
---

# 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

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

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

```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

```markdown
# 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:

```typescript
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

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

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

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

2. **Use toon Mode by Default**: 95% token savings
   - Switch to full mode only when detailed instructions needed
   - Compact mode for balanced approach

3. **Version Your Memory**: Include version in memory file
   - Enables migration when format changes
   - Backward compatibility support

4. **Session History Rotation**: Keep last 50 sessions
   - Prevents unbounded growth
   - Maintains useful context

5. **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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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](https://docs.anthropic.com/en/docs/claude-code)
- [Agent Skills Specification](https://agentskills.io/specification)
- [MCP Protocol](https://modelcontextprotocol.io/)

## Metadata

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

### Related Skills
- [environment-setup](../environment-setup/SKILL.md)
- [skill-standardization](../skill-standardization/SKILL.md)
- [mcp-codex-integration](../mcp-codex-integration/SKILL.md)

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