Search Guide

Nebula searches over a vector graph of entities and relationships, not raw text chunks. You send a natural language query; Nebula traverses the graph and returns structured memory: semantics (facts and inferences), procedures (preferences and habits), and episodes (temporal event clusters). Set include_sources to return the original text grounding those results.

Basic Search

from nebula import Nebula

nebula = Nebula()

results = nebula.memories.search(
    query="What has Sarah worked on?",
    collection_ids=["engineering"],
    include_sources=True,
).results

# Semantic: facts, inferences, and tasks (compact-mode default)
for fact in results.semantic or []:
    print(f"[{fact['category']}] {fact['description']}")
    print(f"  Score: {fact['activation_score']:.2f}")

# Procedural: user preferences and habits
for proc in results.procedural or []:
    print(f"{proc['statement']} (confidence: {proc['confidence']:.2f})")

# Sources: original source text grounding the semantics
for source in results.sources or []:
    print(f"[{source.get('speaker', 'unknown')}]: {source['text']}")

import Nebula from '@nebula-ai/sdk';
const client = new Nebula({ apiKey: process.env.NEBULA_API_KEY });

const { results } = await client.memories.search({
  query: 'What has Sarah worked on?',
  collection_ids: ['engineering'],
  include_sources: true,
});

// Semantic (compact-mode default)
results.semantic?.forEach(f =>
  console.log(`[${f.category}] ${f.description}`)
);

// Procedural
results.procedural?.forEach(p =>
  console.log(`${p.statement} (confidence: ${p.confidence})`)
);

// Sources
results.sources?.forEach(u =>
  console.log(`[${u.speaker ?? u.source_role ?? 'unknown'}]: ${u.text}`)
);

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "What has Sarah worked on?",
    "collection_ids": ["engineering"],
    "include_sources": true
  }'

Understanding Results

Search returns a MemoryResponse with three memory layers plus optional sources:

Layer	Contains	Example
Semantics	Subject-predicate-value triples (facts, inferences, tasks)	`Sarah Chen → led → Aurora migration`
Procedures	User preferences and behavioral patterns	`Prefers PostgreSQL over MySQL`
Episodes	Temporally clustered events	`Q4 database migration project`
Sources	Original source text that grounds the semantics when `include_sources` is enabled	`"Sarah led the migration from PostgreSQL to Aurora last quarter"`

Each item has an activation_score (0-1) reflecting its relevance to the query. With include_sources enabled, semantics link back to source text for a full provenance chain from structured assertions to original content. Semantic and procedural results may include memory_class, such as preference, identity, strategy, trace, or workflow_pattern, to distinguish the kind of memory returned.

The vector graph is built automatically when you store memories. You don’t need to define entities or relationships - Nebula extracts them.

Search Effort

The effort parameter is the primary control for search. It determines how deeply Nebula traverses the vector graph.

Effort	Depth	Use Case
`auto`	Adapts to query	Default - good for most queries
`low`	2 hops, narrow	Fast lookups, simple factual queries
`medium`	2 hops, wider	Broader exploration across more relationships
`high`	3 hops, widest	Deep multi-hop reasoning across the graph

# Quick factual lookup
results = nebula.memories.search(query="Sarah's role", effort="low").results

# Deep exploration
results = nebula.memories.search(
    query="How are the Q4 projects connected?",
    effort="high",
).results

// Quick factual lookup
const { results } = await client.memories.search({
  query: "Sarah's role",
  effort: 'low',
});

// Deep exploration
const { results: deep } = await client.memories.search({
  query: 'How are the Q4 projects connected?',
  effort: 'high',
});

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "How are the Q4 projects connected?",
    "effort": "high"
  }'

Start with the default (auto). Only increase effort if you need the graph to discover connections further from the query.

Scoping with Collections

Use collection_ids to scope which part of the vector graph is searched.

# Search specific collections
results = nebula.memories.search(
    query="customer feedback",
    collection_ids=["support-2024", "support-2023", "surveys"],
).results

# Search all accessible collections (omit collection_ids)
results = nebula.memories.search(query="product roadmap").results

const { results } = await client.memories.search({
  query: 'customer feedback',
  collection_ids: ['support-2024', 'support-2023', 'surveys'],
});

// Search all accessible collections
const { results: all } = await client.memories.search({ query: 'product roadmap' });

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "customer feedback",
    "collection_ids": ["support-2024", "support-2023", "surveys"]
  }'

Searching all collections is slower than targeting specific ones.

Authority Scores

Authority is a store-time parameter on conversation messages that tells Nebula how much to trust a piece of content. It’s stored per-message, not per-memory.

support = nebula.collections.retrieve_by_name("support").results

# Verified answer from support agent
conv = nebula.memories.create(
    collection_id=support.id,
    kind="conversation",
    messages=[{
        "content": "Here is the verified answer...",
        "role": "assistant",
        "authority": 0.9,
    }],
).results
conv_id = conv.id

# Uncertain user message
nebula.memories.append(
    conv_id,
    collection_id=support.id,
    messages=[{
        "content": "I'm not sure, maybe try this?",
        "role": "user",
        "authority": 0.4,
    }],
)

Score	Use Case
`0.9-1.0`	Verified facts, official sources
`0.5-0.7`	General content (default: 0.5)
`0.0-0.3`	Low confidence or uncertain

Advanced Options

Hybrid Search Weights

Control the balance between semantic and full-text matching for seed discovery (how the graph traversal finds its starting points):

results = nebula.memories.search(
    query="neural networks",
    collection_ids=["research"],
    search_settings={
        "semantic_weight": 0.7,
        "fulltext_weight": 0.3,
    },
).results

const { results } = await client.memories.search({
  query: 'neural networks',
  collection_ids: ['research'],
  search_settings: {
    semantic_weight: 0.7,
    fulltext_weight: 0.3,
  },
});

curl -X POST "https://api.zeroset.com/v1/memories/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "neural networks",
    "collection_ids": ["research"],
    "search_settings": {
      "semantic_weight": 0.7,
      "fulltext_weight": 0.3
    }
  }'

Defaults (0.8 semantic, 0.2 fulltext) work well for most cases. Lower semantic weight if you need exact keyword matching.

Metadata Filters

Optionally narrow the search scope using metadata constraints. Filters restrict which part of the graph is entered - the graph still handles discovery within that scope.

results = nebula.memories.search(
    query="project updates",
    collection_ids=["work"],
    filters={
        "status": "active",
        "team": "engineering",
    },
).results

Operators: $eq, $ne, $in, $nin, $gt, $gte, $lt, $lte, $like, $ilike, $overlap, $contains, $and, $or See Metadata Filtering for the full reference.

Next Steps

Metadata Filtering - Filter operator reference
Memory Operations - Store and manage memories

Get Started

Core Guides

Advanced Guides

Device Memory

Integration

Basic Search

Understanding Results

Search Effort

Scoping with Collections

Authority Scores

Advanced Options

Hybrid Search Weights

Metadata Filters

Next Steps

​Basic Search

​Understanding Results

​Search Effort

​Scoping with Collections

​Authority Scores

​Advanced Options

​Hybrid Search Weights

​Metadata Filters

​Next Steps

Basic Search

Understanding Results

Search Effort

Scoping with Collections

Authority Scores

Advanced Options

Hybrid Search Weights

Metadata Filters

Next Steps