Project Memory Store

What this skill does

# Project Memory Store

**⚠️ EXECUTION CONTEXT**: This Skill MUST be executed using Task tool with subagent_type="general-purpose". Runs in separate context to avoid polluting main conversation.

**Purpose**: Extract and store **project-specific insights** (episodic/procedural/semantic) into file-based memory at `.claude/skills/project-memory-store/`.

**Key Architecture**: This SKILL.md + subdirectory README.md files form a **tree guideline structure** for progressive disclosure - overview at top, details deeper. This is very effective for information retrieval.

**Keep SKILL.md lean**: Provide overview and reference other files. When this file becomes unwieldy, split content into separate files and reference them. Trust Claude to read detailed files only when needed.

**When to Use**:
- After making significant architecture decisions for THIS project
- When discovering project-specific patterns or configurations
- User explicitly says "--project-store" or "--learn" (Claude decides if universal or project-specific, may use both)
- Completed tasks revealing important domain logic or codebase structure

**CRITICAL**: Store BOTH successful AND failed trajectories. Failures are equally important - often MORE valuable than successes. Failed approaches in this project teach what NOT to do and why.

**When NOT to Use**:
- Universal patterns applicable to any project (use coder-memory-store)
- Routine tasks or obvious conventions
- Standard debugging without project-specific learnings

**Selection Criteria**: Most conversations yield 0-1 project-specific insights. Focus on details future work on THIS codebase would benefit from.

---

## PHASE 0: Initialize Memory Structure

Check if memory directories exist at `.claude/skills/project-memory-store/`:
- `episodic/` - Concrete events in this project
- `procedural/` - Project-specific workflows
- `semantic/` - Project patterns and principles

If missing, create directories and initialize each with single file:
- `episodic/episodic.md`
- `procedural/procedural.md`
- `semantic/semantic.md`

Update `SKILL.md` (this file) as needed when structure changes - modify ANY part to keep it accurate and useful.

---

## PHASE 1: Extract Project-Specific Insights

Analyze conversation and extract **0-3 insights** (most yield 0-1).

**Classify each as**:
- **Episodic**: Concrete events in THIS project (debugging specific module, implementing feature)
- **Procedural**: Project-specific workflow (how we deploy, how we test this codebase)
- **Semantic**: Project patterns (architecture decisions, domain-specific approaches)

**Extraction Criteria** (ALL must be true):
1. **Project-specific**: Applies to THIS particular codebase/domain
2. **Non-obvious**: Not already in documentation or README
3. **Actionable**: Provides concrete guidance for future work on this project
4. **Important**: Worth remembering for long-term maintenance

**Reject**:
- Universal patterns (use coder-memory-store)
- Routine work
- Obvious conventions already documented

---

## PHASE 2: Search for Similar Memories

For each extracted insight:

**Step 1: Determine target memory type** (episodic/procedural/semantic)

**Step 2 (Optional): Try Vector Search First**

**If Qdrant MCP server available**, try semantic search for similar memories:

1. **Construct query** from new memory - Use full formatted memory for better matching:
   - Use: Title + Description + Content (the complete formatted memory text)
   - This gives embedding model sufficient context for semantic similarity (including project-specific details)

2. **Call search_memory** MCP tool:
   ```
   search_memory(
       query="<full formatted memory text>",
       memory_level="project",
       limit=5
   )
   ```
3. **Extract file_path hints** and similarity scores
4. **If <3 results or tool unavailable**: Continue to file-based search below

**IMPORTANT**: Vector results may be outdated. Use as hints to guide file search, not as absolute truth.

---

**Step 3: File-Based Search (Primary Method)**
- Use Grep to search for keywords across project memory files (prioritize hinted paths if available)
- Search in target memory type directory (e.g., `.claude/skills/project-memory-store/episodic/`)
- Look for similar titles, tags, project components, or core concepts
- Read files with potential matches

**Step 4: Check similarity**
- If found similar content: Read full context
- Determine if: Duplicate, Related, or Different

---

## PHASE 3: Consolidation Decision

**Decision Matrix** (file-based consolidation):

| Similarity | Action | Rationale |
|-----------|--------|-----------|
| **Duplicate/Very Similar** | **MERGE** | Combine into single stronger entry |
| **Related (same topic)** | **UPDATER** | Update existing memory with new information |
| **Pattern Emerges** | **GENERALIZE** | Extract pattern → promote episodic to semantic |
| **Different** | **CREATE** | New file or separate section |

**Actions**:

**MERGE** (duplicate or very similar):
- Combine both memories into single, stronger entry
- Eliminate redundancy, keep unique project-specific details from both
- If contradictory: Add "**Previous Approach:**" and tag #reconsolidated
- Update in existing file

**UPDATER** (related, same topic):
- Update existing memory with new information
- If extends existing: Add new details inline with note "**Updated [date]:**"
- If alternative approach: Add separate entry in same file with cross-reference
- If contradicts: Add "**Previous approach:**" to show evolution of understanding

**GENERALIZE** (pattern emerges from multiple episodic memories):
- Extract common pattern from 2+ similar episodic entries in THIS project
- Create/update semantic memory with the generalized project-specific pattern
- Reference episodic examples in semantic entry
- Tag episodic entries with reference to semantic pattern
- This is how learning happens: specific experiences → general principles
- **Check universality**: If pattern applies beyond this project, also invoke coder-memory-store

**CREATE** (different topic):
- Store in new location (new file or different section)
- Update README.md to reference new content

---

## PHASE 4: Store Memory

**CRITICAL: Use COMPACT format to prevent memory bloat. Each memory = 3-5 sentences MAX.**

**Universal Format** (works for ALL memory types):
```
**Title:** <concise title>
**Description:** <one sentence summary>

**Content:** <3-5 sentences covering: what happened in this project, what was tried (including failures), what worked/failed, key lesson, relevant files/components>

**Tags:** #tag1 #tag2 #success OR #failure
```

**Formatting Rules**:
- NO blank line between Title and Description
- ONE blank line before Content
- ONE blank line before Tags
- Content MUST be 3-5 sentences (not paragraphs, not lists, not verbose sections)
- Include project-specific file paths and components in Content
- Include both failures and successes if relevant
- Tag episodic memories with #episodic, procedural with #procedural, semantic with #semantic

**Determine storage location**:
1. **Read README.md** (if exists) in target memory type directory
2. **Decide based on consolidation action**:
   - MERGE/UPDATER: Modify existing file
   - GENERALIZE: Update semantic/ or create new semantic file
   - CREATE: New file or new section
3. **Max depth**: 2 levels (e.g., `episodic/authentication/` is deepest)

**Execute storage**:
1. **Write to file (Source of Truth)**:
   - Write formatted memory to file (merge, update, generalize, or create)
   - File write is PRIMARY - must succeed

2. **Optional: Dual-Write to Qdrant**:

   **If Qdrant MCP server available**, also store to vector database:

   ```
   store_memory(
       document="<full formatted memory text>",
       metadata={
           "memory_level": "project",
           "memory_type": "<episodic|procedural|semantic>",
           "file_path": "<relative path from project-memory-store/>",
           "skill_root": "project-memory-store",