Agent Memory with Engram: A Practical Guide
By Steven Van ·
Engram's run status guide covers the four run states, committed operations and error handling, and says most apps never need to poll.
Weaviate's Engram docs now include a guide to checking run status, published alongside a practical blog post on agent memory. Every memories.add request in Weaviate's Engram service returns a run_id, and the guide explains how to track that run and read its result.
Polling a run
Engram processes stored memories asynchronously through a pipeline. In the Python SDK, client.runs.wait(run.run_id) returns the run's status, and an async client offers the same call. Over the REST API, the equivalent is a GET request to https://api.engram.weaviate.io/v1/runs/{run-id} with the API key as a bearer token.
The response includes the run ID, status, group and user IDs, starting step, input type, committed_operations and created and updated timestamps.
Run statuses
- running: the pipeline is actively processing the content.
- in_buffer: the run is paused at a buffer step, waiting for a trigger to continue.
- completed: all operations have been committed successfully.
- failed: an error occurred during processing.
Committed operations
When a run completes, committed_operations lists what changed. created holds new memories added to storage. updated holds existing memories that were modified, for example merged or refined. deleted holds memories that were removed, for example because an update superseded them. Each entry has a memory_id and a committed_at timestamp.
Handling failures
If a run fails, its error field describes what went wrong. The guide's example is "extraction failed: invalid input format".
When to poll
The guide says most applications do not need to poll. Memories are eventually consistent and become searchable once the pipeline finishes, and the initial memories.add response is enough to catch immediate errors. It recommends runs.get only when you need to confirm that a specific run has completed, such as during testing or debugging.
