Linear

​

What It Does

• Installs as an agent, not a bot user. The authorize URL carries actor=app, which puts an app user — the agent’s identity — into the workspace. The app:assignable and app:mentionable scopes are what let members delegate issues to it and @mention it. Requested scopes are read,write,app:assignable,app:mentionable.
• Answers agent sessions from memory. A mention or a delegation opens an agent session; Cognee runs a HYBRID_COMPLETION search across every dataset the connecting user can read — not just the Linear one — and replies inside the session.
• Indexes the workspace’s issues. Issue creates and updates are remembered as plain text in one dataset per workspace, plus a backfill of recent issues at install time.
• One workspace, one Cognee user. The credential is owned by whoever completed the install, and answers come from that user’s memory.

​

Prerequisites

• A Cognee dev checkout — see the version note above.
• A running Cognee backend reachable over HTTPS from the public internet: Linear delivers webhooks and the OAuth redirect to it and will not call localhost. For local development use a tunnel (ngrok or similar) — see the Slack integration’s ngrok section, which applies verbatim; for production this is your deployment’s normal public domain.
• Permission to create an OAuth application in the target Linear workspace.

​

Setup

​

1. Create the Linear OAuth app

​

2. Configure Cognee

​

3. Install and connect

# Mint the authorize URL (authenticated as the Cognee user who will own the data)
curl -X POST https://<public-host>/api/v1/integrations/linear/authorize \
  -H "Authorization: Bearer <your-cognee-token>"
# {"authorizeUrl":"https://linear.app/oauth/authorize?...&actor=app&scope=read,write,app:assignable,app:mentionable"}

​

What Gets Indexed

Linear issue ENG-42: Rate limiter drops bursts
URL: https://linear.app/acme-corp/issue/ENG-42
State: In Progress
Description: ...

import cognee

results = await cognee.recall(
    "What is the status of the rate limiter work?",
    datasets=["linear_acme_corp"],
)

​

Answering Agent Sessions

1. Posts a thought activity immediately — “Searching cognee memory…” — before any search or LLM work. Linear requires an activity within 10 seconds of a created event or it marks the session unresponsive, and a HYBRID_COMPLETION search routinely takes longer than that.
2. Builds the query. Linear’s own promptContext (its digest of the issue and prior comments) and workspace-level guidance are prepended to the user’s question, so retrieval is grounded in what the session is about. On a prompted event the question is the new message; on a created event it is the triggering comment, or — for a delegation, which has no comment — the issue’s title and description.
3. Searches memory with HYBRID_COMPLETION across every dataset the connecting user can read, keeping the top three answers and discarding per-chunk completions that are really refusals (“no relevant information…”).
4. Posts a response activity with the answer, which completes the turn.

​

Keeping It in Sync

​

Webhook Security

• Keep the Cognee host’s clock in sync (NTP). More than a minute of drift rejects every delivery even though its signature is perfect.
• Rotating the signing secret is a two-sided change. Deliveries signed with the old secret fail the HMAC, so rotate on Linear and update LINEAR_WEBHOOK_SECRET together and restart the backend. Because the same secret also signs the OAuth state, an install that is mid-flight during a rotation lands on ?linear=error_invalid_state; just mint a fresh authorize URL.

​

Disconnect vs. Uninstall

• Disconnect in Cognee — DELETE /api/v1/integrations/linear/connection — marks the stored credential revoked, so agent sessions and issue syncs stop. It also makes a best-effort remote revoke: Linear exposes a cheap token-revoke endpoint that kills only Cognee’s own token without touching the app install, so unlike the GitHub connector this is actually called. It is best effort by design — the local revoke is the real cut-off, and a network blip must never block a disconnect.
• Removing the app in Linear fires the OAuthApp revoked webhook, which revokes the credential server-side — the same end state, reached from the other side.

​

Troubleshooting

1. POST /authorize returns 503 “linear integration is not configured on this server”: LINEAR_CLIENT_ID, LINEAR_REDIRECT_URI, or LINEAR_WEBHOOK_SECRET (it signs the state) is unset. The backend log names the exact variable. A missing LINEAR_FRONTEND_BASE_URL surfaces later, as the same 503 from the callback instead.
2. Redirected to ?linear=error_invalid_state: the install didn’t start from a freshly minted /authorize URL, more than 10 minutes passed before approving it, or LINEAR_WEBHOOK_SECRET changed in between. Mint a new one.
3. Redirected to ?linear=error_exchange_failed: the callback never 500s — it catches everything and redirects, and the traceback is in the backend log. Usual causes: mismatched LINEAR_CLIENT_ID/LINEAR_CLIENT_SECRET, a LINEAR_REDIRECT_URI that doesn’t exactly match the app’s registered callback URL, a missing INTEGRATION_CREDENTIALS_KEY, or the identity query failing (Linear token response carries no organization id).
4. Redirected to ?linear=error_already_connected: this workspace is bound to another Cognee user. Disconnect it there first.
5. Redirected to ?linear=cancelled: the consent screen was cancelled, or Linear rejected the request. Nothing was stored.
6. Connect succeeds but no issues appear: the backfill runs detached — check the backend log for Syncing N Linear issues for organization <id> into dataset linear_<url_key>, or has no issues to sync. It covers the 50 most recently updated issues only; everything older arrives when those issues are next touched.
7. Webhook deliveries return 401: either LINEAR_WEBHOOK_SECRET doesn’t match the app’s signing secret (easy to hit when juggling more than one app), or the host clock has drifted more than 60 seconds. The response detail distinguishes the two — Invalid Linear signature versus Stale Linear webhook timestamp.
8. Webhook deliveries return 404: the provider name in the URL is wrong, or the backend is running a build without the Linear connector registered. The route is /api/v1/integrations/linear/events.
9. The agent posts an error activity in the session: the search or the reply failed — the backend log carries the traceback under Linear agent session <id>: answering failed. If the answer instead says the connection “is not fully configured”, the Cognee user who installed the integration was deleted; disconnect and reconnect.
10. The agent replies “No relevant information found in cognee memory.”: the search returned nothing usable for that question. Remember that it searches the installing user’s datasets — content ingested by a different Cognee user is not visible to it.

​

Related