Intelligence

The /v1/intelligence endpoint is the core product. One call runs the full memory pipeline: embed, classify, deduplicate, and compress. It is completely stateless — no data is stored, no side effects. You get back enriched results and decide what to do with them.

---

Process Memory

<div class="method-badge post">POST</div> `/v1/intelligence`

Run the Engram intelligence pipeline on a piece of text. Returns an embedding vector, automatic classification, optional deduplication check, and optional proprietary compression.

Authentication required.

Request Body

Code Examples

cURL

curl -X POST https://api.engrammemory.ai/v1/intelligence \
  -H "Authorization: Bearer pr_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "The user prefers TypeScript over JavaScript for backend services",
    "check_dedup": true,
    "compress": true,
    "target_bits": 4
  }'

Python

import requests

response = requests.post(
    "https://api.engrammemory.ai/v1/intelligence",
    headers={"Authorization": "Bearer pr_live_xxxxx"},
    json={
        "text": "The user prefers TypeScript over JavaScript for backend services",
        "check_dedup": True,
        "compress": True,
        "target_bits": 4
    }
)

result = response.json()

# Full-precision vector
vector = result["vector"]                    # 768-dimensional float array
category = result["category"]                # "preference"

# Deduplication results
if result["dedup"]["is_duplicate"]:
    print(f"Duplicate found (similarity: {result['dedup']['similarity']:.2f})")

# Compressed vector
compressed = result["compressed_vector"]     # Quantized vector
ratio = result["compression_ratio"]          # e.g., 6.2
quality = result["quality_score"]            # e.g., 0.994

JavaScript

const response = await fetch("https://api.engrammemory.ai/v1/intelligence", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pr_live_xxxxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "The user prefers TypeScript over JavaScript for backend services",
    check_dedup: true,
    compress: true,
    target_bits: 4
  })
});

const result = await response.json();

// Full-precision vector
const vector = result.vector;           // 768-dimensional float array
const category = result.category;       // "preference"

// Deduplication results
if (result.dedup.is_duplicate) {
  console.log(`Duplicate found (similarity: ${result.dedup.similarity})`);
}

// Compressed vector
const compressed = result.compressed_vector;
const ratio = result.compression_ratio;   // e.g., 6.2
const quality = result.quality_score;     // e.g., 0.994

Response — 200 OK

Full response with all options enabled:

{
  "vector": [0.0234, -0.0891, 0.0412, "...(768 values)"],
  "dimension": 768,
  "category": "preference",
  "tokens_used": 11,
  "dedup": {
    "is_duplicate": false,
    "similarity": 0.42,
    "match_hash": null
  },
  "compressed_vector": [3, -1, 2, "...(768 quantized values)"],
  "compression_ratio": 6.2,
  "quality_score": 0.994
}

When a duplicate is detected:

{
  "vector": [0.0234, -0.0891, 0.0412, "...(768 values)"],
  "dimension": 768,
  "category": "preference",
  "tokens_used": 11,
  "dedup": {
    "is_duplicate": true,
    "similarity": 0.97,
    "match_hash": "hash_a4f29c8e"
  },
  "compressed_vector": [3, -1, 2, "...(768 quantized values)"],
  "compression_ratio": 6.2,
  "quality_score": 0.994
}

Minimal response (no dedup, no compression):

{
  "vector": [0.0234, -0.0891, 0.0412, "...(768 values)"],
  "dimension": 768,
  "category": "fact",
  "tokens_used": 8,
  "dedup": null,
  "compressed_vector": null,
  "compression_ratio": null,
  "quality_score": null
}

Response Schema

How It Works

Embedding — Text is embedded using Engram's optimized model, producing a 768-dimensional vector.

Classification — A lightweight classifier assigns one of five categories based on the text content. Zero configuration required.

Deduplication — When check_dedup is true, the text is checked against your stored memory hashes server-side for near-duplicates. This is a constant-time lookup, not a full vector search.

Compression — When compress is true, the float vector is compressed into a compact representation at the target bit depth. The quality_score confirms how much fidelity is preserved (typically >0.99).

Stateless Guarantee

The intelligence endpoint never stores data. It processes the input, returns enriched results, and forgets. To persist results, use the Store or Overflow Store endpoints.

Errors

Error response format:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly intelligence call limit reached (50000/50000). Resets on 2026-05-01.",
    "details": {
      "tier": "builder",
      "used": 50000,
      "limit": 50000,
      "reset_date": "2026-05-01T00:00:00Z"
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "text": "Field is required",
      "target_bits": "Must be one of: 2, 4, 8"
    }
  }
}