Skip to main content

​
Advanced Features

Advanced capabilities for power users: chunk-level authority, search optimization, and performance tuning.

​
Chunk-Level Authority

Control which parts of documents or conversations should be prioritized in search results.

​
What is Authority?

Authority is a confidence score (0-1) that you can assign to individual messages or document chunks. Higher authority content appears higher in search results, even if semantically similar to lower-authority content. Use cases:
  • Verified information - Mark fact-checked content with high authority
  • Official documentation - Prioritize canonical docs over user comments
  • Expert responses - Weight expert answers higher than general discussion
  • Conversation quality - Boost helpful responses, demote off-topic messages

​
Setting Authority

from nebula import Nebula

nebula = Nebula(api_key="your-api-key")

# Store memory with authority score
memory_id = nebula.store_memory({
    "collection_id": "support-collection",
    "content": "To reset password, go to Settings > Security > Reset Password",
    "metadata": {
        "type": "official_guide",
        "verified": True
    },
    "authority": 0.95  # High authority - this is the canonical answer
})

# Lower authority for user-contributed content
user_memory = nebula.store_memory({
    "collection_id": "support-collection",
    "content": "I think you can reset it in settings somewhere",
    "metadata": {
        "type": "user_comment",
        "verified": False
    },
    "authority": 0.4  # Lower authority - less reliable
})

​
Authority Guidelines

ScoreWhen to Use
0.9-1.0Verified facts, official documentation, expert-reviewed content
0.7-0.9Reliable sources, trusted contributors, quality content
0.5-0.7General content, community contributions, unverified info
0.3-0.5Uncertain information, speculation, off-topic content
0.0-0.3Low-quality, potentially incorrect, or spam content
Default authority is 0.5 if not specified. Start there and adjust based on content quality.

​
Authority in Conversations

# High authority for assistant responses
nebula.store_memory({
    "memory_id": conversation_id,
    "collection_id": "support-collection",
    "content": "Based on your account, you're on the Pro plan.",
    "role": "assistant",
    "authority": 0.85,  # Verified system data
    "metadata": {"verified": True}
})

# Lower authority for user messages
nebula.store_memory({
    "memory_id": conversation_id,
    "collection_id": "support-collection",
    "content": "I think I'm on the Pro plan",
    "role": "user",
    "authority": 0.5,  # User belief, not verified
    "metadata": {"verified": False}
})
cURL
# High authority for assistant responses
curl -X POST "https://api.nebulacloud.app/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "memory_id": "CONVERSATION_ID",
    "collection_ref": "support-collection",
    "engram_type": "conversation",
    "messages": [
      {
        "content": "Based on your account, you'\''re on the Pro plan.",
        "role": "assistant",
        "metadata": {"verified": true}
      }
    ],
    "authority": 0.85
  }'

# Lower authority for user messages
curl -X POST "https://api.nebulacloud.app/v1/memories" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "memory_id": "CONVERSATION_ID",
    "collection_ref": "support-collection",
    "engram_type": "conversation",
    "messages": [
      {
        "content": "I think I'\''m on the Pro plan",
        "role": "user",
        "metadata": {"verified": false}
      }
    ],
    "authority": 0.5
  }'

​
Updating Authority

Update authority scores as content is verified or becomes outdated: 
# Update existing memory's authority
nebula.update_memory(
    memory_id=memory_id,
    authority=0.3  # Downgrade outdated information
)
cURL
curl -X POST "https://api.nebulacloud.app/v1/engrams/YOUR_MEMORY_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"authority": 0.3}'

​
Search Optimization Techniques

​
1. Metadata Design

# Bad - unstructured metadata
metadata = {
    "info": "high priority user_123 bug",
    "notes": "reported on 2024-01-15"
}

# Good - structured, filterable metadata
metadata = {
    "priority": "high",
    "user_id": "user_123",
    "type": "bug",
    "status": "open",
    "created_date": "2024-01-15",
    "tags": ["login", "authentication"]
}

​
2. Batch Operations

# Bad - individual stores
for item in items:
    nebula.store_memory(item)  # Slow!

# Good - batch store
nebula.store_memories(items)  # Fast!

​
3. Smart Limits

# User-facing search - need quick results
results = nebula.search(query="test", collection_ids=[collection_id], limit=10)

# Background processing - need comprehensive results
results = nebula.search(query="test", collection_ids=[collection_id], limit=100)

​
Bulk Operations

​
Bulk Delete with Filters

# Delete all memories matching criteria
memories = nebula.list_memories(
    collection_ids=["temp-collection"],
    filters={"status": "archived"},
    limit=1000
)

memory_ids = [m.memory_id for m in memories]
nebula.delete(memory_ids)

​
Bulk Update

# Get memories to update
memories = nebula.list_memories(
    collection_ids=["docs-collection"],
    filters={"version": "1.0"},
    limit=500
)

# Update each with new metadata
for memory in memories:
    nebula.update_memory(
        memory_id=memory.memory_id,
        metadata={**memory.metadata, "deprecated": True}
    )

​
Best Practices Summary

  1. Use authority scores for content quality differentiation
  2. Design structured metadata for efficient filtering
  3. Batch operations whenever possible
  4. Regular cleanup - archive or delete old/unused memories

​
Common Patterns

​
Quality-Based Ranking

# Store high-quality content
official_doc = nebula.store_memory({
    "collection_id": "docs",
    "content": "Official API documentation...",
    "authority": 0.95,
    "metadata": {"source": "official", "verified": True}
})

# Store community content
community_doc = nebula.store_memory({
    "collection_id": "docs",
    "content": "Community guide...",
    "authority": 0.6,
    "metadata": {"source": "community", "verified": False}
})

# Search automatically ranks by authority + relevance

​
Time-Based Authority Decay

from datetime import datetime, timedelta

def calculate_authority(base_authority: float, created_date: str) -> float:
    """Reduce authority of old content"""
    created = datetime.fromisoformat(created_date)
    age_days = (datetime.now() - created).days

    # Reduce authority by 0.1 per year
    decay = min(0.3, (age_days / 365) * 0.1)
    return max(0.3, base_authority - decay)

# Apply when storing
nebula.store_memory({
    "collection_id": "docs",
    "content": "Documentation content...",
    "authority": calculate_authority(0.9, "2023-01-15"),
    "metadata": {"created_date": "2023-01-15"}
})

​
Next Steps