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

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.

Days 2-3: Search and Observe

Search for what you’ve stored.Notice how semantic search finds related info without exact keywords.

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 ✓

Customer insight: Teams who start small have 3x higher adoption than those who migrate everything at once.

Content Writing

What to Store

✅ DO Store

Decisions & reasoning (“Why PostgreSQL?”)
Code patterns (“Our error handling”)
Customer context (“Acme prefers email”)
Insights (“Customer hates manual organization”)
Information you’ll need later

❌ DON'T Store

Easily Googled info (“What is React?”)
Temporary debugging thoughts
Extremely personal/sensitive data
Duplicate information (search first!)

Writing Effective Memories

❌ Bad
✅ Good

"PostgreSQL"

Problem: No context, no connections, won’t be useful

Writing Principles

Be Specific: “API limit: 60 req/min” not “API has limits”
Add Context: Include who, what, when, why, where
Link Related: Reference docs, tickets, people
Clear Language: Write for future you or teammates
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)

✅ DO Tag

Projects (memory-module, api-v2)
Entities (acme-corp, sarah-chen, stripe)
Topics (authentication, performance)
Types (adr, bug-report, meeting-notes)

❌ DON'T Tag

Common words (important, good, useful)
Full sentences (this-is-about-api-auth)
Redundant info (already in content)
Ephemeral details (temporary, draft)

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

Everything as Semantic

Problem: Lose benefit of appropriate decay ratesFix: Think about information type:

Time-bound → Episodic
Strategic → Reflective
How-to → Procedural

Everything as Reflective

Problem: Nothing fades, defeats purpose of decayFix: Reserve Reflective for strategic insights. Meeting notes are Episodic.

Ignoring Emotional

Problem: Lose valuable sentiment contextFix: Capture sentiment:

Customer feedback & satisfaction
Team morale in retrospectives
User reactions to features

Reinforcement Strategy

Immediately (Emergency)
Weekly (Deep Learning)
Bi-Weekly (Maintenance)
As-Needed (Quick Refresh)

Profile: Emergency (Δ0.25)Use for:

Production incident procedures
Security protocols
Critical customer context
Core product docs

Reinforce memory [id] with Emergency profile

Automated Reinforcement:

// 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

Concept Search

Search: "state management in React"

Returns: Hooks, Redux, Context API—without exact keywordsWhy: Vector embeddings understand concepts

Filtered Search

Search semantic for "API documentation"

Filters to Semantic sector before rankingWhen: Reduce noise, know the type

Context Expansion

Search "microservices" with context

Returns: Direct + related decisions + patterns + lessonsWhen: Need comprehensive context

Recency Search

Search recent for "customer feedback"

Ranks by recency over similarityWhen: Looking for latest info

Search Tips:

Start broad, then filter
Use natural language (“How do we handle errors?”)
Enable waypoints for research
Disable waypoints for precision
Try different phrasings

Token Management

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

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

Default to Free

Use Typesense + Regex unless you need higher quality.Most customers find free features sufficient!

Batch Operations

Store multiple memories in one session.Amortizes overhead, reduces per-item cost.

Monitor Usage

Check admin panel monthly.Adjust strategy if approaching limits.

Selective Paid

Use OpenAI only for critical memories.Tag differently, specify provider via API.

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

Storing Everything

Problem: Information overload, defeats selective memoryFix: Ask “Will I need this later?” Only store future value.

Ignoring Decay

Problem: Important memories fadeFix: Weekly/monthly reinforcement schedules

Over-Tagging

Problem: 20+ tags, redundant with contentFix: 3-7 meaningful tags. Semantic search handles the rest.

Not Using Sectors

Problem: Everything Semantic, missing decay benefitsFix: Spend 2 seconds choosing right sector!

Manual Organization

Problem: Trying to create folder structuresFix: Trust waypoints and reinforcement!

Skipping Admin Panel

Problem: No visibility into memory healthFix: Weekly 5-minute check-in

Performance Optimization

Slow Searches (>2s)?

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

Slow Storage?

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

Security & Privacy

✅ DO

Store keys in environment variables
Separate keys per environment
Rotate keys quarterly
Revoke immediately if exposed

❌ DON'T

Commit keys to git
Share keys via Slack/email
Use same key across projects

Data Privacy:

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

GDPR Compliance:

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

Success Metrics

Track Impact:

Time Saved: Context search time (before vs after)
Adoption: % of team using daily
Memory Health: Avg salience, hot count, sector distribution
Search Quality: Finding on first search?
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

Workflows

Real-world usage examples

Cognitive Sectors

Master the 5 memory types

API Reference

Automate memory management

Decay & Reinforcement

Control memory lifespan

Need Help?

Docs: docs.ulpi.io/memory
Admin: app.ulpi.io/admin/memories
Email: 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.

Getting Started

Documentation

Skills

Coordination

Memory

Hooks

Tasks

Help & Security

​Best Practices

​Start Right: Your First Week

​Content Writing

​What to Store

✅ DO Store

❌ DON'T Store

​Writing Effective Memories

​Writing Principles

​Tagging Strategy

✅ DO Tag

❌ DON'T Tag

​Sector Selection

​Common Mistakes

​Reinforcement Strategy

​Search Optimization

Concept Search

Filtered Search

Context Expansion

Recency Search

​Token Management

​Token Costs

​Staying Within Limits

Default to Free

Batch Operations

Monitor Usage

Selective Paid

​Admin Panel Usage

​Daily (1 minute)

​Weekly (5 minutes)

​Monthly (15 minutes)

​Common Pitfalls

​Performance Optimization

​Slow Searches (>2s)?

​Slow Storage?

​Security & Privacy

✅ DO

❌ DON'T

​Success Metrics

​Next Steps

Workflows

Cognitive Sectors

API Reference

Decay & Reinforcement

Best Practices

Start Right: Your First Week

Content Writing

What to Store

Writing Effective Memories

Writing Principles

Tagging Strategy

Sector Selection

Common Mistakes

Reinforcement Strategy

Search Optimization

Token Management

Token Costs

Staying Within Limits

Admin Panel Usage

Daily (1 minute)

Weekly (5 minutes)

Monthly (15 minutes)

Common Pitfalls

Performance Optimization

Slow Searches (>2s)?

Slow Storage?

Security & Privacy

Success Metrics

Next Steps