Engine Advanced

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

Semantic neighbors

POST/v1/engine/semantic/neighbors

Find semantically similar patterns in the memory space. Returns the neighborhood graph around a memory.

memory_idstringrequired

Center memory for neighborhood exploration.

radiusintegerDefault: 5

Number of neighbor hops to explore (1-10).

min_similaritynumberDefault: 0.3

Minimum similarity threshold for neighbors.

200Response

{
  "center": "mem_abc123",
  "neighbors": [
    {
      "id": "mem_def456",
      "text": "France has 67 million inhabitants",
      "similarity": 0.82,
      "hop": 1,
      "link_type": "context"
    },
    {
      "id": "mem_ghi789",
      "text": "The EU has 27 member states",
      "similarity": 0.61,
      "hop": 2,
      "link_type": "related"
    }
  ],
  "graph_density": 0.34
}

import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

neighbors = client.engine.semantic_neighbors(
    memory_id="mem_abc123",
    radius=3,
    min_similarity=0.5
)
for n in neighbors:
    print(f"  hop {n.hop}: [{n.similarity:.2f}] {n.text[:60]}")

Semantic score

POST/v1/engine/semantic/score

Calculate the semantic similarity score between two texts or memories without storing them.

text_astring

First text to compare. Use this OR memory_id_a.

text_bstring

Second text to compare. Use this OR memory_id_b.

memory_id_astring

First memory ID to compare.

memory_id_bstring

Second memory ID to compare.

200Response

{
  "similarity": 0.87,
  "breakdown": {
    "cosine": 0.91,
    "semantic_overlap": 0.83,
    "structural": 0.72
  }
}

Semantic stats

GET/v1/engine/semantic/stats

Get statistics about the semantic index: cluster count, average density, distribution.

200Response

{
  "total_vectors": 1247,
  "clusters": 23,
  "avg_cluster_size": 54,
  "avg_density": 0.67,
  "orphan_count": 12,
  "index_health": 0.91,
  "last_reindex": "2026-01-14T03:00:00Z"
}

Explorer: Entropy

GET/v1/engine/explorer/entropy

Measure the entropy (information diversity) of your memory space. High entropy means diverse, well-distributed knowledge.

scopestringDefault: global

Entropy scope: global (entire space), cluster (per cluster), or recent (last 7 days).

200Response

{
  "global_entropy": 0.78,
  "max_possible": 1,
  "interpretation": "Well-distributed knowledge with some clusters of concentration",
  "clusters": [
    {
      "name": "geography",
      "entropy": 0.45,
      "size": 142
    },
    {
      "name": "engineering",
      "entropy": 0.82,
      "size": 534
    }
  ]
}

Explorer: Select

POST/v1/engine/explorer/select

Intelligently select a subset of memories for exploration. Uses entropy-maximizing selection to show the most diverse cross-section.

countintegerDefault: 10

Number of memories to select.

strategystringDefault: diverse

Selection strategy: diverse (maximize coverage), boundary (cluster boundaries), anomaly (unusual patterns), or random.

200Response

{
  "selected": [
    {
      "id": "mem_abc123",
      "text": "Paris is the capital of France",
      "cluster": "geography",
      "selection_reason": "cluster_representative"
    }
  ],
  "coverage": 0.73,
  "strategy": "diverse"
}

Explorer: Batch

POST/v1/engine/explorer/batch

Run batch exploration across memory space. Returns a structured map of knowledge clusters, connections, and gaps.

depthstringDefault: standard

Exploration depth: shallow (clusters only), standard (clusters + connections), or deep (full graph analysis).

200Response

{
  "clusters": [
    {
      "id": "cluster_001",
      "label": "geography",
      "size": 142,
      "density": 0.78,
      "top_memories": [
        "mem_abc123",
        "mem_def456"
      ]
    }
  ],
  "connections": [
    {
      "from": "cluster_001",
      "to": "cluster_003",
      "strength": 0.45,
      "bridge_memories": [
        "mem_ghi789"
      ]
    }
  ],
  "gaps": [
    {
      "between": [
        "geography",
        "history"
      ],
      "suggestion": "Store memories connecting geographic facts to historical events"
    }
  ]
}

exploration = client.engine.explorer.batch(depth="deep")
for cluster in exploration.clusters:
    print(f"{cluster.label}: {cluster.size} memories (density: {cluster.density:.2f})")
for gap in exploration.gaps:
    print(f"Gap between {gap.between}: {gap.suggestion}")

Consolidation: Preview

POST/v1/engine/consolidation/preview

Preview what a consolidation cycle would do without actually executing it.

200Response

{
  "would_merge": 12,
  "would_prune": 5,
  "would_strengthen": 34,
  "would_weaken": 8,
  "estimated_time_ms": 2400,
  "merge_candidates": [
    {
      "ids": [
        "mem_abc123",
        "mem_def456"
      ],
      "similarity": 0.94,
      "merged_text_preview": "Paris is the capital of France with 67 million inhabitants"
    }
  ]
}

preview = client.engine.consolidation.preview()
print(f"Would merge: {preview.would_merge}")
print(f"Would prune: {preview.would_prune}")
print(f"Would strengthen: {preview.would_strengthen} links")
for candidate in preview.merge_candidates:
    print(f"  Merge {candidate.ids} → {candidate.merged_text_preview[:60]}")

Consolidation: Execute

POST/v1/engine/consolidation/merge

Execute a consolidation cycle. Merges duplicates, prunes weak memories, strengthens frequent links, and builds new causal connections.

aggressivebooleanDefault: false

If true, uses lower thresholds for merging and pruning. More cleanup but higher risk of losing nuance.

protect_recent_hoursintegerDefault: 24

Don't consolidate memories stored in the last N hours.

200Response

{
  "merged": 12,
  "pruned": 5,
  "strengthened": 34,
  "weakened": 8,
  "new_links": 6,
  "duration_ms": 2340,
  "before_count": 1247,
  "after_count": 1230
}

result = client.consolidate(
    aggressive=False,
    protect_recent_hours=48
)
print(f"Merged: {result.merged}")
print(f"Pruned: {result.pruned}")
print(f"New links: {result.new_links}")
print(f"Before: {result.before_count} → After: {result.after_count}")

Info

Consolidation is idempotent — running it multiple times without new data has no effect. It counts as 1 API call regardless of how many patterns it processes.

Consolidation: Protected list

GET/v1/engine/consolidation/protected

List all memories marked as protected from consolidation.

200Response

{
  "protected": [
    {
      "id": "mem_abc123",
      "text": "Production database is at db.prod.internal:5432",
      "importance": 0.99,
      "protected_at": "2026-01-10T10:00:00Z"
    }
  ],
  "total": 8
}

Consolidation: Sleep stats

GET/v1/engine/consolidation/sleep-stats

View statistics about automatic consolidation cycles (sleep cycles).

200Response

{
  "total_cycles": 42,
  "last_cycle": {
    "started_at": "2026-01-20T03:00:00Z",
    "duration_ms": 4200,
    "merged": 3,
    "pruned": 1,
    "strengthened": 12
  },
  "avg_cycle_duration_ms": 3100,
  "next_scheduled": "2026-01-21T03:00:00Z",
  "frequency": "daily"
}

Diagnostics: Prefetch

POST/v1/engine/diagnostics/prefetch

Warm up the retrieval cache for expected queries. Reduces latency for anticipated requests.

queriesarrayrequired

Array of query strings to prefetch (max 20).

200Response

{
  "prefetched": 5,
  "cache_hits": 2,
  "cache_misses": 3,
  "estimated_speedup_ms": 45
}

Diagnostics: Warmup

POST/v1/engine/diagnostics/warmup

Warm up the entire memory engine. Loads indexes and frequently accessed patterns into memory.

200Response

{
  "status": "warm",
  "indexes_loaded": 3,
  "patterns_cached": 312,
  "duration_ms": 890
}

Diagnostics: Invalidate cache

POST/v1/engine/diagnostics/invalidate

Invalidate the retrieval cache. Forces fresh computations on next request.

scopestringDefault: all

What to invalidate: all, retrieval, semantic, or consolidation.

200Response

{
  "invalidated": true,
  "scope": "all",
  "entries_cleared": 1247
}

Diagnostics: Structure

GET/v1/engine/diagnostics/structure

Inspect the internal structure of the memory engine: index health, tier distribution, link graph stats.

200Response

{
  "index": {
    "type": "hnsw",
    "dimensions": 1536,
    "total_vectors": 1247,
    "fragmentation": 0.03
  },
  "tiers": {
    "hot": {
      "count": 312,
      "avg_access": 12.4
    },
    "warm": {
      "count": 645,
      "avg_access": 3.1
    },
    "cold": {
      "count": 290,
      "avg_access": 0.4
    }
  },
  "causal_graph": {
    "nodes": 1247,
    "edges": 834,
    "avg_degree": 1.34,
    "max_depth": 7,
    "cycles": 0
  },
  "health": {
    "overall": 0.91,
    "index_health": 0.95,
    "tier_balance": 0.88,
    "graph_connectivity": 0.89
  }
}

structure = client.engine.diagnostics.structure()
print(f"Index: {structure.index.type} ({structure.index.dimensions}d)")
print(f"Vectors: {structure.index.total_vectors}")
print(f"Health: {structure.health.overall:.0%}")
print(f"Graph: {structure.causal_graph.edges} edges, max depth {structure.causal_graph.max_depth}")

Configuration

GET/v1/engine/config

Retrieve current engine configuration for your account.

200Response

{
  "retrieval": {
    "default_top_k": 5,
    "default_threshold": 0,
    "confidence_router_enabled": true,
    "pathway_weights": {
      "exact": 0.4,
      "energy": 0.3,
      "attention": 0.3
    }
  },
  "consolidation": {
    "auto_enabled": true,
    "frequency": "daily",
    "aggressive": false,
    "protect_recent_hours": 24,
    "merge_threshold": 0.85
  },
  "regime": {
    "current": "normal",
    "auto_detection": true
  }
}

PATCH/v1/engine/config

Update engine configuration. Only provided fields are changed.

retrievalobject

Retrieval settings: default_top_k, default_threshold, confidence_router_enabled, pathway_weights.

consolidationobject

Consolidation settings: auto_enabled, frequency, aggressive, protect_recent_hours, merge_threshold.

regimeobject

Regime settings: auto_detection.

200Response

{
  "updated": true,
  "changes": [
    "consolidation.frequency",
    "consolidation.merge_threshold"
  ]
}

# Adjust consolidation settings
client.engine.update_config(
    consolidation={
        "frequency": "twice_daily",
        "merge_threshold": 0.90
    }
)

State: Save

POST/v1/engine/state/save

Save a snapshot of the current engine state. Useful before major changes or experiments.

labelstring

Optional label for the snapshot.

201Response

{
  "snapshot_id": "snap_abc123",
  "label": "pre-migration",
  "created_at": "2026-01-15T10:00:00Z",
  "size_mb": 12.4,
  "patterns_count": 1247
}

State: Restore

POST/v1/engine/state/restore

Restore the engine to a previously saved snapshot. All changes since the snapshot are lost.

snapshot_idstringrequired

The snapshot to restore.

200Response

{
  "restored": true,
  "snapshot_id": "snap_abc123",
  "label": "pre-migration",
  "patterns_restored": 1247,
  "patterns_lost": 53
}

Danger

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

# Save state before experiment
snapshot = client.engine.state.save(label="pre-experiment")
print(f"Saved: {snapshot.snapshot_id}")

# ... run experiment ...

# Restore if experiment failed
result = client.engine.state.restore(snapshot_id=snapshot.snapshot_id)
print(f"Restored {result.patterns_restored} patterns")

Next steps

Memory Core — Store, retrieve, recall, explain
Consolidation Guide — Best practices for triggering consolidation
Errors — Error codes and troubleshooting