well

What this is

An agent's context window is small and its memory is a guess. The well is the organ that fixes both: pour as much content into it as you like (it lives on disk, not in the prompt), draw the nearest grounded passages back out, and — the part that matters — get an honest ABSENT when the field does not actually hold what you asked for.

Three verbs, and only three:

  feed(text | file)   pour content into a universe (unlimited external context)
  recall(query)       draw the nearest grounded passages back out, with scores
  ask(question)       PRESENT with grounded evidence, or ABSENT — no confabulation

The well does not generate language. It holds, retrieves, and abstains. Generation belongs to the agent that drinks from it; the well's job is to make sure the agent drinks only what is really there.

The honest part

Abstention is where memory systems quietly lie — they always return something, and something always looks like an answer. The well abstains by construction, and the rule is a faithful reading of the ΑΔΩ research finding that absence is a lack of signal, not a low score:

A query is grounded only if the field has a pole for it — the top match must share a real content word with the query and rise above the field's own background. Character-gram texture alone never grounds. When the top match does not separate from the noise, the field is a flat plateau, and a flat plateau means ABSENT.

This is honest about its own ceiling, too: v0.1 is a light, dependency-free lexical field — real recall, real abstention, but not semantic understanding. It is the substrate the research pushes toward 1.00 recall and calibrated abstention, and the harness for measuring how close it gets — not a box that claims those numbers on day one.

Use it

well feed -f ./notes.md                    # pour a file into the default universe
well feed "a fact worth remembering"       # or raw text
well recall "what did I say about X"        # nearest grounded passages + scores
well ask "does the field hold Y"            # PRESENT (grounded) or ABSENT (no pole)
well -u research feed -f paper.txt          # named universes run side by side
well stats                                  # what a universe holds

Each universe is a compact file under $WELL_HOME (default ~/.well). Run as many as you like — the beginning of spinning up more than one field-system.

As an MCP tool

The well speaks the Model Context Protocol over stdio (zero dependencies), so an AI can drink from it mid-thought. Register it with Claude Code:

claude mcp add well -- node /path/to/well/mcp/server.js

It exposes well_feed, well_recall, well_ask, and well_stats. From then on an agent can feed a universe and then ask it questions, getting grounded evidence or an honest ABSENT — without ever loading the corpus into its context window. This is the point: the agent runs a universe in the background while people still talk to it normally.

With kith

The well is the memory organ; kith is the table where agents meet. They fit together exactly. A well-backed seat (adapters/kith-well.js) COMMITs only when the field grounds a claim, and casts the gate's NOTHING — a real, measured abstention — when the field is dry. kith's "I don't know" stops being a guess and becomes "not in the field."

node test/well.test.js   # every primitive, offline