iris-development says it "currently covers one product in that family: Redis Agent Memory", and that additional Iris products will be added as separate sections when they ship. Filing this as the case for Context Retriever being one of them, with the specific rules that cost us the most — rather than opening a PR, because a new product section needs a new eval suite and baseline, which is yours to scope.
Context: we built a production app on Context Retriever (schema-first entities → generated MCP tools) plus Agent Memory. Everything below is measured against a live surface, not read from docs.
1. A key component can never be indexed — so some reads are impossible, not unimplemented
The service rejects redis_indices on any field that appears in a redis_key_template:
key component field "owner_id" cannot have redis_indices
The consequence is not a limitation, it is an architectural constraint that has to be designed around from the start. Our Connection entity is keyed by owner_id, so owner_id can never be filtered, so no generated tool argument can confine a connection read to one owner. All four generated Connection tools had to be withheld from the model permanently and the graph reached another way.
We assumed the opposite for a milestone, changed the schema on that assumption, and it failed after the delete step of a re-provision — leaving no surface at all. A skill saying this once, in one sentence, is worth a lot.
2. A surface's data_source is immutable, and recreating it issues a new agent key
UpdateContextSurfaceRequest has no data_source. So changing the address, the password, or enabling TLS means delete-and-recreate — and the new surface comes with a new agent key. Until the application's key is updated it reads nothing and reports nothing: no auth error surfaced to the user, just empty results.
The second half is the dangerous half. "Enable TLS on the backing database" sounds like a settings change; it is a credential rotation.
3. Re-provisioning the same data model can change the generated tool list — including its shape
This is the one I would most want written down, because it is a security property.
The same schema produced 28 tools, then 32 after a re-provision to enable TLS. The four new ones took the entity as an argument rather than encoding it in the tool name — so a filter that decided what the model could reach by matching tool names silently stopped covering them, and the whole social graph became reachable through a tool the allowlist had never seen.
Nothing failed. No error, no diff, no log line. We caught it only because a separate check fingerprints the tool list and the fingerprint changed.
The practical guidance: fingerprint the generated tool list, persist the baseline outside the process, and treat a change as something a human accepts rather than something the monitor adopts. A baseline held in memory cannot survive a restart, and the change that mattered to us happened while nothing was running.
4. Smaller, but each cost an afternoon
- Vector fields with no
source_field generate raw-vector _similarity tools whose required argument is an array of vector_dim floats. A model cannot produce that, so those tools are unusable by an agent directly and the query has to be embedded on your side. Worth stating, because it is also the design that keeps query text out of the embedding provider's hands via Redis — a genuine benefit, not just a constraint.
list_context_surfaces paginates, default page_size=20. A "does this surface already exist" check that reads one page will happily create a duplicate. Ours nearly did; the account had ~20 surfaces.- The admin key can modify every surface in the account, including other people's. Ours must never live in a
.env the application runtime loads — it is exported per command instead. That is a deployment rule, not a preference.
Why a skill rather than docs
Every item above is a thing an agent will get wrong confidently: it will add redis_indices to a key component because that is what indexing a field looks like, it will call update to change an address, and it will filter tools by name because the names are stable — right up until they aren't.
Happy to draft skills/iris-development/references/cr-*.md (or a separate context-retriever skill, whichever fits your roadmap) and the eval suite, if you want it. Related PRs from the same project: #53, #54, #55. Streams gap filed separately as #56.
🤖 Generated with Claude Code
iris-developmentsays it "currently covers one product in that family: Redis Agent Memory", and that additional Iris products will be added as separate sections when they ship. Filing this as the case for Context Retriever being one of them, with the specific rules that cost us the most — rather than opening a PR, because a new product section needs a new eval suite and baseline, which is yours to scope.Context: we built a production app on Context Retriever (schema-first entities → generated MCP tools) plus Agent Memory. Everything below is measured against a live surface, not read from docs.
1. A key component can never be indexed — so some reads are impossible, not unimplemented
The service rejects
redis_indiceson any field that appears in aredis_key_template:The consequence is not a limitation, it is an architectural constraint that has to be designed around from the start. Our
Connectionentity is keyed byowner_id, soowner_idcan never be filtered, so no generated tool argument can confine a connection read to one owner. All four generated Connection tools had to be withheld from the model permanently and the graph reached another way.We assumed the opposite for a milestone, changed the schema on that assumption, and it failed after the delete step of a re-provision — leaving no surface at all. A skill saying this once, in one sentence, is worth a lot.
2. A surface's
data_sourceis immutable, and recreating it issues a new agent keyUpdateContextSurfaceRequesthas nodata_source. So changing the address, the password, or enabling TLS means delete-and-recreate — and the new surface comes with a new agent key. Until the application's key is updated it reads nothing and reports nothing: no auth error surfaced to the user, just empty results.The second half is the dangerous half. "Enable TLS on the backing database" sounds like a settings change; it is a credential rotation.
3. Re-provisioning the same data model can change the generated tool list — including its shape
This is the one I would most want written down, because it is a security property.
The same schema produced 28 tools, then 32 after a re-provision to enable TLS. The four new ones took the entity as an argument rather than encoding it in the tool name — so a filter that decided what the model could reach by matching tool names silently stopped covering them, and the whole social graph became reachable through a tool the allowlist had never seen.
Nothing failed. No error, no diff, no log line. We caught it only because a separate check fingerprints the tool list and the fingerprint changed.
The practical guidance: fingerprint the generated tool list, persist the baseline outside the process, and treat a change as something a human accepts rather than something the monitor adopts. A baseline held in memory cannot survive a restart, and the change that mattered to us happened while nothing was running.
4. Smaller, but each cost an afternoon
source_fieldgenerate raw-vector_similaritytools whose required argument is an array ofvector_dimfloats. A model cannot produce that, so those tools are unusable by an agent directly and the query has to be embedded on your side. Worth stating, because it is also the design that keeps query text out of the embedding provider's hands via Redis — a genuine benefit, not just a constraint.list_context_surfacespaginates, defaultpage_size=20. A "does this surface already exist" check that reads one page will happily create a duplicate. Ours nearly did; the account had ~20 surfaces..envthe application runtime loads — it is exported per command instead. That is a deployment rule, not a preference.Why a skill rather than docs
Every item above is a thing an agent will get wrong confidently: it will add
redis_indicesto a key component because that is what indexing a field looks like, it will callupdateto change an address, and it will filter tools by name because the names are stable — right up until they aren't.Happy to draft
skills/iris-development/references/cr-*.md(or a separatecontext-retrieverskill, whichever fits your roadmap) and the eval suite, if you want it. Related PRs from the same project: #53, #54, #55. Streams gap filed separately as #56.🤖 Generated with Claude Code