Short answer: Structured memories use typed filterable fields; free-text memories keep content as natural language for semantic search.
Structure pays off for dates, ids, categories, and exact comparisons. Free text is better when nuance and narrative matter more than exact filters. One memory can combine both: searchable prose plus a few structured properties. Draw the line by asking whether a detail must be filtered exactly or only recalled in context. Engram supports that mixed representation deliberately.
The previous chapter treated schema design as a matter of choosing the right properties and the right level of rigidity. A related question sits underneath that one: for any given piece of memory content, should it actually be captured as tightly defined, structured properties at all, or is it better left as loosely organized free text that a search interprets more directly? Neither answer is universal, and understanding when each genuinely fits is worth examining on its own.
What Actually Distinguishes a Structured Memory from a Free-Text One?
A structured memory breaks its information down into distinct, individually typed properties, a category here, a numeric value there, a date in its own dedicated field, each one directly filterable and exactly comparable. A free-text memory instead keeps its information as one continuous block of natural language, relying on semantic search to surface it rather than on any exact, structured filter. The same underlying fact can often be represented either way, the real question is which representation actually serves how that fact needs to be found and used later.
When Does Structuring a Piece of Memory Content Actually Pay Off?
Structure earns its cost when a system genuinely needs to filter, sort, or compare a value exactly, a price threshold, a specific date range, a precise category a caller wants to narrow results down to reliably. A structured property supports exactly this kind of precise operation because it’s stored as its own distinct, typed value rather than buried somewhere inside a larger block of prose that a search would only ever approximate its way toward. Whenever an application’s actual behavior depends on comparing a value exactly, greater than, equal to, within a specific range, that value belongs in its own structured property, not left to be inferred from free text after the fact.
When Does Keeping Something as Free Text Actually Serve a System Better Than Forcing It into Structure?
Free text keeps its natural nuance and its natural connections between ideas intact, which matters enormously for content that doesn’t reduce cleanly to a handful of discrete fields. A rich, narrative observation, one that captures how several different details relate to each other in context, loses exactly that connective nuance the moment someone tries to force it into a rigid set of separate structured properties. Forcing structure onto content that doesn’t naturally fit it produces exactly the kind of brittle, awkward schema the previous chapter warned against, structured fields populated with meaningless placeholder values just to satisfy a template that was never actually the right shape for that content in the first place.
Can a Single Memory Genuinely Combine Both Approaches at Once?
Most real, useful memories do exactly this, keeping their core substance as searchable free text while attaching a handful of genuinely structured properties alongside it for the specific details that actually need exact filtering. This hybrid approach gets the best of both: the free-text portion preserves nuance and lets semantic search do what it does best, while the structured properties give a caller a precise, reliable way to narrow results down by exactly the dimensions that actually matter for that content. Treating structured and free-text representation as a strict either-or choice misses this far more common and far more useful middle ground.
How Should a Team Decide Where to Draw This Line for a Specific Kind of Memory?
The right test is asking whether a specific detail is something a caller would ever need to filter or compare exactly, rather than simply recall as part of a broader narrative. A detail that clears that bar, a date, an identifier, a numeric threshold, belongs in its own structured property. A detail that exists mainly to give context and nuance to the broader memory, without ever needing to be filtered on its own, is better left inside the free-text content where it can keep its natural connection to everything else the memory is actually describing. This judgment call has to be made deliberately for each kind of memory a system actually stores, since the right balance for one kind of content won’t automatically be the right balance for another.
How Does Weaviate Engram Support This Kind of Deliberate, Mixed Representation?
Weaviate Engram stores every memory with both a searchable text body and a set of structured properties alongside it, letting a team apply exactly this hybrid judgment rather than being forced to choose one representation for everything. Consider a wildlife conservation organization’s field-observation logging assistant, helping researchers record sightings during long stretches of remote fieldwork:
from engram import EngramClient
client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])
client.memories.add(
"Spotted a family group of eleven African wild dogs moving north along the dry riverbed at dawn, unusually far from their known den site, possibly following a shift in impala herd movement after recent rains.",
properties={"reserve_id": "reserve-northern-block", "species": "african-wild-dog", "count": 11},
)
The narrative content stays as rich, connected free text, preserving the researcher’s actual reasoning about why the pack might have moved, while the species and count properties give a research coordinator an exact, reliable way to filter sightings later:
results = client.memories.search(
query="Any recent wild dog sightings away from the usual den site?",
properties={"reserve_id": "reserve-northern-block", "species": "african-wild-dog"},
)
Forcing this entire observation into rigid structured fields, trying to capture “possibly following impala movement after recent rains” as some kind of categorical value, would strip away exactly the nuanced reasoning a researcher actually needs preserved. Leaving the species and count buried only in free text, meanwhile, would make it considerably harder for a coordinator to reliably pull every wild dog sighting across months of accumulated field notes. Engram’s combination of structured properties and searchable free text lets this specific memory keep both: precise, filterable facts alongside the full narrative context that gives those facts their actual meaning.
Deciding what to structure and what to leave as free text is ultimately about matching representation to how a specific detail actually needs to be found and used. A related concern emerges once memory starts describing not just isolated facts but the people, places, and things those facts are actually about, and how those things relate to each other across many different memories. Our next chapter, What are entities and relationships in agent memory?, takes up exactly that concern.