Engramma

Memory Vectors

advanced

Low-level vector API: store, query, retrieve, compose, and manage patterns directly with embedding vectors.

Store pattern

POST/v1/memory/store

Store a key-value pattern in the tenant's memory space.

keyarray[number]required

Embedding vector (key) — any dimension accepted.

valuearray[number]required

Value vector — any dimension accepted.

metadataobject | null

Arbitrary metadata to attach to the pattern.

source_diminteger | null

Original embedding dimension (for inverse projection on query results).

200Response
{
  "success": true,
  "pattern_id": "pat_a1b2c3",
  "patterns_used": 1524,
  "patterns_limit": 100000
}

Query memory

POST/v1/memory/query

Query the memory with an embedding vector. Returns raw matches ranked by confidence.

embeddingarray[number]required

Query embedding — any dimension accepted.

top_kintegerDefault: 1

Number of results to return (1–100).

return_native_dimbooleanDefault: false

If true, unproject results back to the query's original dimension.

200Response
{
  "results": [
    {
      "value": [
        0.12,
        -0.34,
        0.56,
        "..."
      ],
      "confidence": 0.92,
      "pathway": "exact"
    }
  ],
  "latency_ms": 3.2
}

Retrieve intelligent

POST/v1/memory/retrieve

Intelligent retrieval with Active Inference + semantic re-ranking + metadata.

embeddingarray[number]required

Query embedding vector.

top_kintegerDefault: 5

Number of results to return (1–100).

200Response
{
  "results": [
    {
      "confidence": 0.94,
      "metadata": {
        "source": "user_input",
        "category": "science"
      },
      "was_reranked": true,
      "semantic_score": 0.89
    }
  ],
  "info": {
    "boosted": true,
    "n_candidates": 12,
    "original_top_score": 0.87,
    "boosted_top_score": 0.94
  },
  "latency_ms": 8.1
}

Compose patterns

POST/v1/memory/compose

Compose multiple patterns via compositional retrieval.

keysarray[array[number]] | null

Patterns to compose as embedding vectors (2–10 items).

textsarray[string] | null

Patterns to compose as text strings, auto-embedded (2–10 items).

weightsarray[number] | null

Composition weights (must match length of keys/texts).

200Response
{
  "result": [
    0.23,
    -0.45,
    0.67,
    "..."
  ],
  "confidence": 0.85
}
Tip

Provide either keys (raw embeddings) or texts (auto-embedded server-side), not both.

Compose fractional (SLERP)

POST/v1/memory/compose/fractional

SLERP interpolation between two patterns with continuous alpha blending.

key_aarray[number] | null

First pattern embedding.

key_barray[number] | null

Second pattern embedding.

text_astring | null

First pattern as text (auto-embedded).

text_bstring | null

Second pattern as text (auto-embedded).

pattern_a_idstring | null

First pattern ID (looked up from metadata store).

pattern_b_idstring | null

Second pattern ID (looked up from metadata store).

alphanumberDefault: 0.5

Blend ratio: 0.0 = A pure, 1.0 = B pure (0.0–1.0).

200Response
{
  "result": [
    0.34,
    -0.12,
    0.78,
    "..."
  ],
  "confidence": 0.91,
  "info": {
    "geodesic_distance": 0.42,
    "blend_type": "slerp",
    "alpha_used": 0.5
  }
}
Tip

Specify patterns via one of: key_a/key_b, text_a/text_b, or pattern_a_id/pattern_b_id.

Update pattern

PUT/v1/memory/pattern

Update the value of an existing pattern without delete/recreate.

keyarray[number]required

Key of the pattern to update.

new_valuearray[number]required

New value vector.

metadataobject | null

Updated metadata.

200Response
{
  "message": "Pattern updated"
}

Delete pattern

DELETE/v1/memory/pattern

Forget a pattern (GDPR-compliant deletion).

The request body is a raw JSON array containing the key vector identifying the pattern to forget.

200Response
{
  "message": "Pattern forgotten"
}
curl -X DELETE https://api.engramma-memory.com/v1/memory/pattern \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[0.12, -0.34, 0.56, 0.78]'

Get pattern by index

GET/v1/memory/pattern/{pattern_idx}

Retrieve a specific pattern by its internal index.

pattern_idxintegerrequired

Pattern index (path parameter).

200Response
{
  "key": [
    0.12,
    -0.34,
    "..."
  ],
  "value": [
    0.56,
    0.78,
    "..."
  ],
  "metadata": {}
}

Semantic query (deprecated)

POST/v1/memory/query/semantic

Query with semantic re-ranking. Deprecated — use POST /v1/memory/retrieve instead.

embeddingarray[number]required

Query embedding.

top_kintegerDefault: 5

Number of results (1–50).

Warning

This endpoint is deprecated. Migrate to POST /v1/memory/retrieve which provides Active Inference + semantic re-ranking.

Batch store

POST/v1/memory/batch/store

Store multiple patterns in a single request.

patternsarray[BatchPatternItem]required

Array of patterns to store.

Each BatchPatternItem:

FieldTypeRequiredDescription
keyarray[number]YesEmbedding vector
valuearray[number]YesValue vector
metadataobject | nullNoMetadata
200Response
{
  "stored": 10,
  "failed": 0
}

Batch retrieve

POST/v1/memory/batch/retrieve

Retrieve multiple patterns in a single request.

queriesarray[BatchQueryItem]required

Array of query items.

Each BatchQueryItem:

FieldTypeRequiredDefaultDescription
embeddingarray[number]Yes—Query embedding
top_kintegerNo1Results per query (1–100)
200Response
{
"results": [
  [{"value": [...], "confidence": 0.92, "pathway": "exact"}],
  [{"value": [...], "confidence": 0.87, "pathway": "energy"}]
]
}

Sleep consolidation

POST/v1/memory/sleep

Trigger a sleep/consolidation cycle (LTP/LTD + composition discovery).

batch_sizeintegerDefault: 5

Compositions to explore during sleep (1–20).

200Response
{
  "consolidated": 3,
  "compositions_discovered": 2,
  "patterns_strengthened": 5,
  "patterns_weakened": 1
}

Get brain state

GET/v1/memory/brain

Get full brain/XAI state — regime, surprise, head weights, temporal predictions.

200Response
{
  "regime": "normal",
  "surprise": 0.23,
  "head_weights": [
    0.4,
    0.35,
    0.25
  ],
  "temporal_predictions": [],
  "patterns_total": 1524,
  "consolidation_status": "idle"
}

Next steps

Memory Text (Embed & Similarity)Engine Advanced