cognee 的 Asana 連接器：修正首次版本的刪除判斷錯誤

My Asana connector for cognee got merged during Mergetober. It's a small package, but it taught me more about syncing data than anything I've built before.

What it does

cognee turns your documents into a knowledge graph you can ask questions. My connector is a dlt source that feeds it your Asana projects. Every task becomes a document with its notes, custom fields, subtasks and comments, and each project description becomes one too. Then you can ask things like "what's blocking the website launch?" and the answer covers all your tasks, not just the one you happen to have open.

Setting it up

It isn't on PyPI yet, so you install it from the cognee-community repo:

git clone https://github.com/topoteretes/cognee-community
cd cognee-community/packages/connector/asana
uv sync --all-extras

Create a personal access token in Asana under Settings > Apps > Developer apps, and export it as ASANA_ACCESS_TOKEN along with your usual LLM_API_KEY. Your project gid is the number in the project URL. Then:

await cognee.remember(
    asana_source(project_gids=["1201234567890123"]),
    dataset_name="asana",
    primary_key="id",
    write_disposition="merge",
    max_rows_per_table=0,
)

write_disposition="merge" matters. The default, replace, would drop every document that isn't sent again, and after the first run the connector only sends what changed. The connector only ever sends GET requests, so it can't change anything in your workspace.

The surprise: edits that Asana doesn't report

I tested this on a free workspace. Adding a comment updates a task's modified_at. Editing a comment doesn't. Adding a subtask does, but renaming or deleting one doesn't. So a "fetch what changed since last time" cursor quietly misses those edits.

The fix was Asana's Events API. It does report edited comments, so the connector uses it on top of the cursor. An edited-comment event doesn't say which task it belongs to, so the connector looks it up through the event's target. For subtasks, it keeps a small map from subtask to parent, because a deleted subtask returns 404 and can't tell you its parent anymore.

The hard part: when is it safe to forget something?

If a task disappears from the project listing, it's deleted, and the connector forgets it. The tricky case is a task that's still listed but returns 403 when you fetch it. Was it hidden from you, did your token lose a permission, or is Asana just having a bad minute? Only the first is a reason to forget it.

My first version stopped the run after three failures in a row. goran-radonic, the maintainer, showed me that three permanently hidden tasks next to each other would then break every future run, and new tasks would never come in. That was a real bug, and a fair catch.

The merged version only forgets a task after three runs over at least 24 hours, and only in runs that proved access to other tasks works. Runs that stop early don't count. An outage or a lost permission never deletes anything.

Other things the review fixed

A token with a trailing newline made requests raise an error that included the token. Now errors carry only the status and endpoint.
A Retry-After of a full day would have slept while cognee holds its lock. Waits are now capped at 60 seconds, with 120 seconds in total per run.
Asana OAuth tokens last an hour, so a 401 halfway through a long first sync now stops cleanly and the next run continues.

Trying it for real

I ran the example twice on my own Asana workspace. Between the runs I edited a comment and deleted a task. The second run fetched just the edited task, and the deleted one was gone from cognee's answers. 109 tests pass locally on cognee 1.6.2 and 1.6.5.

The review made the code a lot better than what I first submitted. Thanks, goran.