Statewave

CI npm Docker Pulls License: Apache-2.0

Feed real-world events into Statewave.

Statewave Connectors turn GitHub issues, pull requests, Slack threads, Discord questions, support tickets, docs, email, and automation events into Statewave episodes.

Your agents can then retrieve compact, relevant memory by subject — instead of stuffing raw chat history or rebuilding a custom RAG pipeline for every tool.

Connectors talk to Statewave over its HTTP API and run as a standalone service — so they work with any Statewave app regardless of language (Python, Go, Rust, TypeScript). You don't need a Node app, or even Node installed, to use them.

📋 Issues & feature requests for the entire Statewave workspace are tracked centrally on smaramwbc/statewave — including connector-specific bugs. Issues are disabled on this repo so all reports funnel to one place.

Why

Most "agent memory" implementations are limited to live chat transcripts. Real teams have memory in many places: GitHub history, Slack threads, support tickets, ADRs, email threads, workflow runs. Statewave is open memory infrastructure that holds all of those as episodes, compiles them into durable memories per subject, and serves compact context to agents on demand.

This repository is the connector ecosystem for that.

Two ways to run connectors

Connectors are independent of your application's language. Pick whichever fits your stack:

1. As a deployed service — recommended, no Node required. Run the prebuilt runner container next to your app, the same way you'd run Postgres or Redis, and point it at your Statewave instance with a small TOML config. This is the path to use when your app is Python, Go, Rust — anything that isn't itself a Node service.

docker run --rm -p 3000:3000 \
  -v $PWD/statewave-connectors.toml:/config/statewave-connectors.toml:ro \
  -e STATEWAVE_URL=https://your-instance \
  -e STATEWAVE_API_KEY=… \
  statewavedev/statewave-connectors-runner:latest

Compose / Helm / Fly / Railway recipes ship in deploy/ — see docs/deployment.md.

2. As npm packages — for embedding in a Node app. This is a monorepo for development, but each connector ships as its own published package, so you install only what you need.

npm install @statewavedev/connectors-github
npm install @statewavedev/connectors-gitlab
npm install @statewavedev/connectors-bitbucket
npm install @statewavedev/connectors-gitea
npm install @statewavedev/connectors-azure-devops
npm install @statewavedev/connectors-jira
npm install @statewavedev/connectors-database
npm install @statewavedev/connectors-markdown
npm install @statewavedev/connectors-slack
npm install @statewavedev/connectors-n8n
npm install @statewavedev/connectors-zapier
npm install @statewavedev/connectors-discord
npm install @statewavedev/mcp-server

You do not need to install Slack to use the GitHub connector. The convenience meta-package @statewavedev/connectors exists for the rare case where you want all official connectors at once — it is not required for normal usage.

Using Statewave from Python? You have full connector coverage today via path 1: the container ingests GitHub / Slack / Notion / support tickets into the same instance your pip install statewave app reads from. There is no separate "Python connectors" package because connectors are a service, not an SDK binding.

Status — v0.22.0 (current release wave)

v0.18.0–v0.22.0 build out two preview source connectors — Jira (@statewavedev/connectors-jira) and database (@statewavedev/connectors-database, dialects: PostgreSQL / MySQL / MariaDB / MSSQL). Both ingest selected external records into Statewave memory; they are not Statewave storage backends. The arc: preview Jira + database connectors (v0.18.0), database schema-metadata mode (v0.19.0), Jira webhook receiver via listen jira (v0.20.0), opt-in Jira status transitions + sprint context (v0.21.0), and Jira Server / Data Center support — implemented + unit-tested, not yet live-verified (v0.22.0).

Every connector that supports a push surface in its source system now has a real-time receiver alongside its pull connector. The Tier 2 push-receiver wave (v0.7.0–v0.11.0) is complete — statewave-connectors listen <connector> is the unified daemon. The Tier 3 operator/cloud productization wave (v0.12.0–v0.17.0) is also complete — TOML config file (multi-instance), hosted runner (statewave-connectors run), persistent state adapters (file / Postgres / Redis), built-in OIDC verification for Gmail Pub/Sub, auth-gated Prometheus /metrics, and deployment recipes (Docker / Compose / Helm / Fly / Railway).

Package	Latest	Notes
@statewavedev/connectors-core	0.1.0	Connector contract, episode schema, builder, idempotency, retry, redaction, source-state
@statewavedev/connectors-cli	0.2.5	statewave-connectors CLI — doctor, sync (incl. jira + database, with --mode schema and --deployment server), replay, test, listen (incl. listen jira), run, mcp; per-command help; JSON output
@statewavedev/connectors-config	0.4.0	TOML runner config loader + validator (validate-config) for multi-instance deployments
@statewavedev/connectors-runner	0.3.0	Hosted runner daemon (statewave-connectors run) — persistent state adapters, OIDC verification, auth-gated Prometheus /metrics
@statewavedev/mcp-server	0.1.0	Tool definitions, StatewaveClient, input-validating dispatcher, stdio JSON-RPC 2.0 transport
@statewavedev/connectors-github	0.1.0	Issues, PRs, issue + PR comments, PR reviews, releases. Maps to github.* kinds.
@statewavedev/connectors-gitlab	0.1.0	Preview (live-unverified). Issues, merge requests, notes, approvals, releases. REST v4; PRIVATE-TOKEN auth; nested groups. Maps to gitlab.* kinds.
@statewavedev/connectors-bitbucket	0.1.0	Preview (live-unverified). Bitbucket Cloud 2.0 — pull requests, issues, PR + issue comments. Bearer-token auth, next-cursor pagination. Maps to bitbucket.* kinds.
@statewavedev/connectors-gitea	0.1.0	Preview (live-unverified). Gitea / Forgejo REST v1 (self-hosted) — issues, PRs, comments, reviews, releases. token auth; base URL required. Maps to gitea.* kinds.
@statewavedev/connectors-azure-devops	0.1.0	Preview (live-unverified). Azure DevOps REST 7.1 — pull requests, PR comments, reviewer votes, work items (WIQL). PAT (Basic) auth; organization/project/repository. Maps to azure.* kinds.
@statewavedev/connectors-jira	0.4.0	Preview. Jira Cloud REST v3, API-token auth, pull-mode. Issues + opt-in comments → project:<KEY>. No-email user fields, ADF→text, redaction, project allowlist. jira.issue.created, jira.issue.resolved, jira.comment.created. Webhook receiver (listen jira), opt-in transitions + sprint context, Server/Data Center (--deployment server, live-unverified).
@statewavedev/connectors-database	0.2.0	Preview source connector — selected external rows → Statewave memory (not a Statewave storage backend). Dialects: PostgreSQL / MySQL / MariaDB / MSSQL. Read-only, allowlisted table/query, selected columns, ${ENV} secrets, no schema-wide dump. database.row. All four dialects (PostgreSQL / MySQL / MariaDB / MSSQL) live-verified. Opt-in schema mode (--mode schema).
@statewavedev/connectors-markdown	0.1.0	.md / .mdx scan, frontmatter, decision/ADR/RFC detection, content-hash idempotency
@statewavedev/ide-core	0.1.0	Editor-independent IDE Companion core — workspace scan, project summary, file classification, subject strategy, ide.* episode mapping, redaction + StatewaveClient reuse
statewave-ide-companion	0.1.10	VS Code / Cursor extension — install from VS Code Marketplace / Open VSX (npm-private). Preview-first, opt-in autoIndex. Does not read Copilot/Cursor chat.
@statewavedev/connectors-slack	0.4.0	Pull (channel + thread history) + Events-API webhook (messages, reactions, pins) + opt-in DMs (dm:<user>) + opt-in MPIM/group-DMs (mpim:<channel>). v0.4.0 dispatches DM/MPIM events through the webhook handler too (slack.dm.*, slack.mpim.*).
@statewavedev/connectors-n8n	0.1.0	Workflow executions, failures, and per-node errors. Maps to n8n.workflow.executed, n8n.workflow.failed, n8n.node.errored.
@statewavedev/connectors-zapier	0.1.0	Push-mode helper. formatZapToEpisode() for users who route Zapier "Webhooks by Zapier → POST" payloads through their own server. See package README for the direct-from-Zapier (no-code) path too.
@statewavedev/connectors-discord	0.1.0	Server channel + thread history pull. Maps to discord.message.posted and discord.thread.replied.
@statewavedev/connectors-zendesk	0.2.0	Pull (tickets + comments, with --brands / --statuses allowlists and Incremental Tickets Export delta sync) + webhook receiver (HMAC-SHA256, trigger and event-driven payloads). Customer-scoped subjects (customer:<org_or_requester_id>). Maps to zendesk.ticket.created, zendesk.ticket.solved, zendesk.comment.posted, zendesk.comment.internal_note.
@statewavedev/connectors-intercom	0.2.0	Pull (conversations + replies + admin notes, with --tags / --teams allowlists, US/EU/AU regions) + webhook receiver (HMAC-SHA1 / X-Hub-Signature). Customer-scoped subjects (customer:<company_or_contact_id>). Maps to intercom.conversation.created, intercom.conversation.closed, intercom.conversation.replied, intercom.conversation.note_added.
@statewavedev/connectors-freshdesk	0.2.0	Pull (tickets + conversations, with native updated_since server-side --since filter) + webhook receiver (shared-secret header). Customer-scoped subjects (customer:<company_or_requester_id>). Maps to freshdesk.ticket.created, freshdesk.ticket.resolved, freshdesk.conversation.posted, freshdesk.conversation.internal_note.
@statewavedev/connectors-notion	0.1.2	Pages (and optional body content) + opt-in page-level comments + (v0.1.2) --databases allowlist for database-scoped pulls. Decision-memory subjects (workspace:notion by default; operator overrides via --subject). Maps to notion.page.created, notion.page.updated, notion.comment.posted. Bearer token auth.
@statewavedev/connectors-gmail	0.3.0	Pull (Gmail-query–scoped messages, with --label-ids server-side filter and History-API delta sync via --cursor) + Cloud Pub/Sub push receiver (path-token auth; persistent per-mailbox cursor; cold-start + stale-cursor handling). Relationship-memory subjects (relationship:<other_email>). Maps to gmail.message.received, gmail.message.sent.
@statewavedev/connectors	0.1.0	Convenience meta-package — re-exports all shipped connectors. Optional.

All v0.1 connectors, the v0.5 + v0.6 polish waves, the Tier 2 push-receiver wave (v0.7.0–v0.11.0), and the Tier 3 operator/cloud productization wave (v0.12.0–v0.17.0) have shipped. v0.18.0–v0.22.0 add the preview Jira (pull + webhook + transitions/sprints + Server/Data Center) and database (rows + schema modes) source connectors. Long-running daemon shapes (Slack Socket Mode, Discord Gateway, Gmail service-account auth) are still queued. See RELEASE_NOTES.md for the full release history and docs/roadmap.md for what's next.

Capabilities today:

• Doctor reports cli + node + platform versions and per-env-var diagnostics
• Pull mode (statewave-connectors sync <connector>) with --include, --exclude, --since, --max-items, --json, --dry-run across all connectors; per-connector flags for filtering (e.g. Slack --channels, Gmail --query, Zendesk --brands, Intercom --tags, Notion --databases)
• Cursor-based delta sync (--cursor) on Zendesk (Incremental Tickets Export), Gmail (History API), and Notion (database scoping) so re-runs only fetch what changed
• Push mode (statewave-connectors listen <connector>) for Slack (Events-API + DM/MPIM), Freshdesk (shared-secret header), Zendesk (HMAC-SHA256), Intercom (HMAC-SHA1 / X-Hub-Signature), and Gmail (Cloud Pub/Sub) — same (Request) => Promise<Response> factory mounts on Vercel / Cloudflare / Express identically across the lineup
• MCP StatewaveClient against the Statewave v1 HTTP API (auth, tenant, network errors mapped to typed ConnectorErrors)
• MCP tool dispatcher with input validation for all 5 canonical tools
• mcp start --list-tools prints the canonical tool surface
• HTTP MCP transport is planned; the bundled stdio transport (~120 LOC, no external deps) covers initialize / tools/list / tools/call / ping / shutdown for any MCP-compatible client today

See RELEASE_NOTES.md.

Quickstart

Not running a Node app? You don't need any of this — see Two ways to run connectors for the zero-Node container path. The steps below are for local development or embedding connectors in a Node service.

Connectors feed an existing Statewave server — they don't run one. Don't have a server yet? The Getting Started guide brings one up with Docker Compose in about 5 minutes; STATEWAVE_URL below points at it.

Fastest path — one command

The quickstart command brings up a local Statewave server (Docker), configures your MCP clients (Claude Code, Claude Desktop, Cursor, VS Code / Copilot, Codex), installs the IDE Companion, and seeds the repos you pick — all verified, nothing claimed it didn't do.

Have Node 20+ already:

npx @statewavedev/connectors-cli quickstart

No Node? The bootstrap script fetches Node from the official nodejs.org distribution (SHA-256 verified, into your home directory, no sudo — and it asks first), then runs the same quickstart:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/smaramwbc/statewave-connectors/main/scripts/bootstrap.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/smaramwbc/statewave-connectors/main/scripts/bootstrap.ps1 | iex

It's safe to re-run: existing servers and configs are reused, not duplicated. Pass --help to either for flags (--yes for unattended installs, -- <args> to forward options to quickstart).

Manual / per-connector usage

pnpm install
pnpm build

export STATEWAVE_URL=http://localhost:8100
export STATEWAVE_API_KEY=...

statewave-connectors doctor

# Preview — no ingestion happens
statewave-connectors sync github \
  --repo smaramwbc/statewave \
  --subject repo:smaramwbc/statewave \
  --dry-run

statewave-connectors sync markdown \
  --path ./docs \
  --subject repo:smaramwbc/statewave \
  --dry-run

export SLACK_BOT_TOKEN=xoxb-...
statewave-connectors sync slack \
  --channels general,support \
  --subject team:acme \
  --dry-run

export N8N_API_KEY=...
statewave-connectors sync n8n \
  --workflows "Daily ETL,42" \
  --instance-url https://n8n.example.com \
  --dry-run

# Jira (preview) — Cloud REST v3, API-token auth
export [email protected] JIRA_API_TOKEN=...
statewave-connectors sync jira \
  --host https://myorg.atlassian.net \
  --projects ENG \
  --dry-run

# Database (preview) — selected rows into memory; read-only, allowlisted
export STATEWAVE_DATABASE_SOURCE_URL="postgres://readonly@localhost:5432/app"
statewave-connectors sync database \
  --dialect postgres --table support_tickets \
  --columns id,subject,status,updated_at --id-column id --max-rows 500 \
  --dry-run

# Start the MCP server (stdio JSON-RPC 2.0 transport)
statewave-connectors mcp start

IDE Companion / Copilot / Cursor memory

The Statewave IDE Companion (VS Code / Cursor extension) makes Statewave aware of your developer workspace — project structure, documentation, git state, changed files, and diagnostics — and exposes that memory back to Copilot / Cursor through the existing MCP server. No IDE-specific MCP tools are added: assistants retrieve via the canonical statewave_get_context / statewave_get_timeline.

Zero-config: you run only your Statewave server and install the plugin. From the one statewave.url/apiKey you set, the plugin wires the MCP server itself for Copilot, Cursor, Windsurf, Claude Code, Cline, Roo Code, and Continue — each via that client's own config (in-memory for Copilot; home-dir / editor-storage files for the rest), only when the client is installed, and always keeping secrets out of the repo. No second config file, no extra container. The Statewave memory runtime becomes the always-present project brain so the assistant makes fewer mistakes.

The plugin never reads your Copilot/Cursor/Claude chat — there is no interception. On its own it observes the workspace, docs, git state, diagnostics, and explicit commands. Separately, with statewave.assistantInstructions: read-write (default) the assistant is instructed to persist durable facts you state (preferences/decisions) by calling the public statewave_ingest_episode MCP tool — a visible, approvable model action, not chat scraping. Set it to read-only or off to disable.

• No ingestion on install or activation. Every command previews episodes first; sending is a separate explicit click. The file watcher only sends on save if you opt into statewave.autoIndex (off by default).
• Redaction on by default; diagnostics never carry source code; no telemetry.
• Editor-independent logic ships as @statewavedev/ide-core (fully unit-tested); the thin VS Code / Cursor host is packages/vscode-extension.

pnpm install
pnpm --filter @statewavedev/ide-core build
pnpm --filter statewave-ide-companion build   # then press F5 in packages/vscode-extension, or build a VSIX

See docs/vscode-extension.md, docs/ide-memory.md, and examples/statewave-ide-companion.

Dry-run first

Every connector supports --dry-run. The CLI runs the read path and the mapper, prints the resulting episodes, and does not call the Statewave ingest API. The CLI also refuses to ingest if STATEWAVE_URL is unset.

That's deliberate. We never want a git pull && pnpm install to silently start mirroring private data to a remote service.

Privacy & redaction

• Per-connector credentials. The GitHub connector never reads Slack tokens; the Markdown connector never makes a network call.
• Built-in best-effort redaction for emails, phone numbers, and common API-key shapes. Off by default; opt in per-sync.
• --include / --exclude filters for slicing what a connector reads.
• No telemetry. No phone-home. Source state is local.

See docs/privacy-redaction.md.

Documentation

• docs/connector-contract.md — what every connector must implement
• docs/episode-schema.md — the single normalized episode shape
• docs/subject-strategy.md — how to pick subjects (the most important call you make)
• docs/vscode-extension.md — the VS Code / Cursor IDE Companion (commands, settings, privacy)
• docs/ide-memory.md — how Copilot / Cursor read workspace memory back via the canonical MCP tools
• docs/privacy-redaction.md — safety primitives
• docs/contribution-guide.md — how to add a new connector
• docs/deployment.md — how to deploy the runner (Docker / Compose / Helm / Fly / Railway)
• docs/roadmap.md — what's shipping when

Examples

• examples/repo-memory-quickstart — end-to-end demo: doctor, markdown dry-run on the included sample docs, GitHub dry-run, MCP tool listing. Runs offline.
• examples/github-repo-memory — repo memory from a real GitHub repo
• examples/docs-decision-memory — decision memory from local Markdown
• examples/copilot-mcp-memory — agent memory via the MCP server
• examples/statewave-ide-companion — workspace memory for Copilot / Cursor (sample config, sample episodes, MCP setup)
• examples/slack-support-memory — team / customer support memory from Slack
• examples/discord-community-memory — community memory from Discord
• examples/zendesk-customer-memory — customer support memory from Zendesk

Layout

statewave-connectors/
├── packages/
│   ├── core/                     @statewavedev/connectors-core
│   ├── cli/                      @statewavedev/connectors-cli
│   ├── config/                   @statewavedev/connectors-config        (TOML runner config)
│   ├── runner/                   @statewavedev/connectors-runner        (hosted runner daemon)
│   ├── mcp-server/               @statewavedev/mcp-server
│   ├── github/                   @statewavedev/connectors-github
│   ├── gitlab/                   @statewavedev/connectors-gitlab        (preview; MRs/issues/notes/approvals/releases)
│   ├── bitbucket/                @statewavedev/connectors-bitbucket     (preview; PRs/issues/comments)
│   ├── gitea/                    @statewavedev/connectors-gitea         (preview; Gitea/Forgejo, self-hosted)
│   ├── azure-devops/             @statewavedev/connectors-azure-devops  (preview; PRs/comments/reviews/work items)
│   ├── jira/                     @statewavedev/connectors-jira          (preview, pull-mode)
│   ├── database/                 @statewavedev/connectors-database      (preview; postgres/mysql/mariadb/mssql)
│   ├── markdown/                 @statewavedev/connectors-markdown
│   ├── ide-core/                 @statewavedev/ide-core                 (IDE Companion core)
│   ├── vscode-extension/         statewave-ide-companion                (VS Code / Cursor, private)
│   ├── slack/                    @statewavedev/connectors-slack         (pull + Events-API webhook)
│   ├── n8n/                      @statewavedev/connectors-n8n
│   ├── zapier/                   @statewavedev/connectors-zapier        (helper)
│   ├── discord/                  @statewavedev/connectors-discord
│   ├── zendesk/                  @statewavedev/connectors-zendesk       (pull + webhook receiver)
│   ├── intercom/                 @statewavedev/connectors-intercom      (pull + webhook receiver)
│   ├── freshdesk/                @statewavedev/connectors-freshdesk     (pull + webhook receiver)
│   ├── notion/                   @statewavedev/connectors-notion
│   ├── gmail/                    @statewavedev/connectors-gmail         (pull + Pub/Sub push)
│   └── all/                      @statewavedev/connectors               (convenience)
├── examples/
└── docs/

License

Apache-2.0.