Engramma

Memory Text

intermediate

Text-specific memory operations: semantic search, summarize, compare, tag, link, timeline, context window, and bulk operations.

POST/v1/memory/text/search

Full semantic search across all stored text memories. Returns ranked results with highlighted matches.

querystringrequired

Natural language search query.

top_kintegerDefault: 10

Maximum results to return (1-100).

metadata_filterobject

Filter by metadata fields.

date_rangeobject

Filter by storage date: {from: "ISO date", to: "ISO date"}.

200Response
{
  "results": [
    {
      "id": "mem_abc123",
      "text": "Paris is the capital of France",
      "score": 0.94,
      "highlights": [
        "**Paris** is the **capital** of **France**"
      ],
      "stored_at": "2026-01-15T10:30:00Z",
      "metadata": {
        "category": "geography"
      }
    }
  ],
  "total_matches": 23,
  "search_time_ms": 8
}
import os
from engramma_cloud import EngrammaClient

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

results = client.text.search(
    query="European capitals",
    top_k=5,
    metadata_filter={"category": "geography"}
)
for r in results:
    print(f"[{r.score:.2f}] {r.text}")

Summarize

POST/v1/memory/text/summarize

Generate a summary from a set of memories. Useful for condensing many related memories into a coherent overview.

memory_idsarray

Specific memory IDs to summarize. If omitted, uses query to select memories.

querystring

Summarize memories relevant to this query. Required if memory_ids is not provided.

max_lengthintegerDefault: 200

Maximum summary length in words.

stylestringDefault: paragraph

Summary style: paragraph, bullets, or structured.

200Response
{
  "summary": "France is a Western European country with Paris as its capital. The country has 67 million inhabitants and is known for its cultural influence, cuisine, and historical landmarks.",
  "memories_used": [
    "mem_abc123",
    "mem_def456",
    "mem_ghi789"
  ],
  "coverage": 0.85,
  "style": "paragraph"
}
summary = client.text.summarize(
    query="What do I know about France?",
    max_length=100,
    style="bullets"
)
print(summary.summary)
print(f"Based on {len(summary.memories_used)} memories")

Compare

POST/v1/memory/text/compare

Compare two memories and identify similarities, differences, and potential contradictions.

memory_id_astringrequired

First memory ID.

memory_id_bstringrequired

Second memory ID.

200Response
{
  "memory_a": "mem_abc123",
  "memory_b": "mem_def456",
  "similarity": 0.72,
  "relationship": "complementary",
  "analysis": {
    "common_concepts": [
      "France",
      "geography"
    ],
    "differences": [
      "A focuses on capital city",
      "B focuses on population"
    ],
    "contradictions": [],
    "merge_candidate": false
  }
}
comparison = client.text.compare(
    memory_id_a="mem_abc123",
    memory_id_b="mem_def456"
)
print(f"Similarity: {comparison.similarity:.2f}")
print(f"Relationship: {comparison.relationship}")
if comparison.analysis.contradictions:
    print(f"Contradictions: {comparison.analysis.contradictions}")

Tag

POST/v1/memory/text/tag

Auto-generate semantic tags for a memory based on its content.

memory_idstringrequired

The memory to tag.

max_tagsintegerDefault: 5

Maximum number of tags to generate.

200Response
{
  "memory_id": "mem_abc123",
  "tags": [
    "geography",
    "capital-cities",
    "france",
    "europe",
    "facts"
  ],
  "confidence_per_tag": {
    "geography": 0.95,
    "capital-cities": 0.92,
    "france": 0.99,
    "europe": 0.87,
    "facts": 0.71
  }
}
tags = client.text.tag(memory_id="mem_abc123", max_tags=5)
for tag, conf in tags.confidence_per_tag.items():
    print(f"  {tag}: {conf:.2f}")
POST/v1/memory/text/link

Create an explicit causal or semantic link between two memories.

source_idstringrequired

The source memory ID.

target_idstringrequired

The target memory ID.

relationshipstringrequired

Link type: causes, supports, contradicts, context, follows, or related.

strengthnumberDefault: 0.5

Link strength (0.0 to 1.0). Strong links are more likely to surface during recall.

201Response
{
  "link_id": "lnk_abc123",
  "source_id": "mem_abc123",
  "target_id": "mem_def456",
  "relationship": "causes",
  "strength": 0.8,
  "created_at": "2026-01-15T11:00:00Z"
}
link = client.text.link(
    source_id="mem_abc123",
    target_id="mem_def456",
    relationship="causes",
    strength=0.8
)
print(f"Link created: {link.link_id}")

Timeline

GET/v1/memory/text/timeline

Get a chronological timeline of memories, optionally filtered by topic or metadata.

topicstring

Filter timeline to memories related to this topic.

fromstring

ISO 8601 start date.

tostring

ISO 8601 end date.

limitintegerDefault: 50

Maximum entries to return.

200Response
{
  "timeline": [
    {
      "id": "mem_001",
      "text": "Project kickoff meeting — agreed on microservices architecture",
      "stored_at": "2026-01-10T09:00:00Z",
      "importance": 0.9
    },
    {
      "id": "mem_002",
      "text": "First prototype deployed to staging",
      "stored_at": "2026-01-12T16:00:00Z",
      "importance": 0.7
    }
  ],
  "span": {
    "from": "2026-01-10T09:00:00Z",
    "to": "2026-01-12T16:00:00Z"
  },
  "total": 2
}
timeline = client.text.timeline(
    topic="project milestones",
    from_date="2026-01-01",
    to_date="2026-01-31"
)
for entry in timeline:
    print(f"{entry.stored_at}: {entry.text}")

Context window

POST/v1/memory/text/context

Build a context window of the most relevant memories for a given prompt. Optimized for feeding into LLMs.

promptstringrequired

The LLM prompt or user query to build context for.

max_tokensintegerDefault: 2000

Maximum tokens for the context window (memories are truncated to fit).

strategystringDefault: relevance

Ranking strategy: relevance (by confidence), recency (newest first), or balanced (mix of both).

200Response
{
  "context": "Paris is the capital of France. France has 67 million inhabitants. The Eiffel Tower was built in 1889 for the World's Fair.",
  "memories_used": [
    "mem_abc123",
    "mem_def456",
    "mem_ghi789"
  ],
  "total_tokens": 42,
  "strategy": "relevance",
  "truncated": false
}
context = client.text.context(
    prompt="Tell the user about France",
    max_tokens=1000,
    strategy="balanced"
)
# Inject into your LLM call
llm_prompt = f"Context:\n{context.context}\n\nUser: Tell me about France"

Bulk update metadata

PATCH/v1/memory/text/bulk-metadata

Update metadata on multiple memories at once. Useful for re-categorizing or adding tags in bulk.

memory_idsarrayrequired

Array of memory IDs to update (max 100).

metadataobjectrequired

Metadata fields to set or update. Existing fields not mentioned are preserved.

mergebooleanDefault: true

If true, merges with existing metadata. If false, replaces all metadata.

200Response
{
  "updated": 15,
  "ids": [
    "mem_001",
    "mem_002",
    "..."
  ],
  "errors": []
}
result = client.text.bulk_update_metadata(
    memory_ids=["mem_001", "mem_002", "mem_003"],
    metadata={"project": "v2-migration", "reviewed": True},
    merge=True
)
print(f"Updated {result.updated} memories")

Bulk delete

POST/v1/memory/text/bulk-delete

Delete multiple memories in a single request. Irreversible.

memory_idsarrayrequired

Array of memory IDs to delete (max 100).

confirmbooleanrequired

Must be true to proceed. Safety check.

200Response
{
  "deleted": 5,
  "causal_links_removed": 12,
  "errors": []
}
Danger

Bulk delete is irreversible and removes all causal links associated with the deleted memories. Use with caution.

Next steps

Memory CoreEngine Advanced