# Aim Jira Sync

> Synchronize Jira issues and comments to AI Memory

- Skill: `hidden-history/aim-jira-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hidden-history/aim-jira-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hidden-history/aim-jira-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Hidden-History (https://skillmd.com/u/hidden-history)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/hidden-history/aim-jira-sync

---


# Jira Sync - Synchronize Jira Content

Synchronize Jira issues and comments from configured projects into the AI Memory jira-data collection.

## Activation

```text
# Incremental sync (default) - only fetch updated issues
/aim-jira-sync

# Full sync - fetch all issues and comments
/aim-jira-sync --full

# Sync specific project
/aim-jira-sync --project BMAD

# Check sync status (last sync time, items synced, errors)
/aim-jira-sync --status

# Full sync for specific project
/aim-jira-sync --full --project BMAD
```

## Options

- `--incremental` - Sync only updated issues since last sync (default)
- `--full` - Full sync: fetch all issues and comments from scratch
- `--project <key>` - Sync specific project (default: all configured projects)
- `--status` - Display sync status (last sync time, items synced, errors)

## Sync Modes

### Incremental Sync (Default)

- Fetches issues updated since last sync timestamp
- Faster and more efficient for regular updates
- Uses JQL: `project = PROJ AND updated >= "2026-02-01 00:00"`
- Updates existing documents in-place (by jira_comment_id for comments)

### Full Sync

- Fetches all issues and comments from scratch
- Use for initial setup or after schema changes
- Warning: Can be slow for large projects (hundreds/thousands of issues)
- Overwrites existing documents

## Configuration

Sync requires Jira credentials in `.env`:

```env
JIRA_INSTANCE_URL=https://company.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=your_api_token_here
JIRA_PROJECTS=BMAD,PROJ,DEV
JIRA_SYNC_ENABLED=true
JIRA_SYNC_DELAY_MS=100
```

## Activation Examples

```text
# Daily incremental sync (recommended)
/aim-jira-sync

# Initial full sync for new project
/aim-jira-sync --full --project NEWPROJ

# Check last sync status
/aim-jira-sync --status

# Full refresh of all projects (use sparingly)
/aim-jira-sync --full
```

## Implementation Reference

This skill invokes `scripts/jira_sync.py`:

```bash
"${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/jira_sync.py" --incremental
"${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/jira_sync.py" --full --project BMAD
"${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/memory/run-with-env.sh" "${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}/scripts/jira_sync.py" --status
```

## Technical Details

- **Rate Limiting**: Configurable delay between API requests (default 100ms)
- **Pagination**: Token-based for issues, offset-based for comments
- **Deduplication**: SHA256 content hashing prevents duplicate storage
- **Document Format**: ADF (Atlassian Document Format) → plain text
- **Collection**: jira-data (separate from code-patterns/conventions/discussions)
- **Tenant Isolation**: group_id = Jira instance hostname

## Notes

- Requires Jira Cloud API token (create at id.atlassian.com)
- Sync logs written to `~/.ai-memory/logs/activity.log`
- First sync can take several minutes for large projects
- Incremental sync timestamp stored in jira_sync_state.json
- Comments are linked to parent issues via jira_issue_key