Memory Core

Store, retrieve, recall, explain, predict, and forget memories using the text API. The primary endpoints for memory operations.

The text API (/v1/memory/text/*) is the high-level interface for working with memories as text. The engine handles embedding, storage, and retrieval automatically.

For the low-level vector API (/v1/memory/store, /v1/memory/query, /v1/memory/retrieve), see Memory Vectors.

Store

POST/v1/memory/text/store

Store a text fact in memory. The text is embedded server-side using paraphrase-multilingual-MiniLM-L12-v2.

textstringrequired

The text content to memorize. Min 1, max 10,000 characters.

metadataobject | null

Arbitrary key-value pairs (role, category, source, etc.).

200Response

{
  "success": true,
  "pattern_id": "pat_a7f2c1e9",
  "embedding_dim": 384,
  "patterns_used": 42,
  "patterns_limit": 5000
}

curl -X POST https://api.engramma-memory.com/v1/memory/text/store \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Paris is the capital of France",
    "metadata": {"category": "geography", "source": "textbook"}
  }'

Batch store

POST/v1/memory/text/batch-store

Store multiple text facts in a single request.

itemsarrayrequired

Array of TextStoreRequest objects. Min 1, max 50 items. Each item has text (required) and metadata (optional).

200Response

{
  "stored": 3,
  "failed": 0,
  "pattern_ids": [
    "pat_001",
    "pat_002",
    "pat_003"
  ],
  "latency_ms": 45.2
}

curl -X POST https://api.engramma-memory.com/v1/memory/text/batch-store \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"text": "Python was created by Guido van Rossum"},
      {"text": "JavaScript was created by Brendan Eich"},
      {"text": "Go was created at Google in 2009"}
    ]
  }'

Retrieve

POST/v1/memory/text/retrieve

Retrieve the most relevant stored facts for a text query. Uses cosine similarity in embedding space.

querystringrequired

The query text. Min 1, max 5,000 characters.

top_kintegerDefault: 5

Number of results to return (1-50).

200Response

{
  "results": [
    {
      "text": "Paris is the capital of France",
      "metadata": {
        "category": "geography"
      },
      "similarity": 0.94,
      "pattern_id": "pat_a7f2c1e9"
    }
  ],
  "latency_ms": 2.3
}

curl -X POST https://api.engramma-memory.com/v1/memory/text/retrieve \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the capital of France?", "top_k": 3}'

Recall

POST/v1/memory/text/recall

Intelligent recall with Active Inference + semantic boost. Uses the full 10-step retrieval cycle with semantic re-ranking by co-access patterns. Better results after the memory has been used for a while.

querystringrequired

The query text. Min 1, max 5,000 characters.

top_kintegerDefault: 5

Number of results to return (1-50).

200Response

{
  "results": [
    {
      "text": "Paris is the capital of France",
      "metadata": {
        "category": "geography"
      },
      "similarity": 0.96,
      "pattern_id": "pat_a7f2c1e9"
    }
  ],
  "info": {},
  "latency_ms": 8.1
}

Info

/text/recall returns higher-quality results than /text/retrieve because it uses learned access patterns for re-ranking. Use /text/retrieve for simple similarity search, and /text/recall when you want the full cognitive engine.

Similarity

POST/v1/memory/text/similarity

Compute semantic similarity between two texts. Returns cosine similarity in embedding space.

text_astringrequired

First text. Min 1, max 5,000 characters.

text_bstringrequired

Second text. Min 1, max 5,000 characters.

200Response

{
  "similarity": 0.87,
  "embedding_dim": 384
}

Predict

POST/v1/memory/text/predict

Predict what the user will ask next based on temporal patterns. Uses Granger causality in the temporal tracker.

querystringrequired

Current query/context. Min 1, max 5,000 characters.

top_kintegerDefault: 5

Number of predictions to return (1-50).

200Response

{
  "predictions": [
    {
      "text": "What is the population of France?",
      "pattern_id": "pat_def456",
      "strength": 0.72
    }
  ]
}

Explain

POST/v1/memory/text/explain

Get a human-readable explanation of the last recall. Describes how a memory was retrieved, including source, confidence, method, and age.

querystringrequired

The query that was recalled. Min 1, max 5,000 characters.

langstring | null

Language for explanation: fr or en. Auto-detected if null.

200Response

{
  "explanation": "High-confidence match (0.94) via cosine similarity. The stored fact 'Paris is the capital of France' directly answers the query. Stored 5 days ago, accessed 12 times.",
  "method": "cosine_similarity",
  "confidence": 0.94
}

Forget

DELETE/v1/memory/text/forget

Selective forget — erase patterns by category or semantic query. Unlike GDPR full erasure, this only removes matching patterns.

querystring | null

Semantic query to match patterns to forget. Min 1, max 5,000 characters.

categorystring | null

GDPR category to forget (identity, location, health, etc.).

thresholdnumberDefault: 0.85

Similarity threshold for query-based forget (0.5 to 1.0).

200Response

{
  "forgotten": 3,
  "pattern_ids": [
    "pat_001",
    "pat_002",
    "pat_003"
  ]
}

Warning

At least one of query or category must be provided. Higher threshold = more precise (fewer deletions). Lower threshold = broader match.

curl -X DELETE https://api.engramma-memory.com/v1/memory/text/forget \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "my home address", "threshold": 0.9}'

Stats

GET/v1/memory/text/stats

Get text memory statistics for the current tenant.

200Response

{
  "total_patterns": 142,
  "embedding_dim": 384,
  "storage_bytes": 245760
}

Important

GET/v1/memory/text/important

List all facts classified as important (identity, health, location, etc.). These facts are protected from eviction during sleep consolidation cycles.

200Response

{
  "important": [
    {
      "pattern_id": "pat_abc123",
      "text": "My name is Alice",
      "category": "identity",
      "protected": true
    }
  ]
}

Embed

POST/v1/memory/text/embed

Return the embedding vector for a text string. Uses the same encoder as store/retrieve. Useful for calling vector-based endpoints with text.

textstringrequired

Text to embed. Min 1, max 10,000 characters.

200Response

{
"embedding": [0.023, -0.041, 0.089, ...],
"dim": 384
}

Next steps

Memory Vectors — Low-level vector API (store/query/retrieve with raw embeddings)
Engine Advanced — Semantic, explorer, consolidation
Errors — Error handling