# Aim Jira Search

> Search Jira issues and comments with semantic search and filters

- Skill: `hidden-history/aim-jira-search` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hidden-history/aim-jira-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hidden-history/aim-jira-search/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-search

---


# Search Jira - Semantic Search for Jira Content

Search the jira-data collection for issues and comments using semantic similarity with advanced filtering.

## Activation

```text
# Basic semantic search
/aim-jira-search "authentication bug"

# Filter by project
/aim-jira-search "API errors" --project BMAD

# Filter by type (issue or comment)
/aim-jira-search "implementation details" --type jira_comment

# Filter by issue type
/aim-jira-search "bugs" --issue-type Bug

# Filter by status
/aim-jira-search "in progress work" --status "In Progress"

# Filter by priority
/aim-jira-search "critical issues" --priority High

# Filter by author (comments) or reporter (issues)
/aim-jira-search "alice's comments" --author alice@company.com

# Issue lookup mode (issue + all comments)
/aim-jira-search --issue BMAD-42

# Combine filters
/aim-jira-search "database" --project BMAD --issue-type Bug --status Done --limit 10
```

## Options

- `--project <key>` - Filter by Jira project key (e.g., BMAD, PROJ)
- `--type <type>` - Filter by document type (jira_issue or jira_comment)
- `--issue-type <type>` - Filter by issue type (Bug, Story, Task, Epic)
- `--status <status>` - Filter by issue status (To Do, In Progress, Done, etc.)
- `--priority <priority>` - Filter by priority (Highest, High, Medium, Low, Lowest)
- `--author <email>` - Filter by comment author or issue reporter
- `--issue <key>` - Lookup mode: retrieve issue + all comments (e.g., BMAD-42)
- `--limit <n>` - Maximum results to return (default: 5)

## Result Format

Each result includes:
- **Jira URL** - Direct link to issue/comment
- **Metadata badges** - Type, Status, Priority, Author/Reporter
- **Content snippet** - First ~300 characters
- **Relevance score** - Semantic similarity (0-100%)

---

## Qdrant Connection Details

The jira-data collection is stored in the local Qdrant instance:

| Parameter | Value |
|-----------|-------|
| **Host** | `localhost` |
| **Port** | `26350` (NOT the default 6333) |
| **API Key** | Required. Read from env: `QDRANT_API_KEY` |
| **Collection** | `jira-data` |
| **URL** | `http://localhost:26350` |

---

## Qdrant Payload Schema

Every point in `jira-data` has the following payload fields. Use these **exact names** for filtering — do NOT guess field names like `project_key` or `issue_key`.

### Common Fields (all points)

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `content` | string | Full text content of issue/comment | `"[PROJ-123] Fix login bug..."` |
| `type` | string | Document type | `"jira_issue"` or `"jira_comment"` |
| `group_id` | string | Jira instance hostname (tenant isolation) | `"hidden-history.atlassian.net"` |
| `session_id` | string | Always `"jira_sync"` | `"jira_sync"` |
| `jira_project` | string | Project key | `"BMAD"` |
| `jira_issue_key` | string | Full issue key | `"BMAD-42"` |
| `jira_issue_type` | string | Issue type name | `"Bug"`, `"Story"`, `"Task"`, `"Epic"` |
| `jira_status` | string | Issue status | `"To Do"`, `"In Progress"`, `"Done"` |
| `jira_priority` | string or null | Priority level | `"High"`, `"Medium"`, `"Low"`, `null` |
| `jira_updated` | string | ISO 8601 timestamp | `"2026-02-10T14:30:00.000+0000"` |
| `jira_url` | string | Full Jira URL | `"https://company.atlassian.net/browse/BMAD-42"` |

### Issue-Only Fields (`type: "jira_issue"`)

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `jira_reporter` | string | Issue reporter display name | `"Alice Smith"` |
| `jira_labels` | list[string] | Issue labels | `["backend", "auth"]` |

### Comment-Only Fields (`type: "jira_comment"`)

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `jira_comment_id` | string | Jira comment ID | `"10042"` |
| `jira_author` | string | Comment author display name | `"Bob Jones"` |

### Chunking Metadata (if content was chunked)

| Field | Type | Description |
|-------|------|-------------|
| `chunk_index` | int | Chunk sequence number (0-based) |
| `total_chunks` | int | Total chunks for this document |
| `chunking_strategy` | string | Strategy used (e.g., `"topical"`) |

---

## Direct Query Examples

Use `query.py` via `run-with-env.sh` for all direct Qdrant queries. Auth and
connection are handled by the standard `memory.*` config layer — no manual API
key export required.

```bash
INSTALL="${AI_MEMORY_INSTALL_DIR:-$HOME/.ai-memory}"
QUERY="$INSTALL/_ai-memory/skills/aim-jira-search/scripts/query.py"

# Search by project key (table output)
"$INSTALL/scripts/memory/run-with-env.sh" "$QUERY" \
  --project BMAD --limit 10

# Filter by issue type and status
"$INSTALL/scripts/memory/run-with-env.sh" "$QUERY" \
  --project BMAD --issue-type Bug --status Done --limit 20

# Count points and vectors in the collection
"$INSTALL/scripts/memory/run-with-env.sh" "$QUERY" --count

# Get all comments for a specific issue
"$INSTALL/scripts/memory/run-with-env.sh" "$QUERY" \
  --issue-key BMAD-42 --doc-type jira_comment --limit 50

# JSON output for programmatic use
"$INSTALL/scripts/memory/run-with-env.sh" "$QUERY" \
  --project BMAD --format json --limit 5
```

Available flags (use exact Qdrant payload field values — see schema above):
- `--project` — project key (e.g., `BMAD`)
- `--issue-type` — issue type (e.g., `Bug`, `Story`, `Task`, `Epic`)
- `--status` — status (e.g., `"In Progress"`, `Done`)
- `--issue-key` — full issue key (e.g., `BMAD-42`)
- `--doc-type` — document type (`jira_issue` or `jira_comment`)
- `--limit` — max results (default: 10)
- `--format` — `table` (default) or `json`
- `--count` — return collection info counts instead of scroll

---

## Python Implementation Reference

The `src/memory/connectors/jira/search.py` module is **not importable from
external scripts** — use `query.py` (above) for direct Qdrant access.

## Technical Details

- **Semantic Search**: Uses jina-embeddings-v2-base-en for vector similarity
- **Tenant Isolation**: Mandatory group_id filter prevents cross-instance leakage
- **Performance**: < 2s for typical searches
- **Collection**: jira-data (issues and comments)
- **Score Threshold**: Configurable via SIMILARITY_THRESHOLD (default 0.7)
- **Port**: 26350 (NOT the Qdrant default of 6333)
- **API Key**: Required — stored in `~/.ai-memory/docker/.env` as `QDRANT_API_KEY`

## Notes

- Jira instance URL is auto-detected from project configuration
- Results sorted by relevance score (highest first)
- Issue lookup mode returns chronologically sorted comments
- All filters are optional except query (or --issue for lookup mode)
- Use **exact field names** from the schema above — `jira_project` NOT `project_key`, `jira_issue_key` NOT `issue_key`