aim-jira-search
Search Jira issues and comments with semantic search and filters
SKILL.md_ai-memory/skills/aim-jira-search/SKILL.md
GitHubSearch Jira - Semantic Search for Jira Content
Search the jira-data collection for issues and comments using semantic similarity with advanced filtering.
Activation
# 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.
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_issueorjira_comment)--limit— max results (default: 10)--format—table(default) orjson--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/.envasQDRANT_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_projectNOTproject_key,jira_issue_keyNOTissue_key