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

# Best Practices

> Get maximum value from the Memory Module

# Best Practices

**Proven strategies from real customer usage.** Learn what works, what doesn't, and how to build an effective second brain.

***

## Start Right: Your First Week

<Steps>
  <Step title="Day 1: Store Naturally">
    Don't overthink it. Start storing as you work:

    ```
    "Our API uses JWT tokens that expire after 30 days"
    ```

    Let the system handle classification and connections.
  </Step>

  <Step title="Days 2-3: Search and Observe">
    Search for what you've stored.

    Notice how semantic search finds related info without exact keywords.
  </Step>

  <Step title="Days 4-7: Build Momentum">
    Store 5-10 memories daily from actual work.

    Don't migrate old notes yet—build new habits first.

    By week end: 25-50 memories with automatic connections ✓
  </Step>
</Steps>

<Info>
  **Customer insight:** Teams who start small have 3x higher adoption than those who migrate everything at once.
</Info>

***

## Content Writing

### What to Store

<CardGroup cols={2}>
  <Card title="✅ DO Store" icon="check">
    * Decisions & reasoning ("Why PostgreSQL?")
    * Code patterns ("Our error handling")
    * Customer context ("Acme prefers email")
    * Insights ("Customer hates manual organization")
    * Information you'll need later
  </Card>

  <Card title="❌ DON'T Store" icon="xmark">
    * Easily Googled info ("What is React?")
    * Temporary debugging thoughts
    * Extremely personal/sensitive data
    * Duplicate information (search first!)
  </Card>
</CardGroup>

### Writing Effective Memories

<Tabs>
  <Tab title="❌ Bad">
    ```
    "PostgreSQL"
    ```

    **Problem:** No context, no connections, won't be useful
  </Tab>

  <Tab title="✅ Good">
    ```
    "We use PostgreSQL for analytics because we need
    ACID guarantees for financial data and complex joins.

    Alternative: MongoDB (rejected for lack of joins)
    Decision: 2025-01-15
    See: docs/architecture/database-choice.md"

    Tags: architecture, postgresql, database, adr
    Sector: reflective
    ```

    **Why better:** Context, reasoning, alternatives, dates, links
  </Tab>
</Tabs>

### Writing Principles

1. **Be Specific:** "API limit: 60 req/min" not "API has limits"
2. **Add Context:** Include who, what, when, why, where
3. **Link Related:** Reference docs, tickets, people
4. **Clear Language:** Write for future you or teammates
5. **Include Source:** Where did this come from?

***

## Tagging Strategy

**Ideal: 3-7 tags per memory**

* Under 3: Harder to filter
* Over 10: Diminishing returns (semantic search handles it)

<CardGroup cols={2}>
  <Card title="✅ DO Tag" icon="check">
    - Projects (memory-module, api-v2)
    - Entities (acme-corp, sarah-chen, stripe)
    - Topics (authentication, performance)
    - Types (adr, bug-report, meeting-notes)
  </Card>

  <Card title="❌ DON'T Tag" icon="xmark">
    * Common words (important, good, useful)
    * Full sentences (this-is-about-api-auth)
    * Redundant info (already in content)
    * Ephemeral details (temporary, draft)
  </Card>
</CardGroup>

**Tagging Patterns:**

```
Hierarchical: memory-module:decay, memory-module:waypoints
Entity: customer-acme-corp, team-backend, person-sarah
Status: active, archived, critical, draft
```

***

## Sector Selection

**Quick Decision Guide:**

| If it's...             | Sector     | Example                           |
| ---------------------- | ---------- | --------------------------------- |
| Specific event/meeting | Episodic   | "Sprint planning 2025-01-20"      |
| Timeless fact          | Semantic   | "JWT tokens expire after 30 days" |
| Step-by-step           | Procedural | "How to deploy to production"     |
| Feelings/sentiment     | Emotional  | "Customer frustrated with UI"     |
| Strategic insight      | Reflective | "Why we chose PostgreSQL"         |

### Common Mistakes

<AccordionGroup>
  <Accordion title="Everything as Semantic">
    **Problem:** Lose benefit of appropriate decay rates

    **Fix:** Think about information type:

    * Time-bound → Episodic
    * Strategic → Reflective
    * How-to → Procedural
  </Accordion>

  <Accordion title="Everything as Reflective">
    **Problem:** Nothing fades, defeats purpose of decay

    **Fix:** Reserve Reflective for strategic insights. Meeting notes are Episodic.
  </Accordion>

  <Accordion title="Ignoring Emotional">
    **Problem:** Lose valuable sentiment context

    **Fix:** Capture sentiment:

    * Customer feedback & satisfaction
    * Team morale in retrospectives
    * User reactions to features
  </Accordion>
</AccordionGroup>

***

## Reinforcement Strategy

<Tabs>
  <Tab title="Immediately (Emergency)">
    **Profile: Emergency (Δ0.25)**

    **Use for:**

    * Production incident procedures
    * Security protocols
    * Critical customer context
    * Core product docs

    ```
    Reinforce memory [id] with Emergency profile
    ```
  </Tab>

  <Tab title="Weekly (Deep Learning)">
    **Profile: Deep Learning (Δ0.15)**

    **Use for:**

    * New technology you're studying
    * Onboarding documentation
    * Strategic initiatives in progress

    Set up weekly reminders or scripts.
  </Tab>

  <Tab title="Bi-Weekly (Maintenance)">
    **Profile: Maintenance (Δ0.10)**

    **Use for:**

    * API documentation
    * Code patterns & conventions
    * Common procedures

    Standard "keep this around" reinforcement.
  </Tab>

  <Tab title="As-Needed (Quick Refresh)">
    **Profile: Quick Refresh (Δ0.05)**

    **Use for:**

    * Interesting insights
    * Context for upcoming work
    * Recently relevant info

    Light touch to extend lifespan.
  </Tab>
</Tabs>

**Automated Reinforcement:**

```javascript theme={null}
// Reinforce critical docs weekly
async function reinforceCriticalDocs() {
  const critical = await fetch('https://api.ulpi.io/api/v1/memories/search', {
    method: 'POST',
    body: JSON.stringify({ query: '', tags: ['critical', 'documentation'] })
  }).then(r => r.json());

  for (const memory of critical.data) {
    await fetch(`https://api.ulpi.io/api/v1/memories/${memory.id}/reinforce`, {
      method: 'POST',
      body: JSON.stringify({ profile: 'maintenance' })
    });
  }
}
```

***

## Search Optimization

<CardGroup cols={2}>
  <Card title="Concept Search" icon="brain">
    ```
    Search: "state management in React"
    ```

    Returns: Hooks, Redux, Context API—without exact keywords

    **Why:** Vector embeddings understand concepts
  </Card>

  <Card title="Filtered Search" icon="filter">
    ```
    Search semantic for "API documentation"
    ```

    Filters to Semantic sector before ranking

    **When:** Reduce noise, know the type
  </Card>

  <Card title="Context Expansion" icon="sitemap">
    ```
    Search "microservices" with context
    ```

    Returns: Direct + related decisions + patterns + lessons

    **When:** Need comprehensive context
  </Card>

  <Card title="Recency Search" icon="clock">
    ```
    Search recent for "customer feedback"
    ```

    Ranks by recency over similarity

    **When:** Looking for latest info
  </Card>
</CardGroup>

**Search Tips:**

1. Start broad, then filter
2. Use natural language ("How do we handle errors?")
3. Enable waypoints for research
4. Disable waypoints for precision
5. Try different phrasings

***

## Token Management

<Note>
  **Token costs only apply when using paid features:** OpenAI embeddings or LLM classification. Free (Typesense + Regex) uses zero tokens.
</Note>

### Token Costs

| Operation | Free Option       | Paid Option   | Cost             |
| --------- | ----------------- | ------------- | ---------------- |
| Store     | Typesense + Regex | OpenAI + LLM  | \~150-500 tokens |
| Search    | Typesense vector  | OpenAI        | \~50-100 tokens  |
| Waypoints | Included free     | Included free | \~10-20/hop      |
| Reinforce | Included free     | Included free | \~5 tokens       |

### Staying Within Limits

**Starter (100K/month):**

* Use free features ✅
* \~200-300 memories/month (free) or \~30-40 (paid)

**Pro (1M/month):**

* Mix free and paid strategically
* \~3,000/month (free) or \~300 (paid)

**Enterprise (Unlimited):**

* Use paid everywhere, no restrictions

<CardGroup cols={2}>
  <Card title="Default to Free" icon="piggy-bank">
    Use Typesense + Regex unless you need higher quality.

    Most customers find free features sufficient!
  </Card>

  <Card title="Batch Operations" icon="layer-group">
    Store multiple memories in one session.

    Amortizes overhead, reduces per-item cost.
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Check admin panel monthly.

    Adjust strategy if approaching limits.
  </Card>

  <Card title="Selective Paid" icon="filter">
    Use OpenAI only for critical memories.

    Tag differently, specify provider via API.
  </Card>
</CardGroup>

***

## Admin Panel Usage

### Daily (1 minute)

* **Embeddings Log:** Any failures?
* **Stats:** Total memories, hot memories, average salience

### Weekly (5 minutes)

* **Sector Distribution:** Balanced?
* **Hot Memories:** Frequently accessed? Reinforce?
* **Recent Activity:** Consistent creation?

### Monthly (15 minutes)

* **Prune:** Remove memories under 0.1 salience
* **Reinforce:** Boost strategic documentation
* **Review Waypoints:** Rebuild if bulk imports
* **Export Backup:** Download JSON

***

## Common Pitfalls

<AccordionGroup>
  <Accordion title="Storing Everything">
    **Problem:** Information overload, defeats selective memory

    **Fix:** Ask "Will I need this later?" Only store future value.
  </Accordion>

  <Accordion title="Ignoring Decay">
    **Problem:** Important memories fade

    **Fix:** Weekly/monthly reinforcement schedules
  </Accordion>

  <Accordion title="Over-Tagging">
    **Problem:** 20+ tags, redundant with content

    **Fix:** 3-7 meaningful tags. Semantic search handles the rest.
  </Accordion>

  <Accordion title="Not Using Sectors">
    **Problem:** Everything Semantic, missing decay benefits

    **Fix:** Spend 2 seconds choosing right sector!
  </Accordion>

  <Accordion title="Manual Organization">
    **Problem:** Trying to create folder structures

    **Fix:** Trust waypoints and reinforcement!
  </Accordion>

  <Accordion title="Skipping Admin Panel">
    **Problem:** No visibility into memory health

    **Fix:** Weekly 5-minute check-in
  </Accordion>
</AccordionGroup>

***

## Performance Optimization

### Slow Searches (>2s)?

1. Reduce waypoint expansion: `max_hops: 1` or `expand_waypoints: false`
2. Use filters: Narrow by sector, tags, date first
3. Lower limits: Request fewer results (`limit: 5`)
4. Check Typesense: Admin → Stats → Index status

### Slow Storage?

1. Async embedding: Don't wait (API returns immediately)
2. Batch operations: Multiple memories per session
3. Check queue: Admin → Horizon → Queue depth

***

## Security & Privacy

<CardGroup cols={2}>
  <Card title="✅ DO" icon="check">
    * Store keys in environment variables
    * Separate keys per environment
    * Rotate keys quarterly
    * Revoke immediately if exposed
  </Card>

  <Card title="❌ DON'T" icon="xmark">
    * Commit keys to git
    * Share keys via Slack/email
    * Use same key across projects
  </Card>
</CardGroup>

**Data Privacy:**

* Multi-tenant isolation (complete)
* Encryption: At rest + in transit
* Access logs: All operations tracked
* Export control: You own your data

**GDPR Compliance:**

1. Document PII in memory content
2. Use shorter-decay sectors (Episodic, Emotional)
3. Manual deletion available
4. Export capability for data requests

***

## Success Metrics

**Track Impact:**

1. **Time Saved:** Context search time (before vs after)
2. **Adoption:** % of team using daily
3. **Memory Health:** Avg salience, hot count, sector distribution
4. **Search Quality:** Finding on first search?
5. **Reinforcement:** Which memories reinforced most? (Most valuable!)

**Target Benchmarks:**

* 5-10 new memories/person/week
* 10-20 searches/person/day
* 70%+ team using within 1 month
* Average salience >0.5
* 20-30% hot memories

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Workflows" icon="list-check" href="/memory/workflows">
    Real-world usage examples
  </Card>

  <Card title="Cognitive Sectors" icon="brain" href="/memory/cognitive-sectors">
    Master the 5 memory types
  </Card>

  <Card title="API Reference" icon="code" href="/memory/api-reference">
    Automate memory management
  </Card>

  <Card title="Decay & Reinforcement" icon="chart-line" href="/memory/decay-and-reinforcement">
    Control memory lifespan
  </Card>
</CardGroup>

***

**Need Help?**

* Docs: docs.ulpi.io/memory
* Admin: app.ulpi.io/admin/memories
* Email: [support@ulpi.io](mailto:support@ulpi.io) (Starter: 48h, Pro: 24h, Enterprise: 4h)
* Community: forum.ulpi.io
* Bugs: github.com/ulpi-io/ulpi/issues

***

*Build habits, trust the system, let semantic connections emerge naturally.*