Memory Operations

Practical examples for storing and searching memories with the Nebula API.

Core Operations

Store Memories

Single memory:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Store a memory
memory_id = client.store_memory({
    "cluster_id": "research-cluster",
    "content": "Machine learning automates analytical model building",
    "metadata": {"topic": "AI", "difficulty": "intermediate"}
})
Multiple memories:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Store multiple memories at once
memories = [
    {
        "cluster_id": "research-cluster",
        "content": "Supervised learning uses labeled training data",
        "metadata": {"type": "definition", "topic": "ML"}
    },
    {
        "cluster_id": "research-cluster",
        "content": "Neural networks are inspired by biological systems",
        "metadata": {"type": "concept", "topic": "AI"}
    }
]
memory_ids = client.store_memories(memories)
Conversation messages:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Store conversation with roles
conversation_id = client.store_memory({
    "cluster_id": "support-cluster",
    "content": "Hello! How can I help you?",
    "role": "assistant",
    "metadata": {"session_id": "session_123"}
})

# User response
client.store_memory({
    "cluster_id": "support-cluster",
    "content": "I need help with my account",
    "role": "user",
    "parent_id": conversation_id
})

Search Memories

Basic search:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Search for memories
results = client.search(
    query="machine learning algorithms",
    cluster_ids=["research-cluster"],
    limit=10
)

for result in results:
    print(f"Score: {result.score:.3f}")
    print(f"Content: {result.content[:100]}...")
    print(f"Metadata: {result.metadata}")
Search with filters:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Filter by metadata and score threshold
results = client.search(
    query="artificial intelligence",
    cluster_ids=["research-cluster"],
    limit=5,
    filters={
        "metadata.topic": "AI",
        "score_threshold": 0.6
    }
)

Retrieve & List Memories

Get specific memory:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# Retrieve a memory by ID
memory = client.get_memory(memory_id)
print(f"Content: {memory.content}")
print(f"Metadata: {memory.metadata}")
print(f"Created: {memory.created_at}")
List memories in cluster:
from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# List memories in a cluster
memories = client.list_memories(
    cluster_ids=["research-cluster"],
    limit=20,
    offset=0
)

for memory in memories:
    print(f"ID: {memory.id}")
    print(f"Content: {memory.content[:60]}...")
    print(f"Created: {memory.created_at}")

Complete Workflow

from nebula_client import NebulaClient

client = NebulaClient(api_key="your-api-key")

# 1. Create cluster and store memories
cluster = client.create_cluster("demo-cluster", "Example cluster")
memories = [
    {
        "cluster_id": cluster.id,
        "content": "Python is a high-level programming language",
        "metadata": {"language": "python", "type": "fact"}
    },
    {
        "cluster_id": cluster.id,
        "content": "JavaScript is used for web development",
        "metadata": {"language": "javascript", "type": "fact"}
    }
]
memory_ids = client.store_memories(memories)

# 2. Search memories
results = client.search(
    query="programming languages",
    cluster_ids=[cluster.id],
    limit=5
)

# 3. Retrieve specific memory
memory = client.get_memory(memory_ids[0])
print(f"Retrieved: {memory.content}")

Best Practices

  • Use descriptive metadata for better organization and filtering
  • Batch operations with store_memories() for multiple items
  • Set appropriate limits in search to manage performance
  • Use natural language queries for best search results
  • Validate required fields before storing memories
Attach focused, query-relevant metadata (e.g., topic, type, priority) to improve search precision and filtering.

Next Steps