What's new in Hindsight 1.2.1

Knowledge Pages are now Pages, switch embedding models without downtime, separate query and passage embedders, custom LLM providers, a reranker fallback for decision-model recall, and a round of reliability and speed fixes

Hindsight 1.2.1 renames Knowledge Pages to Pages — nothing breaks, the old names keep working until 2.x. It also lets you switch embedding models while servers keep running, use different embedders for queries and stored text, plug in your own LLM class, and fall back to the reranker when the decision model fails a recall. It is also a big speed release for large banks — entity search, staleness checks, consolidation and keyword recall get up to 50× faster — plus a long round of reliability fixes. Everyone on 1.2.0 should upgrade — see the changelog for the full list.

- [**Knowledge Pages are now Pages**](#knowledge-pages-are-now-pages) : New name everywhere; old routes, tools and settings keep working.
- [**Re-embed without downtime**](#re-embed-without-downtime) : Move a schema to a new embedding model while servers keep serving.
- [**Separate query and passage embedders**](#separate-query-and-passage-embedders) : A small model for searches, a bigger one for stored text.
- [**Custom LLM providers**](#custom-llm-providers) : Name your own class wherever a provider goes.
- [**Reranker fallback for decision-model recall**](#reranker-fallback-for-decision-model-recall) : A recall still answers when the decision model fails.
- [**Faster on large banks**](#faster-on-large-banks) : Entity search, staleness checks, consolidation and recall.
- [**Smaller additions**](#smaller-additions) : Tag edits on documents, rotated database credentials, more stats, Windows CLI.
- [**Reliability**](#reliability) : Retain, refresh, banks, transfer and the worker.

Knowledge Pages are now Pages #

The feature is now called Pages everywhere you see it: the API, the SDKs, the CLI, the MCP tools and the control plane. We're freeing the word "knowledge" for Knowledge Banks, which are coming soon.

Nothing breaks. Every old name keeps working as a deprecated alias until Hindsight 2.x, and there is no database change. Move to the new names when it suits you:

| Before | Now |

|---|---|
| `/v1/default/banks/{bank_id}/knowledge-base/...` | `/v1/default/banks/{bank_id}/pages/...` | 

| hindsight knowledge-base ... | hindsight pages ... | | MCP get_knowledge_page ,search_knowledge_base , ... | get_page ,search_pages , ... | | HINDSIGHT_API_KNOWLEDGE_PAGE_DEFAULT_TRIGGER / bank keyknowledge_page_default_trigger | HINDSIGHT_API_PAGE_DEFAULT_TRIGGER /page_default_trigger | | mental-model list exclude_knowledge_pages | exclude_pages |

Old MCP tool names in an mcp_enabled_tools allow-list still enable the new tools, but agents now only see the new names. If you list Hindsight tools in an OpenClaw tools.allow / tools.deny, rename them there: the plugin warns at startup about each old name it finds.

Re-embed without downtime #

A server won't start on an embedding model with a different dimension once memories are stored. Now you can switch in place: set the new HINDSIGHT_API_EMBEDDINGS_* variables where you run the command, then run hindsight-admin reembed --all-schemas (or --schema <name>). Servers keep serving reads and writes while it re-embeds; once every server runs the new model, --finish lifts the last write guard. See the admin CLI for the full procedure.

Separate query and passage embedders #

Recall queries and stored text can now use different embedding settings. Any HINDSIGHT_API_QUERY_EMBEDDINGS_<X> or HINDSIGHT_API_PASSAGE_EMBEDDINGS_<X> variable replaces HINDSIGHT_API_EMBEDDINGS_<X> for that side only — for example a fast local model for searches and a remote one for stored text.

Custom LLM providers #

For a backend no built-in provider speaks, set the provider to your own class by import path: HINDSIGHT_API_LLM_PROVIDER=mypackage.llm:MyLLM. It works in the global and per-operation settings and in a failover chain. Your class can also opt into batch requests.

Reranker fallback for decision-model recall #

Set HINDSIGHT_API_RECALL_DECISION_MODEL_FALLBACK=true and a recall the decision model fails or refuses is ranked by your configured reranker instead of failing. It's off by default.

Faster on large banks #

Most of the speed work targets banks with hundreds of thousands of memories, where some queries scanned far more rows than they needed.

Also:

• Postgres JIT is off on every pool connection. On big banks Postgres was compiling recall's observation lookup on every call; it now runs as a plain query (210 ms → 50 ms in the reporter's shape).
• Same-bank writers no longer queue behind each other on graph-maintenance locks. A writer that waited 3 s for another retain to commit now doesn't wait.
• Deleting a Pages folder no longer re-scans the bank for every page in it.

Smaller additions #

• Document tags :PATCH a document withadd_tags /remove_tags to change only the tags you name, without sending the full set.
• Rotated database credentials :HINDSIGHT_API_DATABASE_CONNECT_HOOK points at your own connect function, so new pool connections pick up fresh credentials.
• Extensions can review extracted memories and consolidation writes before they're stored, and refuse a refreshed mental-model page.
• Stats count mental models whose automatic refresh is d, andtotal_links now counts every entity link.
• Control plane : per-bank toggles for recall prune and dedup.
• CLI : a native Windows x64 binary ships with each release.

Reliability #

• Temporary failures and LLM-slot waits no longer a mental model's automatic refresh.
• Two concurrent retains of the same content store each fact once; batch extraction rejects duplicate custom ids.
• A deleted bank's running jobs no longer recreate it; a recreated bank no longer shows the old bank's stats.
• Clone, transfer import and rename can no longer take over an existing alias; two restores racing into the same new bank refuse instead of merging.
• On shutdown the worker stops claiming work at once and drains within the grace period.
• Retain skips the LLM pass when the embeddings backend is known to be down.
• Temporal recall works with dateparser 1.5.0.
• A large document update saves in batches, so an interrupted one keeps its progress.
• A tool call's reply is checked against the function it called and corrected once; reflect tool turns and vision retain never send two user turns in a row, which some providers reject.
• Images and files uploaded with a retain that then failed are deleted by a daily sweep instead of being kept forever (HINDSIGHT_API_ATTACHMENT_SWEEP_INTERVAL_SECONDS ,0 turns it off).
• Decision-model recall with the hindsight provider sends the whole candidate pool in one request instead of splitting it, so it makes fewer calls.
• A store-owned bank with store_document_text off no longer keeps chunk text.
• Whole-bank export and import archives stay under the bank's storage prefix.
• Tags derived from labels stay on memories after their label group leaves the config.
• An append chunks its text the same way the next append re-chunks it.
• Consolidation re-asks once when a reply misses the schema, keeps only the newest three earlier-state notes per observation, and a mental-model update can leave a page unchanged for off-topic facts.
• OpenAI Responses replies: only the final answer is read; optional tool arguments use a schema every provider accepts.
• Startup migrates the base schema even when a tenant extension doesn't list it.
• Pages search snippets no longer return 500 on SQL_ASCII databases; on Oracle, a link to a memory deleted mid-retain no longer fails the batch.
• Local models return freed memory to the OS on Windows too.
• MCP multi-bank tools send each result once, not twice.
• total_links in bank stats counts every entity link again, and mental-model read and refresh sizes are reported in tokens.

Database migrations: three migrations run on startup. One adds indexes on Oracle that touch large tables (chunks, memory_units), so allow extra time on big Oracle deployments.