Semantic Search API provides AI-powered content retrieval across 📝MythOS libraries, available through the 📝MythOS MCP tool interface and the internal REST endpoint.

The API combines vector similarity search with keyword text search to find memos by meaning. It powers both the search_memos MCP tool (with mode: "semantic") and the RAG pipeline behind 📝Chat with Library.

Prerequisites

A MythOS library connected via MCP (see 📝MythOS MCP Tools)
An OpenAI API key configured on the library owner's account (for query embedding), or platform pass-through billing enabled

Interface

search_memos (MCP Tool)

Searches a library using vector embeddings and hybrid scoring.

Parameters:

query (string, required) — natural language search query. Richer queries perform better than short acronyms
mode (string, required) — must be "semantic" to use this interface. Default "substring" uses keyword matching instead
limit (number, optional, default: 5, max: 20) — maximum memos to return. Maps to topK internally
tags (string, optional) — comma-separated tags to filter results post-retrieval
library (string, optional) — target library username. Defaults to authenticated user's library

Returns:

{
  "success": true,
  "memos": [
    {
      "memoId": "username-abc123",
      "title": "Memo Title",
      "tags": ["tag1", "tag2"],
      "url": "/me/username/abc123",
      "visibility": "public",
      "accessReason": "owner",
      "memoScore": 0.85,
      "chunks": [
        {
          "chunkText": "Relevant text from the memo...",
          "score": 0.69,
          "section": "body"
        }
      ]
    }
  ],
  "diagnostics": {
    "vectorSearchFailed": false
  }
}

GET /api/internal/memos/semantic-search

REST endpoint used internally by the MCP tool handler. Accepts the same parameters as query strings: q, username, topK, tags. Requires x-mythos-key authentication header.

How Scoring Works

Results are ranked by a hybrid scoring system:

Vector search (70% weight) — embeds the query with text-embedding-3-small and finds nearest chunks by cosine similarity across 200 candidates
Text search (30% weight) — keyword matching on chunk text, titles, and tags for lexical recall
Memo aggregation — chunks are grouped by memo and scored: maxChunkScore + 0.1 * ln(chunkCount), rewarding memos with multiple relevant chunks

Error Handling

422 — no OpenAI embedding key configured on the library, or no embeddings exist. Response includes fallback: "substring" suggestion
503 — Atlas Vector Search index not configured. Response includes setup instructions
403/404/500 — standard auth, not-found, and server errors surface as isError: true with the original message

When vector search fails (missing index, timeout), the API falls back to text-only results and sets diagnostics.vectorSearchFailed: true so callers can detect degraded mode.

📝Semantic Search (MythOS) — feature overview and capabilities
📝MythOS MCP Tools — full MCP tool reference
📝How to Chat with Your Library via MCP — tutorial for RAG-powered chat, which uses the same retrieval pipeline
📝MCP vs RAG — conceptual distinction between connectivity and retrieval