# Changelog Source: https://docs.cogniscape.app/cli/changelog Release history for the Cogniscape CLI. ## v1.17.1 — 08/27/2026 11:13 AM **Fixed: CLI sign-in reaches Cogniscape's live authorization service** The first release with individual CLI sign-in was pointed at a retired address, so sign-in could not finish. This update directs sign-in, refresh, and logout to the active Cogniscape authorization service. * `cogniscape login` can complete the browser or pasted-code sign-in flow * Token refresh and logout use the same live authorization service * Existing configuration and customer-key installations are unchanged *** ## v1.17.0 — 08/13/2026 2:32 PM **Prepared: individual CLI sign-in, with existing installations unchanged** This release pre-distributes the local foundation for future person-level CLI authentication. Existing customer-key installations, hooks, and queued events continue through the same legacy path. Individual sign-in is not active for customers yet, and no action is required from developers. * Adds protected local Ed25519 key and token storage without relying on the operating system keyring; these files are created only by an explicit successful login * Prepares OAuth 2.1 Authorization Code with PKCE and DPoP for loopback and paste-code login, plus silent refresh, logout, and local status commands * Discovers active GitHub CLI and GitLab CLI accounts only during explicit login, without reading or transmitting their tokens * Keeps hooks silent and preserves the current customer key until a future DPoP login completes successfully; installing or updating alone does not start login or migrate credentials * Adds the effective repository Git name and email as structured event context so canonical identity can be resolved after the server-side rollout * [PR #799](https://github.com/cogniscape-org/cogniscape-app/pull/799), [#800](https://github.com/cogniscape-org/cogniscape-app/pull/800), [#802](https://github.com/cogniscape-org/cogniscape-app/pull/802), [#803](https://github.com/cogniscape-org/cogniscape-app/pull/803), [#804](https://github.com/cogniscape-org/cogniscape-app/pull/804), and [#805](https://github.com/cogniscape-org/cogniscape-app/pull/805); closes [#784](https://github.com/cogniscape-org/cogniscape-app/issues/784), [#785](https://github.com/cogniscape-org/cogniscape-app/issues/785), [#786](https://github.com/cogniscape-org/cogniscape-app/issues/786), [#787](https://github.com/cogniscape-org/cogniscape-app/issues/787), [#788](https://github.com/cogniscape-org/cogniscape-app/issues/788), and [#789](https://github.com/cogniscape-org/cogniscape-app/issues/789) *** ## v1.16.2 — 08/11/2026 10:45 AM **Fixed: Codex sessions reported inflated AI cost** Token usage captured from Codex sessions counted cached input twice — once at full price, and again as a cache read. Reported cost for Codex work was inflated by roughly 8x, and the error grew with the session's cache hit rate, so the most efficient sessions looked the most expensive. * Cached input is now recorded net of the full input count, the same way it already worked for Claude Code sessions, so cost across every assistant is measured on the same basis * Claude Code figures were never affected by this and do not change * Cost already recorded for past Codex sessions keeps the old inflated values until a separate correction is applied * [PR #770](https://github.com/cogniscape-org/cogniscape-app/pull/770), closes [#769](https://github.com/cogniscape-org/cogniscape-app/issues/769) *** ## v1.16.1 — 07/18/2026 12:09 PM **Improved: agent session prose is preserved for semantic extraction** Agent coding sessions now keep more of their original outcome prose when they are sent through Cogniscape's semantic extraction path. This gives the knowledge graph richer implementation context without changing the regular activity capture workflow. * CLI session summaries now keep up to 8000 characters of agent result and objective text * Semantic extraction uses the raw task completion payload instead of the shorter session summary, while the legacy Graphiti payload path remains unchanged * Extraction guidance now asks for complete graph facts from agent prose and avoids inventing narratives when the source does not support one * [PR #688](https://github.com/cogniscape-org/cogniscape-app/pull/688), closes [#687](https://github.com/cogniscape-org/cogniscape-app/issues/687) *** ## v1.16.0 — 07/14/2026 1:19 PM **Fixed: Windows developers can receive CLI updates automatically** Windows machines could get stuck on an older Cogniscape CLI because the updater looked for a Unix archive format that is not published for Windows, then hid the failure in the local hook log. This release lets Windows use the same automatic update flow as macOS and Linux, so developers receive fixes and version-gated features without manual reinstall steps. * Windows auto-update now downloads the published `.zip` artifact and verifies it with the release checksums before installing * The updater safely stages the new binary, prevents concurrent update attempts, retries transient file replacement failures, and rolls back if validation fails * Failed Windows updates now surface a visible warning instead of only writing to the local hook log * This release also includes the v1.16.0 fixes for oversized Claude transcripts, stale branch cache fallback, and custom Claude configuration directories * [PR #671](https://github.com/cogniscape-org/cogniscape-app/pull/671), closes [#655](https://github.com/cogniscape-org/cogniscape-app/issues/655) *** ## v1.15.2 — 07/08/2026 5:40 PM **Fixed: Codex App sessions are matched to the right branch when the transcript path is missing** Some Codex App sessions ended without sending the exact local transcript path to the Cogniscape hook. When that happened, the CLI could fall back to a generic project record instead of the branch where the work actually happened, especially for long-running interactive sessions. This release finds the correct Codex session file using the session identity recorded inside the file, then applies the branch and commit recorded by Codex before sending the session summary. * Long-running Codex App sessions are more reliably attributed to the feature branch that produced the work * Pull request cost and branch ROI reports recover Codex sessions that previously looked generic * The session lookup is bounded by scanning the newest files first and stopping as soon as the session identity is known * [PR #644](https://github.com/cogniscape-org/cogniscape-app/pull/644), closes [#643](https://github.com/cogniscape-org/cogniscape-app/issues/643) *** ## v1.15.1 — 06/29/2026 7:45 PM **Fixed: Codex Cloud sessions are attributed to the branch the work happened on** Codex Desktop and Cloud run the agent against a feature branch in the cloud while the developer's local checkout stays on the default branch. The CLI derived the branch and commit from the local working directory, so every Codex "Task Completed" record was attributed to the local default branch and commit instead of the branch the agent actually worked on. Activity showed up under the wrong branch, and Codex sessions could miss their pull request link. This release reads the branch and commit from the authoritative git state Codex records in its session rollout, and applies it to the session record before it is sent. * Codex session records now use the branch and commit from the rollout's recorded git state, not the local working directory * The pull-request join key uses the full commit hash from the rollout, so Codex Cloud sessions correctly link to their pull request * Older CLIs and local-only Codex sessions are unaffected — when no rollout git state is present, the previous behavior is preserved * [PR #595](https://github.com/cogniscape-org/cogniscape-app/pull/595), closes [#594](https://github.com/cogniscape-org/cogniscape-app/issues/594) *** ## v1.15.0 — 06/26/2026 6:50 AM **Added: Opencode sessions are captured, and the CLI update path is hardened** This release prepares the CLI for official Opencode support and tightens the delivery path that keeps developer machines updated. Opencode now joins Claude Code, Codex, and Cursor as a first-class source of coding activity, while auto-update, hook delivery, local file handling, and event schema checks were hardened before the release is cut. * Opencode support adds `cogniscape opencode-hook` and `cogniscape setup-opencode-hooks`, installing a managed Opencode plugin only when Opencode is detected or an explicit `OPENCODE_CONFIG_DIR` is provided * Opencode events are accepted by the shared event schema with `source="opencode"`, and duplicate session summaries from deprecated Opencode lifecycle events are avoided * CLI-owned MCP setup and update commands were removed; MCP client setup is now handled by product docs and client-specific OAuth instructions, while the CLI focuses on developer activity capture * Auto-update now verifies Ed25519-signed release checksums before replacing the binary, extracts archives with safe Go code instead of shelling out to `tar`, validates the new binary, and rolls back on failed validation * Failed hook deliveries now spool locally with bounded retry and backoff, so transient network or server errors no longer drop events immediately * Transcript reads are constrained to expected local roots, and CLI-owned logs, caches, update metadata, and spool files use tighter file modes * Event payload cleanup, transcript deduplication, and schema conformance tests reduce drift between the Go CLI and the Python ingestion schemas * [PR #563](https://github.com/cogniscape-org/cogniscape-app/pull/563), [#564](https://github.com/cogniscape-org/cogniscape-app/pull/564), [#565](https://github.com/cogniscape-org/cogniscape-app/pull/565), [#566](https://github.com/cogniscape-org/cogniscape-app/pull/566), [#568](https://github.com/cogniscape-org/cogniscape-app/pull/568), [#569](https://github.com/cogniscape-org/cogniscape-app/pull/569), [#570](https://github.com/cogniscape-org/cogniscape-app/pull/570), [#571](https://github.com/cogniscape-org/cogniscape-app/pull/571), [#572](https://github.com/cogniscape-org/cogniscape-app/pull/572), and [#580](https://github.com/cogniscape-org/cogniscape-app/pull/580); closes [#562](https://github.com/cogniscape-org/cogniscape-app/issues/562) and [#567](https://github.com/cogniscape-org/cogniscape-app/issues/567) *** ## v1.14.10 — 06/16/2026 6:35 PM **Improved: developer input is kept out of Cursor session records** When Cursor finished a delegated sub-task, the CLI could include the task wording in the session's title and objective. That wording can contain what the developer typed, and developer input is never meant to be ingested. No customer was affected — Cursor activity to date is internal dogfooding only — so this is preventive hardening before any customer adopts Cursor. This release stops passing that wording through. Each Cursor sub-task is still recorded with its outcome and the kind of agent that ran it, but the developer's own input no longer reaches the title or objective. * Cursor sub-task records keep their result and agent type, without developer input * Sibling sub-tasks in the same conversation are still recorded as separate entries * Claude Code and Codex sessions are unaffected * [PR #543](https://github.com/cogniscape-org/cogniscape-app/pull/543), closes [#539](https://github.com/cogniscape-org/cogniscape-app/issues/539) *** ## v1.14.9 — 06/16/2026 5:54 PM **Improved: a leftover diagnostic file is removed from developer machines** During earlier troubleshooting, the CLI wrote a local diagnostic file on each developer's machine that captured raw session data. It never left the machine and was never sent to Cogniscape, but it was no longer needed and kept growing over time. This release stops writing that file and automatically deletes any existing copy the next time the CLI runs — with nothing for developers to do. * The CLI no longer creates the local diagnostic file * Any existing copy is removed automatically, on every supported coding tool * The file always stayed on the developer's machine and was never transmitted * [PR #542](https://github.com/cogniscape-org/cogniscape-app/pull/542), closes [#541](https://github.com/cogniscape-org/cogniscape-app/issues/541) *** ## v1.14.8 — 05/27/2026 9:24 PM **Fixed: AI coding sessions now reliably linked to their pull request** When a developer worked in an isolated workspace, the AI coding session could end up labeled with a different internal name than the pull request it produced. In those cases the pull request's story showed no coding sessions and no AI cost — even though the work clearly happened. Cogniscape now connects each session to its pull request by the actual commits involved, instead of relying on the workspace name matching. Affected pull requests now show their full coding activity and cost. * Pull request stories no longer show "0 sessions" when the work was done in an isolated workspace * AI cost and session attribution for those pull requests are now accurate * Applies going forward; existing records are unchanged * [PR #505](https://github.com/cogniscape-org/cogniscape-app/pull/505), closes [#504](https://github.com/cogniscape-org/cogniscape-app/issues/504) *** ## v1.14.7 — 05/26/2026 6:57 PM **Improved: empty "Session Start" markers are no longer recorded** Every coding session used to begin with a generic "Session Start" entry that recorded only that a session had started — no work, no outcome. These markers added noise to your reports and counted against your usage without telling you anything the rest of the session didn't already show. Cogniscape no longer records these start markers, across every supported coding tool. Session timing and everything meaningful about a session are unaffected — genuine activity, summaries, and results continue to be recorded exactly as before. * Empty "Session Start" entries no longer appear in reports * Less noise and lower usage, with no loss of meaningful activity * Forward-only: previously recorded entries are not changed; the next auto-update picks up the new version * [PR #500](https://github.com/cogniscape-org/cogniscape-app/pull/500) *** ## v1.14.6 — 05/26/2026 5:49 PM **Improved: empty subagent conclusions are no longer recorded** Building on the previous release, Cogniscape now reads each subagent's conclusion from the agent's own work. Some subagent stops, though, produce no written conclusion at all — a delegated step that simply ends without a summary. Those were still being recorded as empty, content-free activity entries that added noise without telling you anything. When there is no genuine agent output to capture, nothing is recorded. Subagent work that actually produced a result — analysis, review summaries, reports — continues to be recorded exactly as before. * Subagent stops with no real conclusion no longer create empty activity entries * Cleaner reports — only subagent work that produced an actual result shows up * Reinforces the privacy commitment: nothing is recorded when the only available text would be the developer's request rather than the agent's output * Forward-only: previously recorded entries are not changed; the next auto-update picks up the new version * [PR #499](https://github.com/cogniscape-org/cogniscape-app/pull/499) *** ## v1.14.5 — 05/26/2026 11:36 AM **Improved: subagent conclusions now capture the agent's actual result** When a coding session delegates part of a task to a subagent, Cogniscape records what that subagent concluded so the work shows up in your activity. Previously the recorded conclusion could capture the wrong text — in many cases the developer's own request rather than the agent's findings — which made those entries noisy and low-value. The conclusion is now read directly from the subagent's own work, so the recorded result always reflects what the agent produced: the real analysis, review summary, or report — not the instruction that started it. The same correction applies to the message captured when a session ends with an error. * Subagent activity now shows the agent's genuine output instead of the request that triggered it * Richer, more useful content lands in reports — full review summaries and findings rather than one-line prompts * Reinforces the privacy commitment: only the agent's output is captured, never the developer's input * Forward-only: previously recorded conclusions are not rewritten; the next auto-update picks up the new version * [PR #498](https://github.com/cogniscape-org/cogniscape-app/pull/498) *** ## v1.14.4 — 05/22/2026 6:42 PM **Improved: session activity now groups reliably under one canonical repository name** The CLI derives a repository identifier from each project's git remote and attaches it to every session event. Previously that identifier varied with how the remote was configured — an HTTPS clone, an SSH clone, and an `scp`-style remote of the very same repository could each produce a different string. The same repo then showed up under multiple names, splitting its activity across reports. Session events now always carry a canonical `owner/repo` identifier, normalized from any common git remote format. Repositories without a remote (purely local work) fall back to the project folder name, exactly as before. Developers don't need to do anything; the next auto-update picks up the new version, and activity from the same repository lands together going forward. * HTTPS, SSH, and `scp`-style git remotes all resolve to the same `owner/repo` identifier * Local-only repositories keep using the folder name — no spurious identifiers * Forward-only: previously recorded session events are not rewritten * [PR #482](https://github.com/cogniscape-org/cogniscape-app/pull/482) *** ## v1.14.3 — 05/16/2026 1:00 PM **Fixed: Claude Code session token usage inflated 40-50%** The CLI summed `message.usage` from every assistant record in Claude Code transcripts, but Claude Code rewrites the same `message.id` multiple times as the message streams. Anthropic's stream emits cumulative usage, so summing every record overcounted tokens by 40-50%. Every `token_usage_by_model` reported to the backend was inflated, and downstream ROI and cost reports inherited the inflation. The transcript scanner now keeps only the latest record per `message.id` for both the main session and any subagent files. Cumulative-usage duplicates correctly resolve to the final value, identical-snapshot duplicates count once, and content blocks (tool\_use, text) are read from the last record so files-read, files-modified, tool counts, commands, and summary text are no longer dropped when a duplicate carries new content. Codex sessions are unaffected (they use delta-based counts already). This is a forward-only fix. Historical inflated metrics stay as recorded. The next auto-update picks up the new version and developers will see their reported token totals drop accordingly — that drop is the correction, not a regression. * Per-message-id last-wins dedup in both main and subagent transcript scans * Records without a `message.id` (legacy / malformed) still sum normally * Content processing decoupled from token dedup so later duplicates' tool\_use blocks are not silently dropped * 4 new regressions added: `DedupsByMessageID`, `SubagentDedupsByMessageID`, `LastWinsOnCumulativeUsage`, `LastRecordContentWins` * [PR #466](https://github.com/cogniscape-org/cogniscape-app/pull/466), closes [#462](https://github.com/cogniscape-org/cogniscape-app/issues/462) *** ## v1.14.2 — 05/09/2026 7:30 AM **Fixed: Codex sessions now show real token usage, tool counts, and files touched** The Codex CLI integration shipped in v1.14.0/v1.14.1 captured each session start and end, but every session-summary event landed with empty token usage, empty tool counts, no files modified, no files read, and no commands. ROI and cost reports treated Codex sessions as if no work happened. The CLI now reads the actual Codex rollout file Codex writes per session and surfaces the real numbers — per-model token usage, the last shell commands that ran, which files were edited via `apply_patch`, which files were read via common shell readers (`cat`, `head`, `tail`, `sed -n p`, …), and the duration of the session. No data is forwarded for sessions that never produced a rollout file. Developers don't need to do anything; the next auto-update picks up the new version. * Token usage by model now flows into ROI and cost reports for every Codex session * Tool call counts and the last 5 shell commands run during the session are captured * Files modified via `apply_patch` are recovered from the session transcript * Files read via common shell readers are surfaced — even paths whose name contains `p` (e.g. `*.py`, `helpers/*.go`) * File paths are relativized against the project root before leaving the developer's machine — same privacy contract as the Claude Code integration * Output redirection (`>`, `>>`, `2>`, …) is honored: `cat src.go > out.go` records `src.go` as read and skips `out.go` * Older Codex rollout files (pre-0.129) still parse correctly — no data is lost during the upgrade * [PR #441](https://github.com/cogniscape-org/cogniscape-app/pull/441), closes [#440](https://github.com/cogniscape-org/cogniscape-app/issues/440) *** ## v1.14.1 — 05/08/2026 6:40 PM **Improved: Codex hook integration is now zero-click for developers** The Codex CLI integration shipped in v1.14.0 required developers to open Codex, run `/hooks`, and individually approve the SessionStart and Stop entries before any data flowed. That contradicted Cogniscape's frictionless onboarding contract for developers — the install path is meant to be invisible. Codex 0.129+ enforces a per-hook trust gate via `~/.codex/config.toml`. The CLI now pre-populates the trust entries during `cogniscape init` / `cogniscape setup-hooks` so the cogniscape hooks become Active on the next Codex launch automatically. Developers don't see the `/hooks` browser at all unless they choose to. * `setup-hooks` now writes `[hooks.state]` entries to `~/.codex/config.toml` alongside `~/.codex/hooks.json` * File permissions are preserved end-to-end — the backup and rewritten config inherit the original mode bits (defaulting to `0600` when freshly created), so MCP server env vars and tokens never widen to world-readable * `cogniscape uninstall` now removes the trust state alongside the hooks file, leaving no Codex integration footprint behind * Trust write failure is non-fatal: if Codex changes the trust algorithm in a future release the hooks fall back to manual `/hooks` approval rather than blocking installation * [PR #439](https://github.com/cogniscape-org/cogniscape-app/pull/439) *** ## v1.14.0 — 05/08/2026 5:55 PM **Added: OpenAI Codex CLI sessions are now captured alongside Claude Code and Cursor** Developers using OpenAI's Codex CLI now have their coding sessions visible in Cogniscape — same level of detail teams already have for Claude Code: session start, session summary with the assistant's final response, tool counts, files touched, and per-model token usage. No data is forwarded for sessions on tools that aren't installed; the CLI silently skips when there's no `~/.codex/` directory on the developer's machine. For developers who have Codex installed, the next CLI auto-update will install the integration automatically. Codex itself asks the developer to approve the new hook on the next launch — a one-time click; the CLI prints a single line reminding the developer to approve when this happens. Nothing else changes for developers using only Claude Code or Cursor. * New CLI subcommand `cogniscape codex-hook` invoked by Codex's hook system * `cogniscape setup-hooks` now also installs `~/.codex/hooks.json` (when Codex is detected) alongside the existing Claude Code and Cursor hooks * Existing customers self-heal on auto-update — no manual `cogniscape init` needed for the integration to activate * [PR #438](https://github.com/cogniscape-org/cogniscape-app/pull/438), closes [#437](https://github.com/cogniscape-org/cogniscape-app/issues/437) *** ## v1.13.2 — 05/06/2026 7:30 PM **Fixed: worktree branch was being overwritten before the session ended** The previous fix (v1.13.1) recovered the correct worktree branch at the end of the session, but a late event firing in the middle of the session — typically after a sub-agent finishes — was silently overwriting the cache with the main repo's branch. When the worktree was then deleted before the session-summary fired, the CLI fell back to the corrupted cache and still recorded the wrong branch. The CLI now locks in the branch on the first capture and only allows the authoritative session-summary to replace it. Worktree sessions are now reliably attributed to their own branch end-to-end. No action required — auto-update will pick up the new version on the next coding session. * Late mid-session events can no longer overwrite the cached worktree branch * The fix is race-safe under concurrent hook processes * [PR #428](https://github.com/cogniscape-org/cogniscape-app/pull/428), closes [#427](https://github.com/cogniscape-org/cogniscape-app/issues/427) *** ## v1.13.1 — 05/06/2026 6:18 PM **Fixed: branch attribution lost when worktree deleted before session-summary** When a developer worked inside a git worktree under `.worktrees//` and the worktree was deleted (post-merge cleanup) before the session ended, the CLI was unable to recover the worktree's branch on the final `session-summary` event. The session was then logged against the repo's current branch (typically `main`) instead of the actual feature branch. The CLI now caches the resolved branch eagerly at every hook event in `~/.cogniscape/sessions/.branch` and falls back to that cache at session-summary when the live worktree probe fails. Stale cache files are swept after 7 days. No action required — auto-update will pick up the new version on the next coding session. * New per-session branch cache survives worktree deletion * TTL sweep (7 days) reaps orphans from sessions that crashed before session-summary * [PR #420](https://github.com/cogniscape-org/cogniscape-app/pull/420), closes [#419](https://github.com/cogniscape-org/cogniscape-app/issues/419) *** ## v1.13.0 — 05/05/2026 7:20 PM **Removed: claude-mem session enrichment** The optional integration that pulled extra context from the local claude-mem database is gone. When the CLI detected the claude-mem plugin on a developer's machine (introduced in v1.9.0), it would attach observations and session summaries to each session-summary event. In practice, only a handful of developers ever had the plugin installed, and the enriched payloads were occasionally large enough to fail processing on the server side. The CLI now sends a single, lean session payload regardless of which local tools the developer uses. There is nothing to configure or remove — developers who never used claude-mem are unaffected, and developers who did keep working as before with a smaller, more reliable payload. * The `enrichment` block no longer appears in `task_completed` / `session-summary` events * Sessions are no longer auto-classified by type (bug fix, feature, refactor, decision); a single "worked on" relationship is recorded instead * No action required — auto-update will pick up the new version on the next coding session * [PR #413](https://github.com/cogniscape-org/cogniscape-app/pull/413), closes [#412](https://github.com/cogniscape-org/cogniscape-app/issues/412) and [#361](https://github.com/cogniscape-org/cogniscape-app/issues/361) *** ## v1.12.1 — 04/29/2026 7:35 AM **Fix: Cost reports showed \$0 for sagas worked on inside developer worktrees** When a developer ran a coding session from a Git worktree they created themselves (with `git worktree add`), the CLI tagged that session's token usage with the wrong branch — it recorded `main` instead of the actual feature branch. As a result, asking the platform for the cost of the related PR or issue returned `$0.00` even though real spend existed for that work. The CLI now recognizes both layouts a developer might use — the AI-managed `.claude/worktrees/` directory and the manually-created `.worktrees/` directory — and attributes token usage to the correct branch in either case. * Cost reports for new sessions in developer worktrees will join correctly to the matching PR or issue * No change for sessions running in the main repository directory or in AI-managed worktrees * Past token records already tagged with `main` are not retroactively re-attributed *** ## v1.12.0 — 04/16/2026 12:30 PM **New: Update all your MCP configurations with a single command** The CLI can now scan your machine for every AI tool that has a Cogniscape MCP connection and update them all at once. If you previously configured Cogniscape in Claude Desktop, Claude Code, Cursor, Codex, or OpenCode, running `cogniscape mcp update` will detect outdated configurations and migrate them to the latest format. * Automatically finds and updates Cogniscape MCP configs across Claude Desktop, Claude Code, Cursor, Codex, and OpenCode * Preview what would change before committing with `--dry-run` * Filter to a specific tool with `--only "Claude Desktop"` or see file paths with `--verbose` * New command namespace: `cogniscape mcp setup` and `cogniscape mcp update` (the old `cogniscape setup mcp` still works) *** ## v1.11.4 — 04/13/2026 **Fix: Claude Code hooks failed on Windows with "command not found"** On Windows, the CLI wrote the full Windows-style binary path (with backslashes) into the Claude Code hooks configuration. Claude Code on Windows runs hooks through git-bash, which consumes backslashes as escape characters — so `C:\Users\name\...\cogniscape.exe` became `C:Usersname...cogniscape.exe` and every hook invocation failed with "command not found". The CLI now writes the hook command with forward slashes (`C:/Users/name/.../cogniscape.exe`), which git-bash handles natively. Developers who already ran `setup-hooks` on Windows should re-run it after upgrading. * Fixes `SessionStart`, `Stop`, `SubagentStop`, `StopFailure` hooks on Windows * No change for Linux or macOS *** ## v1.11.3 — 04/13/2026 **Fix: Windows PowerShell installer failed to copy the binary** The Windows installer script was looking for a binary named `cogniscape_windows_arm64.exe` (or `_amd64.exe`) inside the downloaded zip, but the release pipeline now packages it as plain `cogniscape.exe` so auto-update can find it after extraction. The installer failed with a "PathNotFound" error on every Windows install since v1.11.0. Linux and macOS were not affected — the shell installer was already updated when the binary was renamed. * Windows installer now copies `cogniscape.exe` from the extracted archive * Fixes both amd64 and arm64 installs *** ## v1.11.2 (re-release) — 04/07/2026 **Rollback: v1.12.0 withdrawn** Version 1.12.0 removed the enrichment collection step from the CLI, but the removal was over-scoped — it also deleted compact, high-value fields that were being consumed downstream. A separate change that expanded the reader to use those fields was based on the incorrect assumption that all sessions produce enrichment data (only sessions with the claude-mem plugin do). Both changes have been reverted. The CLI returns to the exact behavior of v1.11.2. Developers on v1.11.2 are unaffected — no action required. * [PR #318](https://github.com/cogniscape-org/cogniscape-app/pull/318) — reverts #313 and #314 *** ## v1.11.2 — 04/01/2026 7:50 PM **Fix: only one of two parallel agents was recorded when they finished at the same time** When two AI agents complete their work at nearly the same time within a session, both should appear as separate entries in the knowledge graph. In practice, only the first one was recorded — the second was silently discarded because the system couldn't tell the two events apart. The root cause was that each agent's completion event was identified by information they shared (the session they belonged to), rather than by what made them unique (their individual identity). When two events look identical, the system assumes they're duplicates and drops one. The fix ensures each agent's completion carries its own identity in the identifier, so no two agents can ever collide. * Parallel agents that finish close together are now both captured reliably * No change to existing hook setup or configuration required *** ## v1.11.1 **Fix: background agent activity not captured in the knowledge graph** When a coding session delegates work to background agents — research assistants that run in parallel while the developer continues working — the outcome of that work was not being recorded. Only agents that ran synchronously (blocking the session until they finished) were tracked. This meant that a significant portion of agent activity was invisible in the knowledge graph. Background agent conclusions are now captured reliably, regardless of how they were dispatched. * Background agent outcomes now appear in the knowledge graph alongside synchronous agent results * Existing hook installations are updated automatically on next setup *** ## v1.11.0 **More accurate AI cost reporting and visibility into session failures** Two meaningful gaps in how Cogniscape tracks AI usage have been closed in this release. When Claude Code spawns subagents — specialized assistants that work in parallel on independent parts of a task — those agents do their own AI processing and consume tokens separately. Until now, Cogniscape only counted the tokens used by the main session, missing the work done by subagents entirely. In practice, this meant that cost and usage data shown to managers was significantly understated. Token reporting now captures the full picture: both the main session and all subagents are counted together. Additionally, sessions that end abruptly because of a billing limit, rate limit, or authentication problem now generate an explicit event in the activity feed. Previously these failures were silent — there was no way to know a developer's session was cut short without them manually reporting it. A new event type records the session error and its cause so team leads can see if a developer was blocked mid-task. * Token usage in session summaries now includes all subagent activity, not just the top-level session * Sessions that fail due to API errors (billing, rate limit, authentication) now appear as a distinct event rather than disappearing silently * Existing hook installations are updated automatically on next setup *** ## v1.10.0 **CLI version tracking and cleaner event pipeline** Cogniscape now tracks which CLI version each developer has installed. This gives team leads a real-time map of update adoption across the organization — no need to ask developers individually or check machines manually. Additionally, three low-value event hooks were removed to reduce unnecessary processing costs. Session summaries already capture the complete picture of what happened during a coding session, making the individual plan-approved, task-created, and task-completed events redundant. * Every event sent by the CLI now includes its version, stored alongside token usage data * Managers can query version adoption per developer at any time * Removed hooks that were producing generic or empty data (saving processing and LLM costs) * Existing machines are cleaned up automatically — obsolete hooks are pruned during the next auto-update *** ## v1.9.0 **Richer development insights from AI-powered session analysis** When developers use tools that analyze their coding sessions (like claude-mem), the CLI now automatically detects and incorporates those insights into the data sent to Cogniscape. This means your knowledge graph gets richer context about each session — what was investigated, what was learned, what types of changes were made — without any extra configuration. * Sessions are automatically classified by type: bug fix, new feature, refactoring, discovery, or decision * Structured summaries replace truncated text, giving managers a clearer picture of what happened * The knowledge graph uses these classifications to build smarter relationships (e.g., "developer fixed X" instead of generic "developer worked on X") * Zero setup required — if the analysis tool is present, enrichment happens automatically; if not, everything works as before *** ## v1.8.3 **Faster session processing and more reliable event delivery** Session data was being extracted by scanning the same transcript file three separate times — once for the summary, once for token usage, and once for metadata (files changed, commands run). This slowed down the session-end hook, especially for long conversations with large transcripts. Additionally, each incoming webhook opened and closed its own connection to the event queue. Under burst traffic, this created connection churn that could exhaust Redis connections. * Session-end hook now processes transcripts in a single pass, reducing I/O and latency * Event queue uses a shared connection for the lifetime of the server, eliminating per-request connection overhead * Queue status endpoint no longer opens a throwaway connection *** ## v1.8.2 **Fix: subagent conclusions not reaching the knowledge graph** After the v1.8.1 fix enabled subagent tracking to fire correctly, the conclusions were still not appearing in the knowledge graph. The server rejected the data because the conclusion text arrived empty — the CLI was not reading the response in the format that AI coding tools actually send it. * Subagent conclusions now appear correctly in the knowledge graph * The CLI handles multiple response formats for forward compatibility *** ## v1.8.1 **Fix: new hooks not applied after auto-update** After auto-updating to a new CLI version, newly introduced hooks (such as the subagent tracking added in v1.8.0) were not being registered automatically. Developers had to run `cogniscape setup-hooks` manually to activate them. This is now fixed — hook definitions are properly synced immediately after every auto-update, for both Claude Code and Cursor. *** ## v1.8.0 **Subagent activity tracking** When AI coding tools delegate work to background research agents, Cogniscape now captures the outcome of that work — what was investigated, what was concluded, and which model was used. Previously, only the final result was visible in the knowledge graph; the reasoning behind decisions was lost. * Works in both Claude Code and Cursor * Captures the agent's objective, conclusion, type, and model * Large responses are handled gracefully *** ## v1.7.2 **Fix: timestamp inconsistency causing delayed data availability** Events from coding sessions and events from GitHub were using different timestamp formats, which occasionally caused data to appear with a delay of several hours in the knowledge graph. All CLI events now use a consistent timestamp format, and data is available within minutes of a session ending. *** ## v1.7.1 **Fix: empty session summaries from Cursor** Cursor session summaries were arriving empty ("no assistant message captured") because the CLI was using the wrong format to read Cursor transcripts. Cursor and Claude Code use different transcript structures. * Cursor sessions now have a dedicated transcript reader * Session summaries are correctly extracted from Cursor conversations *** ## v1.7.0 **Cursor IDE integration** Cogniscape now tracks development sessions from Cursor alongside Claude Code. Sessions from each tool are clearly identified in the knowledge graph, enabling per-tool activity filtering. * Cursor hooks are installed automatically during `cogniscape init` when Cursor is detected * Three session events are captured: session start, session end, and session summary * Developer identity is resolved from Cursor's account email when git config is unavailable * Hooks are removed cleanly on `cogniscape uninstall` * Cursor and Claude Code sessions are labeled separately for easy filtering Token usage tracking is not yet available for Cursor sessions because Cursor does not provide this data in its hook system. This will be supported once Cursor adds the capability. *** ## v1.6.0 **Richer session summaries** Sessions that previously produced generic entries like "completed a session" now generate detailed, structured summaries including what was worked on, which files were touched, and what the outcome was. * Session summaries now include: files modified, files read, recent commands, and tool usage counts * An AI-powered summarizer transforms raw session data into structured narratives with clear objectives and outcomes * File paths are always shown relative to the project root — no personal directory information is exposed * Each session gets a unique identifier, fixing an issue where only the first summary from repeated sessions was recorded *** ## v1.5.2 **Fix: broken auto-update downloads** A naming mismatch between the CLI and the release server was causing auto-update downloads to fail silently. This is now fixed, and both old and new naming conventions are supported for backward compatibility. *** ## v1.5.1 **Fix: subagent activity attributed to wrong repository** When Claude Code delegates work to isolated subagents, the CLI was incorrectly identifying the repository name, causing that activity to disappear from repository-filtered views. * Repository names are now resolved correctly regardless of the working directory * Task events now include complete metadata (title, description, and status transitions) **This fix is distributed automatically** via the silent auto-update mechanism. *** ## v1.5.0 **Git branch tracking + silent auto-update** Two improvements for enterprise teams: **Branch context in every event:** * All events now include the current git branch, making it easy to see which feature or initiative a session relates to * Works gracefully in non-git directories and CI environments **Silent auto-update:** * The CLI now keeps itself up to date automatically — no manual downloads required * Updates are checked once per day and applied in the background without interrupting your work * Integrity is verified via checksum before applying any update * Downgrades are prevented during rollback scenarios **No action required** — existing installations will auto-update on next use. *** ## v1.4.0 **Windows support** The CLI now works on Windows alongside macOS and Linux, removing a platform blocker for enterprise adoption. * Full support for Claude Desktop MCP configuration on all three platforms * Developer identity is resolved correctly on Windows * Uninstall works on all platforms (with guidance for Windows-specific limitations) * New PowerShell install script for Windows environments * Release pipeline now publishes Windows binaries for both AMD64 and ARM64 *** ## v1.3.0 **One-command MCP setup for Claude Desktop** Reduces onboarding from several minutes of manual configuration to a single command. Particularly important for non-developer users (managers, founders) who want to query the knowledge graph from Claude Desktop. * New command: `cogniscape setup mcp` — automatically configures the Cogniscape MCP in Claude Desktop * Supports `cogniscape setup mcp --uninstall` for clean removal without affecting other MCP servers * Safe to run multiple times — updates the configuration in place * Handles edge cases gracefully: missing config files, existing configurations, and corrupted files (creates a backup before modifying) *** ## v1.2.1 **API domain migration** Migrated the CLI to the production API domain (`api.cogniscape.app`). No user action required — the CLI resolves the correct endpoint automatically. *** ## v1.2.0 **Project name tracking** Session summaries now include the project name, enabling per-project filtering and grouping. The project name is derived from your working directory when the session ends. *** ## v1.1.0 **Session duration and token usage tracking** Two features that together enable ROI estimation: knowing how long a session lasted and how many tokens each AI model consumed. * Sessions now include duration (in seconds) computed from the conversation timeline * Token usage is tracked per model, enabling accurate cost breakdowns when multiple models are used in a single session * The Cogniscape MCP includes tools for querying token usage and estimated costs per developer *** ## v1.0.0 **Initial release** The first stable release of the Cogniscape CLI. Provides the complete pipeline from AI coding tool hooks to knowledge graph ingestion. **Onboarding:** * `cogniscape init ` — saves your customer key and installs hooks automatically * `cogniscape update-key ` — updates the customer key without re-running init * `cogniscape setup-hooks` — installs or repairs hooks, preserving any third-party hooks already configured * `cogniscape uninstall` — removes all Cogniscape hooks and deletes the CLI **Session tracking:** * Five events captured automatically: session start, plan approved, task created, task completed, and session summary * Developer identity resolved from your git configuration * All errors are logged silently — the CLI never interrupts your coding tool **Knowledge graph tools:** * `cogniscape writer add-episode` — write custom entries to the knowledge graph * `cogniscape writer add-facts` — create relationship records (e.g., "Alice implemented the payment retry feature") * `cogniscape writer add-entity` — create named entities with descriptions **Configuration:** * `cogniscape config show` — display your current configuration * `cogniscape version` — print the CLI version * Customer key can be set via command flag, environment variable, or config file # CLI Commands Source: https://docs.cogniscape.app/cli/commands Full reference for all cogniscape commands and flags. ## Onboarding commands ### `cogniscape init` Save your customer key to the machine-level config. ```bash theme={null} cogniscape init ``` Your Cogniscape customer key. Find it in the Cogniscape dashboard under Settings → API Keys. **What it does:** Saves the customer key at the machine level — shared across all projects on this machine. Merges Cogniscape hooks into `~/.claude/settings.json` automatically. If `~/.cursor/` exists, merges hooks into `~/.cursor/hooks.json` automatically. Running `cogniscape init` again overwrites the existing key (idempotent). The install script runs `cogniscape init` automatically when you pass your customer key. You only need to run this manually if you installed the binary without a key or want to change keys. *** ### `cogniscape update-key` Update the customer key for the current project. ```bash theme={null} cogniscape update-key ``` Fails with an error if the machine has not been initialized with `cogniscape init` first. *** ### `cogniscape setup-hooks` Install Claude Code hooks manually. ```bash theme={null} cogniscape setup-hooks ``` Merges Cogniscape hooks into `~/.claude/settings.json`, preserving any existing third-party hooks. Creates a backup at `~/.claude/settings.cogniscape-backup.json` before modifying. Idempotent — will not duplicate hooks already present. `cogniscape init` runs this automatically. Use `cogniscape setup-hooks` directly only if you need to repair or re-install hooks without changing your customer key. **Claude Code hooks installed:** | Event | Matcher | What it captures | | -------------- | -------------- | ----------------------------- | | `SessionStart` | — | Session lifecycle begin | | `Stop` | — | Session summary + token usage | | `PostToolUse` | `ExitPlanMode` | Plan approval | | `PostToolUse` | `TaskCreate` | Task creation | | `PostToolUse` | `TaskUpdate` | Task completion | **Cursor hooks installed** (in `~/.cursor/hooks.json`, auto-detected when `~/.cursor/` exists): | Event | What it captures | | -------------- | ------------------------------------------- | | `sessionStart` | Session lifecycle begin | | `stop` | Session summary (full conversation content) | | `sessionEnd` | Session lifecycle end | *** ### `cogniscape mcp update` Scan your machine for all AI tools with Cogniscape MCP configurations and update them to the latest format. ```bash theme={null} cogniscape mcp update ``` Detects and updates configurations in Claude Code, Cursor, Codex, and OpenCode. Migrates legacy URLs and incompatible formats automatically. | Flag | Description | | ----------------- | ----------------------------------------------------- | | `--dry-run` | Preview what would change without modifying any files | | `--verbose` | Show file paths of modified configs | | `--only ""` | Update only a specific tool (e.g., `--only "Cursor"`) | Claude Desktop is configured through the claude.ai web account ([Add custom connector](https://claude.ai/settings/connectors?modal=add-custom-connector), Streamable HTTP) and inherited by the Desktop and mobile apps. The CLI does not manage Claude Desktop config. *** ### `cogniscape uninstall` Remove hooks and the binary. ```bash theme={null} cogniscape uninstall ``` Removes Cogniscape hooks from `~/.claude/settings.json` and `~/.cursor/hooks.json`, then deletes the binary. Idempotent. On Windows, the binary cannot be self-deleted while running — a message will indicate the path for manual removal. *** ## `cogniscape version` ```bash theme={null} cogniscape version # cogniscape (go) v1.7.1 ``` *** ## Authentication All commands that call the API require a customer key, resolved in this order: 1. `--customer-key` flag 2. `COGNISCAPE_CUSTOMER_KEY` environment variable 3. `~/.cogniscape/config.json` (machine-level, set by `cogniscape init`) 4. Error if none of the above is set The key is sent as the `X-Cogniscape-Customer-Key` HTTP header on all requests. *** ## Local files | Path | Purpose | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | | `~/.cogniscape/config.json` | Machine-level customer key. Created by `cogniscape init`. Shared across all projects. | | `~/.cogniscape/hooks.log` | Hook execution log. Rotated to the last 1000 lines when it exceeds 80 KB. | | `~/.cogniscape/hooks-debug.jsonl` | Raw hook payloads in JSONL format (debug). Same rotation policy. | | `~/.cogniscape/task-cache/.json` | Ephemeral task metadata for create→complete correlation. Purged on session end. | | `~/.claude/settings.json` | Global Claude Code settings. `cogniscape setup-hooks` adds hooks here. | | `~/.cursor/hooks.json` | Cursor hooks config. Created automatically by `cogniscape init` when Cursor is detected. | | `~/.cursor/hooks.cogniscape-backup.json` | Backup of Cursor hooks before modification. | # Installation Source: https://docs.cogniscape.app/cli/installation Install the cogniscape CLI on your machine. The install script downloads the binary for your platform, places it in `~/.local/bin`, saves your customer key, and installs Claude Code hooks automatically: ```bash theme={null} curl -fsSL https://install.cogniscape.app/cogniscape.sh | sh -s -- ``` The only output you should see is: ``` SUCCESS ``` ### Custom install directory ```bash theme={null} COGNISCAPE_INSTALL_DIR=/usr/local/bin \ curl -fsSL https://install.cogniscape.app/cogniscape.sh | sh -s -- ``` ### Specific version ```bash theme={null} curl -fsSL https://install.cogniscape.app/cogniscape.sh | sh -s -- 1.4.0 ``` Open PowerShell and run: ```powershell theme={null} & ([scriptblock]::Create((irm https://install.cogniscape.app/cogniscape.ps1))) "" ``` The only output you should see is: ``` SUCCESS ``` The binary is installed to `%LOCALAPPDATA%\Programs\cogniscape\` and added to your user PATH automatically. If PowerShell blocks the script, run this first: ```powershell theme={null} Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``` ### Specific version ```powershell theme={null} & ([scriptblock]::Create((irm https://install.cogniscape.app/cogniscape.ps1))) "" "1.4.0" ``` ### Custom install directory ```powershell theme={null} $env:COGNISCAPE_INSTALL_DIR = "C:\tools\cogniscape" & ([scriptblock]::Create((irm https://install.cogniscape.app/cogniscape.ps1))) "" ``` After installation, open a **new terminal** to use the `cogniscape` command — PATH changes only take effect in new sessions. ## Verify the installation ```bash theme={null} cogniscape version # cogniscape (go) v1.4.0 ``` If `cogniscape` is not found after installation, ensure your install directory is in your `PATH`: * **macOS/Linux**: `~/.local/bin` (or your custom install directory) * **Windows**: `%LOCALAPPDATA%\Programs\cogniscape\` (added automatically by the installer) # AI Coding Session Data Quality Source: https://docs.cogniscape.app/incidents/2026-03-21-session-data-quality Incident report on reduced data quality for AI-assisted coding sessions, identified and resolved within 24 hours. **Date:** March 21, 2026 **Severity:** High **Status:** Resolved **Affected Feature:** AI coding session visibility in dashboards *** ## Summary We identified and resolved a data quality issue affecting how AI-assisted coding sessions (Claude Code) were captured and displayed in Cogniscape dashboards. Instead of showing meaningful details about what developers worked on — files touched, technologies used, objectives and outcomes — the system was producing generic entries such as *"Developer completed a session."* This significantly reduced the value of the five core visibility dimensions Cogniscape provides: **what, who, when, how, and why**. The issue was fully resolved within 24 hours. Session data quality improved from **4/10 to approximately 8/10** across all dimensions. *** ## What Was Affected Engineering managers relying on Cogniscape for AI coding session insights were seeing: * **Vague descriptions** — no detail about what was actually built or investigated * **Missing file data** — no visibility into which files or areas of the codebase were touched * **Incorrect branch information** — always showed the default branch, even for feature work * **Incomplete session capture** — only the first few minutes of long sessions were reflected Timestamp accuracy was unaffected (9/10 throughout). *** ## Root Cause Multiple issues in the data processing pipeline compounded to degrade session quality: 1. **Data loss during processing** — session details (title, result, files) were being dropped when certain metadata was present, replaced by a generic description 2. **Only the first snapshot was kept** — long-running sessions send periodic updates, but only the earliest update was retained, missing hours of subsequent work 3. **Unstructured summaries** — raw conversation fragments were used instead of structured descriptions, making it difficult to extract meaningful insights 4. **Missing metadata** — rich session data (files modified, commands run, tools used) was available but not being captured 5. **Noisy file references** — file paths included developer-specific system paths instead of clean, project-relative references *** ## Resolution We deployed a series of targeted fixes over four releases: | Phase | What Changed | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Fixed data loss — all session details are now preserved through the full processing pipeline | | 2 | Improved entity classification — entities are now correctly categorized (developers, repositories, pull requests, etc.) | | 3 | Enabled progressive session capture — each session update is now stored, reflecting the full scope of work regardless of duration | | 4 | Added AI-powered summarization — raw session data is automatically transformed into structured summaries covering objective, work performed, technologies used, and outcome | Additional improvements: * File paths are now clean and project-relative * Branch detection works correctly for all Git workflows * Metadata noise was reduced by 90% *** ## Results ### Quality Score Comparison | Dimension | Before | After | | -------------------------------- | -------- | ---------- | | **What** (work performed) | 2/10 | 8/10 | | **Who** (people involved) | 3/10 | 7/10 | | **When** (timing) | 9/10 | 9/10 | | **How** (methods and files) | 1/10 | 8/10 | | **Why** (motivation and context) | 1/10 | 7/10 | | **Overall** | **4/10** | **\~8/10** | ### Key Improvements | Metric | Before | After | | -------------------------- | ---------------------- | --------------------------------- | | Files captured per session | 0 | 30+ (modified and read) | | Commands captured | 0 | 5 most recent | | Tool usage breakdown | Not available | Full session breakdown | | Branch accuracy | Incorrect | Correct | | Session coverage | First few minutes only | Entire session | | Summary quality | Generic fragments | Structured objective/work/outcome | *** ## Privacy During the investigation, we evaluated capturing developer prompts (the messages typed to the AI assistant) to improve "why" context. **This was immediately rejected as a privacy violation** — no such data was ever persisted or made available. **Cogniscape's policy remains unchanged:** we never capture what developers type to their AI coding assistants. All insights are derived from structured activity metadata (files, commands, tool usage) and AI-generated summaries of the assistant's responses only. *** ## Lessons Learned 1. **Test with realistic data** — the primary bug went undetected because test scenarios didn't match real-world session patterns 2. **Progressive data matters** — coding sessions evolve over hours; capturing only the initial state misses the majority of the work 3. **AI summarization is essential** — raw conversation text is not a summary; AI-powered structuring dramatically improves downstream analysis 4. **Privacy by design** — even when a data point would improve analytics, it must be evaluated against trust and compliance requirements first *** ## Timeline | Date | Milestone | | ----------------- | ------------------------------------------------- | | March 20, 9:00 AM | Issue identified — quality investigation started | | March 20, 3:00 PM | Root causes identified | | March 20, 7:30 PM | First two fixes deployed | | March 21, 9:30 AM | All fixes deployed and verified in production | | March 21, 9:52 AM | Updated client (v1.6.0) released | | March 21, 9:56 AM | Auto-update to all active installations confirmed | **Total time to resolution: \~24 hours** *** ## Next Steps * Minor client patch (v1.6.1) to clean up a residual configuration item * Continued improvements to entity classification and deduplication * Additional data sanitization for sensitive command-line content # Tenant Validation Service Disruption Source: https://docs.cogniscape.app/incidents/2026-03-25-wal-contention-outage Incident report on API and MCP endpoint degradation caused by database lock contention, resolved within 2 hours. **Date:** March 25, 2026 **Severity:** High **Status:** Resolved **Affected Features:** API event ingestion, MCP endpoint, admin dashboard *** ## Summary We identified and resolved a service disruption affecting all tenant-authenticated endpoints. API event ingestion, MCP tool access, and the admin dashboard experienced a **95% failure rate** for approximately 2 hours. The root cause was database lock contention in the tenant validation layer. Multiple service containers were competing for exclusive access to a shared local database file, causing nearly all authentication checks to fail. The issue was triggered by increased developer load exceeding the concurrency limits of the previous architecture. All services were fully restored and the underlying architecture was permanently improved to eliminate this failure mode. *** ## What Was Affected Customers relying on Cogniscape experienced: * **Failed event ingestion** — CLI `send-episode` calls returned HTTP 500/502 errors * **MCP endpoint unavailable** — external MCP clients could not complete the initialization handshake * **Admin dashboard inaccessible** — the reverse proxy serving `api.cogniscape.app` was offline (pre-existing, unrelated) During this incident, monitoring dashboards incorrectly showed all services as "healthy." The healthcheck endpoints were not testing the tenant validation path, masking the actual failure. This has been added to our improvement backlog. *** ## Root Cause Cogniscape uses a cloud database ([Turso](https://turso.tech)) for tenant metadata — customer keys, session bindings, and usage tracking. To reduce latency, the system previously maintained a **local replica** of this database on the server. The problem: **five service containers** (API, MCP reader, and three event workers) all shared the same local replica file via a Docker volume. Each connection triggered a synchronization checkpoint that requires an exclusive file lock. With increased developer traffic, these lock requests became near-permanent, causing 95% of tenant validation attempts to fail. ### Why did this happen now? The number of developers actively sending signals to Cogniscape increased significantly. The previous architecture worked under lighter load because lock contention was intermittent. At higher concurrency, the contention became effectively permanent. *** ## Resolution We replaced the local database replica with a **direct connection** to the cloud database. This eliminates the shared file entirely — each container connects independently to the remote database without any local state or lock contention. | Aspect | Before | After | | ------------------- | ------------------------------------------------------ | -------------------------- | | **Connection type** | Local file replica with sync | Direct remote connection | | **Shared state** | 5 containers sharing 1 file | No shared state | | **Lock contention** | Permanent under load | Impossible (no local file) | | **Latency impact** | Negligible — database is co-located in the same region | Negligible | This pattern was already proven in production by another service component (analytics), giving us high confidence in the change. *** ## Timeline | Time (UTC) | Event | | ---------- | ---------------------------------------------------------------------- | | 13:55 | Last successful event ingestion from CLI clients | | 13:59 | Failures begin — 95% of requests return HTTP 500 or 502 | | 14:30 | Engineering investigation begins | | 14:34 | Root cause identified: database lock contention in tenant validation | | 15:00 | Fix implemented, tested, and submitted for automated code review | | 15:05 | Code review approved | | 15:08 | Fix merged to main branch | | 15:20 | Fix deployed to production — **zero lock errors** confirmed | | 15:22 | All services fully operational, including reverse proxy and subdomains | **Total time to resolution: \~1.5 hours from investigation start** *** ## Impact Summary | Metric | Value | | ----------------------- | -------------------------------------------------- | | Duration of degradation | \~2 hours (13:59–15:22 UTC) | | Requests affected | \~95% of tenant-authenticated requests | | Error types observed | HTTP 500, HTTP 502 | | Data loss | None — events are queued and retried automatically | | Customers notified | Proactively via status update | *** ## What We Improved Beyond the immediate fix, this incident drove several architectural improvements: All service containers now connect directly to the cloud database. There is no local file to contend over, regardless of how many containers are running. Cleaned up 6 synchronization calls, a file recovery mechanism, and related error handling — approximately 70 lines of code that are no longer needed. The TLS reverse proxy was brought under infrastructure management to prevent silent loss during maintenance operations. *** ## Planned Improvements * **Healthcheck enhancement** — add tenant database connectivity checks to healthcheck endpoints so monitoring accurately reflects service availability * **Error rate alerting** — set up automated alerts on tenant validation failure rates to detect degradation before it reaches 95% * **Deploy pipeline hardening** — enforce that production deploys only pull from the canonical main branch, preventing state divergence *** ## Data & Privacy No customer data was exposed, leaked, or corrupted during this incident. The failure occurred at the authentication layer — requests that failed never reached the data processing pipeline. Events that failed to ingest during the outage are automatically retried by the CLI client. # GitHub Source: https://docs.cogniscape.app/integrations/github Set up a GitHub webhook to capture pushes, pull requests, and code reviews in your knowledge graph. The GitHub integration captures activity from your repositories: pushes, pull requests, code reviews, and more. This is how Cogniscape answers **what** changed, **who** did it, **how** it was done, and **when** it happened. This setup needs to be done **once per repository** you want to observe. If you add new repos later, just repeat the process for each one. **We never store any source code.** Cogniscape only processes event metadata — commit hashes, PR titles, review comments, and similar structured data. Your code stays on GitHub. See [Data Privacy](/security/data-privacy) for details. ## Configure the webhook In GitHub, navigate to your repository and go to **Settings → Webhooks → Add webhook**. Use the following URL, replacing `` with the key from the [Customer Portal](https://customer.cogniscape.app/): ``` https://api.cogniscape.app/api/v1/events/github/ ``` * **Content type:** select `application/json` * **Secret:** copy the webhook signing secret from the [Customer Portal](https://customer.cogniscape.app/get-started/github) (under **Get Started → GitHub Webhook → step 3**) and paste it here. Cogniscape uses this value to verify that incoming events are genuinely from GitHub. Each customer has a unique webhook secret. The portal generates it for you — do not share it across tenants. If you need to rotate the secret, use the **Regenerate** button in the portal and paste the new value back into GitHub. Select **"Send me everything"** for the richest insights. This ensures Cogniscape captures all relevant activity as it happens. If you prefer granular control, you can select specific events in the GitHub webhook creation panel. At a minimum, enable: `push`, `pull_request`, `pull_request_review`, `pull_request_review_comment`, `issues`, `issue_comment`, and `deployment_status`. That's it. Events will start flowing into your knowledge graph immediately. ## Verify the webhook After saving, GitHub will send a `ping` event. You can check the delivery status under **Settings → Webhooks → Recent Deliveries**. A `200` response confirms Cogniscape received the event successfully. The [Customer Portal](https://customer.cogniscape.app/get-started/github) shows a status line under the secret: * **Not verified yet** — the secret is generated but no signed event has been received yet. * **Verified on ``** — Cogniscape received and verified at least one signed webhook event with this secret. Your wiring is correct. The status updates automatically when the first valid signature arrives. You do not need to confirm anything manually. ## Supported events Cogniscape processes these GitHub webhook event types: | Event | What it captures | | ----------------------------- | ----------------------------------------------------------------------- | | `push` | Commits pushed to any branch — who committed, when, and to which branch | | `pull_request` | PR creation, updates, merges, and closures — the full lifecycle | | `pull_request_review` | Code review submissions — approvals, change requests, and comments | | `pull_request_review_comment` | Inline code review comments on specific lines of a diff | | `issues` | Issue creation, updates, assignments, labeling, and closures | | `issue_comment` | Comments on issues and pull requests | | `deployment_status` | Deployment status notifications — success, failure, and pending states | Events not listed above are received but silently ignored. Selecting "Send me everything" is safe — it won't create noise in your knowledge graph. ## Multiple repositories Each repository needs its own webhook pointing to the same URL. The customer key in the URL ensures all events are routed to the correct knowledge graph regardless of which repository sends them. For GitHub organizations with many repositories, consider using an [organization-level webhook](https://docs.github.com/en/organizations/managing-organization-settings/managing-webhooks-for-your-organization) instead. Use the same Payload URL — Cogniscape handles both repository and organization webhooks identically. The same signing secret works across all your webhooks (repository-level or organization-level) — it is scoped to your customer account, not to an individual webhook. ## Why the signing secret matters GitHub signs every webhook payload with an HMAC-SHA256 signature using the secret you configured. Cogniscape verifies this signature before processing any event, ensuring the request is genuinely from GitHub and has not been tampered with. Each customer has their own unique secret. This means: * A leaked secret only affects your tenant — it cannot be used to forge events for other customers. * You can rotate the secret at any time from the [Customer Portal](https://customer.cogniscape.app/get-started/github) without coordinating across customers. * Ex-employees or compromised systems can be cut off by rotating, without disrupting other tenants. Rotating the secret invalidates the previous one **immediately**. Make sure to paste the new secret into your GitHub webhook configuration as soon as you rotate, or events will fail signature verification until the new secret is in place. # GitLab Source: https://docs.cogniscape.app/integrations/gitlab Set up a GitLab webhook to capture pushes, merge requests, issues, pipelines, and deployments in your knowledge graph. The GitLab integration captures repository activity: pushes, merge requests, issues, comments, releases, pipelines, and deployments. This is how Cogniscape connects delivery work to your knowledge graph — **what** changed, **who** did it, **how** it was done, and **when** it happened. You can configure the webhook for a single **project**, or at the **group** level to capture every project and subgroup at once. Group webhooks require **GitLab Premium or Ultimate**. On the Free tier, configure one webhook per project. **We never store any source code.** Cogniscape only processes event metadata — commit hashes, merge request titles, comments, and similar structured data. Your code stays on GitLab. See [Data Privacy](/security/data-privacy) for details. ## Configure the webhook In the top bar, find your project or group. In the left sidebar, select **Settings → Webhooks**, then select **Add new webhook**. Use a descriptive name such as **Cogniscape** so you can identify it later. Use the following URL, replacing `` with the key from the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab): ``` https://api.cogniscape.app/api/v1/events/gitlab/key/ ``` The portal shows the URL already filled in with your key — copy it straight from there instead of assembling it by hand. Under **Request authentication**, select **Generate signing token**. GitLab displays the signing token **only once**. Copy it before leaving the page — if you lose it, you have to generate a new one. Paste the token into the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab) under **Get Started → GitLab Webhook → step 4** and select **Save token**. Cogniscape uses it to verify that incoming events are genuinely from GitLab. Do **not** use the legacy **Secret token** field for a new webhook. Cogniscape verifies GitLab deliveries using the Standard Webhooks signature, which requires the signing token. Select these events so Cogniscape receives the development activity it supports: * Push events * Tag push events * Merge request events * Issue events (Issue Hook, including Work Items) * Comment events (Note Hook) * Release events * Pipeline events * Deployment events Select **Add webhook**. From the webhook list, open **Test** and send a **Push events** test. Confirm the test succeeds in GitLab, then return to the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab) and check that the signing token shows as saved. ## Verify the webhook After saving, GitLab records every delivery under **Settings → Webhooks → Edit → Recent events**. A `200` response confirms Cogniscape received and verified the event. Common failure responses: | Response | What it means | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `401 Unauthorized` | The signing token in the portal does not match the one GitLab is signing with, or the delivery timestamp is outside the 5-minute replay window. Regenerate the token in GitLab and re-save it in the portal. | | `403 Forbidden` | The customer key in the URL is invalid or the account is disabled. | | `422 Unprocessable Content` | The `X-Gitlab-Event` header is missing or the payload is malformed — usually a sign the URL was pasted into the wrong integration. | ## Supported events Cogniscape processes these GitLab webhook event types: | Event | What it captures | | -------------------- | -------------------------------------------------------------------------- | | Push events | Commits pushed to any branch — who committed, when, and to which branch | | Tag push events | Tags created or deleted — release checkpoints in the delivery timeline | | Merge request events | MR creation, updates, merges, and closures — the full lifecycle | | Issue events | Issue and Work Item creation, updates, assignments, labeling, and closures | | Comment events | Comments on merge requests, issues, commits, and code snippets | | Release events | Releases published, updated, and deleted | | Pipeline events | Pipeline runs — status, duration, and outcome | | Deployment events | Deployment status notifications — success, failure, and running states | Events not listed above are received but silently ignored. Enabling extra event types is safe — it won't create noise in your knowledge graph. ## Project vs group webhooks A **group webhook** covers every project and subgroup underneath it, including projects created later. This is the recommended setup if your plan supports it — you configure it once and new repositories are captured automatically. A **project webhook** covers a single project. On GitLab Free, repeat the setup for each project you want to observe. Both use the same webhook URL. The customer key routes all events to the correct knowledge graph regardless of which project or group sends them. You can mix both. If a project already has its own webhook and later falls under a group webhook, Cogniscape deduplicates deliveries — the same event won't be ingested twice. ## Why the signing token matters GitLab signs every webhook payload using the [Standard Webhooks](https://www.standardwebhooks.com/) scheme: an HMAC-SHA256 signature over the delivery ID, timestamp, and raw body, sent in the `webhook-signature` header. Cogniscape verifies this signature before processing any event, and rejects deliveries whose timestamp is more than **5 minutes** old to prevent replay attacks. Each customer has their own unique token. This means: * A leaked token only affects your tenant — it cannot be used to forge events for other customers. * You can rotate the token at any time from GitLab without coordinating across customers. * Ex-employees or compromised systems can be cut off by rotating, without disrupting other tenants. Rotating the token in GitLab invalidates the previous one **immediately**. Save the new token in the [Customer Portal](https://customer.cogniscape.app/get-started/gitlab) as soon as you rotate, or events will fail signature verification with `401` until the new token is in place. Full GitLab reference: [Webhooks documentation](https://docs.gitlab.com/user/project/integrations/webhooks/). # Jira Source: https://docs.cogniscape.app/integrations/jira Set up a Jira webhook to capture issue lifecycle, sprint, and project activity in your knowledge graph. The Jira integration captures issue lifecycle activity: created and updated issues, assignments, comments, status transitions, sprint movement, and project changes. Combined with GitHub and AI coding session data, this gives Cogniscape a complete picture of **what** your team is working on, **who** is involved, and **how** work moves from backlog to delivery. This setup needs to be done **once per Jira site** (or for each Jira instance you want Cogniscape to observe). Only a **Jira administrator** can create and manage webhooks. Both the Webhook URL and the signing secret are exclusive to your account. Keep the secret private — the endpoint rejects every request that does not include the matching secret. ## Choose exactly one setup path Jira Cloud and Jira Data Center / Server use different authentication mechanisms. Follow the section that matches your deployment — do not configure both for the same Jira instance. ## Jira Cloud Use this path only when your Jira is hosted by Atlassian Cloud. In Jira Cloud, go to **Settings → System → Webhooks**, then create a new webhook. Use something descriptive like **Cogniscape** so you can identify it later. Use the following URL, replacing `` with the key from the [Customer Portal](https://customer.cogniscape.app/): ``` https://api.cogniscape.app/api/v1/events/jira/ ``` Paste the secret from the [Customer Portal](https://customer.cogniscape.app/) (**Get Started → Jira Integration**) into Jira's **Secret** field. Cogniscape uses it to verify that incoming events are genuinely from your Jira site. Do not click **Generate secret**. That button makes Jira create its own value, but Cogniscape and Jira must use the same secret already registered for your account. Jira may warn that the secret cannot be displayed again after saving — that's fine, paste the Cogniscape secret and save. Select the development activity events Cogniscape uses to build the Jira layer of your graph: * **Issue**: created, updated, deleted * **Comment**: created, updated, deleted * **Worklog**: created, updated, deleted * **Issue link**: created, deleted * **Sprint**: created, updated, deleted, started, closed * **Project**: created, updated, deleted * **Version**: created, released (moved, merged, updated, and unreleased are optional) Leave **Board**, **Issue Type**, **User**, **Filter**, **Attachment**, **Entity property**, and **Feature status change** unchecked. Those are configuration or admin events, not development activity. Leave **Exclude body** unchecked — Cogniscape needs the JSON event body. JQL is optional. Leave it blank to receive all projects, or add a filter to restrict issue events. Sprint, Version, and Board events are sent for all projects and do not follow the JQL filter. ## Jira Data Center / Server Use this path only when your organization hosts Jira Data Center or Jira Server. In Jira administration, go to **System → WebHooks → Create**. Use the same URL as above, with your customer key from the [Customer Portal](https://customer.cogniscape.app/): ``` https://api.cogniscape.app/api/v1/events/jira/ ``` Add this header so Cogniscape can authenticate requests from your Jira instance, using the secret from the [Customer Portal](https://customer.cogniscape.app/): ``` X-Cogniscape-Token: ``` Use the same event selection from the Jira Cloud section: **Issue**, **Comment**, **Worklog**, **Issue link**, **Sprint**, **Project**, and **Version**. Leave configuration and admin events unchecked. Leave **Exclude body** unchecked, then save. Make sure your Jira server can make outbound HTTPS requests to `https://api.cogniscape.app` through your egress firewall. Create the webhook from the admin **WebHooks** screen above — that webhook type does not expire. Avoid REST or dynamic webhooks, which expire after 30 days. ## Verify the webhook After saving, trigger a test by creating or updating an issue in Jira. Check the webhook delivery log to confirm events are being sent with a `200` response. ## Supported resources Cogniscape processes these Jira webhook resource types: | Resource | Actions | What it captures | | ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------ | | `Issue` | create, update, delete | Title, key, status, priority, assignee, labels, description, and previous state on updates | | `Comment` | create, update, delete | Comment body on issues — discussions, decisions, and context | | `Worklog` | create, update, delete | Time logged against issues | | `Issue link` | create, delete | Relationships between issues (blocks, relates to, duplicates) | | `Sprint` | create, update, delete, start, close | Sprint name, state, and dates | | `Project` | create, update, delete | Project key, name, and metadata | | `Version` | create, release | Release version name and status | Resources not listed above are received but silently ignored. Selecting only the events above keeps your knowledge graph free of configuration and admin noise. ## Why the secret matters Cogniscape verifies every incoming Jira event against the secret saved in the Customer Portal before processing it. Without a matching secret, webhook events are rejected. Treat the secret as sensitive. If it's exposed, regenerate it in the [Customer Portal](https://customer.cogniscape.app/) and update the Jira webhook (Cloud secret field or Data Center header) before relying on new events. Old secrets stop working immediately after rotation. # Linear Source: https://docs.cogniscape.app/integrations/linear Set up a Linear webhook to capture issues, comments, and projects in your knowledge graph. The Linear integration captures your project management activity: issues, comments, projects, and project updates. Combined with GitHub and Claude Code data, this gives Cogniscape a complete picture of **what** your team is working on, **who** is involved, and **how** work progresses from idea to delivery. This setup needs to be done **once per Linear workspace**. Only a **workspace admin** can create webhooks in Linear. ## Configure the webhook In Linear, go to **Settings → API → New webhook**. Use something descriptive like **Cogniscape** so you can identify it later. Use the following URL, replacing `` with the key from the [Customer Portal](https://customer.cogniscape.app/): ``` https://api.cogniscape.app/api/v1/events/linear/ ``` Select **all available resources** for the most complete insights. Linear lets you pick individual resource types if you prefer granular control. At a minimum, enable: **Issues**, **Comments**, **Projects**, and **Project Updates**. These are the core resources Cogniscape uses to build the project management layer of your knowledge graph. After creating the webhook, Linear will show you a **signing secret**. Copy this value — you'll need to save it in the [Customer Portal](https://customer.cogniscape.app/) so Cogniscape can verify that incoming events are genuinely from Linear and have not been tampered with. The signing secret is only shown once when the webhook is created. Make sure to copy it before closing the dialog. Go to the [Customer Portal](https://customer.cogniscape.app/) and paste the signing secret in the Linear integration section under **Get Started → Linear Integration**. That's it. Events will start flowing into your knowledge graph immediately. ## Verify the webhook After saving, you can trigger a test by creating or updating an issue in Linear. Check the webhook delivery log under **Settings → API** to confirm events are being sent with a `200` response. ## Supported resources Cogniscape processes these Linear webhook resource types: | Resource | Actions | What it captures | | --------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------- | | `Issue` | create, update, remove | Title, identifier (e.g. ENG-123), state, priority, assignee, labels, description, and previous state on updates | | `Comment` | create, update | Comment body on issues — discussions, decisions, and context | | `Project` | create, update | Project name and state (planned, started, completed) | | `ProjectUpdate` | create, update | Status reports posted to projects — body text and health status (on track, at risk, off track) | Resources not listed above are received but silently ignored. Selecting all resources is safe — it won't create noise in your knowledge graph. ## Why the signing secret matters Linear signs every webhook payload with an HMAC-SHA256 signature using the signing secret. Cogniscape verifies this signature before processing any event. Without the signing secret saved in the Customer Portal, webhook events will be rejected with a `401` response. If you've lost the signing secret, delete the webhook in Linear and create a new one — Linear will generate a fresh secret. # Monday.com Source: https://docs.cogniscape.app/integrations/monday Set up a Monday.com webhook to capture board items, updates, and status changes in your knowledge graph. The Monday.com integration captures activity from your boards: items, updates (comments), column value changes, and subitems. Combined with GitHub, Linear, and Claude Code data, this gives Cogniscape a complete picture of **what** your team is working on, **who** is involved, and **how** work progresses from idea to delivery. This setup needs to be done **once per board** you want to observe. If you add new boards later, just repeat the process for each one. Only a **board owner** or **workspace admin** can add integrations to a board. ## Configure the webhook In Monday.com, open the board and click the **Integrate** button in the top-right corner. In the Integrations Center, search for **Webhooks** and pick a recipe such as **When an item is created, send a webhook**. Monday.com offers one recipe per trigger type — add one recipe per event you want to capture. Use the following URL, replacing `` with the key from the [Customer Portal](https://customer.cogniscape.app/): ``` https://api.cogniscape.app/api/v1/events/monday/key/ ``` For the richest insights, add a webhook recipe for each of these triggers: * **When an item is created** * **When an item's name changes** * **When a column value changes** (covers status, person, date, and any custom columns) * **When an update is posted** (comments on items) * **When a subitem is created** * **When an item is moved to a group** At a minimum, enable **item created**, **column value changes**, and **update posted**. These cover the core lifecycle Cogniscape uses to build the project management layer of your knowledge graph. On save, Monday.com sends a `challenge` request to the Webhook URL. Cogniscape responds with the matching `challenge` token automatically — no manual confirmation is required. If Monday rejects the recipe with a verification error, double-check the URL and customer key and try again. Once the handshake succeeds, events start flowing into your knowledge graph immediately. ## How requests are verified Board webhook recipes do not use a signing secret. Monday.com authorizes the endpoint **once at creation time** via a challenge/response handshake: 1. Monday sends `POST` with `{ "challenge": "" }` to the Webhook URL. 2. Cogniscape replies with the same `{ "challenge": "" }` payload. 3. Monday saves the recipe and starts delivering events. Because there is no per-payload signature, the customer key embedded in the URL is what scopes incoming events to your tenant. **Treat the Webhook URL as a secret** — anyone who can read it can post events into your knowledge graph. Do not share the Webhook URL outside your workspace. If the URL leaks, rotate your customer key from the [Customer Portal](https://customer.cogniscape.app/) and update every Monday.com recipe with the new URL. Programmatic webhooks created via the Monday GraphQL `create_webhook` mutation under an integration app token include a JWT in the `Authorization` header. Cogniscape verifies that JWT when present, but the standard board-recipe path covered above does not produce one. ## Verify the webhook After saving, trigger a test by creating or updating an item on the board. Monday surfaces failed deliveries in the recipe's **Activity** log; a `200` response from Cogniscape confirms the event was received. ## Supported events Cogniscape processes these Monday.com webhook event types: | Event | What it captures | | -------------------------------- | ------------------------------------------------------------------------ | | `create_item` | New item created — name, board, group, and creator | | `change_name` | Item name changes — previous and new value | | `change_column_value` | Column updates — status, person, date, text, numbers, and custom columns | | `change_status_column_value` | Status column transitions — previous and new label | | `create_update` | Comments posted on items — body text and author | | `create_subitem` | Subitem creation — parent item, name, and creator | | `item_moved_to_any_group` | Item moved between groups — source and destination group | | `item_archived` / `item_deleted` | Lifecycle terminal states for items | Events not listed above are received but silently ignored. Enabling additional triggers is safe — it won't create noise in your knowledge graph. ## Multiple boards Each board needs its own webhook recipe pointing to the same URL. The customer key in the URL ensures all events are routed to the correct knowledge graph regardless of which board sends them. For workspaces with many boards, configure the recipes once on a template board and duplicate it — Monday.com copies webhook integrations along with the board structure. # Integrations Source: https://docs.cogniscape.app/integrations/overview Connect your development tools to the Cogniscape knowledge graph. Cogniscape ingests data from multiple sources. The CLI captures AI coding activity from Claude Code and Cursor locally; GitHub, GitLab, Linear, Jira, and Monday.com webhooks capture code changes and project management activity remotely. Sessions, tasks, plans, and token usage — installed per developer machine. Automatically detects and hooks into both Claude Code and Cursor. Pushes, pull requests, and code reviews — one webhook per repository. Pushes, merge requests, pipelines, and deployments — one webhook per project, or one per group. Issues, comments, projects, and cycles — one webhook per workspace. Issues, comments, worklogs, sprints, projects, and versions — one webhook per Jira site. Board items, updates, and column changes — one webhook per board. GitHub, GitLab, Linear, Jira, and Monday.com integrations are configured entirely through webhook settings in those platforms. No additional software is needed on your machine — just the webhook URL containing your customer key. Jira also requires a signing secret (Cloud) or the `X-Cogniscape-Token` header (Data Center / Server). ## Claude Code vs Cursor: what's captured Both AI coding tools feed into the same knowledge graph, but they provide different levels of detail: | Capability | Claude Code | Cursor | | -------------------------------------- | --------------------- | ------------------------------------------- | | Session lifecycle (start/stop) | Yes | Yes | | Session summary (conversation content) | Yes | Yes | | Files modified/read | Yes (from transcript) | Not yet (transcript format limitation) | | Commands executed | Yes (from transcript) | Not yet | | Tool usage counts | Yes (from transcript) | Not yet | | Token usage per model | Yes (from transcript) | Not available (upstream limitation) | | Developer identity | git config | git config, falls back to Cursor user email | | Repository + branch | Yes | Yes | | Source discrimination | `source="agent"` | `source="cursor"` | Events from both tools are distinguishable in the knowledge graph and can be filtered independently in MCP queries. ## Where to find your customer key Your customer key is available in the [Cogniscape Customer Portal](https://customer.cogniscape.app/) under your account settings. It is used to route events to your knowledge graph. ## Data privacy Cogniscape only processes event metadata. **We never store source code.** GitHub and GitLab webhook payloads contain commit metadata, PR/MR titles, and review comments — not file contents. Linear, Jira, and Monday.com payloads contain issue/item titles, descriptions, and status updates. For more details, see [Data Privacy](/security/data-privacy). # What is Cogniscape? Source: https://docs.cogniscape.app/introduction A knowledge graph of your entire development workflow — automatically built from Claude Code, Cursor, GitHub, GitLab, Linear, Jira, and Monday.com. Cogniscape captures everything that happens across your development workflow and stores it in a searchable knowledge graph. No manual notes. No context switching. Just ask your AI assistant what happened, why something changed, or what's in progress — and get a grounded answer. ## Ingestion points Cogniscape automatically captures activity from the places where development actually happens: Sessions, plans, tasks, token usage, and session summaries — captured via hooks on the developer's machine. Sessions and conversation summaries — captured via Cursor hooks, automatically detected during installation. Pushes, pull requests, and code reviews — captured via repository webhooks. Pushes, merge requests, pipelines, and deployments — captured via project or group webhooks. Issues, comments, projects, and project updates — captured via workspace webhooks. Issues, comments, worklogs, sprints, projects, and versions — captured via site webhooks. Board items, updates, and column changes — captured via board webhooks. All streams feed into the same knowledge graph, so you can ask questions that span AI activity, code changes, and project management in a single query. ## How it works ```text theme={null} LOCAL (developer machine) Claude Code hooks Cursor hooks ├── SessionStart ├── sessionStart ├── ExitPlanMode ├── stop ├── TaskCreate └── sessionEnd ├── TaskUpdate └── Stop │ │ ▼ ▼ cogniscape CLI (local enrichment: git identity, transcript, session summary) │ │ REMOTE (platform webhooks) │ ├── GitHub push, pull_request, pull_request_review ├── GitLab push, merge_request, pipeline, deployment ├── Linear Issue, Comment, Project, ProjectUpdate ├── Jira Issue, Comment, Worklog, Issue link, Sprint, Project, Version └── Monday.com Item created, Column value changed, Update created, Subitem created │ ▼ Cogniscape API → Redis Queue │ ▼ Event Worker → Knowledge Graph (Neo4j) │ ▼ Cogniscape MCP → AI assistants ``` ## Query from any MCP-enabled tool Once events are in the graph, you retrieve context through the Cogniscape MCP — available in any tool that supports the Model Context Protocol, including Claude Code, Claude Desktop, OpenAI Codex, and others. Ask things like: * *"What did the team deliver this week? Summarize completed issues, merged PRs, and any blockers."* * *"What is our average cycle time from opening an issue to merging the PR? Which items are taking the longest, and why?"* * *"Is the team on track to finish the current sprint? Which issues haven't had any activity in the last 3 days?"* * *"How much of our engineering effort is going to new features versus bug fixes versus infrastructure? Has that changed compared to last month?"* * *"How much of our codebase is being built with AI assistance? What is the concrete return on that investment?"* * *"How efficient is our code review process? How many PRs required rework, and what are the most common reasons?"* ## Get started Install the CLI and start capturing Claude Code and Cursor activity automatically. Full reference for all cogniscape commands and flags. Set up a webhook to capture pushes, PRs, and code reviews. Set up a webhook to capture pushes, merge requests, pipelines, and deployments. Set up a webhook to capture issues, comments, and project updates. Set up a webhook to capture issues, comments, sprints, and versions. Set up a webhook to capture board items, updates, and column changes. Query the knowledge graph from Claude Code, Claude Desktop, or any MCP client. # Cogniscape MCP Source: https://docs.cogniscape.app/mcp-reader/overview Query your development knowledge graph from any MCP-enabled AI assistant. This is where the magic happens. The MCP Reader is the interface designed for **engineering managers, tech leads, and everyone above them**. It gives you complete freedom to query your knowledge graph and shape the data exactly the way you need it. Ask anything: team performance summaries, AI token ROI, sprint progress, individual contribution reports. The MCP Reader understands natural language, so you simply describe what you need and get the answer in the format you prefer. ## Authentication The MCP Reader uses **OAuth with JWT**. On first connection, your client will open a login page where you authenticate with your Cogniscape account. Tokens expire after 60 minutes and are automatically renewed. After 30 days of inactivity, a new login is required. This applies to all clients listed in the [setup guide](/mcp-reader/setup). ## Beyond interactive queries The MCP Reader is not limited to AI clients like Claude Desktop. It's a standard MCP endpoint that can be integrated into **automated workflows and scheduled tasks**. Build pipelines that generate reports automatically and deliver them via Slack, email, WhatsApp, Telegram, or any channel your organization uses. Weekly team summaries, monthly performance reviews, daily token usage digests: all fully automated. ## Tools The Cogniscape MCP exposes seven tools that AI assistants can call to retrieve data from your knowledge graph. ### get\_activity\_timeline The primary tool for understanding what happened. Returns entities (PRs, issues, features, developers) that were active during a time period, along with their summaries and temporally-scoped facts. | Parameter | Type | Default | Description | | ------------ | -------- | ----------- | --------------------------------------------------------------- | | `since` | `string` | `"24h"` | Time period — ISO-8601 datetime or relative (`7d`, `24h`, `2w`) | | `source` | `string` | all | Filter by data source: `agent`, `github`, `linear`, or `monday` | | `repository` | `string` | all | Filter by repository (e.g. `org/repo`) | | `group_id` | `string` | tenant-wide | Scope to a specific namespace | | `max_items` | `int` | all | Maximum number of entities to return | **When to use:** Broad questions like "what happened this week?", "what did the team deliver?", or any time-based query. ### search\_nodes Semantic search for entities (nodes) in the knowledge graph — developers, repositories, PRs, issues, features, and any other concept Cogniscape has extracted. | Parameter | Type | Default | Description | | ------------- | -------- | ----------- | ------------------------------------ | | `query` | `string` | *required* | Natural language search query | | `num_results` | `int` | `10` | Maximum number of entities to return | | `group_id` | `string` | tenant-wide | Scope to a specific namespace | **When to use:** Entity questions like "who is Alice?", "what is the billing service?", or "find all repositories related to payments". ### search\_facts Semantic search for relationships (edges) between entities. Facts include temporal validity — you can see when a relationship was true and when it expired. | Parameter | Type | Default | Description | | ------------- | -------- | ----------- | ------------------------------------------------------ | | `query` | `string` | *required* | Natural language search query | | `num_results` | `int` | `10` | Maximum number of facts to return | | `group_id` | `string` | tenant-wide | Scope to a specific namespace | | `since` | `string` | — | Filter facts created at or after this date (ISO-8601) | | `until` | `string` | — | Filter facts created at or before this date (ISO-8601) | **When to use:** Relationship questions like "what PRs did Alice merge?", "which issues are blocking the release?", or "what was authored this week?" (use `since` for temporal filtering). ### get\_episodes Retrieves raw ingestion events — the conversations, code changes, and webhook payloads that were added to the graph. Useful for understanding provenance and context. | Parameter | Type | Default | Description | | ---------------- | -------- | ----------- | -------------------------------------- | | `group_id` | `string` | tenant-wide | Scope to a specific namespace | | `max_episodes` | `int` | `10` | Maximum number of episodes to return | | `reference_time` | `string` | now | ISO-8601 timestamp to anchor the query | **When to use:** Provenance questions like "when was this information added?", "show me the raw events from yesterday", or debugging data ingestion. ### get\_token\_usage Returns AI token consumption and estimated cost in USD, broken down by model and developer. | Parameter | Type | Default | Description | | ------------ | -------- | -------- | ---------------------------------------------- | | `period` | `string` | `"week"` | Predefined period: `today`, `week`, or `month` | | `developer` | `string` | all | Filter by developer name | | `date_start` | `string` | — | Custom start date (`YYYY-MM-DD`, inclusive) | | `date_end` | `string` | — | Custom end date (`YYYY-MM-DD`, inclusive) | | `repository` | `string` | all | Filter by repository name | When `date_start` and `date_end` are provided, the `period` parameter is ignored. **When to use:** Cost questions like "how much did Claude cost this week?", "what's our token usage by developer?", or "show me AI spending for the billing repo". ### get\_developer\_roi Returns ROI analysis per developer: total cost, daily average, daily trend, and breakdowns by model and repository. | Parameter | Type | Default | Description | | ------------ | -------- | --------- | ---------------------------------------------- | | `developer` | `string` | all | Filter by developer name | | `period` | `string` | `"month"` | Predefined period: `today`, `week`, or `month` | | `date_start` | `string` | — | Custom start date (`YYYY-MM-DD`, inclusive) | | `date_end` | `string` | — | Custom end date (`YYYY-MM-DD`, inclusive) | | `repository` | `string` | all | Filter by repository name | **When to use:** ROI questions like "what's the cost per developer?", "show me the spending trend", or "is our AI investment efficient?". ### get\_saga\_timeline Retrieves the ordered timeline of episodes belonging to a lifecycle saga. Sagas automatically group related events — every PR, issue, and coding session gets its own saga, linking all events in chronological order. | Parameter | Type | Default | Description | | ----------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------ | | `saga_name` | `string` | *required* | The saga identifier (e.g. `"PR #99 cogniscape-app"`, `"Issue #42 cogniscape-app"`, `"Session sess-abc-123"`) | | `group_id` | `string` | tenant-wide | Scope to a specific namespace | Saga names follow a deterministic pattern based on the event source: | Event type | Saga name format | | --------------------- | ------------------------------ | | Pull request events | `PR # ` | | Issue events | `Issue # ` | | Coding session events | `Session ` | **When to use:** Lifecycle questions like "show me the full history of PR #99", "what happened with issue #42?", or "trace this coding session from start to finish". ## Prompts The Cogniscape MCP includes six built-in prompts — pre-written conversation starters that guide the AI assistant to use the right tools and present results in a structured way. These appear as suggested prompts in compatible clients. ### daily\_standup Summarizes the last 24 hours of activity: what was done, what's in progress, and attention points. Accepts optional `repository` and `developer` filters. ### weekly\_review Generates a comprehensive weekly report: deliveries, merged PRs, deployments, decisions, and blockers. Designed for team review meetings. ### developer\_profile Shows a developer's activity profile: recent contributions, repositories, contribution types (code, reviews, issues), and AI token consumption. ### document\_history Shows the change history for a specific document, repository, or component: who modified it, when, and what changed. ### cost\_report Generates an AI cost report for a given period using `get_token_usage` and `get_developer_roi`. Includes total estimated cost, distribution by model and developer, daily trend, and average daily cost. Presented for non-technical managers. ### team\_overview Maps the project's contributors: areas of expertise, contribution types (code, reviews, management), and recent activity. Presented as a team map. ## Tool selection guide Not sure which tool to use? Here's a quick reference: | Question type | Recommended tool | | ------------------------------ | ------------------------------- | | "What happened this week?" | `get_activity_timeline` | | "Who is this developer?" | `search_nodes` → `search_facts` | | "What PRs did Alice merge?" | `search_facts` | | "What was authored this week?" | `search_facts` with `since` | | "Show me PR #99 full history" | `get_saga_timeline` | | "How much did Claude cost?" | `get_token_usage` | | "Show me ROI by developer" | `get_developer_roi` | | "When was this data ingested?" | `get_episodes` | | Broad time-based questions | `get_activity_timeline` | | Lifecycle tracking (PR/issue) | `get_saga_timeline` | | Entity lookup + relationships | `search_nodes` → `search_facts` | For complex questions, the AI assistant will combine multiple tools automatically. For example, "what did Alice work on this week and how much did it cost?" will use both `get_activity_timeline` and `get_token_usage`. # Setup Source: https://docs.cogniscape.app/mcp-reader/setup Install the Cogniscape MCP on your preferred AI client. ## Claude (web, Desktop, mobile) The installed Claude Desktop app does not natively accept Streamable HTTP connectors, but the **claude.ai web interface does**, and the Desktop, iPhone, and Android apps all inherit connectors from the web account. Configure once on the web and it works everywhere. Sign in at claude.ai and open the [Add custom connector](https://claude.ai/settings/connectors?modal=add-custom-connector) dialog directly. * **Name:** `Cogniscape` * **Remote MCP server URL:** `https://mcp.cogniscape.app` Claude custom connector dialog with Name and Remote MCP server URL fields Click **Add**. Claude will open the Cogniscape OAuth flow. Sign in with your Cogniscape account to authorize the connector. The connector is now available on claude.ai, Claude Desktop, and the Claude iOS and Android apps under the same account. No per-device setup. *** ## Claude Code (CLI) Run this command in your terminal to add Cogniscape as an MCP server available across all your projects: ```bash theme={null} claude mcp add --transport http --scope user cogniscape https://mcp.cogniscape.app ``` To verify the server is connected, run `/mcp` inside a Claude Code session. To limit the server to a single project, replace `--scope user` with `--scope local`. *** ## Cursor Open Cursor and go to **Settings > MCP**, then click **Add new MCP Server**. Alternatively, create or edit the file `~/.cursor/mcp.json` for global access: ```json theme={null} { "mcpServers": { "cogniscape": { "type": "http", "url": "https://mcp.cogniscape.app" } } } ``` For project-level configuration, place the file at `.cursor/mcp.json` in your project root instead. The server should appear with a green status indicator in Cursor settings after saving. *** ## Codex (OpenAI CLI) Run this command in your terminal: ```bash theme={null} codex mcp add --url https://mcp.cogniscape.app cogniscape ``` This saves the configuration to `~/.codex/config.toml`. Restart Codex CLI to pick up the new server. *** ## OpenCode Create or edit `opencode.json` in your project root and add: ```json theme={null} { "mcp": { "cogniscape": { "type": "remote", "url": "https://mcp.cogniscape.app" } } } ``` Restart OpenCode after saving. Run `opencode mcp list` to verify the server is connected. # Quick Setup Source: https://docs.cogniscape.app/quickstart Get Cogniscape running in one command. Run the install script with your customer key — it downloads the binary, saves your key to `~/.cogniscape/config.json`, and installs hooks for Claude Code and Cursor automatically: ```bash theme={null} curl -fsSL https://install.cogniscape.app/cogniscape.sh | sh -s -- ``` ```powershell theme={null} & ([scriptblock]::Create((irm https://install.cogniscape.app/cogniscape.ps1))) "" ``` The only output you should see is: ``` SUCCESS ``` Your customer key is stored in `~/.cogniscape/config.json` — machine-level, shared across all projects. You only need to configure it once per machine. That's it. Claude Code and Cursor will now capture sessions, tasks, and plans across all your projects and send them to the Cogniscape knowledge graph automatically. Cursor hooks are installed automatically when `~/.cursor/` is detected on the machine. If you install Cursor after Cogniscape, run `cogniscape init ` again to pick up the Cursor hooks. ## Uninstall To fully remove Cogniscape from the machine (removes hooks and the binary): ```bash theme={null} cogniscape uninstall ``` ## Connect your Claude client To query your knowledge graph from Claude, add the Cogniscape MCP to your client config. Configure once on claude.ai and the connector is automatically available on Claude Desktop, iPhone, and Android under the same account. 1. Open the [Add custom connector](https://claude.ai/settings/connectors?modal=add-custom-connector) dialog directly. 2. **Name:** `Cogniscape`. 3. **Remote MCP server URL:** `https://mcp.cogniscape.app`. 4. Click **Add** and complete the OAuth login with your Cogniscape account. The installed Claude Desktop app does not accept Streamable HTTP connectors directly. Configuration must come from the web account, which is the single source of truth across all Claude surfaces. Run this in your terminal to add Cogniscape across all projects: ```bash theme={null} claude mcp add --transport http --scope user cogniscape https://mcp.cogniscape.app ``` For Cursor, Codex, and OpenCode setup, see the [MCP setup guide](/mcp-reader/setup). # Data Privacy & Code Safety Source: https://docs.cogniscape.app/security/data-privacy How Cogniscape protects your intellectual property — what we store, what we don't, and why you might occasionally see code-like content in responses. Cogniscape captures **development activity metadata** — who did what, when, and why — not source code. Every event from GitHub, GitLab, Linear, Jira, Monday.com, and developer tools passes through a multi-stage sanitization pipeline that strips code blocks, diff hunks, and raw payloads before anything reaches our knowledge graph. In rare cases, the Cogniscape MCP may return content that *resembles* code. This is not stored code leaking out — it is your own LLM reconstructing code-like patterns from the semantic descriptions stored in the graph. This page explains exactly how that works and why your source code remains safe. Cogniscape stores semantic descriptions of what happened in your codebase — never the code itself. ## How we process developer activity Every event that enters Cogniscape passes through four stages before it reaches the knowledge graph. Each stage reduces the payload to only the semantic information needed for developer intelligence. ````text theme={null} Stage 1: Event Reception GitHub / GitLab / Linear / Jira / Monday.com / Developer Tools → raw event payload received Stage 2: Normalization Raw payload → structured event model Only selected fields are mapped (title, action, developer, timestamps) The full raw payload is discarded Stage 3: Sanitization Fenced code blocks (```...```) → removed Inline code (`...`) → removed Diff hunks → excluded Raw payloads → excluded Internal identifiers → excluded Stage 4: Knowledge Graph Ingestion Sanitized data → AI extraction → entities, facts, and episodes The AI extracts semantic meaning: "who did what to what, and why" Output: natural-language descriptions, not code ```` Every event type (pull requests, reviews, comments, issues, pushes) has a dedicated processing path that explicitly selects which fields to include. Unknown event types fall back to a conservative default that still excludes all code and sensitive fields. ## What we store vs. what we don't The tables below show exactly which fields from common developer events are kept and which are discarded. ### Pull request events | Field | Stored | Example of what reaches the graph | | ---------------------------- | ------------- | ---------------------------------------------------------- | | Developer | Yes | `"alice"` | | Repository | Yes | `"acme/backend"` | | Action | Yes | `"opened"`, `"merged"` | | PR number | Yes | `42` | | Title | Yes | `"Add retry logic to payment service"` | | State | Yes | `"open"`, `"closed"` | | Branch names | Yes | `"feat/retry-payments"` | | Labels | Yes | `["bug", "priority:high"]` | | Assignees / Reviewers | Yes | `["bob", "carol"]` | | PR body (description) | **Sanitized** | Code blocks and inline code removed; surrounding text kept | | Diff / changed files content | **No** | Never captured | | Raw event payload | **No** | Always excluded | ### Review and comment events | Field | Stored | Notes | | ------------ | ------------- | -------------------------------------------------- | | Review state | Yes | `"approved"`, `"changes_requested"` | | Review body | **Sanitized** | Code blocks removed | | Comment body | **Sanitized** | Code blocks removed | | Code diffs | **No** | Contains actual code — always excluded | | File path | Yes | `"src/payments/retry.ts"` (path only, not content) | ### Push events | Field | Stored | Notes | | ----------------------------------- | ------ | ------------------------------------ | | Branch | Yes | `"main"` | | Commit messages | Yes | Human-written text describing intent | | Commit identifiers | **No** | Excluded | | File lists (added/modified/removed) | **No** | Excluded | | File contents | **No** | Not included in event payloads | Commit messages are written by developers and may occasionally reference code patterns. Cogniscape stores them as-is because they represent developer intent, not source code. ## Understanding LLM-reconstructed content This is the most important section of this document. Even with all code stripped from stored data, you may occasionally see what looks like source code in a Cogniscape MCP response. Here is why. ### What the knowledge graph actually contains When Cogniscape processes a sanitized event, our AI engine extracts **entities** and **facts** in natural language. For example, from a pull request review that discusses a timestamp bug fix, the graph might store the following (function and variable names are extracted from PR discussions, not from source code): **Entities:** * `addNotification` — *"A helper function that captures the current ID before incrementing to ensure correct timestamp alignment in notification creation."* * `currentId` — *"A variable used to generate sequential notification IDs and corresponding timestamp offsets."* **Facts:** * *"The addNotification helper was introduced to fix an off-by-one bug where the template literal evaluated before the ID increment."* These are natural-language descriptions. There is no stored code. ### How code-like content appears in responses When you query the Cogniscape MCP — for example, asking *"What technical issues were found in the notifications PR?"* — the following happens: 1. The Cogniscape MCP searches the knowledge graph and retrieves relevant entities and facts 2. These results are passed to **your LLM** (the one powering your Claude Code, Claude Desktop, or other MCP client) 3. Your LLM synthesizes a response from the semantic descriptions Because the entity names are code identifiers (`addNotification`, `currentId`) and the fact descriptions are detailed enough to convey the logic, **your LLM can reconstruct plausible code** as part of its response. It is doing what LLMs do — generating the most helpful answer from the context it received. The code in such responses is **generated by your own LLM at query time**, not retrieved from the Cogniscape database. It may not even match your actual implementation — it is the LLM's best interpretation of the semantic descriptions. ### A concrete example Here is what is stored in the graph versus what your LLM might generate: ```text theme={null} Entity: addNotification Summary: "A helper function that captures the current ID before incrementing to ensure correct timestamp alignment." Fact: "The template literal was previously causing potential misalignment due to how the ID was being incremented inside the function." ``` ```js theme={null} // Before — bug: currentId++ increments AFTER being // read in the template literal `notif-${currentId++}` // After — fix: helper captures id BEFORE incrementing const addNotification = () => { const id = currentId; currentId++; return { id: `notif-${id}`, timestamp: ... } } ``` This code was **not stored anywhere in Cogniscape**. The LLM reconstructed it from the natural-language descriptions to illustrate the concept in its response. ## Security by design Cogniscape's data protection is enforced at multiple layers, ensuring that no single point of failure can expose source code. | Layer | Protection | | ------------------- | ---------------------------------------------------------------------------------------------------- | | **Event reception** | Only selected event types are accepted; others are rejected | | **Normalization** | Raw payloads are discarded — only structured metadata fields proceed | | **Sanitization** | Code blocks, inline code, diff hunks, and sensitive fields are stripped | | **Knowledge graph** | AI extracts natural-language entities and facts, not code | | **Cogniscape MCP** | Returns semantic search results; any code in the final response is generated by the client's own LLM | If you have questions about how Cogniscape handles your data, contact us at [support@cogniscape.app](mailto:support@cogniscape.app). # Developer Privacy Source: https://docs.cogniscape.app/security/developer-privacy What Cogniscape captures from Claude Code, Codex, and Cursor sessions, what it doesn't, and why — full transparency for developers whose activity flows through the platform. When you use Claude Code, Codex, or Cursor with Cogniscape installed, a lightweight background process captures **development activity metadata** from your coding sessions. This page explains exactly what is collected, what is not, and the purpose behind each data point. Cogniscape never reads your prompts, your conversation history, or the content of your files. It captures activity metadata — the same kind of information that already appears in your git log. ## What triggers data collection Cogniscape registers hooks in your AI coding tool that fire at specific moments during a session. No data is collected outside of these events. | Event | When it fires | | ------------------- | ------------------------------------------------------ | | Session start | You open a new Claude Code session | | Session summary | The agent finishes its work and returns control to you | | Subagent conclusion | A background agent finishes its work | | Stop failure | The agent stops on an unrecoverable error | The session-start hook only seeds local context (your current branch) — it stores no activity episode. Every captured field comes from the session-summary, subagent-conclusion, and stop-failure events. | Event | When it fires | | --------------- | -------------------------------------------------- | | Session start | You open a new Codex session | | Session summary | Codex finishes its turn and returns control to you | Codex uses only the session-start and session-summary hooks. As with Claude Code, session-start stores no episode — it seeds local context. Tool counts and work context are extracted from the session transcript when the turn ends. | Event | When it fires | | --------------- | ------------------------------------------------------ | | Session start | You open a new Cursor AI session | | Session summary | The agent finishes its work and returns control to you | | Session end | You close the session | Cursor integration captures less metadata than Claude Code. Token usage, file lists, and command history are not available through Cursor's hook system. As elsewhere, the session-start hook stores no episode. ## What we capture and why Every field we collect serves a specific purpose in answering the five core questions Cogniscape is built around: **what** happened, **who** did it, **when**, **how**, and **why**. ### Identity and context | Field | Example | Purpose | | ---------------- | ------------------------ | ---------------------------------------------------- | | Developer name | `"alice"` | Attribute activity to the right person (**who**) | | Repository | `"acme/backend"` | Scope activity to a project (**what**) | | Branch | `"feat/retry-payments"` | Track which initiative is being worked on (**what**) | | Session duration | `1842` (seconds) | Understand effort distribution (**when** / **how**) | | Timestamp | `"2026-03-28T14:32:00Z"` | Place activity in time (**when**) | ### What the AI assistant did | Field | Example | Purpose | | -------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | | AI response summary | `"Implemented retry logic with exponential backoff..."` | Understand the work that was done (**what** / **why**) | | Tool usage counts | `{"Edit": 12, "Read": 8, "Bash": 5}` | Gauge session complexity (**how**) | | Files touched | `["src/payments/retry.ts", "tests/retry.test.ts"]` | Track which areas of the codebase were involved (**what**) | | Recent commands | `["npm test", "git status"]` | Understand the development workflow (**how**) | | Test results | `passed: true` | Track quality signals (**how**) | | Token usage by model | `{"claude-opus-4-6": 45000}` | Resource attribution (internal analytics) | The AI response summary contains only the **assistant's messages** — never your prompts or questions. It is also truncated and sanitized before storage: code blocks, URLs, and identifiers are stripped. ## What we do NOT capture This is the most important section of this page. The following data **never leaves your machine**: When you type a message to Claude Code, Codex, or Cursor, that text stays local. Cogniscape explicitly filters out all user messages — only assistant responses are processed, and even those are truncated and sanitized. The full transcript of your session is never sent to Cogniscape. The CLI reads the transcript file locally to extract metadata (duration, tool counts, file lists) and then discards the file reference. The transcript itself is never uploaded. Cogniscape captures **file paths** (e.g., `src/payments/retry.ts`) but never the content of those files. Paths are also converted to repository-relative format — absolute paths and home directory references are stripped before transmission. No IDE configuration, environment variables, `.env` files, API keys, or authentication tokens are ever accessed or transmitted. The CLI only reads the hook payload provided by the AI tool and your local git configuration (name, email, branch). Only the **last 5 commands** you ran are captured, and each is **truncated to 200 characters**. Long commands, heredocs, and multi-line scripts are dropped entirely. Command output (stdout/stderr) is never captured. All file paths are converted to repository-relative paths before transmission. Your home directory, workspace root, and any worktree prefixes are stripped. The server never learns your filesystem layout. ## How data flows from your machine The following diagram shows the complete data path from your coding session to the Cogniscape knowledge graph. ```text theme={null} Your Machine Cogniscape Cloud ───────────── ──────────────── Claude Code / Codex / Cursor │ ▼ Hook fires (e.g., session summary) │ ▼ Cogniscape CLI (local binary) ├── Reads hook payload (provided by AI tool) ├── Reads git config (name, email, branch) ├── Reads transcript locally (extracts metadata only) ├── Strips absolute paths ├── Truncates commands (200 chars, last 5) ├── Filters out user messages └── Sends structured event ──────────────► API endpoint │ ▼ Sanitization ├── Code blocks removed ├── URLs stripped ├── Identifiers excluded └── Passes to knowledge graph │ ▼ AI extraction ├── Entities (natural language) ├── Facts (natural language) └── Stored as semantic descriptions ``` Sanitization happens at two stages: first on your machine (the CLI strips paths and truncates data), then on the server (the ingestion pipeline removes code blocks, URLs, and sensitive patterns). Defense in depth — even if something slips past the first stage, the second stage catches it. ## Frequently asked questions No. Your prompts are never captured, transmitted, or stored. No one — including Cogniscape, your manager, or your organization's admin — can access what you typed into Claude Code, Codex, or Cursor. No. Cogniscape sees file **paths** (which files you touched) but never file **contents**. This is architecturally enforced — the CLI does not read your source files, only the hook payload and git metadata. It stays local. Since Cogniscape never captures user messages, anything you paste into a prompt — passwords, API keys, personal notes — is never transmitted to Cogniscape. No. Cogniscape only fires during the specific hook events listed above. There is no background monitoring, no keystroke logging, and no screen capture. Between hook events, the CLI is completely idle. Yes. The Cogniscape CLI is a local binary that runs on your machine. You can inspect the hook configuration in `~/.claude/settings.json` (Claude Code), `~/.codex/hooks.json` (Codex), or `~/.cursor/hooks.json` (Cursor) to see exactly which events trigger data collection. You can also run the CLI with verbose logging to see the exact payload before it is sent. Running `cogniscape uninstall` removes all hooks from your AI tool's configuration and deletes the CLI binary. No residual data collection occurs after uninstall. Historical data already in the knowledge graph is retained according to your organization's data retention policy. If you have questions about developer privacy, contact us at [support@cogniscape.app](mailto:support@cogniscape.app).