> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Moorcheh Integration

> Configure and integrate Moorcheh as the backend for Memanto.

# Moorcheh Setup & Integration

Moorcheh.ai is a no-indexing semantic database for AI memory and retrieval workloads. Memanto uses Moorcheh as its semantic memory backend. This guide focuses on Moorcheh platform concepts, account setup, API key management, and operational best practices.

This page explains Moorcheh itself. For Memanto installation and CLI/API setup flow, use [Installation & Setup](/getting-started/installation).

## The Moorcheh Difference

### Traditional Vector Databases

Traditional systems (Pinecone, Weaviate, Milvus) use HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search:

```
Write Memory → Index (5-10 minutes wait) → Available for search
                  ↑ (CPU-intensive)
```

Problems:

* **Indexing delays** - Wait minutes before memories are searchable
* **Approximate search** - Results are probabilistic, not exact
* **High costs** - Always-running infrastructure
* **Complex setup** - Complex configuration and tuning

### Moorcheh's Approach

Moorcheh uses Information Theoretic Vector Compression (ITVC) with full vector scans:

```
Write Memory → Instant availability (no indexing) → Search immediately
                     ↑ (efficient)
```

Advantages:

* **Zero indexing delay** - Memories searchable immediately
* **Exact search** - Deterministic results, same query always returns same results
* **Serverless** - Scales to zero, pay only for operations
* **Efficient** - 80% less compute than traditional systems

## How Moorcheh Works

### Storage

```
Memory: "User prefers email"
    ↓
Memanto: Converts to vector representation
    ↓
Moorcheh: Compresses vector using ITVC
    ↓
Result: Instantly searchable (no indexing wait)
```

### Retrieval

```
Query: "How should we contact the user?"
    ↓
Memanto: Converts to vector
    ↓
Moorcheh: Searches with full vector scans
    ↓
Result: Exact match: "User prefers email"
```

## Integration Details

Moorcheh can be used directly from your application, or through a higher-level memory layer such as Memanto.

### Connection

Memanto connects to Moorcheh via REST API:

```
Your App → Moorcheh API
          └─ Uses your API key

or

Your Agent → Memanto API → Moorcheh API
                           └─ Uses your API key
```

### Authentication

Moorcheh's own API uses the `Authorization: Bearer` header. **Memanto consumes this on the server side** — it reads `MOORCHEH_API_KEY` from its environment and authenticates against Moorcheh internally. Clients calling the Memanto API never send the Moorcheh key.

```
# Direct Moorcheh API call (server-to-server, or your own integration)
Authorization: Bearer your_moorcheh_key
```

### Data Flow

```
1. Store Memory
   Agent → Memanto → Moorcheh (vector storage)

2. Recall Memory
   Agent → Memanto → Moorcheh (vector search)
           ↑ (vector conversion)

3. Semantic Matching
  Memanto uses Moorcheh's semantic search
   (not traditional keyword matching)
```

## Getting Your API Key

### Step 1: Create Moorcheh Account

1. Visit [https://moorcheh.ai](https://moorcheh.ai)
2. Click **"Sign Up"** or **"Get Started"**
3. Enter your email and create a password
4. Verify your email (check your inbox)
5. Log in to the dashboard

### Step 2: Generate API Key

1. Log in to [Moorcheh Console](https://console.moorcheh.ai)
2. Navigate to **API Keys** section (left sidebar)
3. Click **"Create New API Key"**
4. Choose a name (e.g., "Memanto Development")
5. Click **"Generate"**
6. **Copy the key immediately**

⚠️ **Important**: The key is only shown once. Copy it to a safe place.

### Step 3: Keep It Secret

**Never:**

* Commit API keys to Git
* Share in emails or chat
* Hardcode in public repositories
* Add to client-side code

**Instead:**

* Use environment variables
* Use `.env` files (excluded from git)
* Use secrets managers (AWS Secrets Manager, HashiCorp Vault, etc.)

## Using Your API Key Securely

### Option 1: Environment Variable

```bash theme={null}
export MOORCHEH_API_KEY=your_api_key_here
```

### Option 2: .env File

Create `.env` in your project:

```bash theme={null}
MOORCHEH_API_KEY=your_api_key_here
```

Then load it:

```bash theme={null}
source .env
```

For Python projects:

```python theme={null}
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("MOORCHEH_API_KEY")
```

## Verify Connectivity

Check Moorcheh API health:

```bash theme={null}
curl https://api.moorcheh.ai/v1/health
```

### Test from Code

```python theme={null}
import httpx
import os

api_key = os.getenv("MOORCHEH_API_KEY")

response = httpx.get(
   "https://api.moorcheh.ai/v1/health",
   headers={"Authorization": f"Bearer {api_key}"}
)

print(response.json())  # Should return {"status": "healthy"}
```

## Cost Advantage

### Traditional System

```
Scenario: 100K memories, weekly queries

Fixed Infrastructure: $500/month
  └─ Always-running indexing service

Query Operations: $200/month
  └─ 10K queries × $0.02 per query

TOTAL: $700/month + complexity
```

### Moorcheh + Memanto

```
Scenario: 100K memories, weekly queries

Fixed Infrastructure: $0
  └─ Serverless (scales to zero)

Query Operations: $150/month
  └─ 100K operations × $0.0015 per operation

TOTAL: $150/month + simplicity
```

**Savings: 78% cost reduction**

## Scalability

Moorcheh scales naturally:

```
1,000 memories:    Same cost and speed
100,000 memories:  Same cost and speed
1,000,000 memories: Same cost and speed
```

No indexing means no scaling complexity.

## Understanding Free Tier

Moorcheh's free tier includes:

* **500 monthly credits** (\~100,000 operations)
* **Create up to 5 agents**
* **Unlimited sessions** (no session limits)
* **No credit card required**
* **Zero Indexing Delay** & **Exact Search**

### What Counts as Operations?

* **Write operations**: storing semantic records
* **Read operations**: semantic and exact retrieval queries
* **Special operations**: workload-dependent metadata and management operations

### Estimation

| Scenario                      | Memories | Operations/Day | Days Limit |
| ----------------------------- | -------- | -------------- | ---------- |
| Small agent (10 mem/day)      | 10       | 10             | 5,000      |
| Medium agent (50 mem/day)     | 50       | 50             | 1,000      |
| Large agent (100 queries/day) | -        | 100            | 500        |
| Development (200 ops/day)     | -        | 200            | 250        |

The free tier is **plenty for heavy development and testing**.

## Upgrading to Paid Plan

When you need more than 500 credits/month:

1. Go to [https://console.moorcheh.ai](https://console.moorcheh.ai)
2. Select a plan:
   * **Pro**: 10,000 monthly credits
   * **Enterprise**: Custom limits
3. Add payment method
4. Your free API key automatically upgrades

No code changes needed - same API key works with your new plan.

## Multi-Environment Key Management

### Development

```bash theme={null}
# .env.development
MOORCHEH_API_KEY=dev_key_here
```

### Testing

```bash theme={null}
# .env.test
MOORCHEH_API_KEY=test_key_here
```

### Production

Use a secrets manager:

**AWS Secrets Manager:**

```python theme={null}
import boto3

client = boto3.client('secretsmanager')
secret = client.get_secret_value(SecretId='memanto/moorcheh-key')
api_key = secret['SecretString']
```

**HashiCorp Vault:**

```python theme={null}
import hvac

client = hvac.Client(url='https://vault.example.com')
secret = client.secrets.kv.read_secret_version(path='memanto/moorcheh-key')
api_key = secret['data']['data']['api_key']
```

**Azure Key Vault:**

```python theme={null}
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

credential = DefaultAzureCredential()
client = SecretClient(vault_url="https://myvault.vault.azure.net/", credential=credential)
secret = client.get_secret("moorcheh-api-key")
api_key = secret.value
```

## Troubleshooting

### "Invalid API Key" Error

```bash theme={null}
# Check your key is correct
echo $MOORCHEH_API_KEY

# Verify it starts with 
# Get a new key if needed from console.moorcheh.ai
```

### "Connection Refused" Error

```bash theme={null}
# Check Moorcheh status
curl https://api.moorcheh.ai/v1/health

# If Moorcheh is down, check status page
# https://status.moorcheh.ai
```

### "Rate Limited" Error

You've exceeded quota. Free tier includes 500 credits/month.

**Solutions:**

1. Wait for next month's reset
2. Upgrade to paid plan
3. Optimize your agent to use fewer operations

### "Unauthorized" Error

API key is not being passed correctly.

**Check:**

```bash theme={null}
# Verify key is in environment
echo $MOORCHEH_API_KEY

# Check header format
# Should be: Authorization: Bearer your_key
```

## Using Sovereign Moorcheh

For enterprises requiring data residency:

1. Contact [sales@moorcheh.ai](mailto:sales@moorcheh.ai)
2. Deploy Moorcheh to your VPC:
   * AWS (Terraform templates provided)
   * GCP (Cloud Deployment Manager templates provided)
3. Get a private endpoint URL
4. Configure your clients to use it:

```bash theme={null}
export MOORCHEH_BASE_URL=https://moorcheh.your-company.internal
export MOORCHEH_API_KEY=your_key
```

## Architecture Benefits

### For Memanto Users

1. **Fast onboarding** - Memanto provides a ready-made memory layer while Moorcheh handles semantic retrieval.
2. **Immediate recall after writes** - New memories become searchable without indexing delays.
3. **Deterministic retrieval behavior** - Stable search behavior helps with predictable agent outputs.

### For Application Teams

1. **Instant Memory Availability** - No waiting for indexing
2. **Predictable Performance** - Same query = same result every time
3. **Affordable Scaling** - Costs don't increase with scale
4. **Simple Deployment** - No infrastructure to manage

### For Developers

1. **Easy Integration** - Just an API key, no setup
2. **Reliable** - No indexing issues or rebalancing
3. **Cost-Effective** - Perfect for startups and projects
4. **Deterministic** - Easier to debug than probabilistic systems

## Best Practices

### <Icon icon="check" /> DO

* Store API keys in environment variables
* Rotate keys regularly
* Use secrets manager for production

### <Icon icon="xmark" /> DON'T

* Commit keys to Git
* Share keys in Slack/Email
* Hardcode keys in client code

## Next Steps

* **Configure Memanto with your key**: [Installation Guide](../getting-started/installation)
* **Moorcheh Console**: [https://console.moorcheh.ai](https://console.moorcheh.ai)
* **Moorcheh Website**: [https://moorcheh.ai](https://moorcheh.ai)

***

All set! Your Moorcheh account and API key are ready to use.