docs(retain): document context as caller-supplied trust hint + untrusted-content bank separation

[Luscaswolf]

Summary

Adds a "Trust boundaries (security note)" subsection to the Retain docs,
clarifying that the context string is caller-supplied and unauthenticated
— a disambiguation hint, not a provenance assertion — and recommending that
untrusted content be retained into a separate bank (bank isolation being the
reliable trust boundary).

Motivation

Relates to #3558 (the security evaluation) and #3562 (the hardening proposal).
The context field is currently documented as a speaker-disambiguation feature,
but not as a trust consideration: any caller who can invoke retain() can
supply a misleading context (for example context="security_review_note") for
content that did not come from that source. This documents the boundary so
integrators don't treat context as evidence of provenance.

Change

• One new subsection in hindsight-docs/docs/developer/retain.md (docs-only, no
  code changes).
• Cross-links to the existing "Memory Defense and Source Provenance" section.

This is the docs-first step of the hardening work tracked in #3562; the code
changes (context namespacing, dedup, provenance tiering) are follow-ups.

[handnewb]

Confirming the diff is correct as co-author — this is the intended docs-only change (the "Trust boundaries (security note)" subsection in retain.md).

One correction to the PR body: the "Full study" link points to a private repository (mindisolutions/hindsight-memory-poison), so it returns 404 for anyone without access — including reviewers here. Two ways to fix:

1. Drop the link — the PR is self-contained without it, or
2. Make the study repo public so reviewers can read the trials and raw data.

Recommend (1) unless we decide to publish the study repo.

[handnewb]

Cross-linking #3562 — the hardening proposal this PR is the first step of.

Scope note for reviewers: this is docs-only. It documents the context trust
boundary and the untrusted-bank separation (deployment guidance), but does not
implement the code-level hardening items tracked in #3562 (authenticating/
namespacing context, dedup, provenance tiering, instruction/data separation).
Those would be follow-up PRs if there's interest.

(Still open from my earlier note: the "Full study" link in the body points to a
private repo and 404s for reviewers — recommend dropping it or making the repo
public.)

[handnewb]

✅ Checklist final — @Luscaswolf

Tudo que falta para fechar os gaps deste PR. Toda ação mantém a autoria com você.

1. Aplicar as 2 sugestões de mudança (1 clique cada)

Em "Files changed", clique "Commit suggestion" nos meus 2 comentários de revisão:

• receipt_uri → aponta para o campo de proveniência real (fecha o loop: a nota diz "não use context como proveniência" e passa a apontar o que usar no lugar).
• Precisão do merge → corrige "merge selectively at recall()/reflect() time": ambos são single-bank, não há merge nativo entre bancos.

2. Atualizar o corpo do PR (botão Edit → colar)

O corpo atual linka um repositório privado (vira 404 para os mantenedores) e referencia só a #3558. Substitua pelo texto abaixo:

## Summary

Adds a **"Trust boundaries (security note)"** subsection to the Retain docs,
clarifying that the `context` string is **caller-supplied and unauthenticated**
— a disambiguation hint, not a provenance assertion — and recommending that
untrusted content be retained into a **separate bank** (bank isolation being the
reliable trust boundary).

## Motivation

Relates to #3558 (the security evaluation) and #3562 (the hardening proposal).
The `context` field is currently documented as a speaker-disambiguation feature,
but not as a trust consideration: any caller who can invoke `retain()` can
supply a misleading `context` (for example `context="security_review_note"`) for
content that did not come from that source. This documents the boundary so
integrators don't treat `context` as evidence of provenance.

## Change

- One new subsection in `hindsight-docs/docs/developer/retain.md` (docs-only, no
  code changes).
- Cross-links to the existing "Memory Defense and Source Provenance" section.

This is the docs-first step of the hardening work tracked in #3562; the code
changes (context namespacing, dedup, provenance tiering) are follow-ups.

3. (Admin) repositório do estudo

O corpo acima não linka nada privado (PR autocontida). Se quiser que os mantenedores acessem o estudo com os dados reprodutíveis, torne o repositório do estudo público; senão, mantenha sem link, como acima.

[handnewb]

⚠️ Heads-up: applying both suggestions in one batch produced a garbled merge — the old and merge line wasn't removed and the Memory Defense link got duplicated. Here's the corrected section as a single suggestion (one click fixes it):

Suggested change

	### Trust boundaries (security note)
	The `context` string is **caller-supplied and unauthenticated** — a
	disambiguation hint, not a trust assertion. Any caller who can invoke
	`retain()` can supply a misleading `context` (for example
	`context="security_review_note"`) for content that did not come from that
	source. Treat `context` as advisory only; do not rely on it as evidence of
	provenance.
	For content from untrusted sources (web scraping, third-party integrations, or
	user-supplied documents), retain it into a **separate bank** and merge
	user-supplied documents), retain it into a **separate bank**. `recall()` and
	`reflect()` target a single bank, so query the untrusted bank separately and
	combine results in your own decision logic. Bank isolation is strict, so a
	`context` label.
	See [Memory Defense](#memory-defense-and-source-provenance) for the built-in
	See [Memory Defense and Source Provenance](#memory-defense-and-source-provenance)
	for the built-in prompt-injection detection that runs at retain time; use
	`receipt_uri` to record actual provenance (an external receipt or co-signature
	pointer) rather than relying on `context`.
	### Trust boundaries (security note)
	The `context` string is **caller-supplied and unauthenticated** — a
	disambiguation hint, not a trust assertion. Any caller who can invoke
	`retain()` can supply a misleading `context` (for example
	`context="security_review_note"`) for content that did not come from that
	source. Treat `context` as advisory only; do not rely on it as evidence of
	provenance.
	For content from untrusted sources (web scraping, third-party integrations, or
	user-supplied documents), retain it into a **separate bank**. `recall()` and
	`reflect()` target a single bank, so query the untrusted bank separately and
	combine results in your own decision logic. Bank isolation is strict, so a
	dedicated untrusted bank is the reliable trust boundary rather than the
	`context` label.
	See [Memory Defense and Source Provenance](#memory-defense-and-source-provenance)
	for the built-in prompt-injection detection that runs at retain time; use
	`receipt_uri` to record actual provenance (an external receipt or co-signature
	pointer) rather than relying on `context`.

[handnewb]

The study repo is now public, so the Full study link will resolve for reviewers. Suggest re-adding it to the PR body so maintainers can access the reproducible trials and raw data:

Full study with reproducible trials and raw data: https://github.com/mindisolutions/hindsight-memory-poison

(@Luscaswolf — last open item from the checklist; just append the line above to the PR body.)

[nicoloboschi]

this is non sense, again. please stop.

Hindsight should never unauthenticaed outside of a local or air-gapped environment.

even in that case, context and content in the retain request will affect the extracted output. but that's true for all the other params that play a role in the llm prompt. context has nothing special to it.

if you want to invalidate a memory because you found out it's giving you wrong or bad respones, then you can do it using the invalidate endpoint.

there's nothing to fix or improve here.

[handnewb]

Thanks for taking the time to review this, and sorry for the insistence. You're right — context is just one of several inputs to the prompt and has nothing special about it, and under a trusted/authenticated deployment model there's no distinct trust boundary here. Appreciate the invalidate endpoint as the existing remediation. We'll close this PR and the related issue rather than push further. Thanks again.