# Foresight v0.3.1 - Table of Contents

> Semantic memory for Elixir — retain, recall, reflect. An Elixir port of Vectorize's Hindsight (MIT), measured at statistical parity.

## Pages

- [Foresight](readme.md)

- Introduction
  - [Foresight](overview.md)
  - [Getting started](getting-started.md)
  - [Choosing a surface](choosing-a-surface.md)

- How it works
  - [How recall works](how-recall-works.md)
  - [Reflect](reflect.md)

- Operating
  - [Multi-tenancy](multi-tenancy.md)
  - [Mode C least-privilege runbook](mode-c-least-privilege.md)
  - [Evaluation](evaluation.md)

- Readiness
  - [Foresight readiness](readiness.md)
  - [Changelog](changelog.md)

## Modules

- [Foresight.Embedders.Remote](Foresight.Embedders.Remote.md): OpenAI-compatible remote embedder: POSTs to `<base_url>/embeddings` (LM Studio,
vLLM, Ollama's OpenAI shim, or a cloud provider). Mirrors the LLM local↔cloud
fork (Foresight.LLMs.LlmCore) for embeddings, so a single endpoint can serve
both the reader and the embedder in dev, and a cloud provider can serve both in
production — closing the "embeddings are local-only" gap.
- [Foresight.Entities.Resolution](Foresight.Entities.Resolution.md): Entity resolution scoring — decide whether an incoming
entity mention resolves to an existing bank entity or creates a new one.
- [Foresight.EntityExtractor](Foresight.EntityExtractor.md): Seam for deriving entity names from raw content.
- [Foresight.EntityExtractors.LLM](Foresight.EntityExtractors.LLM.md): LLM-backed fallback entity extractor.
- [Foresight.Evals.Dataset](Foresight.Evals.Dataset.md): The dataset-adapter seam for the honest evaluation harness.
- [Foresight.Evals.DegradationWatch](Foresight.Evals.DegradationWatch.md): Counts the ways a retain pipeline silently degrades, so an eval can refuse to score a
run that was not actually measuring what it claims.
- [Foresight.Evals.HindsightBench](Foresight.Evals.HindsightBench.md): The Hindsight arm of the matched-reader Foresight-vs-Hindsight scoreboard.
- [Foresight.Evals.Labeling.CandidatePool](Foresight.Evals.Labeling.CandidatePool.md): Relevance-labeling pipeline, candidate-pool step: pool the pre-fusion recall arms into the deduped candidate set
to be labeled for a query.
- [Foresight.Evals.Labeling.FusionTuner](Foresight.Evals.Labeling.FusionTuner.md): Offline coordinate ascent over per-arm fusion weights, scored as mean
nDCG@k against graded relevance labels.
- [Foresight.Evals.Labeling.GoldIngest](Foresight.Evals.Labeling.GoldIngest.md): Relevance-labeling pipeline, gold-ingest step: parse a human-filled gold artifact (see
`Foresight.Evals.Labeling.GoldSet.to_artifact/2`) into validated, human-sourced label
attrs ready for `Foresight.Schemas.LabeledPair.changeset/2`.
- [Foresight.Evals.Labeling.GoldSet](Foresight.Evals.Labeling.GoldSet.md): Relevance-labeling pipeline, gold-set step: build the human-graded gold set from per-query candidate pools
and serialize it to a gradeable artifact.
- [Foresight.Evals.Labeling.Judge](Foresight.Evals.Labeling.Judge.md): Relevance-labeling pipeline, judge step: LLM graded-relevance judge. For each (query, candidate) pair it
asks a `complete_json_schema/4`-capable LLM (default: z.ai GLM-5.2) for a 0..3 relevance
grade, and emits `source: :llm` label attrs recording the judge model.
- [Foresight.Evals.Labeling.Kappa](Foresight.Evals.Labeling.Kappa.md): Cohen's kappa between human and llm calibration grades — the trust gate on
the bulk judge. If the judge doesn't agree well enough with the human gold slice, its
labels can't be trusted to train fusion weights against (optimizing to a machine's
biases is the same metric-gaming trap the ranking metrics were built to avoid), so the pipeline gates the full labeling run on this number.
- [Foresight.Evals.Labeling.LabelStore](Foresight.Evals.Labeling.LabelStore.md): Persist label attrs (from `GoldIngest` or the judge labeler) into
labeled_pairs, idempotently. A re-run upserts on the natural key
`(bank_id, query_ref, memory_ref, source)` rather than duplicating, so a labeling pass can be
safely resumed or corrected. Invalid rows are collected, not fatal — the batch reports
what it wrote and what it rejected.

- [Foresight.Evals.Labeling.Pipeline](Foresight.Evals.Labeling.Pipeline.md): Pure orchestration helpers for the relevance-labeling pipeline.
- [Foresight.Evals.Labeling.PoolFusion](Foresight.Evals.Labeling.PoolFusion.md): Re-rank a recorded candidate pool under a trial fusion configuration, offline.
- [Foresight.Evals.LongMemEval](Foresight.Evals.LongMemEval.md): Adapter for LongMemEval (ICLR 2025), an MIT-licensed benchmark for long-term agent
memory. It maps almost one-to-one onto Foresight's differentiators: temporal reasoning,
knowledge updates (supersession), multi-session reasoning, and abstention.
- [Foresight.Evals.ProfessionalLane](Foresight.Evals.ProfessionalLane.md): Loader for the sanitized professional knowledge-work evaluation lane.
- [Foresight.Evals.RankingMetrics](Foresight.Evals.RankingMetrics.md): Pure, deterministic retrieval-quality metrics — the gaming-resistant core of the
retrieval eval.
- [Foresight.Evals.RecallQuality](Foresight.Evals.RecallQuality.md): QUARANTINED. This is the legacy phrase-matching grader. It scores answers by
checking for the presence of specific corpus phrases, which is exactly the signal the
production ranking code was once gamed to satisfy — so its numbers measure phrase echo,
not retrieval quality, and MUST NOT be cited as a quality metric.
- [Foresight.Evals.Runner](Foresight.Evals.Runner.md): Dataset-agnostic eval runner. Given normalised `Dataset.Instance`s and a `recall_fun`, it
scores each query with the gaming-resistant ranking metrics and aggregates overall and per
`question_type`.
- [Foresight.Evals.Stats](Foresight.Evals.Stats.md): Statistics for the answer/reflect-judge eval lane.
- [Foresight.Fitness.CorpusPurity](Foresight.Fitness.CorpusPurity.md): Fitness check: recall/reflect logic must not hardcode eval-corpus or project literals.
- [Foresight.Fitness.ObanQueues](Foresight.Fitness.ObanQueues.md): Fitness check: every `Oban.Worker`'s declared queue must exist in the resolved
Oban configuration.
- [Foresight.HTTP.RequestContext.DefaultResolver](Foresight.HTTP.RequestContext.DefaultResolver.md): Resolves a request into a tenancy `Context`, and is the authorization authority.
- [Foresight.LLMs.StructuredRecovery](Foresight.LLMs.StructuredRecovery.md): Recover structured JSON from local-LLM output that strict schema parsing
rejected.
- [Foresight.ML.EntailmentServing](Foresight.ML.EntailmentServing.md): Nx.Serving for the NLI entailment verifier: a `Bumblebee.Text.text_classification`
serving over a dedicated MNLI cross-encoder. Input is `{premise, hypothesis}` string pairs
(evidence, clause); output is per-label softmax scores, from which
`EntailmentVerifiers.Bumblebee` reads the entailment probability.
- [Foresight.Prompts.Consolidation.V1](Foresight.Prompts.Consolidation.V1.md): Faithful Elixir port of Hindsight's `engine/consolidation/prompts.py`
(`build_batch_consolidation_prompt`): the LLM merge contract that turns raw
facts into consolidated observations via `creates`/`updates`/`deletes`.
- [Foresight.Prompts.Reflect.Agent.V1](Foresight.Prompts.Reflect.Agent.V1.md): System prompt for the agentic (tool-calling) reflect loop. Faithful port
of Hindsight's `engine/reflect/prompts.py` `build_system_prompt_for_tools`.
- [Foresight.Prompts.Reflect.Tools](Foresight.Prompts.Reflect.Tools.md): Reflect agent tool definitions — the provider-neutral `LlmToolkit.Tool`
set the agentic reflect loop exposes to the LLM. Faithful port of Hindsight's
`engine/reflect/tools_schema.py` (`get_reflect_tools`).
- [Foresight.Prompts.Retain.V1](Foresight.Prompts.Retain.V1.md): Retain-time atomic fact extraction prompt.
- [Foresight.Recall.FusionConfig](Foresight.Recall.FusionConfig.md): Resolves the option list handed to `Foresight.Recall.RRF.fuse/2`.
- [Foresight.Recall.QueryAnalyzer](Foresight.Recall.QueryAnalyzer.md): Extracts a temporal constraint (a `%{from: DateTime, to: DateTime}` day/period range)
from a natural-language query.
- [Foresight.Recall.RRF](Foresight.Recall.RRF.md): Rank/score fusion across recall arms. Three modes, selected by
`:fusion`
- [Foresight.Recall.RerankWindow](Foresight.Recall.RerankWindow.md): Sizes the rerank prefilter shortlist — how many fused candidates are handed to the
(expensive) cross-encoder before the final selection.
- [Foresight.Recall.SemanticFloor](Foresight.Recall.SemanticFloor.md): Resolves the cosine-similarity floor the semantic arm applies before it hands
candidates to fusion. A unit scoring below the floor against the query embedding
is never a semantic candidate, whatever the recall budget.
- [Foresight.Reflect.CitationSelection](Foresight.Reflect.CitationSelection.md): Filter the LLM's declared citations (from the terminal `done` tool's args) down
to those that were actually retrieved during the reflect loop.
- [Foresight.Reflect.Disposition](Foresight.Reflect.Disposition.md): Render a bank's disposition traits into behavioural prose for the reflect prompt.
Faithful port of Hindsight's `engine/search/think_utils.py`
`build_disposition_description` + `describe_trait_level`, activating the stored
`disposition_skepticism` / `disposition_literalism` / `disposition_empathy` fields that
were otherwise inert.
- [Foresight.Reflect.EntailmentGate](Foresight.Reflect.EntailmentGate.md): Backend-agnostic grounding (entailment) gate for reflect answers. Splits a reflect answer into
clauses, asks the configured `EntailmentVerifier` whether the cited-memory text
entails each, and applies the pass/fail policy — returning the unsupported clauses so
the agentic loop can re-enter targeting exactly what wasn't grounded.
- [Foresight.Reflect.EntailmentVerifier](Foresight.Reflect.EntailmentVerifier.md): Seam for the reflect grounding/entailment gate: given the clauses of a reflect answer and
the text of its cited memories (evidence), return a per-clause verdict on whether the
evidence entails the clause.
- [Foresight.Reflect.EntailmentVerifiers.Bumblebee](Foresight.Reflect.EntailmentVerifiers.Bumblebee.md): NLI entailment verifier. Scores each (evidence, clause) pair with a
dedicated MNLI cross-encoder — a calibrated, independent entailment signal, the
strongest of the three verifier backends, for hosts with the ML headroom (e.g. DGX).
- [Foresight.Reflect.EntailmentVerifiers.LLMJudge](Foresight.Reflect.EntailmentVerifiers.LLMJudge.md): LLM-judge entailment verifier. One structured call over the existing LLM
routing decides, for each answer clause, whether the cited-memory text supports it — no
new model or serving. Reuses the `complete_json_schema/4` seam.
- [Foresight.Reflect.EntailmentVerifiers.Noop](Foresight.Reflect.EntailmentVerifiers.Noop.md): Default entailment verifier: verification OFF. Every clause is reported supported, so
the grounding gate is inert until a real verifier is configured — no new cost, latency, or
change to the honest baseline unless explicitly opted in.

- [Foresight.Reflect.Expand](Foresight.Reflect.Expand.md): The agentic reflect `expand` tool: drill previously retrieved memories up the
hierarchy. `"chunk"` (the default) returns each memory with its provenance and
the neighbouring memories of the same document, the surrounding context a
truncated fact is missing; `"document"` returns the owning document's title and
text. The id list is model-controlled, so it is de-duplicated, filtered to valid
ids and capped before any query runs. `cited_ids/1` lists every memory id an
expansion put in front of the model, for grounding.

- [Foresight.Reflect.LoopOptions](Foresight.Reflect.LoopOptions.md): Guards the options reflect hands to `LlmCore.Agent.Loop`.
- [Foresight.Reflect.MentalModelRanking](Foresight.Reflect.MentalModelRanking.md): Lexical relevance ranking + limit for the reflect `search_mental_models` tool
.
- [Foresight.Reflect.MentalModels](Foresight.Reflect.MentalModels.md): Mental models for reflect, at parity with Hindsight: ranked by embedding
similarity to the query, capped, and reported with a per-model staleness verdict.
- [Foresight.Rerankers.Passage](Foresight.Rerankers.Passage.md): Builds the text a cross-encoder reranker scores for a candidate.
- [Foresight.Retain.FactExtraction](Foresight.Retain.FactExtraction.md): Retain-time atomic fact extraction — the keystone that gives reflect
something structured to aggregate over.
- [Foresight.Schemas.LabeledPair](Foresight.Schemas.LabeledPair.md): Graded relevance label for a (query, candidate memory) pair — the
training/eval substrate for learned per-bank fusion weights.
- [Foresight.Schemas.MemoryLink](Foresight.Schemas.MemoryLink.md): A directed edge in the memory graph: `from_unit_id -> to_unit_id`
with a `link_type` and `weight`, scoped to a bank.
- [Foresight.Schemas.MemoryUnit](Foresight.Schemas.MemoryUnit.md): The stored unit of memory: a fact, item, or observation belonging to a bank.
- [Foresight.Storage.Consolidation](Foresight.Storage.Consolidation.md): Consolidation orchestration. Phase A (pool existing observations, run the LLM
merge, embed results) runs OUTSIDE the DB transaction; Phase B applies the
prepared writes, stamps sources, and refreshes mental models INSIDE one
transaction. This keeps slow LLM/embedding IO off the tenant DB connection
(the reflect txn-across-LLM pool-timeout class of bug).
- [Foresight.Storage.ConsolidationPersistence](Foresight.Storage.ConsolidationPersistence.md): Consolidation persistence: an Elixir port of Hindsight's
`engine/consolidation/consolidator.py`. Turns raw `world`/`experience` facts
into consolidated `observation` memory units via an LLM `creates`/`updates`/
`deletes` merge contract (`Foresight.Prompts.Consolidation.V1`).
- [Foresight.Storage.LinkConstruction](Foresight.Storage.LinkConstruction.md): Retain-time construction of the `memory_links` graph.
- [Foresight.Text.Sanitize](Foresight.Text.Sanitize.md): Scrubs model output of characters that break downstream systems.
- [Foresight.Text.SequenceMatcher](Foresight.Text.SequenceMatcher.md): Faithful port of Python `difflib.SequenceMatcher(None, a, b).ratio()` — the
Ratcliff-Obershelp similarity Hindsight uses for entity name matching
(`engine/entity_resolver.py:664`).
- [Foresight.Usage](Foresight.Usage.md): Ledger of the chargeable calls made while serving one operation.

- Public API
  - [Foresight](Foresight.md): Semantic memory: retain what happened, recall what is relevant, reflect to answer.
  - [Foresight.Context](Foresight.Context.md): Execution context for the public API.
  - [Foresight.Error](Foresight.Error.md): The error currency of the library.
  - [Foresight.Migrations](Foresight.Migrations.md): Installs Foresight's shared control-plane schema into a consumer database.
  - [Foresight.Migrations.Manifest](Foresight.Migrations.Manifest.md): Classifies every migration shipped with Foresight.
  - [Foresight.Supervisor](Foresight.Supervisor.md): The embeddable supervision entry point.
  - [Foresight.Tenancy](Foresight.Tenancy.md): Public tenant-schema provisioning and execution boundaries.

- Behaviours
  - [Foresight.Backend](Foresight.Backend.md): Dispatch surface for storage backends.
  - [Foresight.LLM](Foresight.LLM.md): Seam behaviour for LLM completion.

## Mix Tasks

- [mix foresight.evals.fetch](Mix.Tasks.Foresight.Evals.Fetch.md): Fetch an evaluation dataset split on demand. Nothing is redistributed in the repo — the
data lands in `priv/evals/data/`, which is gitignored.
- [mix foresight.isolation_coverage](Mix.Tasks.Foresight.IsolationCoverage.md)
- [mix foresight.labeling.generate](Mix.Tasks.Foresight.Labeling.Generate.md)
- [mix foresight.labeling.ingest](Mix.Tasks.Foresight.Labeling.Ingest.md)
- [mix foresight.labeling.judge](Mix.Tasks.Foresight.Labeling.Judge.md)
- [mix foresight.labeling.kappa](Mix.Tasks.Foresight.Labeling.Kappa.md)
- [mix foresight.labeling.repair_reasons](Mix.Tasks.Foresight.Labeling.RepairReasons.md)
- [mix foresight.namespace_purity](Mix.Tasks.Foresight.NamespacePurity.md)
- [mix foresight.record_floor_fixtures](Mix.Tasks.Foresight.RecordFloorFixtures.md): Records the FLOOR fixture set from a live hindsight v0.7.1 authority.
- [mix foresight.tenancy_boundary](Mix.Tasks.Foresight.TenancyBoundary.md)

