> ## Documentation Index
> Fetch the complete documentation index at: https://ulpi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Integration

> How pre-compact hooks preserve critical context automatically through memory snapshots

# Never Lose Context Again: Pre-Compact Memory Snapshots

**The most frustrating moment in AI conversations: Claude compacts your context and forgets everything important.**

That architecture decision you spent 30 minutes discussing? **Gone.**
The specific conventions for your codebase? **Forgotten.**
The active tasks and pending obligations? **Lost.**

**ULPI's pre-compact hook solves this.** Before Claude compresses conversation history, the hook automatically creates a memory snapshot of everything that matters.

**Result: 100% context preservation across sessions.**

***

## The Problem: Context Compaction Amnesia

###

Without Pre-Compact Hooks

<Tabs>
  <Tab title="The Scenario">
    **Long conversation with Claude Code:**

    * 9:00 AM: Discuss authentication architecture
      * Decided on OAuth 2.0 with JWT tokens
      * Custom session management approach
      * Specific error handling pattern

    * 10:30 AM: Implement login function
      * 200 lines of code written
      * Tests added
      * Edge cases discussed

    * 12:00 PM: Context approaching token limit (200K tokens)
      * Claude shows warning: "Context will be compacted soon"
      * You continue working...

    * 12:15 PM: **COMPACTION HAPPENS**
      * Claude compresses conversation to free tokens
      * Removes "less important" parts
      * Keeps recent code but loses rationale

    * 12:30 PM: You ask: "Why did we choose OAuth over session cookies?"
      * Claude: "I don't have that information in our current context. Can you remind me?"

    **YOU JUST EXPLAINED THIS 3 HOURS AGO.**
  </Tab>

  <Tab title="What Gets Lost">
    ### Common Context Losses

    **Architecture Decisions:**

    * Why we chose technology X over Y
    * Tradeoffs discussed
    * Future considerations

    **Code Conventions:**

    * Naming patterns specific to your project
    * Error handling approaches
    * Testing strategies

    **Active Context:**

    * Which tasks are in progress
    * Pending code reviews
    * Known issues and workarounds

    **Relationships:**

    * How different parts of codebase connect
    * Dependencies between features
    * Integration points

    ### The Impact

    * **Re-explanation time:** 15-30 minutes per compaction
    * **Compaction frequency:** Every 2-3 hours in long sessions
    * **Weekly waste:** 3-5 hours explaining things Claude already knew
    * **Annual cost:** 150-250 hours of lost productivity
  </Tab>

  <Tab title="Current Workarounds">
    ### What People Try (And Why It Fails)

    **1. "Put it in a file"**

    ```markdown theme={null}
    # CONTEXT.md
    ## Architecture Decisions
    - OAuth because...
    - JWT tokens because...
    ```

    **Problem:** Claude won't read the file unless you explicitly tell it to load CONTEXT.md in every session. Also becomes stale quickly.

    **2. "Start a new chat"**

    **Problem:** Loses ALL context, not just compacted parts. Even worse than compaction.

    **3. "Copy-paste important parts before compaction"**

    **Problem:** You have to:

    * Predict what Claude will forget
    * Manually copy it somewhere
    * Remember to paste it back
    * Do this every 2-3 hours

    **None of these work well. You need automatic preservation.**
  </Tab>
</Tabs>

***

## The Solution: Automatic Memory Snapshots

### How Pre-Compact Hook Works

<Steps>
  <Step title="Detect Imminent Compaction">
    Claude Code (or your IDE) detects context approaching token limit:

    ```plaintext theme={null}
    ⚠️  Context Warning

    Current tokens: 185,000 / 200,000
    Compaction will occur soon

    ULPI Pre-Compact Hook: ACTIVE
    Critical context will be preserved automatically.
    ```
  </Step>

  <Step title="Pre-Compact Hook Fires">
    **BEFORE** compaction happens, the hook triggers:

    ```plaintext theme={null}
    🎣 Pre-Compact Hook Triggered

    Token usage: 195,000 / 200,000
    Time until compaction: ~30 seconds

    Analyzing conversation for critical context...
    ```
  </Step>

  <Step title="Intelligent Context Extraction">
    Hook uses AI to extract important context:

    **What it looks for:**

    * Architecture decisions and their rationale
    * Code patterns and conventions
    * Active tasks and their status
    * Pending obligations (reviews, acks, etc.)
    * Key insights and learnings
    * Critical code snippets

    **Salience scoring:** Each potential memory rated 0.0-1.0

    * 0.9-1.0: Critical (always save)
    * 0.7-0.9: Important (save)
    * 0.5-0.7: Moderate (save if space)
    * Below 0.5: Skip (not important enough)
  </Step>

  <Step title="Create Memory Snapshot">
    Hook stores high-salience memories to ULPI Memory:

    ```bash theme={null}
    # MCP Tool: store-memory (bulk insert)
    POST /api/memory/store-bulk
    {
      "memories": [
        {
          "content": "Chose OAuth 2.0 over session cookies because...",
          "type": "architecture_decision",
          "importance": 0.95,
          "tags": ["auth", "oauth", "architecture"]
        },
        {
          "content": "Error handling pattern: wrap in try-catch, log to Winston...",
          "type": "code_convention",
          "importance": 0.85,
          "tags": ["error-handling", "conventions"]
        },
        // ... more memories
      ]
    }
    ```
  </Step>

  <Step title="Compaction Proceeds Safely">
    Hook returns exit code `0` → Compaction allowed:

    ```plaintext theme={null}
    ✓ Memory Snapshot Created

    Saved to ULPI Memory:
    - 12 architecture decisions
    - 8 code conventions
    - 3 active tasks
    - 5 pending obligations
    - 14 key insights

    Total: 42 memories preserved

    Compaction can now proceed safely.
    ```

    Claude compacts conversation, but critical context is saved.
  </Step>

  <Step title="Next Session: Auto-Load Memories">
    When you start a new session, **session-start hook** automatically loads relevant memories:

    ```plaintext theme={null}
    🧠 Loading Relevant Memories

    Project: my-auth-project
    Loaded 47 memories:
    - 12 architecture decisions
    - 8 code conventions
    - 3 active tasks (resumed)
    - 24 insights and patterns

    Claude now has context from previous sessions.
    ```

    **YOU DON'T HAVE TO RE-EXPLAIN ANYTHING.**
  </Step>
</Steps>

***

## What Gets Preserved

### Memory Types

<CardGroup cols={2}>
  <Card title="Architecture Decisions" icon="compass-drafting" color="#8b5cf6">
    **Examples:**

    * "We chose PostgreSQL over MongoDB because..."
    * "Microservices pattern instead of monolith due to..."
    * "REST over GraphQL for this project because..."

    **Salience:** Typically 0.9-1.0 (very high)

    **Why important:** These guide all future development
  </Card>

  <Card title="Code Conventions" icon="code" color="#3b82f6">
    **Examples:**

    * "Use camelCase for functions, PascalCase for classes"
    * "Error handling: always wrap in try-catch, log to Winston"
    * "Testing: Jest, minimum 80% coverage"

    **Salience:** 0.8-0.9 (high)

    **Why important:** Ensures consistency across codebase
  </Card>

  <Card title="Active Tasks" icon="check-square" color="#10b981">
    **Examples:**

    * "Implementing OAuth login (60% complete)"
    * "Refactoring auth module (started, 3 files done)"
    * "Adding rate limiting middleware (planned)"

    **Salience:** 0.8-0.95 (high)

    **Why important:** Can resume exactly where you left off
  </Card>

  <Card title="Pending Obligations" icon="bell" color="#f59e0b">
    **Examples:**

    * "Code review required for auth.ts changes"
    * "Security audit needed before deployment"
    * "Alice requested collaboration on user model"

    **Salience:** 0.9-1.0 (very high)

    **Why important:** Don't forget commitments
  </Card>

  <Card title="Key Insights" icon="lightbulb" color="#eab308">
    **Examples:**

    * "Performance bottleneck in N+1 queries"
    * "Discovered better pattern for async error handling"
    * "Caching strategy reduces DB load by 80%"

    **Salience:** 0.7-0.9 (moderate to high)

    **Why important:** Learnings that improve future work
  </Card>

  <Card title="Code Snippets" icon="brackets-curly" color="#06b6d4">
    **Examples:**

    * Reusable utility functions
    * Complex regex patterns
    * Configuration templates

    **Salience:** 0.6-0.8 (moderate)

    **Why important:** Avoid reinventing the wheel
  </Card>
</CardGroup>

***

## Salience Scoring: How It Works

### Automatic Importance Detection

The pre-compact hook uses AI to score each potential memory:

```typescript theme={null}
interface SalienceFactors {
  // Content characteristics
  isDecision: boolean;        // Architecture or design decision?
  isConvention: boolean;      // Code pattern or standard?
  isInsight: boolean;         // New learning or discovery?

  // Context signals
  discussionLength: number;   // How long was this discussed?
  userEmphasis: boolean;      // Did user say "important" or "remember"?
  repetition: number;         // How many times mentioned?

  // Impact indicators
  affectsMultipleFiles: boolean;  // Impacts many parts of codebase?
  breakingChange: boolean;         // Changes existing behavior?
  securityRelated: boolean;        // Security implication?

  // Temporal factors
  recentlyDiscussed: boolean;     // Discussed in last hour?
  activeTask: boolean;             // Related to current work?
}
```

### Scoring Examples

<AccordionGroup>
  <Accordion title="High Salience (0.9-1.0): Architecture Decision">
    **Conversation excerpt:**

    ```
    User: "Should we use OAuth or session cookies for authentication?"

    Claude: "For your use case, I recommend OAuth 2.0 with JWT tokens because:
    1. You need mobile app support (cookies don't work well)
    2. Microservices architecture requires stateless auth
    3. Third-party integrations planned (OAuth is standard)"

    User: "Great point about mobile. Let's go with OAuth. This is important
          for the whole project architecture."
    ```

    **Salience factors:**

    * ✅ isDecision: true
    * ✅ discussionLength: 5 messages
    * ✅ userEmphasis: "important for whole project"
    * ✅ affectsMultipleFiles: true (architecture choice)
    * ✅ securityRelated: true

    **Score: 0.95** → Definitely saved
  </Accordion>

  <Accordion title="High Salience (0.8-0.9): Code Convention">
    **Conversation excerpt:**

    ```
    User: "How should we handle errors in this codebase?"

    Claude: "Based on your existing code, I see a pattern:
    - All async functions wrapped in try-catch
    - Errors logged with Winston logger
    - User-facing errors return { success: false, error: message }
    - System errors return 500 with generic message"

    User: "Yes, that's our standard. Always follow this pattern."
    ```

    **Salience factors:**

    * ✅ isConvention: true
    * ✅ userEmphasis: "always follow this"
    * ✅ affectsMultipleFiles: true
    * ✅ repetition: 3 (discussed multiple times)

    **Score: 0.85** → Saved
  </Accordion>

  <Accordion title="Moderate Salience (0.6-0.8): Useful Insight">
    **Conversation excerpt:**

    ```
    User: "The database queries are slow. Any ideas?"

    Claude: "I see N+1 query problem in your user loading:
    - Each user triggers separate query for posts
    - Solution: Use eager loading with JOIN
    - Performance improvement: 500ms → 50ms"

    User: "Nice catch! Let's implement that."
    ```

    **Salience factors:**

    * ✅ isInsight: true
    * ✅ discussionLength: 3 messages
    * ⚠️  affectsMultipleFiles: false (one query)
    * ✅ recentlyDiscussed: true

    **Score: 0.75** → Saved
  </Accordion>

  <Accordion title="Low Salience (0.3-0.5): Routine Exchange">
    **Conversation excerpt:**

    ```
    User: "What's the syntax for array map in JavaScript?"

    Claude: "array.map(item => item * 2)"

    User: "Thanks"
    ```

    **Salience factors:**

    * ❌ isDecision: false
    * ❌ isConvention: false
    * ❌ isInsight: false (basic syntax question)
    * ❌ discussionLength: 2 messages
    * ❌ userEmphasis: none

    **Score: 0.35** → NOT saved (generic knowledge)
  </Accordion>
</AccordionGroup>

***

## Configuration

### Customize Pre-Compact Behavior

```json ~/.ulpi/config.json theme={null}
{
  "hooks": {
    "preCompact": {
      // Enable/disable the hook
      "enabled": true,

      // Create memory snapshot before compaction
      "createSnapshot": true,

      // Minimum salience to save (0.0-1.0)
      "minImportance": 0.5,

      // Include code snippets in memories
      "includeCode": true,

      // Maximum code snippet length (characters)
      "maxCodeLength": 500,

      // Include active task status
      "includeTasks": true,

      // Include pending obligations
      "includeObligations": true,

      // Memory types to save (filter)
      "saveTypes": [
        "architecture_decision",
        "code_convention",
        "insight",
        "active_task",
        "obligation",
        "code_snippet"
      ],

      // Maximum memories to save per snapshot
      "maxMemoriesPerSnapshot": 100,

      // Block compaction if snapshot fails
      "blockOnFailure": false
    }
  }
}
```

### Salience Threshold Tuning

**Recommended settings based on usage:**

<Tabs>
  <Tab title="Conservative (Save More)">
    ```json theme={null}
    {
      "minImportance": 0.4
    }
    ```

    **Effect:** Saves more memories, including moderately useful ones

    **Use when:**

    * You frequently need historical context
    * Working on complex projects with lots of decisions
    * Want comprehensive memory coverage

    **Tradeoff:** More memories = more storage, slightly slower session-start
  </Tab>

  <Tab title="Balanced (Default)">
    ```json theme={null}
    {
      "minImportance": 0.5
    }
    ```

    **Effect:** Saves important and very important memories

    **Use when:**

    * Standard development workflows
    * Want good balance of coverage and performance

    **Tradeoff:** Good middle ground
  </Tab>

  <Tab title="Aggressive (Save Less)">
    ```json theme={null}
    {
      "minImportance": 0.7
    }
    ```

    **Effect:** Only saves highly important memories

    **Use when:**

    * Quick scripts or one-off projects
    * Want minimal memory storage
    * Don't need extensive historical context

    **Tradeoff:** Might lose some useful context
  </Tab>
</Tabs>

***

## Integration with ULPI Memory

Pre-compact hooks are powered by ULPI Memory product:

### Memory Storage

**Where snapshots go:**

* Stored in ULPI Memory with vector embeddings
* Searchable via semantic similarity
* Tagged with project, timestamp, agent identity
* Automatically decayed based on relevance

### Memory Retrieval

**Session-start hook** automatically loads relevant memories:

```plaintext theme={null}
🧠 Memory Loading (Session Start)

Searching ULPI Memory for relevant context:
- Project: my-auth-project
- Agent: claude-code-yourname
- Timeframe: Last 30 days
- Min importance: 0.7

Found 47 relevant memories:
✓ Loaded 12 architecture decisions
✓ Loaded 8 code conventions
✓ Loaded 3 active tasks
✓ Loaded 24 insights

Injecting into Claude's context...
Done.
```

**You start every session with full context.**

### Cross-Session Continuity

**Example workflow:**

**Monday 9 AM:**

* Discuss OAuth architecture
* Implement login function
* Context compacted at noon
* **Pre-compact hook saves 15 memories**

**Monday 3 PM:**

* New session starts
* **Session-start hook loads OAuth memories**
* Continue implementing logout function
* Claude remembers OAuth decision without re-explanation

**Tuesday 9 AM:**

* Another new session
* **Session-start hook loads recent memories**
* Implement password reset
* Claude still remembers OAuth approach

**One week later:**

* **Memories still accessible**
* Can search: "Why did we choose OAuth?"
* Get instant answer from memory

***

## Real-World Examples

### Example 1: Architecture Decision Preservation

<Tabs>
  <Tab title="Without Pre-Compact Hook">
    **9:00 AM** - Discuss authentication approach

    ```
    User: "Should we use OAuth or session cookies?"

    Claude: [Long discussion about tradeoffs]

    Decision: OAuth 2.0 with JWT tokens
    Rationale: Mobile support, stateless, scalable
    ```

    **12:00 PM** - Context compacted

    **3:00 PM** - New session

    ```
    User: "Why did we choose OAuth again?"

    Claude: "I don't have that information in our current context.
             Could you remind me of the decision and rationale?"
    ```

    **YOU SPEND 15 MINUTES RE-EXPLAINING.**
  </Tab>

  <Tab title="With Pre-Compact Hook">
    **9:00 AM** - Discuss authentication approach

    ```
    User: "Should we use OAuth or session cookies?"

    Claude: [Long discussion about tradeoffs]

    Decision: OAuth 2.0 with JWT tokens
    Rationale: Mobile support, stateless, scalable
    ```

    **12:00 PM** - Context compacted

    **🎣 Pre-compact hook fires:**

    ```
    💾 Saving architecture decision to memory...
    ✓ Stored: "OAuth 2.0 choice and rationale" (salience: 0.95)
    ```

    **3:00 PM** - New session

    **🚀 Session-start hook loads memories:**

    ```
    🧠 Loaded: OAuth decision from this morning
    ```

    ```
    User: "Why did we choose OAuth again?"

    Claude: "We chose OAuth 2.0 with JWT tokens because:
             1. Your mobile app needs token-based auth (cookies don't work)
             2. Microservices architecture requires stateless authentication
             3. You plan third-party integrations (OAuth is standard)

             This decision was made this morning and affects the entire
             authentication architecture."
    ```

    **ZERO RE-EXPLANATION TIME.**
  </Tab>
</Tabs>

***

### Example 2: Code Convention Retention

<Tabs>
  <Tab title="Without Pre-Compact Hook">
    **Week 1** - Establish error handling pattern

    ```
    User: "How should we handle errors?"

    Claude: "Let's use this pattern:
    - try-catch around async functions
    - Log to Winston
    - Return { success, error } objects"

    User: "Perfect, use this everywhere."
    ```

    **Week 2** - Context compacted multiple times

    **Week 3** - New feature

    ```
    User: "Add error handling to the new login function"

    Claude: [Uses generic error handling, not project convention]

    User: "No, use our standard pattern!"

    Claude: "What's your standard pattern?"
    ```

    **YOU EXPLAIN AGAIN.**
  </Tab>

  <Tab title="With Pre-Compact Hook">
    **Week 1** - Establish error handling pattern

    ```
    User: "How should we handle errors?"

    Claude: "Let's use this pattern:
    - try-catch around async functions
    - Log to Winston
    - Return { success, error } objects"

    User: "Perfect, use this everywhere."
    ```

    **🎣 Pre-compact hook saves:**

    ```
    💾 Code convention stored (salience: 0.85)
    Type: error_handling_pattern
    Tags: ["conventions", "error-handling", "winston"]
    ```

    **Week 3** - New session, new feature

    **🚀 Session-start loads conventions:**

    ```
    🧠 Loaded: Error handling pattern
    ```

    ```
    User: "Add error handling to the new login function"

    Claude: [Applies project convention automatically]

    try {
      // login logic
    } catch (error) {
      logger.error('Login failed', error);
      return { success: false, error: 'Login failed' };
    }
    ```

    **CONVENTION APPLIED CORRECTLY WITHOUT REMINDER.**
  </Tab>
</Tabs>

***

## Performance

### Hook Execution Time

Pre-compact hook is the **slowest hook** (\~200ms), but this is acceptable:

**Why it's slower:**

* Must analyze entire conversation (large context)
* Extract and score potential memories (AI-powered)
* Store multiple memories to API (bulk insert)

**Why 200ms is acceptable:**

* Only fires every 2-3 hours (rare)
* Runs BEFORE compaction (not blocking user)
* Saves 15-30 minutes of re-explanation time
* **ROI: 200ms cost → 15 min savings = 4500x return**

### Memory Snapshot Size

**Typical snapshot:**

* 20-50 memories saved
* Each memory: 100-500 characters
* Total: \~20KB of text
* Storage cost: Negligible

**Large snapshot (major session):**

* 80-100 memories
* Total: \~50KB
* Still very small

***

## Best Practices

<AccordionGroup>
  <Accordion title="Mark important decisions explicitly" icon="bookmark">
    **Recommendation:** When making important decisions, say "This is important" or "Remember this"

    **Example:**

    ```
    User: "We're choosing PostgreSQL over MongoDB. This is important
          for the whole project architecture."
    ```

    **Effect:** Boosts salience score, ensures preservation
  </Accordion>

  <Accordion title="Review memories periodically" icon="eye">
    **Recommendation:** Check stored memories to ensure important context is saved

    ```bash theme={null}
    # List recent memories
    ulpi memory search --project my-project --limit 50 --sort recent

    # Search for specific topic
    ulpi memory search "authentication" --project my-project
    ```

    **Benefit:** Catch any missed important context
  </Accordion>

  <Accordion title="Manually store critical memories" icon="plus">
    **Recommendation:** For extremely critical decisions, store manually to guarantee preservation

    ```bash theme={null}
    ulpi memory store \
      --content "OAuth 2.0 chosen over session cookies for mobile support" \
      --type architecture_decision \
      --importance 1.0 \
      --tags auth,oauth,architecture
    ```

    **When to use:** Business-critical decisions, security choices, compliance requirements
  </Accordion>

  <Accordion title="Tune salience threshold for your workflow" icon="sliders">
    **Recommendation:** Experiment with `minImportance` setting

    **Start conservative (0.4)** → Review what's saved → **Increase if too much** (0.6-0.7)

    **Find your sweet spot:** Saves important context without cluttering memory
  </Accordion>
</AccordionGroup>

***

## Success Metrics

Teams using pre-compact hooks report:

<CardGroup cols={2}>
  <Card title="100% Context Preservation" icon="brain" color="#8b5cf6">
    Critical decisions and conventions never lost

    Down from 40% preservation without hooks
  </Card>

  <Card title="30 Minutes Saved Daily" icon="clock" color="#10b981">
    Per developer, per day

    No more re-explaining architecture decisions
  </Card>

  <Card title="Seamless Session Continuity" icon="rotate" color="#3b82f6">
    Every session starts with full context

    Like you never left the conversation
  </Card>

  <Card title="Better Onboarding" icon="user-plus" color="#f59e0b">
    New team members browse memory archives

    Learn project decisions and patterns quickly
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="ULPI Memory Product" icon="brain" href="/memory">
    Explore the full Memory product powering pre-compact snapshots
  </Card>

  <Card title="Use Cases" icon="book-open" href="/hooks/use-cases">
    See how teams use hooks for perfect context preservation
  </Card>

  <Card title="Lifecycle Events" icon="diagram-project" href="/hooks/lifecycle-events">
    Learn about all 8 hooks and when they fire
  </Card>

  <Card title="Performance Metrics" icon="chart-line" href="/hooks/performance">
    Detailed analysis of hook latency and optimization
  </Card>
</CardGroup>