> ## 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.

# Cognitive Sectors

> The 5 types of memory and when to use each

# Cognitive Sectors

**Different information needs different lifespans.** The Memory Module organizes memories into 5 cognitive sectors, each with appropriate decay rates.

<Note>
  Your brain doesn't treat "yesterday's lunch" the same as "your wedding day." Neither does the Memory Module.
</Note>

***

## Quick Reference

| Sector         | Half-Life | Decay     | Best For                                                       |
| -------------- | --------- | --------- | -------------------------------------------------------------- |
| **Episodic**   | 46 days   | Fast      | Time-bound events (meetings, bugs, deployments)                |
| **Semantic**   | 139 days  | Slow      | Facts & concepts (API docs, definitions)                       |
| **Procedural** | 87 days   | Medium    | How-to knowledge (processes, tutorials)                        |
| **Emotional**  | 35 days   | Very Fast | Sentiment & feedback (morale, satisfaction)                    |
| **Reflective** | 693 days  | Very Slow | Strategic insights (architecture decisions, "why we did this") |

***

## 1. Episodic

<CardGroup cols={2}>
  <Card title="What" icon="calendar">
    **Time-bound events & experiences**

    Has specific "when" and "where"

    Examples: Meeting notes, bug investigations, deployments
  </Card>

  <Card title="Decay" icon="gauge-high">
    **Half-life: 46 days (medium-fast)**

    Week 1: Fresh, highly relevant
    Week 4: Still useful
    Week 12: Fading
    Week 24: Mostly forgotten
  </Card>
</CardGroup>

**Use for:**

* Meeting notes and decisions
* Bug investigation logs
* Deployment records
* Customer interaction logs
* Project milestone events
* Incident reports

**Examples:**

<Tabs>
  <Tab title="Standup">
    ```
    "Daily standup - Jan 25, 2025
    - Marcus: Finished auth refactor PR #234
    - Sarah: Blocked on DB migration
    - Aisha: Starting memory docs
    Next standup: Jan 26"

    Sector: episodic
    ```

    **Why:** Specific date/time, useful short-term, less relevant after sprint
  </Tab>

  <Tab title="Bug Investigation">
    ```
    "Payment bug investigation - Jan 20
    - Issue: Stripe webhook timing out
    - Cause: 30s timeout, webhook takes 45s
    - Fix: Moved to background job
    - Deployed: v2.3.1"

    Sector: episodic
    ```

    **Why:** Event-based, valuable while debugging, fades after fix deployed
  </Tab>

  <Tab title="Support Call">
    ```
    "Support call - Acme Corp - Jan 20, 2pm
    - Issue: API rate limiting (429 errors)
    - Resolution: Upgraded to Pro plan
    - Follow-up: Jan 27"

    Sector: episodic
    ```

    **Why:** Specific interaction, useful for follow-up, fades after resolved
  </Tab>
</Tabs>

***

## 2. Semantic

<CardGroup cols={2}>
  <Card title="What" icon="book">
    **Facts, concepts & general knowledge**

    Timeless information

    Examples: API docs, definitions, configurations
  </Card>

  <Card title="Decay" icon="gauge-simple">
    **Half-life: 139 days (slow)**

    Month 1: Fresh
    Month 3: Still strong (0.85)
    Month 6: Moderate (0.65)
    Year 1: Fading (0.40)
  </Card>
</CardGroup>

**Use for:**

* API documentation and references
* Technical definitions
* Company policies
* Product feature descriptions
* Configuration settings
* Integration docs

**Examples:**

<Tabs>
  <Tab title="API Docs">
    ```
    "Our REST API uses JWT bearer tokens.
    Tokens expire after 30 days inactivity.
    Header: Authorization: Bearer {token}

    Generate: POST /api/auth/token
    Refresh: POST /api/auth/refresh"

    Sector: semantic
    ```

    **Why:** Timeless factual information, referenced frequently
  </Tab>

  <Tab title="Product Knowledge">
    ```
    "ULPI subscription plans:
    - Starter: $49/mo, 1K memories
    - Pro: $199/mo, 10K memories
    - Enterprise: Custom pricing

    All plans: MCP integration, API access"

    Sector: semantic
    ```

    **Why:** Facts about product, useful long-term, rarely changes
  </Tab>

  <Tab title="Technical Concepts">
    ```
    "Semantic waypoints:
    - Graph edges connecting similar memories
    - Created when similarity ≥0.75
    - BFS search up to 3 hops
    - 20% salience decay per hop

    Purpose: Automatic context expansion"

    Sector: semantic
    ```

    **Why:** Conceptual knowledge, relevant as long as feature exists
  </Tab>
</Tabs>

***

## 3. Procedural

<CardGroup cols={2}>
  <Card title="What" icon="list-check">
    **How-to knowledge & processes**

    Step-by-step instructions

    Examples: Deployment processes, coding patterns, tutorials
  </Card>

  <Card title="Decay" icon="gauge">
    **Half-life: 87 days (medium)**

    Week 2: Fresh
    Month 2: Still reliable (0.80)
    Month 4: Need refresh (0.60)
    Month 6: Update needed (0.45)
  </Card>
</CardGroup>

**Use for:**

* Deployment procedures
* Setup guides
* Troubleshooting steps
* Coding patterns
* Configuration workflows
* Testing procedures

**Examples:**

<Tabs>
  <Tab title="Deployment">
    ```
    "Production deployment process:
    1. Run tests: npm run test
    2. Build: npm run build
    3. Tag: git tag v{version}
    4. Push: git push origin v{version}
    5. Deploy: vercel --prod
    6. Verify: Check /health endpoint
    7. Monitor: Watch logs for 10min"

    Sector: procedural
    ```

    **Why:** Step-by-step process, needs occasional updates
  </Tab>

  <Tab title="Setup Guide">
    ```
    "Setting up local dev environment:
    1. Install Node 20: nvm install 20
    2. Clone repo: git clone {repo}
    3. Install deps: npm install
    4. Copy env: cp .env.example .env.local
    5. Start: npm run dev
    6. Verify: localhost:3000"

    Sector: procedural
    ```

    **Why:** Workflow that may change with tooling updates
  </Tab>

  <Tab title="Troubleshooting">
    ```
    "Fixing 'Module not found' errors:
    1. Clear cache: rm -rf .next
    2. Delete modules: rm -rf node_modules
    3. Reinstall: npm install
    4. Restart: npm run dev
    5. Still broken? Check imports for typos"

    Sector: procedural
    ```

    **Why:** Process that may need updates as tools evolve
  </Tab>
</Tabs>

***

## 4. Emotional

<CardGroup cols={2}>
  <Card title="What" icon="heart">
    **Sentiment & feedback**

    Feelings, morale, reactions

    Examples: Customer frustration, team morale, satisfaction
  </Card>

  <Card title="Decay" icon="gauge-high">
    **Half-life: 35 days (very fast)**

    Day 1: Fresh
    Week 2: Fading (0.70)
    Week 4: Mostly gone (0.50)
    Week 8: Very faint (0.25)
  </Card>
</CardGroup>

**Use for:**

* Customer sentiment
* Team morale tracking
* User satisfaction
* Frustration points
* Positive feedback
* Emotional context

**Why fast decay:** Sentiment changes quickly, old emotions less relevant

**Examples:**

<Tabs>
  <Tab title="Customer Feedback">
    ```
    "Acme Corp frustrated with API rate limits.
    Expressed urgency - blocking their launch.
    Tone: Frustrated but professional.
    Resolution: Upgraded plan, now satisfied.

    Sentiment: Frustrated → Satisfied"

    Sector: emotional
    ```

    **Why:** Sentiment snapshot, less relevant after resolution
  </Tab>

  <Tab title="Team Morale">
    ```
    "Team morale high after successful launch.
    Everyone excited about positive customer feedback.
    Celebrating at team dinner tonight.

    Context: v2.0 launch week"

    Sector: emotional
    ```

    **Why:** Emotional state, changes as project progresses
  </Tab>

  <Tab title="User Reaction">
    ```
    "Users love the new search feature!
    Twitter feedback overwhelmingly positive.
    Multiple users saying 'game changer.'

    Feature: Semantic waypoints"

    Sector: emotional
    ```

    **Why:** Reaction to feature, fades as feature becomes expected
  </Tab>
</Tabs>

***

## 5. Reflective

<CardGroup cols={2}>
  <Card title="What" icon="telescope">
    **Strategic insights & decisions**

    The "why" behind choices

    Examples: Architecture decisions, lessons learned, retrospectives
  </Card>

  <Card title="Decay" icon="gauge-simple-low">
    **Half-life: 693 days (very slow)**

    Month 6: Still 0.95
    Year 1: Still 0.85
    Year 2: Still 0.70
    Year 3: Still 0.60
  </Card>
</CardGroup>

**Use for:**

* Architecture decisions
* Technology choices
* Lessons learned
* Strategic pivots
* Post-mortems
* "Why we did this"

**Why slow decay:** Strategic insights remain valuable for years

**Examples:**

<Tabs>
  <Tab title="Architecture">
    ```
    "Why we chose microservices over monolith:

    Context: Scaling to 100+ developers across teams
    Decision: Microservices architecture
    Reasoning:
    - Team autonomy (deploy independently)
    - Technology flexibility (right tool per service)
    - Fault isolation (one service down ≠ all down)

    Trade-offs accepted:
    - Increased operational complexity
    - Distributed system challenges
    - Network latency between services

    Date: Jan 2024"

    Sector: reflective
    ```

    **Why:** Strategic decision that informs future architecture choices
  </Tab>

  <Tab title="Lesson Learned">
    ```
    "Production outage retrospective - Dec 2024

    What happened: Database migration ran during peak traffic
    Impact: 45min downtime, 500 affected users
    Root cause: No maintenance window policy

    Lessons:
    - Always schedule maintenance windows
    - Run migrations in off-peak hours
    - Test migrations on staging first
    - Have rollback plan ready

    Actions: Created maintenance window policy"

    Sector: reflective
    ```

    **Why:** Hard-won wisdom that prevents future incidents
  </Tab>

  <Tab title="Tech Choice">
    ```
    "Why we chose React over Vue for frontend:

    Context: Rebuilding admin dashboard
    Decision: React + Next.js
    Reasoning:
    - Larger talent pool (hiring)
    - Better TypeScript support
    - Rich ecosystem (libraries)
    - Server components (performance)

    Alternatives considered:
    - Vue 3: Smaller ecosystem
    - Svelte: Less mature

    Date: Feb 2024"

    Sector: reflective
    ```

    **Why:** Technology rationale that guides future tech decisions
  </Tab>
</Tabs>

***

## Choosing the Right Sector

**Decision tree:**

```
Is it about feelings/sentiment?
  → Emotional (fast decay)

Is it a time-bound event?
  → Episodic (medium-fast decay)

Is it a step-by-step process?
  → Procedural (medium decay)

Is it a fact or definition?
  → Semantic (slow decay)

Is it strategic insight or "why"?
  → Reflective (very slow decay)
```

**When in doubt:**

* Events with dates → Episodic
* Timeless facts → Semantic
* How-to guides → Procedural
* Strategic reasons → Reflective

***

## Sector Comparison

| Aspect        | Episodic       | Semantic          | Procedural           | Emotional        | Reflective        |
| ------------- | -------------- | ----------------- | -------------------- | ---------------- | ----------------- |
| **Question**  | When/Where?    | What is it?       | How to do it?        | How did it feel? | Why did we do it? |
| **Timeframe** | Specific date  | Timeless          | Periodic             | Short-lived      | Long-lasting      |
| **Example**   | Bug fix Jan 15 | API uses JWT      | Deploy: 7 steps      | Customer happy   | Why microservices |
| **Decay**     | 46 days        | 139 days          | 87 days              | 35 days          | 693 days          |
| **Update**    | Rarely         | When facts change | When process changes | Often            | Rarely            |

***

## Auto-Classification

**The system can auto-classify based on content:**

```typescript theme={null}
store_memory({
  content: "Fixed payment bug on Jan 20...",
  sector: "auto"  // System detects: episodic (has date, event)
})

store_memory({
  content: "API authentication uses JWT tokens...",
  sector: "auto"  // System detects: semantic (factual, timeless)
})

store_memory({
  content: "Deploy process: 1. Build 2. Test 3. Push...",
  sector: "auto"  // System detects: procedural (step-by-step)
})
```

**Override when needed:**

```typescript theme={null}
store_memory({
  content: "Why we chose React...",
  sector: "reflective"  // Manual: strategic decision
})
```

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Be Explicit" icon="tag">
    **Specify sector when storing**

    ✅ Good:

    ```typescript theme={null}
    store_memory({
      content: "...",
      sector: "reflective"
    })
    ```

    ❌ Risky:

    ```typescript theme={null}
    store_memory({
      content: "..."  // Auto-classify may guess wrong
    })
    ```
  </Card>

  <Card title="Match Content to Sector" icon="bullseye">
    **Write for the sector**

    Reflective: Include "why" and context

    ```
    "Why we chose X:
    Context: ...
    Reasoning: ...
    Trade-offs: ..."
    ```

    Episodic: Include date/time

    ```
    "Meeting notes - Jan 25, 2025
    Attendees: ...
    Decisions: ..."
    ```
  </Card>

  <Card title="Use Reflective for Decisions" icon="telescope">
    **Strategic choices = Reflective**

    Not episodic (will fade too fast)
    Not semantic (not just facts)

    ✅ "Why we chose microservices..." → Reflective
    ❌ "We use microservices" → Semantic
  </Card>

  <Card title="Emotional for Sentiment Only" icon="heart">
    **Pure sentiment = Emotional**

    Not for facts about sentiment

    ✅ "Customer frustrated about X" → Emotional
    ❌ "Customer satisfaction score: 8.5" → Semantic
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Decay & Reinforcement" icon="chart-line" href="/memory/decay-and-reinforcement">
    How salience changes over time
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/memory/best-practices">
    Optimize memory usage
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/memory/workflows">
    Put sectors to work
  </Card>
</CardGroup>

***

*Different memories need different lifespans. Choose the right sector, let the system handle the rest.*