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

> Discover how Open Notebook's note creation links your sources and insights using SurrealDB's graph database. Explore artifact and source_insight relationships for better knowledge management.

- Repository: [Luis Novo/open-notebook](https://github.com/lfnovo/open-notebook)
- Tags: how-to-guide
- Published: 2026-06-07

---

**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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.

```python

# 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`](https://github.com/lfnovo/open-notebook/blob/main/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.

```python

# 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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/open_notebook/domain/notebook.py), with API routing handled in [`api/routers/notes.py`](https://github.com/lfnovo/open-notebook/blob/main/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`](https://github.com/lfnovo/open-notebook/blob/main/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.