Skip to main content

​
Core Concepts

Understanding Nebula’s architecture helps you work more effectively with memories, conversations, and documents.

​
Memories: Universal Information Containers

In Nebula, everything is stored as a memory - a container for related information:
  • Conversation Memory: Contains all messages in a conversation
  • Document Memory: Contains an entire document (potentially split into chunks)
  • Simple Memory: Contains a single piece of information

​
Memories vs Chunks

  • Memory: The container with a unique memory_id
  • Chunks: Individual pieces within a memory (messages in conversations, sections in documents)
  • Chunk ID: Unique identifier for each chunk, used for granular operations
# Create a conversation memory
conv_id = client.store_memory({
    "collection_id": "support_chats",
    "content": "Hello! How can I help?",
    "role": "assistant"
})

# Add messages to the same conversation
client.store_memory({
    "memory_id": conv_id,
    "collection_id": "support_chats",
    "content": [
        {"content": "I need help", "role": "user"},
        {"content": "I'll help you", "role": "assistant"}
    ]
})

​
Types of Memories

​
Document Memories

Contain entire documents, split into chunks internally for processing. You can upload text, pre-chunked text, or a file. 
from nebula import Memory

# Store document text
doc_id = client.create_document_text(
    collection_id=collection.id,
    raw_text="Full document content...",
    metadata={"title": "Research Paper"}
)

# Upload a file
doc_id = client.store_memory(
    Memory.from_file("document.pdf", collection_id=collection.id, metadata={"title": "Research Paper"})
)

​
Conversation Memories

Contain full conversations. Add messages by calling store_memory() with the same memory_id. See Conversations Guide for examples.

​
Simple Memories

Standalone pieces of information that don’t need chunking. 
memory_id = client.store_memory({
    "collection_id": "preferences",
    "content": "User prefers dark mode",
    "metadata": {"user_id": "user_789"}
})

​
Memory Lifecycle

  1. Creation: store_memory() without memory_id creates new memory
  2. Expansion: store_memory() with memory_id adds content to existing memory
  3. Retrieval: get_memory() returns complete memory with all chunks
  4. Chunk Operations: Use chunk IDs for granular updates/deletes
  5. Deletion: delete() removes entire memory and all its chunks

​
Best Practices

  • Build complete units: Use memory_id to build entire conversations/documents in one container
  • Use descriptive metadata: Identify memory types and add context
  • Choose appropriate collections: Group related memories logically
  • Chunk operations when needed: Use chunk IDs only for granular edits

​
Next Steps