# Communication Integration Model

## Principle

Communication integrations extract evidence. The agent promotes memory.

Connectors should not decide that a message is durable project truth. They should fetch, normalize, and store evidence in predictable files so the agent can apply memory rules.

---

## Connector Types

### Live Communication Connector

Use for active systems such as Mattermost, Slack, Teams, or email.

Expected behavior:

- fetch recent messages from configured channels or conversations
- support a forced refresh for "latest message" prompts
- write the latest evidence to `workspaces/<profile>/inbox/`
- write status separately from project memory
- fail safely without updating logs, state, or context

### Historical Archive Connector

Use for exports such as Slack archives.

Expected behavior:

- read raw archive files from an ignored archive location
- select high-signal evidence without treating the archive as current truth
- write generated summaries and JSONL to `scripts/<source>/generated/`
- preserve enough source metadata for later review

---

## Standard Evidence Shape

Connectors should emit JSONL records with this minimum shape when practical:

```json
{
  "source": "communication-system",
  "channel": "readable-channel-name",
  "timestamp": "ISO-8601 timestamp",
  "username": "display name or handle",
  "message": "message text",
  "thread_id": "optional thread id",
  "metadata": {}
}
```

Additional fields are allowed when useful, but the core should not depend on project-specific fields.

---

## Environment Variables

Prefer generic `AIW_*` variables for reusable workspaces:

- `AIW_PROJECT_PROFILE`
- `AIW_CHANNEL_PREFIX`
- `AIW_MATTERMOST_SYNC_CMD`
- `AIW_MATTERMOST_SYNC_INTERVAL_MINUTES`
- `AIW_SLACK_EXPORT_PATH`

Project-specific variables may remain as profile aliases, but new integrations should prefer `AIW_*`.

---

## Failure Rules

If a connector fails:

- record operational status only
- do not update daily logs
- do not update current state
- do not update stable context
- do not infer project facts from the failure

The agent may report the operational failure to the user, but it must not promote the failure as project memory unless the user explicitly asks to track tooling work.