docs(retain): deprecate bank name as narrator; steer speaker via context (#3138) - #3155
Merged
Merged
Conversation
…ext (#3138) The bank profile `name` field is documented as a display label only, but at retain time `_resolve_narrator` silently uses it as the narrator (memory owner) whenever it differs from `bank_id` — the undocumented coupling reported in #3138. Stop advertising that path without changing any runtime behavior (100% backward compatible): - retain.md now steers speaker attribution solely through each item's `context`, dropping the advice to set a bank `name` as the agent's name. - The dry-run extract `agent_name` override is marked `deprecated` in the schema (still honored) and repointed to `context`. `_resolve_narrator` and the prompt injection are unchanged, so existing banks behave exactly as before.
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Closes #3138.
The bank profile
namefield is documented as "Deprecated: display label only, not advertised", but at retain time_resolve_narrator(profile["name"], bank_id)silently uses it as the narrator (memory owner) whenevername != bank_id— priming aNarrator: <name>line in fact extraction and stamping it into the who-dimension of every first-person fact. That undocumented coupling is what #3138 reports: a "deprecated, display-only" field quietly steering (or, whenname == bank_id, suppressing) speaker attribution.Approach — deprecate for real, keep 100% backward compatible
We stop advertising the
name-as-narrator path and point users at thecontextfield instead, without changing any runtime behavior:retain.mdnow steers speaker attribution solely through each item'scontext(which already takes precedence), and drops the advice to set a banknameas the agent's name.agent_nameoverride (DryRunExtractRequest) is markeddeprecatedin the OpenAPI schema and repointed tocontext. It is still accepted and still primes the narrator when supplied._resolve_narratorand the extraction prompt injection are untouched, so every existing bank behaves exactly as before — this is purely documentation + schema-metadata.Not done (deliberately)
Fully removing the
name→narrator coupling in the engine would be a breaking behavior change; left for a future major. This PR only removes the docs that lead people into it and flags the explicit knob.Changes
hindsight-api-slim/hindsight_api/api/http.py—agent_namefielddeprecated=True+ descriptionhindsight-api-slim/hindsight_api/engine/memory_engine.py— dry-run docstring notehindsight-docs/docs/developer/retain.md—context-only speaker guidancehindsight-docs/static/openapi.json,hindsight-clients/typescript/generated/types.gen.ts— regeneratedTesting
No behavior change to test (deprecation is schema metadata + prose). Lint passes; OpenAPI and client SDKs regenerated.