How Note Creation Links Sources and Insights in the Open Notebook Graph Database

When creating a note in Open Notebook, the system persists a node in SurrealDB and establishes relationship edges that connect the note to notebooks via artifact edges and to original sources through source_insight relationships when converting insights to notes.

Open Notebook leverages SurrealDB as its graph database to manage complex relationships between research materials. Understanding how note creation establishes connections between sources, insights, and notebooks is essential for building queries that trace the lineage of ideas. This article examines the exact mechanism used in the lfnovo/open-notebook repository to link these entities.

Understanding the Graph Database Architecture

Open Notebook uses SurrealDB to store entities as nodes and relationships as typed edges. The system defines specific edge types to represent semantic connections: artifact edges link notes to notebooks, while source_insight edges connect insights to their parent sources. This graph structure enables bidirectional traversal from any note back to its original source material.

Creating Direct Notes and Linking to Notebooks

When users create notes directly through the API, the system establishes the primary notebook relationship immediately.

The Note Creation Process

The POST /notes endpoint in api/routers/notes.py (lines 84‑90) handles incoming requests to create new notes. When a notebook_id is provided in the request payload, the endpoint invokes the add_to_notebook() method after persisting the note node. This ensures every note created through the API can be immediately associated with its containing notebook.

Establishing Notebook Relationships

The Note.add_to_notebook() method, defined in open_notebook/domain/notebook.py (lines 606‑610), writes an artifact edge from the note node to the notebook node. This edge serves as the primary graph relationship that associates notes with their parent notebooks, allowing queries to retrieve all artifacts belonging to a specific notebook.

# Creating a note directly and attaching it to a notebook

new_note = Note(
    title="Meeting summary",
    content="Discussed project milestones …",
    note_type="human",
)
await new_note.save()
await new_note.add_to_notebook(notebook_id="notebook:123")   # creates `artifact` edge

Converting Insights to Notes

Insights extracted from sources can be promoted to full notes, preserving their provenance through the graph structure.

The SourceInsight Flow

Insights are stored as SourceInsight nodes that maintain a source_insight edge to their parent Source node. The SourceInsight.save_as_note() method in open_notebook/domain/notebook.py (lines 776‑787) handles the conversion process. This method creates a new Note instance, persists it to the database, and optionally attaches it to a notebook using the same add_to_notebook() workflow.

Preserving Source Lineage

When an insight becomes a note, the graph retains the chain: Source → source_insight → Note. This indirect lineage enables the UI and search logic to display notes alongside the source material that inspired them, maintaining full traceability from raw material to synthesized knowledge.

# Converting an insight into a note

insight = await SourceInsight.get(insight_id="source_insight:456")
note = await insight.save_as_note(notebook_id="notebook:123")

# `note` now has:

#   - artifact edge to the notebook

#   - implicit link back to the original Source via the source_insight node

Technical Implementation Reference

The implementation relies on three critical code locations:

• open_notebook/domain/notebook.py (lines 606‑610): Contains Note.add_to_notebook(), which constructs the artifact edge using SurrealDB's graph query syntax.

• open_notebook/domain/notebook.py (lines 776‑787): Implements SourceInsight.save_as_note(), which instantiates notes from insights while preserving the source relationship chain.

• api/routers/notes.py (lines 84‑90): The FastAPI endpoint that orchestrates direct note creation and optional notebook linking.

Each method uses asynchronous operations to persist nodes and edges, ensuring the graph database maintains consistency even when handling complex relationship creation.

Summary

• Direct note creation establishes an artifact edge to the notebook via Note.add_to_notebook().
• Insight conversion creates notes that maintain indirect source connections through the source_insight relationship chain.
• The graph structure uses SurrealDB to persist nodes (Note, SourceInsight, Source) and typed edges (artifact, source_insight).
• All relationship creation happens asynchronously in open_notebook/domain/notebook.py, with API routing handled in api/routers/notes.py.

Frequently Asked Questions

How does Open Notebook maintain relationships between notes and their source materials?

The system stores insights as SourceInsight nodes connected to Source nodes via source_insight edges. When converting an insight to a note, the original SourceInsight node remains in the graph, allowing traversal from the new note back to the source through the preserved relationship chain.

What is the purpose of the artifact edge in the Open Notebook graph database?

The artifact edge connects Note nodes to Notebook nodes, serving as the primary relationship that organizes notes within their respective notebooks. This edge is created when calling Note.add_to_notebook() or when the API endpoint processes a note creation request with a notebook_id parameter.

Can a note exist without being linked to a notebook?

Yes. While the API supports optional notebook linking via the notebook_id parameter, notes can be created as standalone nodes in the graph. However, the typical workflow in Open Notebook associates notes with notebooks through the artifact edge to maintain organizational structure.

Where is the logic for converting insights to notes implemented?

The conversion logic resides in open_notebook/domain/notebook.py within the SourceInsight.save_as_note() method (lines 776‑787). This method creates a Note instance from the insight's content, saves it to SurrealDB, and optionally links it to a notebook while preserving the connection to the original source.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}