Compression

Engram's compression API reduces vector storage size while preserving recall quality. Engram's proprietary compression method achieves higher compression ratios than standard scalar quantization with minimal quality loss.

Compress Vectors

Compress one or more vectors using the specified quantization method.

POST /v1/compress

Request Body

Compression Methods

Quality Presets

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/compress \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": [
      [0.1, 0.2, -0.3, 0.4, 0.5, -0.1, 0.8, 0.3],
      [0.9, -0.2, 0.1, 0.6, -0.4, 0.7, 0.2, -0.5]
    ],
    "target_bits": 4,
    "method": "TURBOQUANT",
    "quality": "BALANCED"
  }'

Python

from engrammemory import Engram

client = Engram(api_key="pr_live_xxxxx")

result = client.compress(
    vectors=[
        [0.1, 0.2, -0.3, 0.4, 0.5, -0.1, 0.8, 0.3],
        [0.9, -0.2, 0.1, 0.6, -0.4, 0.7, 0.2, -0.5],
    ],
    target_bits=4,
    method="TURBOQUANT",
    quality="BALANCED",
)

print(f"Compression ratio: {result.ratio}")
print(f"Quality score: {result.quality_metrics.cosine_similarity}")

JavaScript

import { Engram } from "engrammemory-ai";

const client = new Engram({ apiKey: "pr_live_xxxxx" });

const result = await client.compress({
  vectors: [
    [0.1, 0.2, -0.3, 0.4, 0.5, -0.1, 0.8, 0.3],
    [0.9, -0.2, 0.1, 0.6, -0.4, 0.7, 0.2, -0.5],
  ],
  targetBits: 4,
  method: "TURBOQUANT",
  quality: "BALANCED",
});

console.log(`Compression ratio: ${result.ratio}`);
console.log(`Quality score: ${result.qualityMetrics.cosineSimilarity}`);

Response

{
  "compressed_vectors": [
    "base64-encoded-data...",
    "base64-encoded-data..."
  ],
  "original_size_bytes": 128,
  "compressed_size_bytes": 32,
  "ratio": 4.0,
  "method": "TURBOQUANT",
  "target_bits": 4,
  "quality_metrics": {
    "cosine_similarity": 0.9847,
    "mean_squared_error": 0.00023,
    "max_absolute_error": 0.012,
    "signal_to_noise_ratio": 42.3
  }
}

Response Fields

---

Get Compression Analytics

Retrieve aggregate compression statistics for your account.

GET /v1/compression/analytics

Code Examples

cURL

curl https://api.engrammemory.ai/v1/compression/analytics \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

analytics = client.compression.analytics()
print(f"Total compressed: {analytics.total_vectors_compressed}")
print(f"Storage saved: {analytics.storage_saved_mb} MB")

JavaScript

const analytics = await client.compression.analytics();
console.log(`Total compressed: ${analytics.totalVectorsCompressed}`);
console.log(`Storage saved: ${analytics.storageSavedMb} MB`);

Response

{
  "total_vectors_compressed": 1250000,
  "total_original_size_mb": 4800.5,
  "total_compressed_size_mb": 1200.1,
  "average_ratio": 4.0,
  "average_cosine_similarity": 0.9823,
  "method_breakdown": {
    "TURBOQUANT": {
      "count": 1000000,
      "average_ratio": 4.2,
      "average_quality": 0.9847
    },
    "SCALAR_QUANTIZATION": {
      "count": 250000,
      "average_ratio": 3.5,
      "average_quality": 0.9612
    }
  },
  "storage_saved_mb": 3600.4,
  "last_compression_at": "2026-04-10T08:30:00Z"
}

---

Compare Compression Methods

Compare compression results between methods for a sample of your data.

GET /v1/compression/comparison

Code Examples

cURL

curl https://api.engrammemory.ai/v1/compression/comparison \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

comparison = client.compression.comparison()
for method in comparison.methods:
    print(f"{method.name}: ratio={method.ratio}, quality={method.quality}")

JavaScript

const comparison = await client.compression.comparison();
comparison.methods.forEach((method) => {
  console.log(`${method.name}: ratio=${method.ratio}, quality=${method.quality}`);
});

Response

{
  "sample_size": 10000,
  "methods": [
    {
      "name": "SCALAR_QUANTIZATION",
      "ratio": 3.5,
      "quality": 0.9612,
      "compression_time_ms": 120,
      "decompression_time_ms": 45
    },
    {
      "name": "TURBOQUANT",
      "ratio": 4.2,
      "quality": 0.9847,
      "compression_time_ms": 340,
      "decompression_time_ms": 62
    }
  ],
  "recommendation": "TURBOQUANT",
  "recommendation_reason": "20% better compression with 2.4% higher quality retention"
}

---

List Compression Jobs

List all compression jobs with pagination.

GET /v1/compression/jobs

Query Parameters

Code Examples

cURL

curl "https://api.engrammemory.ai/v1/compression/jobs?page=1&page_size=10&status=COMPLETED" \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

jobs = client.compression.jobs.list(page=1, page_size=10, status="COMPLETED")
for job in jobs.items:
    print(f"Job {job.id}: {job.status} — ratio {job.ratio}")

JavaScript

const jobs = await client.compression.jobs.list({
  page: 1,
  pageSize: 10,
  status: "COMPLETED",
});
jobs.items.forEach((job) => {
  console.log(`Job ${job.id}: ${job.status} — ratio ${job.ratio}`);
});

Response

{
  "items": [
    {
      "id": "cjob_abc123",
      "status": "COMPLETED",
      "method": "TURBOQUANT",
      "quality": "BALANCED",
      "target_bits": 4,
      "vectors_count": 50000,
      "ratio": 4.1,
      "created_at": "2026-04-10T08:00:00Z",
      "completed_at": "2026-04-10T08:02:30Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 10,
  "total_pages": 5
}

---

Get Job Details

Retrieve detailed information about a specific compression job.

GET /v1/compression/jobs/{job_id}

Path Parameters

Code Examples

cURL

curl https://api.engrammemory.ai/v1/compression/jobs/cjob_abc123 \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

job = client.compression.jobs.get("cjob_abc123")
print(f"Status: {job.status}")
print(f"Progress: {job.progress_pct}%")

JavaScript

const job = await client.compression.jobs.get("cjob_abc123");
console.log(`Status: ${job.status}`);
console.log(`Progress: ${job.progressPct}%`);

Response

{
  "id": "cjob_abc123",
  "status": "RUNNING",
  "method": "TURBOQUANT",
  "quality": "HIGH",
  "target_bits": 4,
  "vectors_count": 50000,
  "vectors_processed": 32000,
  "progress_pct": 64.0,
  "ratio": 4.1,
  "quality_metrics": {
    "cosine_similarity": 0.9851,
    "mean_squared_error": 0.00021
  },
  "created_at": "2026-04-10T08:00:00Z",
  "started_at": "2026-04-10T08:00:02Z",
  "completed_at": null,
  "error": null
}

---

Create Compression Batch

Create a scheduled batch compression job that runs on a cron schedule.

POST /v1/compression/batches

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/compression/batches \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Compression",
    "schedule": "0 2 * * *",
    "method": "TURBOQUANT",
    "quality": "HIGH",
    "target_bits": 4,
    "collections": ["col_abc123", "col_def456"],
    "retention_days": 14
  }'

Python

batch = client.compression.batches.create(
    name="Nightly Compression",
    schedule="0 2 * * *",
    method="TURBOQUANT",
    quality="HIGH",
    target_bits=4,
    collections=["col_abc123", "col_def456"],
    retention_days=14,
)
print(f"Batch created: {batch.id}")

JavaScript

const batch = await client.compression.batches.create({
  name: "Nightly Compression",
  schedule: "0 2 * * *",
  method: "TURBOQUANT",
  quality: "HIGH",
  targetBits: 4,
  collections: ["col_abc123", "col_def456"],
  retentionDays: 14,
});
console.log(`Batch created: ${batch.id}`);

Response

{
  "id": "cbatch_xyz789",
  "name": "Nightly Compression",
  "schedule": "0 2 * * *",
  "method": "TURBOQUANT",
  "quality": "HIGH",
  "target_bits": 4,
  "collections": ["col_abc123", "col_def456"],
  "retention_days": 14,
  "enabled": true,
  "next_run_at": "2026-04-11T02:00:00Z",
  "created_at": "2026-04-10T12:00:00Z"
}

---

List Compression Batches

List all scheduled compression batches.

GET /v1/compression/batches

Code Examples

cURL

curl https://api.engrammemory.ai/v1/compression/batches \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

batches = client.compression.batches.list()
for batch in batches.items:
    print(f"{batch.name}: next run at {batch.next_run_at}")

JavaScript

const batches = await client.compression.batches.list();
batches.items.forEach((batch) => {
  console.log(`${batch.name}: next run at ${batch.nextRunAt}`);
});

Response

{
  "items": [
    {
      "id": "cbatch_xyz789",
      "name": "Nightly Compression",
      "schedule": "0 2 * * *",
      "method": "TURBOQUANT",
      "quality": "HIGH",
      "enabled": true,
      "last_run_at": "2026-04-10T02:00:00Z",
      "next_run_at": "2026-04-11T02:00:00Z",
      "last_run_status": "COMPLETED"
    }
  ],
  "total": 3
}

---

Update Compression Batch

Update an existing scheduled compression batch.

PATCH /v1/compression/batches/{batch_id}

Path Parameters

Request Body

All fields are optional. Only include fields you want to update.

Code Examples

cURL

curl -X PATCH https://api.engrammemory.ai/v1/compression/batches/cbatch_xyz789 \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "enabled": false
  }'

Python

batch = client.compression.batches.update(
    "cbatch_xyz789",
    schedule="0 3 * * *",
    enabled=False,
)

JavaScript

const batch = await client.compression.batches.update("cbatch_xyz789", {
  schedule: "0 3 * * *",
  enabled: false,
});

Response

Returns the updated batch object (same schema as create response).

---

Delete Compression Batch

Delete a scheduled compression batch. Running jobs are not affected.

DELETE /v1/compression/batches/{batch_id}

Path Parameters

Code Examples

cURL

curl -X DELETE https://api.engrammemory.ai/v1/compression/batches/cbatch_xyz789 \
  -H "Authorization: Bearer pr_live_xxxxx"

Python

client.compression.batches.delete("cbatch_xyz789")

JavaScript

await client.compression.batches.delete("cbatch_xyz789");

Response

204 No Content

---

Error Codes