Skip to content

docs: reframe observations as evidence-grounded consolidated knowledge#1051

Merged
nicoloboschi merged 2 commits intomainfrom
docs-observations-reframing
Apr 14, 2026
Merged

docs: reframe observations as evidence-grounded consolidated knowledge#1051
nicoloboschi merged 2 commits intomainfrom
docs-observations-reframing

Conversation

@nicoloboschi
Copy link
Copy Markdown
Collaborator

Summary

The docs currently describe observations as "auto-synthesized patterns" / "synthesized knowledge representations". That framing reads as LLM summarization and undersells what observations actually are per the code (hindsight-api-slim/hindsight_api/engine/consolidation/consolidator.py, engine/reflect/observations.py):

  • Deduplicated, not re-summarized — overlapping facts merge into one durable belief with a proof_count, not repeated observations.
  • Evidence-grounded — each observation references its source memories with exact quotes (ObservationEvidence.quote).
  • Refined, not overwritten — contradictions are incorporated while preserving history.
  • Freshness trend computed from evidence timestamps (stable / strengthening / weakening / new / stale).

This PR updates the five spots that used the old framing to describe what observations really are.

Files changed

  • hindsight-docs/src/pages/best-practices.mdx — taxonomy row + memory-type row
  • hindsight-docs/docs/developer/api/recall.mdxtypes parameter description + observation tip
  • hindsight-docs/docs/developer/observations.mdx — page intro, "What Are Observations?", bullet list
  • hindsight-docs/docs/developer/index.mdx — consolidation overview
  • hindsight-docs/docs/developer/configuration.md — observations section intro + `OBSERVATIONS_MISSION` description

Docs-only, no code or schema changes.

Test plan

  • Build docs site locally (`./scripts/dev/start-docs.sh`) and spot-check the five edited pages render cleanly
  • Verify no broken internal links introduced

The previous framing leaned on "synthesis" and "patterns", which reads as
LLM summarization and undersells what observations actually are: deduplicated
beliefs grounded in specific source memories (with quotes), refined — not
overwritten — when new evidence arrives, and carrying a computed freshness
trend (stable / strengthening / weakening / stale).
@nicoloboschi nicoloboschi merged commit 6a80ecb into main Apr 14, 2026
46 checks passed
@nicoloboschi nicoloboschi deleted the docs-observations-reframing branch April 14, 2026 10:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant