/semantic-search - Search Messages by Meaning

Search 650K+ session messages using semantic similarity, hybrid (semantic + FTS5), or keyword modes. Powered by all-MiniLM-L6-v2 embeddings (384 dimensions).

Usage

# Semantic search (default) - find by meaning
/semantic-search "authentication patterns"

# Limit results
/semantic-search "error handling" --limit 20

# Hybrid mode - combines semantic + keyword for best results
/semantic-search "database migration" --hybrid

# Keyword only (FTS5, instant, no model loading)
/semantic-search "backfill" --keyword

# Filter by role
/semantic-search "API design" --role assistant

# Filter by LLM source
/semantic-search "deployment" --llm claude

# Filter by project
/semantic-search "license" --project PILOT

# JSON output
/semantic-search "testing" --json

# Full message content (no truncation)
/semantic-search "config" --full

# Database statistics
/semantic-search --stats

# Combine filters
/semantic-search "security" --hybrid --role assistant --project PILOT --limit 15

System Prompt

EXECUTION DIRECTIVE: When the user invokes /semantic-search, you MUST:

1. IMMEDIATELY execute the search script
2. Show all results returned by the script
3. Summarize findings if the user seems to want analysis

python3 "$(git rev-parse --show-toplevel)/.coditect/scripts/semantic-search.py" $ARGS

Parse user arguments and map to CLI options:

User Says	CLI Option
--limit N, -n N	--limit N
--hybrid	--hybrid
--keyword	--keyword
--role ROLE	--role ROLE
--llm SOURCE	--llm SOURCE
--project ID	--project ID
--json	--json
--full	--full
--threshold N	--threshold N
--stats	--stats
--snippet N	--snippet N

---

Search Modes

Mode	Flag	Speed	Uses Model	Best For
Semantic	(default)	~16s	Yes	Finding by meaning, concept search
Hybrid	--hybrid	~16s	Yes	Best overall results, combines meaning + keywords
Keyword	--keyword	<0.1s	No	Exact term matching, instant results

Semantic Mode

Encodes your query into a 384-dim vector and computes cosine similarity against all 650K+ message embeddings. Finds messages that are semantically similar even if they use different words.

Hybrid Mode (Recommended)

Combines semantic similarity with FTS5 keyword matching using Reciprocal Rank Fusion (RRF). Gets the benefits of both approaches. Default weights: 60% semantic, 40% FTS5.

Keyword Mode

Pure FTS5 full-text search with BM25 ranking. Instant results (<0.1s) with no model loading. Best when you know the exact terms to search for.

Filters

Filter	Description	Example
--role	Message role	--role assistant, --role user
--llm	LLM source	--llm claude, --llm codex, --llm gemini
--project	Project ID	--project PILOT
--threshold	Min similarity (0-1)	--threshold 0.5 (stricter)
--limit	Max results	--limit 50

Output Formats

Default (Human-Readable)

============================================================
CODITECT Semantic Search (semantic mode)
============================================================
  Query: "authentication patterns"
  Results: 5 (limit: 5, threshold: 0.3)
  Time: 16.22s
------------------------------------------------------------
  [1] | id:395006 | role:assistant | llm:claude | 2025-12-08 | sim: 0.6190
    Continuing with Phase 2: Authentication System.

  [2] | id:383319 | role:assistant | llm:claude | 2026-01-01 | sim: 0.5940
    Now I understand the auth pattern. Let me implement the auth integration:
============================================================

JSON Output (--json)

{
  "query": "authentication patterns",
  "mode": "semantic",
  "elapsed_seconds": 16.22,
  "count": 5,
  "results": [
    {
      "message_id": 395006,
      "role": "assistant",
      "similarity": 0.619,
      "content": "Continuing with Phase 2...",
      "timestamp": "2025-12-08T22:38:53",
      "llm_source": "claude",
      "project_id": null
    }
  ]
}

Examples

Find Past Architecture Decisions

/semantic-search "why did we choose SQLite over PostgreSQL" --role assistant --limit 10

Recall Error Solutions

/semantic-search "TypeError Cannot read property" --hybrid --limit 20

Search Specific Project

/semantic-search "deployment configuration" --project PILOT --role assistant

Quick Keyword Lookup

/semantic-search "ADR-118" --keyword --limit 5

Comparison with /cxq

Feature	/semantic-search	/cxq
Standalone CLI	Yes	No (needs Claude)
Semantic search	Direct vector query	Via MCP tools
Keyword search	FTS5 BM25	FTS5 BM25
Hybrid mode	RRF fusion	RRF fusion
JSON output	--json flag	--json flag
Decisions/patterns	No	Yes (--decisions)
Knowledge extraction	No	Yes (--extract)
Session log indexing	No	Yes (J.32)

Use /semantic-search when you want direct CLI access to message search. Use /cxq when you need higher-level features (decisions, patterns, knowledge extraction).

Related

• /cxq - Full context query with knowledge extraction
• /cx - Context extraction (populates the database)
• /cxq --recall - RAG-style semantic recall (similar but via MCP)

Technical Details

• Model: all-MiniLM-L6-v2 (384 dimensions, float32)
• Database: sessions.db (ADR-118 Tier 3)
• Tables: embeddings (vectors), messages (content), messages_fts (FTS5)
• Coverage: 100% (650K+ messages embedded)
• Script: scripts/semantic-search.py

---

Success Output

Results displayed with similarity scores and content snippets.

Completion Checklist

• Query executed against sessions.db
• Results displayed with scores
• Filters applied correctly

Failure Indicators

• No sessions.db found (run /cx first)
• sentence-transformers not installed (for semantic/hybrid)
• FTS5 index missing (run /cx to rebuild)

---

Script: scripts/semantic-search.py Track: J (Memory Intelligence) Task: J.4.1 Version: 1.0.0 Created: 2026-02-15