Engramma

Engine Advanced

advanced

Semantic neighbors, explorer, consolidation, diagnostics, configuration, and state management endpoints.

All endpoints below are under /v1/memory/ (not /v1/engine/).

Semantic neighbors

POST/v1/memory/semantic/neighbors

Find semantically similar patterns in the memory space around a given embedding.

keyarray[number]required

Pattern embedding vector.

top_kintegerDefault: 5

Number of neighbors to return (1-50).

200Response
{
  "neighbors": [
    {
      "pattern_id": "pat_def456",
      "similarity": 0.82,
      "metadata": {
        "category": "geography"
      }
    }
  ]
}

Semantic composition score

POST/v1/memory/semantic/composition-score

Score how well two patterns compose relative to a query.

queryarray[number]required

Query embedding.

key_aarray[number]required

First component pattern embedding.

key_barray[number]required

Second component pattern embedding.

200Response
{
  "composition_score": 0.78,
  "individual_scores": {
    "a": 0.65,
    "b": 0.71
  }
}

Semantic similarity (vectors)

POST/v1/memory/semantic/similarity

Compute cosine similarity between two embedding vectors.

key_aarray[number]required

First embedding vector.

key_barray[number]required

Second embedding vector.

200Response
{
  "similarity": 0.87
}

Semantic clusters

GET/v1/memory/semantic/clusters

Get the current cluster structure of the semantic space.

200Response
{
  "clusters": [
    {
      "id": 0,
      "size": 42,
      "centroid_pattern_id": "pat_abc"
    },
    {
      "id": 1,
      "size": 28,
      "centroid_pattern_id": "pat_def"
    }
  ],
  "total_patterns": 142
}

Semantic rerank

POST/v1/memory/semantic/rerank

Re-rank a list of candidates by semantic relevance to a query.

queryarray[number]required

Query embedding.

candidatesarrayrequired

Array of candidate objects to rerank.

Semantic pre-liaison

POST/v1/memory/semantic/pre-liaison

Create a semantic pre-liaison between two text patterns.

key_astringrequired

First pattern (text, auto-embedded).

key_bstringrequired

Second pattern (text, auto-embedded).

strengthnumberDefault: 0.8

Link strength (0.0 to 1.0).

Semantic stats

GET/v1/memory/semantic/stats

Get statistics about the semantic layer.

200Response
{
  "total_patterns": 142,
  "avg_similarity": 0.34,
  "clusters": 5
}

Explorer: Entropy

GET/v1/memory/explorer/entropy

Measure the entropy (information diversity) of your memory space.

200Response
{
  "entropy": 0.78,
  "max_possible": 1,
  "pattern_count": 142
}

Explorer: Select next

POST/v1/memory/explorer/select-next

Select the next most informative pattern pair to explore (entropy-maximizing).

max_candidatesintegerDefault: 20

Max candidate pairs to consider (1-100).

200Response
{
  "selected": {
    "pattern_a": "pat_abc",
    "pattern_b": "pat_def",
    "expected_information_gain": 0.34
  }
}

Explorer: Batch

POST/v1/memory/explorer/batch

Run batch exploration across memory space.

batch_sizeintegerDefault: 5

Number of explorations to run (1-20).

200Response
{
  "explored": 5,
  "compositions_found": 3,
  "entropy_after": 0.82
}

Consolidation: Preview

GET/v1/memory/consolidation/preview

Preview what a consolidation cycle would do without executing it.

200Response
{
  "merge_candidates": 12,
  "estimated_patterns_after": 130
}

Consolidation: Merge candidates

GET/v1/memory/consolidation/merge-candidates

List patterns that are candidates for merging (high similarity duplicates).

200Response
{
  "candidates": [
    {
      "pattern_a": "pat_abc",
      "pattern_b": "pat_def",
      "similarity": 0.94
    }
  ]
}

Consolidation: Merge duplicates

POST/v1/memory/consolidation/merge-duplicates

Execute duplicate merging.

thresholdnumberDefault: 0.85

Similarity threshold for merging (0.0 to 1.0).

200Response
{
  "merged": 5,
  "patterns_before": 142,
  "patterns_after": 137
}

Consolidation: Sleep

POST/v1/memory/consolidation/sleep

Trigger a sleep consolidation cycle (LTD eviction, strengthening, reorganization).

modestringDefault: full

Sleep mode: full or light.

protect_categoriesarray | null

Categories to protect from LTD eviction (e.g. ["identity", "health"]).

200Response
{
  "status": "completed",
  "evicted": 3,
  "strengthened": 12,
  "duration_ms": 2340
}

Consolidation: Wake

POST/v1/memory/consolidation/wake

Wake from sleep mode — reactivate normal operations after sleep consolidation.

200Response
{
  "status": "awake"
}

Consolidation: Status

GET/v1/memory/consolidation/status

Get the current consolidation status.

200Response
{
  "status": "idle",
  "last_run": "2026-01-14T03:00:00Z",
  "next_scheduled": null
}

Consolidation: Importance

GET/v1/memory/consolidation/importance

Get importance rankings for all patterns.

Consolidation: Protected

GET/v1/memory/consolidation/protected

List patterns protected from consolidation.

Consolidation: Sleep stats

GET/v1/memory/consolidation/sleep-stats

Statistics about past sleep cycles.

200Response
{
  "total_cycles": 42,
  "last_cycle": {
    "started_at": "2026-01-20T03:00:00Z",
    "duration_ms": 4200,
    "evicted": 3,
    "strengthened": 12
  }
}

Diagnostics: Structure

GET/v1/memory/diagnostics/structure

Inspect the internal structure of the memory engine.

Diagnostics: Prefetch

GET/v1/memory/diagnostics/prefetch

Get prefetch cache diagnostics.

Diagnostics: Warmup

POST/v1/memory/diagnostics/prefetch/warmup

Warm up the prefetch cache around a query embedding.

queryarray[number]required

Query embedding to prefetch around.

Diagnostics: Invalidate

POST/v1/memory/diagnostics/prefetch/invalidate

Invalidate the prefetch cache.

Configuration

GET/v1/memory/config

Retrieve current engine configuration for your tenant.

200Response
{
  "engine_version": "0.5.0",
  "embedding_dim": 384,
  "max_patterns": 5000,
  "consolidation_enabled": true
}

State: Save

POST/v1/memory/state/save

Save a snapshot of the current engine state.

200Response
{
  "snapshot_id": "snap_abc123",
  "patterns_count": 142,
  "created_at": "2026-01-15T10:00:00Z"
}

State: Restore

POST/v1/memory/state/restore

Restore the engine to a previously saved snapshot.

200Response
{
  "restored": true,
  "snapshot_id": "snap_abc123",
  "patterns_restored": 142
}
Danger

Restoring a snapshot is irreversible. All patterns stored after the snapshot was taken will be permanently lost.

Next steps

Memory VectorsCausal