---
name: initiate-memory
description: Comprehensive guide for initializing or reorganizing agent memory and project context. Use when setting up a new project, when the user asks you to learn about the codebase, or when you need to create effective memory blocks for project conventions, preferences, and workflows.
---

# Initializing Memory

The user has requested that you initialize or reorganize your memory state for this project. This skill helps you systematically explore and document a codebase to build effective working memory.

## Understanding Your Context

**Important**: This skill is designed for stateful agents that work with users over extended periods. Your memory is not just a convenience; it's how you get better over time and maintain continuity across sessions.

This command may be run in different scenarios:

- **Fresh project**: Starting work on a new codebase
- **Existing project**: User wants you to reorganize or significantly update your understanding
- **Deep dive**: User wants comprehensive analysis of the project

Before making changes, inspect your current context and understand what already exists.

## What to Remember About a Project

### 1. Procedures (Rules & Workflows)

Explicit rules and workflows that should always be followed:

- "Never commit directly to main - always use feature branches"
- "Always run lint before running tests"
- "Use conventional commits format for all commit messages"
- "Always check for existing tests before adding new ones"

### 2. Preferences (Style & Conventions)

User and project coding style preferences:

- "Never use try/catch for control flow"
- "Always add JSDoc comments to exported functions"
- "Prefer functional components over class components"
- "Use early returns instead of nested conditionals"

### 3. History & Context

Important historical context that informs current decisions:

- "We fixed this exact pagination bug two weeks ago - check PR #234"
- "This monorepo used to have 3 modules before the consolidation"
- "The auth system was refactored in v2.0 - old patterns are deprecated"

## Memory Scope Considerations

Consider whether information is:

**Project-scoped**:

- Build commands, test commands, lint configuration
- Project architecture and key directories
- Team conventions specific to this codebase
- Technology stack and framework choices

**User-scoped**:

- Personal coding preferences that apply across projects
- Communication style preferences
- General workflow habits

**Session/Task-scoped**:

- Current branch or ticket being worked on
- Debugging context for an ongoing investigation
- Temporary notes about a specific task

## Recommended Memory Structure

### Core Information Categories

**Project Overview**: Your behavioral guidelines and project purpose

- Technology stack and architecture
- Key directories and their purposes
- Build/test/lint commands

**Conventions**: Project-specific rules and patterns

- Commit message format
- Code style preferences
- PR process and review guidelines

**User Preferences**: User-specific information

- Communication style preferences
- Cross-project preferences
- Working style and habits

### Optional Categories (Create as Needed)

**Current Task**: Scratchpad for current work item context

- Ticket ID, branch name, PR number
- Relevant links and context
- Current focus area

**Decisions**: Architectural decisions and their rationale

- Why certain approaches were chosen
- Trade-offs that were considered

## Research Depth

You can ask the user if they want a standard or deep research initialization:

**Standard initialization** (~5-20 tool calls):

- Scan README, package.json/config files, AGENTS.md, CLAUDE.md
- Review git status and recent commits
- Explore key directories and understand project structure
- Create/update your memory to contain the essential information

**Deep research initialization** (~100+ tool calls):

- Everything in standard initialization, plus:
- Use TodoWrite to create a systematic research plan
- Deep dive into git history for patterns, conventions, and context
- Analyze commit message conventions and branching strategy
- Explore multiple directories and understand architecture thoroughly
- Search for and read key source files to understand patterns

**What deep research can uncover:**

- **Contributors & team dynamics**: Who works on what areas? Who are the main contributors?
- **Coding habits**: When do people commit? What's the typical commit size?
- **Writing & commit style**: How verbose are commit messages? What conventions are followed?
- **Code evolution**: How has the architecture changed? What major refactors happened?
- **Pain points**: What areas have lots of bug fixes? What code gets touched frequently?

## Research Techniques

**File-based research:**

- README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md
- Package manifests (package.json, Cargo.toml, pyproject.toml, go.mod)
- Config files (.eslintrc, tsconfig.json, .prettierrc)
- CI/CD configs (.github/workflows/, .gitlab-ci.yml)

**Git-based research** (if in a git repo):

- `git log --oneline -20` - Recent commit history and patterns
- `git branch -a` - Branching strategy
- `git log --format="%s" -50 | head -20` - Commit message conventions
- `git shortlog -sn --all | head -10` - Main contributors
- Recent PRs or merge commits for context on ongoing work

## How to Do Thorough Research

**Don't just collect data - analyze and cross-reference it.**

Shallow research (bad):

- Run commands, copy output
- Take everything at face value
- List facts without understanding

Thorough research (good):

- **Cross-reference findings**: If two pieces of data seem inconsistent, dig deeper
- **Resolve ambiguities**: Don't leave questions unanswered
- **Read actual content**: Don't just list file names - read key files to understand them
- **Look for patterns**: What do the commit messages tell you about workflow?
- **Form hypotheses and verify**: "I think this team uses feature branches" → check git branch patterns
- **Think like a new team member**: What would you want to know on your first day?

**Questions to ask yourself during research:**

- Does this make sense?
- What's missing?
- What can I infer?
- Am I just listing facts, or do I understand the project?

The goal isn't to produce a report - it's to genuinely understand the project and how to be an effective collaborator.

## Recommended Questions to Ask

Bundle these questions together when starting:

1. **Research depth**: "Standard or deep research (comprehensive, as long as needed)?"
2. **Identity**: "Which contributor are you?" (You can often infer from git logs)
3. **Related repos**: "Are there other repositories I should know about?"
4. **Communication style**: "Terse or detailed responses?"
5. **Any specific rules**: "Rules I should always follow?"

**What NOT to ask:**

- Things you can find by reading files ("What's your test framework?")
- Permission for obvious actions - just do them
- Questions one at a time - bundle them

## Your Task

1. **Ask upfront questions**: Bundle the recommended questions above
2. **Inspect existing context**: See what already exists in AGENTS.md, README, etc.
3. **Identify the user**: From git logs and their answers
4. **Research the project**: Explore based on chosen depth. Use TodoWrite for a systematic plan.
5. **Document findings**: Create notes or update project documentation
6. **Reflect and review**: Check for completeness and quality
7. **Ask user if done**: Check if they're satisfied or want you to continue

## Reflection Phase

Before finishing, do a reflection step:

1. **Completeness check**: Did you gather all relevant information?
2. **Quality check**: Are there gaps or unclear areas?
3. **Structure check**: Would this information make sense to your future self?

**After reflection**, summarize what you learned:

> "I've completed the initialization. Here's a brief summary of what I set up: [summary]. Should I continue refining, or is this good to proceed?"

Remember: Good memory management is an investment. The effort you put into organizing your knowledge now will pay dividends as you work with this user over time.