DEV Community: Gauarv Chaudhary

I connected Contentful to Cognee. Importing content was the easy part.

Gauarv Chaudhary — Thu, 08 Oct 2026 16:41:59 +0000

Built for the WeMakeDevs × Cognee Mergetober 2026.

Imagine running an online store where hundreds of products are managed in Contentful.

You want an AI assistant that can answer questions about those products using Cognee's memory.

Getting the content into Cognee is one problem. Keeping that memory correct when someone edits or deletes a product is another.

Say a product's warranty changes from two years to one. Or the product gets discontinued entirely.

If Cognee still remembers the old information, your assistant could confidently give customers the wrong answer.

That was the problem behind Cognee issue #4787.

I built a Contentful connector that imports published content into Cognee, keeps it synchronized, and removes outdated information when the original content disappears.

What it actually does

The connector lives in cognee-community/packages/connector/contentful/.

It does five things:

Connects to Contentful using a Content Delivery API token.
Imports entries, asset metadata, and content models as documents Cognee can understand.
Syncs changes without downloading everything again.
Handles deletions so removed content doesn't remain in AI memory.
Keeps sources isolated so changing one selection doesn't affect another.

Content models are especially useful here.

Suppose an entry has a field called batteryLife with the value 12.

Twelve what? Hours? Days?

The content model provides the field's structure and description. Without that context, an AI system has less information to interpret the value correctly.

So the connector imports content models separately instead of just dumping entry values into documents.

One synchronization run. Entries and assets use the Sync API, while content models are fetched separately.

The tricky part: knowing when to forget

The obvious approach to synchronization is simple.

Fetch everything once, then use sys.updatedAt to find recently edited entries.

That works for updates.

But what about deletions?

A deleted entry won't appear in the normal listing anymore. A timestamp filter alone can't reliably tell Cognee which information it should forget.

That's why I used Contentful's native Sync API.

The first run imports the available content and saves a checkpoint. Later runs use that checkpoint to retrieve changes.

More importantly, Contentful also returns deletion events like DeletedEntry and DeletedAsset.

The connector turns those events into dlt hard-delete markers, allowing Cognee to clean up obsolete documents and their associated graph and vector data.

There's another detail I didn't want to get wrong: pagination.

If Contentful returns five pages and page three fails, the connector must not save the final checkpoint.

Otherwise, the next synchronization could skip changes it never processed.

So it follows every page before accepting the terminal sync token. If the response is incomplete, the run fails instead of silently losing information.

One source shouldn't delete another source's memory

Here's another situation.

Suppose one integration imports English product descriptions, while another imports articles in multiple languages.

Changing the first integration shouldn't touch the second.

I added a source_id to give each logical source its own synchronization state.

Changing filters under the same source ID triggers a selection refresh. The connector removes documents that no longer belong to that selection while preserving other sources.

Credentials are also kept separate from source identity.

Rotating an API token shouldn't mean importing the entire collection as a new source.

The failure case I cared about

A successful API request doesn't mean the whole synchronization succeeded.

Think about this sequence:

Contentful returns an update or deletion.
dlt successfully loads the change.
Cognee fails while processing or cleaning up its stored memory.
The next Contentful sync returns no new changes.

Now what?

If the connector only trusts the latest API response, that earlier failed work could remain unfinished.

The implementation relies on Cognee's retained dlt staging so a later run can reconcile existing records again, even when the provider returns an empty delta.

I also covered individual cleanup failures that Cognee logs without raising an exception.

That's the distinction that matters here: successfully loading a change isn't the same as successfully updating AI memory.

Proving it works locally

I wanted to test more than whether the connector could parse some JSON.

The important questions were:

Does updating an entry replace obsolete content?
Does deleting the final entry remove its memory?
Can two sources coexist without deleting each other's data?
Can an interrupted ingestion recover on the next run?

The October 8 local verification report recorded 94 passing tests.

Tests	Coverage
87	Contentful provider behavior, synchronization, and dlt
7	Real local Cognee ingestion, storage, deletion, and recovery

The same 94 tests passed on Python 3.11, 3.12, and 3.13, plus another Python 3.12 run with the newest permitted dependencies.

Eight relevant upstream Cognee regression tests also passed, along with Ruff checks and package builds.

Local test evidence. Contentful responses and model operations were mocked; SQLite, Ladybug, and LanceDB storage paths were exercised for real.

That distinction is important.

These tests provide evidence of local correctness, including deletion from relational, graph, and vector storage. They don't yet prove authenticated Contentful lifecycle behavior.

How to try it

The implementation is available in my Contentful connector branch.

From the connector directory:

uv sync --locked

Configure your Contentful space and Delivery token:

export CONTENTFUL_SPACE_ID="your-space-id"
export CONTENTFUL_DELIVERY_TOKEN="your-token"
export CONTENTFUL_ENVIRONMENT_ID="master"
export LLM_API_KEY="your-model-key"

Then run:

uv run python examples/example.py

The example synchronizes published content into Cognee and runs a search query.

You can select specific content types and languages, or disable asset ingestion. Subsequent runs synchronize changes for the same source.

For example, a product-catalog application could import descriptions, search for products matching a customer's requirements, and refresh its memory after catalog edits.

That's an illustrative use case. A live Contentful-to-Cognee demonstration is still needed to establish real-provider behavior.

What it doesn't do

A few limitations worth mentioning:

It reads published content, not drafts.
It imports asset metadata, not image or video contents.
It doesn't recursively expand every linked entry.
It doesn't include a built-in scheduler.
Authenticated Contentful import, update, unpublish, and deletion are not yet live-verified.

An invalid synchronization checkpoint also requires deliberate recovery rather than an automatic destructive reset.

What I'd take away from this

Importing data once is straightforward.

Keeping it correct when the source changes, an entry disappears, or processing fails halfway through is the harder problem.

The useful lesson from this connector is that synchronization needs to account for both sides: what the source says changed, and what the destination actually finished processing.

Otherwise, everything can appear to work while the AI is still remembering yesterday's information.

Code and references

Built as part of WeMakeDevs × Cognee Mergetober 2026.

I built a OneNote connector for Cognee. Importing notes was the easy part.

Gauarv Chaudhary — Thu, 08 Oct 2026 11:19:46 +0000

Built for the Cognee community connector hackathon → issue #4727.

Say you're working on a project. You've got architecture decisions in one OneNote section, meeting notes in another, and a few pages explaining why you abandoned certain approaches.

Two months later, someone asks a simple question:

"Why did we choose this approach instead of the other one?"

You know you wrote it down somewhere.

Now you have to remember which notebook it was in, which section you used, and what you called the page.

That's the situation I had in mind when I picked up Cognee issue #4727.

OneNote already does a good job of storing and organizing notes. I wasn't trying to replace it. I wanted to make those notes available to Cognee, so someone could ask a question and retrieve information from the pages they'd already written.

But there was another problem I hadn't wanted to ignore.

What happens when those notes change?

If someone edits a decision, moves a page, or deletes something entirely, the searchable memory shouldn't keep treating the old version as the truth.

That turned out to be the more interesting part of the implementation.

Here's what I built.

Code: OneNote connector implementation

What it actually does

The connector lets you select specific OneNote notebooks and bring their content into Cognee's document-memory pipeline.

The workflow looks like this:

Sign in using Microsoft Graph's delegated authentication.
Choose the notebooks you want to use.
The connector walks through notebooks, sections, nested section groups, and pages.
It converts the page HTML into readable text while preserving notebook and section context.
Cognee processes the documents so their content can be retrieved later.

The important part is that you choose what gets ingested.

You don't have to import every notebook in your account just because you connected Microsoft.

And the context matters.

Imagine two pages both called "Database."

One is inside Prototype / Experiments. The other is inside Production / Architecture.

Without that context, they're just two documents with the same title. The connector includes the notebook and section path in the searchable text, so the original location isn't lost.

It also preserves existing image alt text and resource references. It doesn't download binary images or attachments.

Getting it running

I kept this as a Python connector rather than building another dashboard.

That's also what the issue asked for: a package, documentation, a runnable example, and tests. No new frontend was needed.

The implementation lives in packages/connector/onenote/ in cognee-community.

With Python 3.11–3.13 and uv, the setup starts with:

cd packages/connector/onenote
uv sync --locked --group dev

Connecting your Microsoft account

There's one detail worth explaining here.

Microsoft's OneNote API doesn't support app-only authentication. The connector needs delegated access, meaning it works on behalf of a signed-in user.

The example uses MSAL's device-code login flow.

You register an application in the Microsoft Entra admin center, enable public-client authentication, and add the delegated Notes.Read permission. Depending on your organization's settings, administrator consent might be required.

Microsoft documents the authentication requirement here.

After registering the app:

export MICROSOFT_CLIENT_ID="your-application-id"
export MICROSOFT_TENANT_ID="common"

uv run --frozen python examples/onenote_example.py

The first run is designed to guide you through authentication and list the notebooks available to your account.

Then you choose one or more notebook IDs.

export ONENOTE_NOTEBOOK_IDS="your-notebook-id"
export ONENOTE_DATASET="onenote-project-demo"
export LLM_API_KEY="your-provider-key"
export ONENOTE_QUESTION="Why did we choose this project approach?"

uv run --frozen python examples/onenote_example.py

You'll also need to configure Cognee's LLM and embedding providers appropriately.

The example is designed to ingest the selected notebook, process its documents, and run the question.

For a first experiment, I'd use a disposable notebook with a decision and its explanation, rather than importing personal notes immediately.

For example, a hypothetical page might say:

We chose local storage for the first prototype because users needed to work without an internet connection.

Then ask:

"Why did we choose local storage?"

The result should be grounded in that page, not in a generic explanation of storage options.

This is an example of the workflow, not a result from a completed live Microsoft test.

The part that needed more thought: synchronization

Importing documents once is only half the job.

Suppose you wrote that your project uses SQLite. A week later, you switch to PostgreSQL and update the explanation in OneNote.

If Cognee still retrieves the old explanation, having searchable notes hasn't really solved your problem.

So I needed the connector to handle repeated synchronization.

Here's how that works.

Every sync checks the metadata of the selected notebooks. Each OneNote page has a lastModifiedDateTime value, which helps determine whether its content needs to be fetched again.

If the page hasn't changed, the connector can reuse its cached body.

If it's new or modified, the connector fetches its HTML again.

One distinction matters: this is incremental content fetching, not a delta-only metadata feed. The connector still enumerates the selected notebooks to determine what's present.

There's another edge case.

What if you rename a section without changing the page itself?

The page text might be identical, but its location has changed.

So the connector caches the page body separately and rebuilds the notebook and section context from current metadata.

That way, a rename doesn't require downloading an unchanged page body just to update its location.

And if a timestamp changes without changing the actual emitted document, the document identity can stay the same.

Less unnecessary processing, while keeping the stored context up to date.

Deleting a page is where things get risky

This was the part I wanted to get right.

Imagine Cognee has already ingested 50 pages from a notebook.

On the next sync, Microsoft Graph returns only 30 because a request failed partway through pagination.

If the connector blindly assumes the missing 20 pages were deleted, it could remove perfectly valid information.

That's a pretty bad outcome for something that's supposed to help you remember things.

So the connector doesn't treat a missing listing entry as proof of deletion.

It checks previously known missing pages directly and considers the API's error responses and the surrounding notebook context.

Microsoft has different OneNote error codes for deleted resources, nonexistent resources, invalid identifiers, and access problems.

Those differences matter.

A confirmed deletion can lead to removing obsolete memory after successful reconciliation.

A permission failure or ambiguous response shouldn't.

The connector also handles a case that's easy to overlook:

What happens when you delete the very last page?

An empty Python generator isn't necessarily enough to make a loading system replace an existing table with an empty one.

For the final-page case, the implementation uses DLT's empty-table materialization marker:

if notebook_rows:
    yield from notebook_rows.values()
else:
    yield dlt.mark.materialize_table_schema()

That explicitly represents an empty notebook table instead of creating a fake blank document.

There are also deliberate boundaries.

Deselecting a notebook doesn't automatically delete its previous memory. A page moved outside the selected scope retains its earlier ingested copy with a warning.

Those choices may sound conservative, but I'd rather have a connector report uncertainty than silently delete data because an API request failed.

What I actually tested

I didn't want to stop after checking whether the connector could parse a page.

The important cases were the ones where something changed or went wrong.

For local verification, I tested the connector using mocked Microsoft Graph responses and mocked external model calls.

The storage layer wasn't mocked.

Five integration tests exercised real SQLite, Ladybug, and LanceDB persistence and retrieval.

The tests covered things like:

Deleting the final page and checking that its owned stored artifacts disappear.
Updating a document without retaining the obsolete version.
Recovering from a processing failure on a later sync.
Retrying cleanup after an earlier failure.
Keeping shared graph information that still belongs to another document.

66 package tests passed locally on Python 3.12.

Another 24 nearby Cognee regression tests also passed, along with lint, formatting, package-build, and wheel-import checks.

The five persistence integration tests also passed separately.

The package suite can be run with:

uv run --frozen pytest tests -ra

The captured local test runs also reported warnings, so the passing summaries shouldn't be read as proof that every possible environment is free of issues.

And one limitation is important enough to say separately:

I haven't completed live Microsoft validation yet.

That means I haven't demonstrated the full sign-in, notebook selection, edit, and deletion workflow against a real Microsoft account.

The tests exercise the behavior with controlled Graph responses and real local storage. They don't prove that Microsoft's live API will behave exactly like the mocks.

Hosted GitHub Actions CI validation is also still pending in this report.

I don't want to turn a successful local test run into a claim about something I haven't tested.

Things it doesn't do

A few boundaries are worth knowing before using this on important notes.

There's no dedicated OneNote dashboard. This contribution is a Python data-source connector. Authentication and notebook selection are handled through the example and API.

It doesn't download attachments. Existing image descriptions and resource references are preserved, but binary attachments aren't ingested.

It doesn't perform a delta-only metadata sync. Each run enumerates the selected scope, while unchanged page bodies can come from the cache.

Processing isn't one atomic transaction. Snapshot validation, staging, document ingestion, graph processing, and cleanup happen in separate stages. If later processing fails, rerunning the same selection is the recovery path.

It needs persistent state. Cached notebook bodies and sync state are stored locally. That state can contain sensitive notes and should be protected.

Concurrent syncs are limited. The current supported usage is one active sync per account and dataset scope.

These aren't things I'd hide behind a nice screenshot. They're part of knowing what the connector can safely do.

What I'd take away from building this

The issue looked like a straightforward integration task at first: authenticate, fetch pages, convert HTML, send documents to Cognee.

But a useful connector has to answer a harder question:

When the source changes, what should happen to the information we've already stored?

Fetching a page is one operation.

Knowing when to reuse it, update it, or safely forget it requires a lot more care.

That's what most of this contribution ended up focusing on.

The implementation is available in the community repository, with local tests passing and live Microsoft validation still to be completed.

If you're interested in how it works, the code and tests are here:

Repository: https://github.com/topoteretes/cognee-community

Implementation: https://github.com/ANAMASGARD/cognee-community/tree/feat/4727-onenote-connector/packages/connector/onenote

Issue: https://github.com/topoteretes/cognee/issues/4727