DEV Community: Gauarv Chaudhary

I built an agent that refuses to connect two files unless the graph already did

Gauarv Chaudhary — Sun, 18 Oct 2026 18:23:29 +0000

Built for the WeMakeDevs × FalkorDB Graph Hacks hackathon. Track: Agents That Act on Connected Data.

There are two ways to ask an AI about a codebase you never read, and both of them are wrong.

The first hands the repository to a model and lets it describe the structure. It is fast, and a dependency that is ninety percent right is worse than no dependency, because there is no way to tell which ten percent is wrong. The moment a model is allowed to guess an edge, every edge becomes a maybe.

The second draws a picture. Folders as boxes, imports as lines, a canvas you can pan. If you take the database away and the picture still answers "what imports this?", the database was decoration. Graph Hacks says that in the rules, and it should. A visualisation on top of ordinary storage does not qualify.

I wanted the picture and the answer to be the same object. A parser reads the TypeScript and JavaScript and proves each edge. FalkorDB stores those edges. The agent may only ask questions that graph can answer, through tools that run fixed queries. It does not get to write Cypher. It does not get to say two files are connected because that seems likely.

That is Graph Verse.

Repo: https://github.com/ANAMASGARD/graph-verse

Live: https://graph-verse.vercel.app/

What it actually does

You paste a public github.com/owner/name. No token. Nothing private.

Graph Verse then, on its own:

Fetches the public tarball and records the commit.
Parses the tree. A resolved import, re-export, dynamic import(), or require() becomes an edge. An import it cannot resolve is counted, with a reason, and is never stored as a line.
Writes the result into that team's FalkorDB graph. One graph per Clerk organization. Switching team switches graph. There is no organization column to filter on.
Draws the map from those nodes. Click a file and the detail pane is a walk of the edges already stored: what it imports, what imports it, what sits two hops out.
Lets you ask, in a panel that shows each tool call as it happens.
Stops the model from inventing a path. If a tool did not return a path, that path is not in the answer.

Step 6 is the whole project. Everything before it is there so the agent has a graph worth walking.

The part I care about: the edge is real

Anyone can tell a model "only use real imports" and hope. That is a convention. The model can ignore it. A later prompt can soften it. The answer still looks confident.

In Graph Verse the split is structural.

The parser does not know Next, React, or FalkorDB exist. It takes a directory and returns files, edges, and a coverage report. An edge exists only when a specifier resolved to a file that is actually in the tree. IMPORTS, RE_EXPORTS, DYNAMIC_IMPORT, and REQUIRES are the only ways two files get connected.

The agent does not see the database. It is a separate process. It is never told which analysis it is reading. A short-lived credential, minted on the server, names one organization and one analysis. The six tools call back into the app, and the app runs one fixed query each:

summary of the repository
search by part of a path
list files by role
direct neighbours
a walk of at most two hops, in or out, including a shortest chain between two files
the route table

The walk is Cypher, variable length, capped at two:

MATCH (a:Analysis {id: $id})-[:HAS_FILE]->(start:File {path: $path})
MATCH p = (start)-[:IMPORTS|RE_EXPORTS|DYNAMIC_IMPORT|REQUIRES*1..2]->(other)
WHERE other <> start
RETURN other.path AS path, length(p) AS depth
ORDER BY depth, path

If the question needs a third hop, the instructions say to walk again from a file the first walk returned. They do not say to guess the rest.

The browser never opens FalkorDB. If the agent process is down, the map, the blast radius, and Explain still work, because those read the same stored edges. If FalkorDB is down, none of them work. That is the test I kept using. A product that still answers with the graph removed has a picture, not a graph.

How FalkorDB fits

I want to be precise, because "we used the sponsor database" can mean a logo in the README.

FalkorDB is the context layer. My code does not walk the import graph in memory and then draw the result. The relationships are the product.

Four things it actually does:

One graph per team. selectGraph(orgId) opens the Clerk organization's graph. Two teams on one instance do not share nodes. Tenancy is which graph you opened, not a WHERE clause.
The traversals the UI and the agent share. Neighbours, blast radius, dependency chain, and the agent walk are the same four relationship types. Fan-in and fan-out are counts stored on the file. Who depends on a file is a query.
Routes as nodes, only when both ends are known. A route is a :Route with a method, a path, and a line, linked HAS_ROUTE and DEFINED_IN. If the parser cannot recover both the method and the full path, it stores none. A wrong route is the same failure as an invented edge.
Memory in that same graph. An explanation is written from the file and its real neighbours, then stored on an :AiCache node. The next request for the same explanation is a graph read. Each Ask is stored as an :Inquiry on the analysis: the question, the thread, and the paths the tools returned. The next session can show how an earlier answer was reached. That is the memory. It is not a chat log in the browser.

src/components/Layout/index.tsx in xizon/fullstack-nextjs-app-template is a file a lot of other files import. What it itself imports is this, not a sentence the model felt like writing:

MATCH (p:Project {repoOwner: 'xizon', repoName: 'fullstack-nextjs-app-template'})
      -[:HAS_ANALYSIS]->(a:Analysis)
      -[:HAS_FILE]->(f:File {path: 'src/components/Layout/index.tsx'})
      -[r:IMPORTS|RE_EXPORTS|DYNAMIC_IMPORT|REQUIRES]->(other:File)
RETURN type(r) AS kind, other.path AS path, r.specifier AS specifier
ORDER BY path

That returns BackToTop, Footer, Header, MultilevelDropdownMenu, and src/store/actions/demoMenuActions.js. If the agent names a sixth file, it is wrong, full stop.

Proving it is not pattern-matching

One happy question proves nothing. Ask "what imports this?" on a file whose name is Header and a model will invent a reasonable list. It will look like the tool worked.

So the checks disagree with each other.

The lookup. Ask what Layout imports. The answer is allowed to contain only paths a tool returned. The five files above are the list. A sixth name, however plausible, fails. There is a separate check that does the same thing to explanations: any token that looks like a source file must have been in the set the model was shown. Score is 1 or 0. A model does not grade the model.

The refusal. Ask it to grade the code. Say whether a file is good, safe, or well written. The instructions are to decline in one sentence and say what it can answer instead: where a file is, what it imports, what imports it, what sits two hops out, which routes exist. If it writes a review, the run failed. The product explains a codebase. It does not score one. A score is how people stop reading the map.

Same agent. Same tools. Same graph. One question must come back with those five paths. The other must come back with no opinion at all.

What went wrong

Almost none of this was the model being clever. The failures were the system letting a guess look like a fact, or hiding the graph I had just stored.

Clicking a box made the map vanish. Opening a folder recenters the camera on that one node. The rest of the graph left the viewport, which feels exactly like a delete. On top of that, React Flow will draw nothing if its parent has no height, and the canvas was sizing itself from content that is positioned absolutely. The parent collapsed, the library logged that it had no width and no height, and the edges were gone. The fix was to give the canvas the space under the header, and to fit the whole graph after a folder opens, not one box.

The dashboard crashed on a team with no graph yet. Listing analyses used a read-only query. FalkorDB answers that with Invalid graph operation on empty key when that organization's graph has never been written. A session refresh then sent the browser to /dashboard instead of back to the analysis, and the error overlay replaced the map. An empty team is an empty list. It is not an exception.

The agent would not even compile. The dev server refreshes a lockfile and tries to fetch an optional WebAssembly package. npm on this machine refuses remote tarballs unless you allow them. The agent is a separate service. Until that fetch was allowed, Ask had no process to talk to, and the map was the whole product. Which is fine. Ask is allowed to be down. The map is not allowed to lie.

Progress could not use the database's pub/sub. The FalkorDB user cannot SUBSCRIBE. Analysis progress is a server-sent event on an in-process bus, after the server has checked that the analysis id is in the current organization's graph. The browser still never opens a database connection.

Every one of those would have left a demo that looked finished while the claim was soft. The happy path, a map with lines on it, works either way.

What I would tell you if you are building one of these

Put the edge in the parser, not the prompt. "Please do not invent imports" is a wish. A resolved specifier written as a relationship is a property of the system. If your graph story depends on the model cooperating, you do not have a graph.

Build the question your agent should get wrong. "What does Layout import?" is the easy one, and it can be faked. "Grade this file" is the one that shows whether the refusal is real.

The strings you return from a tool are the only nouns the model is allowed to use. A path that was not in the tool result does not get to appear because it would make a nicer sentence.

When the agent behaves strangely, suspect the instruction that was quietly wrong about the world. The two-hop cap is one of those. Past two hops it must start again from a file it already has, and say so. Letting it "just continue" is how invented files come back.

What it does not do

It does not score, rate, or review the code.
It does not open private repositories. Public GitHub URLs only.
It does not parse languages other than TypeScript and JavaScript.
A walk is two hops. Farther than that is another walk, from a file the first one returned.
A route is stored only when both the method and the full path come back from the syntax.
Ask needs the agent process running. With it stopped, the map, the blast radius, and Explain still answer from the stored edges.

Try it

https://graph-verse.vercel.app/

Sign in, create or pick an organization, paste a public repository, and wait for the four stages. Then ask what a file imports, and ask it to grade that file. The first answer should be a list of paths. The second should be a refusal.

The video is the same run: https://youtu.be/hz-TFz4LJ4I

Source: https://github.com/ANAMASGARD/graph-verse
The graph model, the decision that the parser proves edges and FalkorDB walks them, and the checks above are the part I had to be able to explain without them.

I built a Read.ai connector for Cognee. Importing once wasn’t enough

Gauarv Chaudhary — Wed, 14 Oct 2026 19:13:21 +0000

Built for WeMakeDevs × Cognee Mergetober.

A meeting report says the launch is on Friday. Someone corrects it to Monday. Your assistant still retrieves Friday.

Nothing crashed. The import worked. The copy is just out of date.

That is the problem behind the Read.ai connector I built for Cognee: importing meeting reports is useful, but those reports do not stop changing once they reach your database.

The demo below uses fictional reports and synthetic model responses with real local Cognee storage. The screenshots are evidence views, not a new chatbot interface or a production deployment.

What it actually does

Choose meeting IDs or a date range, then choose whether to include summaries, transcripts, and metrics. Each available report becomes one document, with the summary first and the transcript last. Participant names, timestamps, and the report link keep the surrounding context attached. Pasted text

The supported workflow runs through sync_read_ai(...), which handles ingestion, recovery, Cognee processing, and cleanup verification. You can then search the selected dataset. Pasted text

For a project assistant, the intended benefit is straightforward: make meeting context searchable and refresh it on subsequent syncs, instead of manually exporting and uploading reports after every correction. The connector supplies the documents; it does not decide which of two conflicting decisions is authoritative.

Authentication uses OAuth 2.1, not the API-key wording in the original issue. The read-ai-connect command handles setup, and token refresh is process-locked so concurrent runs do not refresh the same credential simultaneously. Pasted text

An old meeting can still contain a new edit

The tempting approach is to fetch only meetings newer than the last sync.

But correcting last month’s summary does not change last month’s meeting date. Read.ai’s documented date filters use meeting start time, not report modification time. A date-only cursor would miss that correction.

So the connector uses full upstream reconciliation with incremental downstream processing.

In plain English: recheck the selected reports, render their content consistently, and compare hashes. Under normal operation, send only new or changed content downstream.

This avoids repeated extraction and embedding work for unchanged documents. It does not avoid rereading the selected reports from Read.ai. Pasted text

The successful checkpoint comes last—after ingestion, Cognee’s processing step, and verification. Loading data into staging is not the same as finishing the sync. Pasted text

The implementation flow. Incomplete reconciliation stops before new staging changes; later failures can leave unfinished work without advancing the successful checkpoint.

Two reports, then the changes that matter

The local demonstration starts with two fictional reports: a Friday launch plan and a support handover. Both become searchable documents.

Run the same selection again, and both Data IDs stay the same. The measured synchronization deltas are zero extractions and zero embeddings. Those counters are checked before another search, so query work is not mixed into the sync measurement.

Next, the launch report changes from Friday to Monday. Its meeting ID stays the same. One document changes, the other stays unchanged, and the old document’s references and chunk vectors are removed.

The retrieved chunk contains:

Alphacorp and Sharedcorp moved the launch to Monday after the security review.

That is stored report text, not a generated answer.

Then the launch report is removed from the synthetic provider. Its document and owned chunks disappear during that sync. The handover report and the shared entity it still references survive.

Finally, a simulated 403 permission failure leaves the sync incomplete and preserves the previous corpus and successful checkpoint.

Synthetic reports and model responses, real local storage. The five phases check updates, reuse, removal, and failure handling—not the quality of a real model’s answers.

Missing is not enough evidence to delete

For a date-based selection, a previously imported report must be absent from a complete inventory, return 404 on retrieval, and remain absent from a second complete inventory. All of that happens within the same sync attempt. Explicit-ID selections use two detail requests.

A broken page or permission error is not treated as a deletion instruction.

There is a trade-off: previously imported content can remain locally accessible while permissions are uncertain. This is not complete access-control synchronization. Pasted text

What passed—and what still needs work

The fresh run shown below reports 149 passing tests on Python 3.12.15, with no failures, errors, or skips. Ruff lint, formatting, and the existing offline example also passed. The test run emitted 1,559 warnings.

This run used Cognee 1.6.4, dlt 1.30.0, SQLite, Ladybug, and LanceDB. Only Python 3.12 was exercised in this particular evidence run.

An earlier harness attempt had setup errors. The screenshot records those separately: the external scripts were corrected, the original logs retained, and the connector tests left unchanged.

Fresh local verification for commit 130f52d34ec2. Provider and model responses are synthetic; this is not hosted CI or live-provider acceptance.

There is also a known Cognee 1.6.4 cleanup limitation. A relationship-type vector can remain after its graph node is removed if vector deletion fails. A later retry does not automatically repair it.

The connector detects that leftover vector, raises VerificationError, and refuses to advance the successful checkpoint. Repair still requires a core change or independently verified operator intervention.

A passing test that detects this failure does not mean the failure is fixed. Pasted text

Live Read.ai OAuth, report edits, field availability, and deletion/permission transitions remain unverified. The local results should not be read as proof of a production-ready integration. Pasted text

I built an Airtable connector for Cognee. The hard part was knowing what to delete.

Gauarv Chaudhary — Fri, 09 Oct 2026 06:23:23 +0000

A project record gets deleted. Its old context should leave Cognee on the next successful sync.

An Airtable request fails. The last successfully imported data should stay.

Those are opposite outcomes. A connector that reduces both to “nothing came back” can either keep obsolete information or erase information it was never told to delete.

That distinction shaped my contribution to Cognee issue #4766 for WeMakeDevs × Cognee Mergetober. After assignment, I added the Airtable connector in cognee-community, without changing Cognee core. There is also an earlier Airtable proposal, PR #198, which deserves acknowledgment. Pasted text

A handover question, not another export

Consider a team keeping project owners, blockers, and decisions in Airtable. During a handover, someone asks:

What is blocking the project handover?

An export can answer that question once. A useful integration needs to keep the answer’s supporting information current as fields and comments change.

The connector turns selected records into documents, including comments when enabled. Table schemas—the descriptions of the fields—become separate documents. Pasted text

The demonstration here uses synthetic project facts, mocked Airtable responses, and deterministic model outputs, with real SQLite, Ladybug, and LanceDB storage. These are local verification reports, not a live Airtable deployment. image(20261009-051147)

Change the comment. Leave the timestamp alone.

The first capture retrieves this passage:

The blocker is AmberPermit approval.

After a comment-only edit, the retrieved passage becomes:

The blocker is TealCertificate approval.

The record timestamp stays at 2026-01-01T00:00:00Z. Neither distinctive fact appears in the question.

Finding the replacement is only half the check. The report also checks that AmberPermit is absent from the graph and vector storage, while TealCertificate appears in retrieved passages. All nine assertions in this scenario passed.

Comment-only update with an unchanged timestamp. These are selected CHUNKS retrieval excerpts, not generated answers. Airtable and model responses are controlled substitutes; storage is real.

Why the connector reads more than it writes

The implementation keeps per-table modified-time watermarks, but timestamps do not decide everything. Comments and schema need independent checks; computed values, blank timestamps, and restored records complicate timestamp-only filtering.

The design is full source reconciliation with incremental document emission: read the complete selected source, compare it with persisted document fingerprints, then emit changed documents and confirmed deletion markers.

That means incremental writes, not an API request that fetches only changed records. Pasted text

The documents themselves are normalized consistently. Field and comment ordering is deterministic. Cursor values and temporary attachment URLs are excluded, so those transport details do not become artificial content changes. Pasted text

The example passes this configuration to remember():

dlt_config={
    "primary_key": "id",
    "write_disposition": "merge",
    "max_rows_per_table": 0,
}

Explicit merge keeps unchanged documents in staging—the intermediate storage before Cognee processes them. Cognee’s default replace would discard those unchanged staged documents. The unlimited read keeps the retained document set available for reconciliation. Pasted text

Two empty-looking outcomes that must disagree

In one fixture, a selected table is emptied successfully. Its known record rows are removed, but three Cognee documents remain: that table’s enabled schema, an independent control record, and the control table’s schema.

Zero records in one table does not mean zero documents everywhere.

In the contrasting fixture, an earlier table read succeeds, but a later required comments request returns HTTP 403. The connector aborts before publishing the partial result. Existing staging, connector state, and documents remain unchanged.

Two separate local scenarios: a confirmed empty table removes records; a failed required read preserves the prior state. The report records 23/23 and 14/14 passing assertions respectively.

Required reads finish before any changes are emitted. Only a complete inventory is used to identify missing records. A confirmed disappearance of a previously synchronized, still-selected table removes its records and schema. Deselecting a table, however, preserves its earlier imports. Pasted text

Completing pagination is still not the same as obtaining a transactionally consistent upstream snapshot.

Recovery worked in specific tests. One result remains unexplained.

Staging can succeed before Cognee stores or processes the documents. In the captured storage-failure scenario, an unchanged retry brings the staged SilverRunbook fact into document storage without another upstream edit.

Cleanup has a more important caveat. With an injected deletion failure, remember() reports completed while stale graph content remains. The isolated cleanup retry and final chained capture passed.

An earlier chained attempt did not. Document/vector content remained, and the second process exited with -11. The report explicitly preserves that inconsistency. A later passing run does not establish its cause or demonstrate that it has been fixed. image(20261009-051204)

The supported claim is recovery in the recorded successful scenarios—not that cleanup recovery is consistently reliable. The unexplained failure still needs investigation.

What the local checks actually say

The October 9 report for revision 862c98b09bbb records 107 passing tests on Python 3.12, with no failures, errors, or skips. Python 3.11 compatibility records 97 passes, and targeted core checks record 33.

Another available regression group records 25 passes and one skip; the broader connector-regression check is marked blocked. Lint, formatting, package build, and installed-wheel smoke checks passed. Compatibility reruns are not additional unique tests.

These results concern the local fixture setup. Live Airtable behavior, real-model answer quality, and hosted CI remain unverified in this report. image(20261009-051205)

Try the handover workflow

Use a disposable base. Give its Personal Access Token data.records:read and schema.bases:read, plus data.recordComments:read when comments are enabled. Pasted text

Add a Last modified time field to each selected table, tracking All editable fields with time included. Check that setting in Airtable’s interface; the connector cannot conclusively establish it from metadata. Pasted text

From packages/connector/airtable/ on the implementation branch, configure Cognee’s model providers as described in the README, then run:

uv sync --frozen --all-extras --python 3.12

export AIRTABLE_ACCESS_TOKEN="your-personal-access-token"
export AIRTABLE_BASE_ID="appYourBaseId"
export AIRTABLE_TABLE_IDS="tblYourTableId"
export AIRTABLE_QUESTION="What is blocking the project handover?"

uv run --frozen python examples/example.py

Add a distinctive blocker, retrieve it, edit only its comment, and run the example again. Then delete a record and check what remains. The example retrieves dataset-scoped passages; it does not generate an answer or run continuously.

Full reconciliation reads unchanged records and enabled comments, so polling large tables has a cost. Select only needed tables and disable unnecessary comments. Attachments contribute stable metadata, not downloaded file contents. Pasted text Pasted text

Importing the new fact is the visible part. Removing the old one—and knowing when not to—is the harder requirement.

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