Engramma

Memory Core

intermediate

Store, retrieve, recall, explain, predict, and manage memories. The primary endpoints for memory operations.

Store

POST/v1/memory/store

Store a new memory. The engine automatically encodes it, selects the optimal pathway, and indexes it for retrieval.

textstringrequired

The text content to memorize. Max 10,000 characters.

importancenumberDefault: 0.5

Importance weight (0.0 to 1.0). High-importance memories resist pruning during consolidation.

metadataobject

Arbitrary key-value pairs for filtering and organization.

protectedbooleanDefault: false

If true, this memory cannot be pruned or merged during consolidation.

201Response
{
  "id": "mem_abc123",
  "text": "Paris is the capital of France",
  "stored_at": "2026-01-15T10:30:00Z",
  "importance": 0.5,
  "tier": "hot",
  "pathway": "exact",
  "metadata": {}
}
import os
from engramma_cloud import EngrammaClient

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

result = client.store(
    "Paris is the capital of France",
    importance=0.8,
    metadata={"category": "geography", "source": "textbook"}
)
print(f"Stored: {result.id} via {result.pathway}")

Batch store

POST/v1/memory/batch-store

Store multiple memories in a single request. More efficient than individual stores for bulk imports.

memoriesarrayrequired

Array of memory objects. Each object has text, optional importance, metadata, and protected fields. Max 100 items per batch.

201Response
{
  "stored": 5,
  "ids": [
    "mem_001",
    "mem_002",
    "mem_003",
    "mem_004",
    "mem_005"
  ],
  "errors": []
}
results = client.batch_store([
    {"text": "Python was created by Guido van Rossum", "importance": 0.6},
    {"text": "JavaScript was created by Brendan Eich", "importance": 0.6},
    {"text": "Go was created at Google in 2009", "importance": 0.5},
])
print(f"Stored {results.stored} memories")
print(f"IDs: {results.ids}")
Info

Batch store is atomic per-item: if one memory fails validation, the others still succeed. Check the errors array for partial failures.

Retrieve

POST/v1/memory/retrieve

Retrieve memories relevant to a query. The Confidence Router selects the optimal pathway (Exact, Energy, or Attention) automatically.

querystringrequired

The query text. What are you trying to remember?

top_kintegerDefault: 5

Maximum number of results to return (1-50).

thresholdnumberDefault: 0.0

Minimum confidence score (0.0 to 1.0). Results below this threshold are excluded.

metadata_filterobject

Filter results by metadata. Supports exact match and operators.

pathwaystring

Force a specific pathway: exact, energy, or attention. Omit to let the Confidence Router decide.

200Response
{
  "results": [
    {
      "id": "mem_abc123",
      "text": "Paris is the capital of France",
      "confidence": 0.94,
      "pathway": "exact",
      "stored_at": "2026-01-15T10:30:00Z",
      "importance": 0.8,
      "metadata": {
        "category": "geography"
      }
    },
    {
      "id": "mem_def456",
      "text": "France has 67 million inhabitants",
      "confidence": 0.71,
      "pathway": "energy",
      "stored_at": "2026-01-14T08:00:00Z",
      "importance": 0.5,
      "metadata": {
        "category": "geography"
      }
    }
  ],
  "pathway_used": "exact",
  "query_time_ms": 12
}
results = client.retrieve(
    "What is the capital of France?",
    top_k=3,
    threshold=0.5,
    metadata_filter={"category": "geography"}
)
for r in results:
    print(f"[{r.confidence:.2f}|{r.pathway}] {r.text}")

Recall

POST/v1/memory/recall

Recall memories through natural language. Unlike retrieve, recall uses the full cognitive cycle including causal reasoning to find contextually relevant memories.

querystringrequired

Natural language question or context description.

depthstringDefault: standard

Recall depth: shallow (fast, similarity only), standard (includes causal links), or deep (full reasoning chain).

include_causalbooleanDefault: true

Whether to follow causal links when recalling.

200Response
{
  "memories": [
    {
      "id": "mem_abc123",
      "text": "Paris is the capital of France",
      "confidence": 0.94,
      "pathway": "exact",
      "causal_links": [
        {
          "target_id": "mem_def456",
          "relationship": "context",
          "strength": 0.72
        }
      ]
    }
  ],
  "reasoning_chain": [
    "Query matches stored fact directly (exact pathway)",
    "Causal link found: France population data provides context"
  ],
  "depth_used": "standard",
  "query_time_ms": 28
}
memories = client.recall(
    "Tell me about France",
    depth="deep",
    include_causal=True
)
for m in memories:
    print(f"{m.text}")
    for link in m.causal_links:
        print(f"  → linked to {link.target_id} ({link.relationship})")

Similarity

POST/v1/memory/similarity

Find memories similar to a given memory. Useful for deduplication checks and exploring neighborhoods.

memory_idstringrequired

The ID of the reference memory.

top_kintegerDefault: 5

Number of similar memories to return.

thresholdnumberDefault: 0.3

Minimum similarity score.

200Response
{
  "reference": "mem_abc123",
  "similar": [
    {
      "id": "mem_ghi789",
      "text": "The capital city of France is Paris, known as the City of Light",
      "similarity": 0.91,
      "overlap_type": "semantic_duplicate"
    }
  ]
}

Stats

GET/v1/memory/stats

Get statistics about your memory space: total patterns, tier distribution, health metrics.

200Response
{
  "total_patterns": 1247,
  "tiers": {
    "hot": 312,
    "warm": 645,
    "cold": 290
  },
  "avg_importance": 0.52,
  "avg_confidence": 0.73,
  "causal_links": 834,
  "last_consolidation": "2026-01-14T03:00:00Z",
  "storage_mb": 45.2,
  "health_score": 0.87
}
stats = client.stats()
print(f"Total patterns: {stats.total_patterns}")
print(f"Health: {stats.health_score:.0%}")
print(f"Tiers: {stats.tiers.hot} hot / {stats.tiers.warm} warm / {stats.tiers.cold} cold")

Important memories

GET/v1/memory/important

List the most important memories, ranked by importance score. Useful for reviewing what the system considers critical.

top_kintegerDefault: 10

Number of important memories to return (1-100).

min_importancenumberDefault: 0.7

Minimum importance threshold.

200Response
{
  "memories": [
    {
      "id": "mem_abc123",
      "text": "Production database credentials are in Vault at /secret/prod/db",
      "importance": 0.99,
      "protected": true,
      "access_count": 47,
      "last_accessed": "2026-01-20T09:15:00Z"
    }
  ]
}

Predict

POST/v1/memory/predict

Use causal links to predict outcomes based on stored memories. Three levels of causal reasoning are available.

conditionstringrequired

The condition or scenario to reason about.

levelstringDefault: intervention

Causal level: association (correlation), intervention (what-if), or counterfactual (what would have been).

200Response
{
  "condition": "What happens if we double the traffic?",
  "level": "intervention",
  "predictions": [
    {
      "outcome": "Latency increases by ~40% based on historical pattern",
      "confidence": 0.82,
      "supporting_memories": [
        "mem_abc123",
        "mem_def456"
      ],
      "causal_chain": [
        "traffic_increase → queue_depth_increase → latency_increase"
      ]
    }
  ]
}
prediction = client.predict(
    condition="What happens if we double the traffic?",
    level="intervention"
)
for p in prediction.predictions:
    print(f"Outcome: {p.outcome}")
    print(f"Confidence: {p.confidence:.2f}")
    print(f"Chain: {' → '.join(p.causal_chain)}")

Explain

POST/v1/memory/explain

Get a human-readable explanation of why a specific memory was retrieved or how it connects to a query.

memory_idstringrequired

The memory to explain.

querystring

The query context. If provided, explains why this memory is relevant to the query.

detailstringDefault: simple

Detail level: simple (one sentence), detailed (paragraph), or technical (full breakdown with scores).

200Response
{
  "memory_id": "mem_abc123",
  "explanation": {
    "simple": "This memory directly answers your question about the capital of France.",
    "detailed": "The memory 'Paris is the capital of France' was retrieved because it contains an exact semantic match for your query. The Confidence Router selected the Exact pathway with 94% confidence. This memory also has a causal link to population data about France, providing additional context.",
    "technical": {
      "pathway": "exact",
      "confidence": 0.94,
      "pathway_scores": {
        "exact": 0.94,
        "energy": 0.67,
        "attention": 0.72
      },
      "factors": [
        {
          "name": "semantic_similarity",
          "score": 0.96,
          "weight": 0.4
        },
        {
          "name": "recency",
          "score": 0.8,
          "weight": 0.2
        },
        {
          "name": "importance",
          "score": 0.8,
          "weight": 0.2
        },
        {
          "name": "access_frequency",
          "score": 0.65,
          "weight": 0.2
        }
      ]
    }
  }
}
explanation = client.explain(
    memory_id="mem_abc123",
    query="What is the capital of France?",
    detail="technical"
)
print(explanation.simple)
print(f"Pathway: {explanation.technical.pathway}")
print(f"Confidence: {explanation.technical.confidence}")
for factor in explanation.technical.factors:
    print(f"  {factor.name}: {factor.score:.2f} (weight: {factor.weight})")

Forget

DELETE/v1/memory/{memory_id}

Permanently delete a specific memory. This is irreversible.

memory_idstringrequired

The ID of the memory to delete (path parameter).

200Response
{
  "deleted": true,
  "id": "mem_abc123",
  "causal_links_removed": 3
}
result = client.forget("mem_abc123")
print(f"Deleted: {result.id}")
print(f"Causal links removed: {result.causal_links_removed}")
Warning

Forgetting a memory also removes all causal links that reference it. This can affect the quality of predictions and recall for related memories.

Next steps

  • Memory Text — Text-specific operations and semantic search
  • Engine Advanced — Consolidation, diagnostics, explorer
  • Errors — Error handling and troubleshooting
AuthenticationMemory Text