moorcheh-ai/moorcheh

Moorcheh — Universal Memory Layer Operations

This skill provides comprehensive access to the Moorcheh platform including namespace management, data operations, semantic search with ITS scoring, and AI-powered answer generation.

Moorcheh Account

If the user does not have an account yet, direct them to the console to register and create a free account.

Create a Moorcheh account at console.moorcheh.ai.

Environment Variables

export MOORCHEH_API_KEY="your-api-key-here"

For full environment setup, see Environment Requirements.

Script Index

Namespace Management

• Create Namespace: Use to create a new text or vector namespace for organizing data. Text namespaces handle automatic embedding; vector namespaces require pre-computed embeddings.
• List Namespaces: Use to discover what namespaces exist in the account. This should be the first step before any operation.
• Delete Namespace: Use to permanently remove a namespace and all its data. This action is irreversible.

Data Operations

• Upload Text Data: Use to upload text documents with metadata to a text namespace. Documents are automatically embedded and indexed for semantic search.
• Upload File: Use to upload a file directly (PDF, TXT, MD, CSV, JSON, DOCX) to a text namespace. Moorcheh handles parsing, chunking, and embedding automatically. Prefer this over Upload Text when the user has a file on disk.
• Upload Vectors: Use to upload pre-computed vector embeddings to a vector namespace. Best when you have your own embedding pipeline.
• Delete Data: Use to remove specific documents or vectors from a namespace.
• Create Example Data: Use to create sample data for demos and testing when no data is available.

Search & AI

• Semantic Search: Primary search operation. Performs semantic search across one or more namespaces using ITS scoring. Supports text queries, metadata filters, keyword filters, and relevance thresholds.
• Generate AI Answer: Use to generate AI-powered answers from your data (RAG). Searches relevant context and synthesizes a natural-language answer. Supports chat history, custom prompts, and structured output.

Recommendations

• Always run List Namespaces first to discover available data before searching or uploading.
• For text data, prefer text namespaces — Moorcheh handles embedding automatically.
• Use ITS scoring thresholds (0.0–1.0) to control result quality. Higher = stricter matching.
• The Generate Answer endpoint is the primary RAG capability — use it for Q&A over documents.

Output Formats

• Search results include id, score, label (relevance category), text, and metadata.
• AI answers include answer, model, contextCount, and optional structuredData.

Error Handling

• 401 Unauthorized: Verify MOORCHEH_API_KEY is set and valid
• 404 Namespace not found: Create the namespace first or check spelling (case-sensitive)
• 400 Vector dimension mismatch: Ensure vectors match the namespace's configured dimension
• 429 Too Many Requests: Implement exponential backoff

Code Generation Rules

Follow these rules when generating Python code that uses the Moorcheh SDK:

No Unicode Emoji in Output

Do not use emoji characters (e.g. ✅ ❌ 📁 ⏳ 🎉) in print() statements or log messages. On Windows with cp1252 encoding, these cause UnicodeEncodeError and mask actual success/failure output. Use plain ASCII prefixes instead:

| Instead of | Use | |---|---| | ✅ Success | [OK] Success | | ❌ Error | [ERROR] Error | | ⏳ Waiting | [WAIT] Waiting | | 📁 folder | - folder |

Python SDK Uses snake_case

The REST API uses camelCase (aiModel, chatHistory, headerPrompt, footerPrompt, structuredResponse). The Python SDK uses snake_case. Always use snake_case in Python code:

| REST API (JSON/curl) | Python SDK kwarg | |---|---| | aiModel | ai_model | | chatHistory | chat_history | | headerPrompt | header_prompt | | footerPrompt | footer_prompt | | structuredResponse | structured_response | | top_k | top_k | | namespace_name | namespace_name |

Using camelCase kwargs in Python will raise TypeError or be silently ignored by the SDK.