initializing-memory

name	initializing-memory
description	Comprehensive guide for initializing or reorganizing agent memory into a deeply hierarchical file structure. Use when running /init, when user asks to set up memory, or when memory needs a major reorganization. Trigger phrases: "initialize memory", "set up memory", "populate memory", "build my memory", "memory init".

Memory Initialization

Initialize persistent memory into a deeply hierarchical structure of 15-25 small, focused files in .pi/memory/.

Run /init again after major project changes or when you want to re-analyze.

Target Output

Metric	Target
Total files	15-25 (aim for ~20)
Max lines per file	~40 (split if larger)
Hierarchy depth	2-3 levels using / naming
Nesting requirement	Every file MUST be nested under a parent

Anti-patterns:

• ❌ Only 3-5 large files
• ❌ Flat naming (all files at top level)
• ❌ Mega-files with 10+ sections

Example Target Structure

system/
├── human/
│   ├── identity.md
│   ├── context.md
│   └── prefs/
│       ├── communication.md
│       ├── coding_style.md
│       └── workflow.md
├── project/
│   ├── overview.md
│   ├── architecture.md
│   ├── conventions.md
│   ├── gotchas.md
│   └── tooling/
│       ├── testing.md
│       └── linting.md
└── persona/
    ├── role.md
    └── behavior.md
reference/
├── README.md
└── history/
    └── decisions.md

What to Remember

1. Procedures (Rules & Workflows)

• Commit conventions, branching strategy
• Build/test/lint commands and order
• Review process, CI requirements

2. Preferences (Style & Conventions)

• Coding style rules (formatting, patterns, anti-patterns)
• Communication preferences (terse vs detailed)
• Tool preferences (which tools, how to use them)

3. History & Context

• Key refactors, past bugs, architectural decisions
• Project evolution, deprecated patterns
• Ongoing work and current priorities

Workflow

Step 1: Backup existing memory

Use memory_backup tool first if memory already has content.

Step 2: Ask upfront questions (bundle in one message)

1. Research depth: Standard (~5-20 tool calls) or deep (~100+)?
2. Identity: Which contributor are you? (check git context from /init)
3. Related repos: Other repositories you should know about?
4. Historical sessions: If prior agent sessions were detected, ask: "I found prior Claude Code / Pi / Codex sessions. Should I analyze them to learn your preferences and project context?"
5. Communication: Terse or detailed responses?
6. Rules: Any rules I should always follow?

Don't ask things you can find by reading files. Be autonomous during execution.

Step 3: Research the project

Standard research:

• README, AGENTS.md, CLAUDE.md, CONTRIBUTING.md
• Package manifests (package.json, Cargo.toml, pyproject.toml, go.mod)
• Config files (tsconfig, eslint, prettier, etc.)
• git log --oneline -20 — recent history
• git log --format="%s" -50 | head -20 — commit conventions
• Explore key directories and understand structure

Deep research (if chosen):

• Everything above, plus:
• git shortlog -sn --all | head -10 — contributors
• git branch -a — branching strategy
• git log --format="%an <%ae>" | sort -u — deduplicate contributors by email
• Deep dive into architecture, patterns, CI config
• Analyze multiple source directories
• Read key source files to understand patterns
• Cross-reference findings, resolve ambiguities

Think like a new team member: What would you want to know on your first day?

Step 4: Analyze prior sessions (if approved)

If the user approved session history analysis:

Claude Code sessions (~/.claude/projects/):

• Each project dir contains session JSONL files
• Look for the project matching the current working directory
• Extract: user preferences, communication style, project knowledge, conventions

Pi sessions (~/.pi/agent/sessions/):

• Session directories named by project path
• Read recent session files for patterns and preferences

Codex sessions (~/.codex/):

• history.jsonl contains session history
• Extract coding preferences, project context

Focus on extracting:

• User identity and preferences → system/human/
• Behavioral rules discovered → system/persona/
• Project knowledge → system/project/
• Working patterns → system/human/prefs/

Step 5: Create hierarchical file structure

Use memory_write for each file. Every file needs:

• Proper frontmatter (description, limit)
• Hierarchical / naming (e.g. system/project/tooling/testing.md)
• Focused, single-purpose content (~40 lines max)

Write findings as you go — don't wait until the end.

Memory scope guide:

• system/ (always in context): Active preferences, project conventions, agent behavior
• reference/ (on-demand): Historical info, archived decisions, detailed reference

Step 6: Checkpoint

find .pi/memory/system -name '*.md' | wc -l

If count < 15, split more aggressively.

Step 7: Reflect and review

Before finishing, verify:

• 15-25 files total
• All files use / naming (2-3 levels deep)
• No file exceeds ~40 lines
• Each file has one concept
• Every file has real content (no placeholders)
• human/ updated with user identity + preferences
• persona/ updated with behavioral rules
• No redundancy across files

Ask the user: "I've completed initialization with N files. Want me to refine anything?"

Step 8: Commit and sync

memory_commit({ message: "init: populate memory with N files from project research" })

If a remote is configured, push: git -C .pi/memory push

Writing Good Memory Files

Descriptions are critical — write as if explaining to a future self with zero context:

• ✅ "User's coding style preferences applied to all code I write or review"
• ❌ "Preferences"

Content should be:

• Well-organized with headers and bullets
• Scannable at a glance
• Pruned of outdated info
• Concrete and actionable