Mao Semantic Search

Search Mao Zedong Selected Works by conceptual meaning using vector embeddings. Builds a local embedding index over all 230 articles across 5 volumes, then performs cosine similarity search at query time.

When to Use

• User asks a thematic/conceptual question about Mao's works ("What did Mao say about guerrilla warfare?")
• Keyword search over the .md files is insufficient
• User wants to find passages related to a concept without knowing exact terminology
• As a pre-retrieval step before deep-reading specific articles

Architecture

assets/mao-selected-works/  ──build_index.py──>  temp/mao/embeddings.json  <──search.py──  User Query
(.md files, 5 vols)                             │
                                                 └── JSON index, 230 entries

• Index: Flat JSON, one embedding per article (full body text, frontmatter excluded), stored at temp/mao/embeddings.json
• Embeddings: Reuses stable_jarvis.llm.embed() — same provider stack as obsidian-semantic-search (local / qwen / openai)
• Search: Brute-force cosine similarity, O(n) over all articles

Workflow

Phase 0: Check Index Freshness (Always First)

Before any search, the agent MUST check the index state:

python skills/mao-semantic-search/scripts/build_index.py --stats

Decision logic:

The index is static — articles don't change, so rebuild is only needed once.

Phase 1: Build Index (If Needed)

python skills/mao-semantic-search/scripts/build_index.py

With optional provider override:

python skills/mao-semantic-search/scripts/build_index.py --provider qwen

The scripts locate the Mao works automatically via MAO_WORKS_DIR env var or the default path assets/mao-selected-works/. If the works are at a non-standard location, set it first:

export MAO_WORKS_DIR="/path/to/mao-selected-works"

Phase 2: Semantic Search

python skills/mao-semantic-search/scripts/search.py "query text" --top-k 5

Returns JSON array of results, each with:

• title — Article title
• volume — Volume number (1–5)
• path — Relative path in mao-selected-works/ (for reading full text)
• score — Cosine similarity (0–1, higher = more relevant)
• text_snippet — First 200 chars of the article body

Phase 3: Read Full Articles

After getting results, use the Read tool with the path field to read full content:

Read(assets/mao-selected-works/vol-01/001-中国社会各阶级的分析.md)

Phase 4: Present Results

Format search results for the user with:

• Article title and volume
• Relevance score
• Brief excerpt from text_snippet
• Direct path for further reading

Commands

Configuration

All settings via environment variables (loaded from .env):

The local provider uses sentence-transformers (paraphrase-multilingual-MiniLM-L12-v2) and requires no API key.

Index Management

• Static index: Articles don't change, so the index is built once and reused indefinitely
• Index size: ~230 embeddings, ~4MB total article text, resulting index ~200–400KB
• Rebuild: Only needed if the source .md files are regenerated or updated