Foresight

Copy Markdown View Source

CI Hex pm License: MIT

Semantic memory for Elixir: retain what happened, recall what's relevant, reflect on what it means — in the BEAM, next to your application.

Foresight is an Elixir port of Hindsight, and it is measured against the original rather than described in relation to it: three matched-reader replicates put the two at statistical parity (reflect 0.800 vs 0.711, McNemar not significant in any replicate). Nothing in this repository should be read as claiming parity was exceeded. See Provenance below, and read READINESS.md before depending on this — it states what is measured, what is assumed, and which surface you should actually use.

Installation

def deps do
  [{:foresight, "~> 0.1", hex: :foresight_memory}]
end

The package is published as foresight_memory (the plain name is taken on hex by an unrelated package); the application and modules are Foresight. Foresight compiles and boots with no configuration; capabilities are opt-in with their dependencies.

Three surfaces

In recommended order:

  • In-BEAM library — take foresight as a dependency and call it directly. Foresight.Supervisor is the embeddable supervision entry point; errors arrive as Foresight.Error structs. Everything else is a wrapper over this.
  • REST — 67 routes under /v1/:tenant/banks/... covering banks, memories, recall, reflect, observations, mental models, operations, and import/export.
  • MCP — 11 tools over Hermes streamable-HTTP. Works; see READINESS.md for the two structural properties to understand before choosing it.

Optional dependencies (HTTP / ML / Repo / Oban) are declared in mix.exs with their runtime capabilities disabled by default in config/config.exs, so an embedding consumer pays only for what it enables. The two that are required at compile time (:plug, :llm_toolkit) are carried for you.

Documentation

The full documentation is written as a manual, not a file listing:

  • Overview — the three verbs (retain, recall, reflect) and what Foresight is honestly good at.
  • Getting started — running in about five minutes, including the config trap that catches most people.
  • Choosing a surface — library, REST, or MCP; this choice has real consequences.

Verifying

mix deps.get
mix ci

mix ci is the real gate: format check, compile --warnings-as-errors, three architectural fitness checks (namespace purity, tenancy boundary, isolation coverage), then the suite — 957 tests. Plain mix test runs the suite alone.

Provenance

The architecture this library carries — memory banks, fact-extracting retain, hybrid recall, agentic reflect, observations, mental models — originates with Hindsight, MIT-licensed work by Vectorize AI, Inc. (paper: arXiv:2512.12818).

Foresight holds itself accountable to the original in two ways: their copyright notice is preserved in the LICENSE third-party notice, and capability claims here are measured against their reference implementation rather than asserted. Where this repository later diverges from the ported architecture, the divergence is documented where it is introduced.

Development

Local qualification workflows — the full-ML authority, contract fixture recording against a Hindsight reference, and the heavier test lanes — live in DEVELOPMENT.md.