Skip to main content

​
Memories and Sources

In Nebula, everything is stored as a memory. A memory is a container with a unique memory_id that holds one or more sources:
  • Document Memory: An entire document, automatically split into sources for processing. You can upload text, pre-chunked text, or a file. A short piece of text (like a user preference) is a document memory with a single source.
  • Conversation Memory: A full conversation where each message is a source. Passing a role parameter tells Nebula to treat the memory as a conversation.
Each source has a unique source ID for granular updates or deletes.

​
Document Memories

from nebula import Nebula, Memory

nebula = Nebula()
collection = nebula.create_collection(name="research_papers")

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

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

# Or store a short piece of text
nebula.store_memory(
    Memory(
        collection_id=collection.id,
        content="User prefers dark mode",
        metadata={"user_id": "user_789"}
    )
)

​
Conversation Memories

Create a conversation by passing a role. Append messages by calling store_memory() with the same memory_id. 
collection = nebula.create_collection(name="support_chats")

# Create a conversation memory
conv_id = nebula.store_memory(
    Memory(
        collection_id=collection.id,
        content="Hello! How can I help?",
        role="assistant"
    )
)

# Add messages to the same conversation
nebula.store_memory(
    Memory(
        memory_id=conv_id,
        collection_id=collection.id,
        content=[
            {"content": "I need help", "role": "user"},
            {"content": "I'll help you", "role": "assistant"}
        ]
    )
)
See Conversations Guide for multi-turn patterns.

​
The Vector Graph

When you store memories, Nebula automatically extracts structured knowledge and builds a graph of entities and relationships. When you search, the response contains four layers of memory:
  • Semantics: Subject-predicate-value assertions (e.g., “Sarah - led - the Aurora migration”), with confidence that grows through corroboration across sources
  • Procedures: User preferences and behavioral patterns (e.g., “Prefers dark mode”)
  • Episodes: Temporally clustered events with timestamps
  • Sources: The original source text that grounds each assertion, providing provenance back to the stored memory
The use of metadata is highly discouraged. Nebula already consolidates all the semantics from your content automatically.

​
Memory Lifecycle

  1. Creation: store_memory() without memory_id creates a new memory
  2. Expansion: store_memory() with memory_id adds content to an existing memory
  3. Extraction: Nebula extracts entities, facts, and relationships into the vector graph
  4. Retrieval: search() returns semantics, procedures, episodes, and sources; get_memory() returns the raw memory with all sources
  5. Source Operations: Use source IDs for granular updates or deletes
  6. Deletion: delete() removes an entire memory and all its sources
Build complete units by using memory_id to group entire conversations or documents in one container, and group related memories into collections.

​
Next Steps