Reflect-only long-term memory for coding agents in OpenCode, with a git+chat
backfill and (opt-in) live session write-back.
- reflect + INJECT: on a task, reflect() the symptom and push the root-cause
answer into the system prompt (no tools/recall).
- backfill: every commit (full message + full diff, commit timestamp + git
metadata) under a 'git' retain strategy; each chat as a JSON user/assistant
transcript with custom extraction (<=2 coherent facts) under a 'chat' strategy;
observations on; optional codebase knowledge pages.
- live write-back (opt-in HINDSIGHT_RETAIN_SESSIONS): every N turns upsert the
tool-filtered transcript under a stable conversation:<sessionID> document_id.
Client-created pages had no server curation applying a trigger, so they fell back
to the plain mental-model default (no refresh, full mode, all fact types). Make a
knowledge page a living document by default: when the client omits `trigger`, use
observation-only + delta + exclude_mental_models + refresh_after_consolidation;
when it omits `max_tokens`, default to 4096 (vs the mental-model 2048). Clients
can still override either.
The knowledge base is now purely client-managed (CRUD over folders/pages); the
server no longer auto-curates. Removes the folder curator entirely and the
folder `mission` concept, and leads the sidebar with Knowledge Base.
- Remove engine/knowledge_curator.py, the curate_folder task (handler + dispatch
+ submit_async_curate_folder / _bank_folders), the post-consolidation curation
hook, and the folder-create / mission-update curation triggers.
- Remove folder `mission` and `last_curated_at` (columns + engine + API + UI);
keep `managed` as a client-set flag. Migration a5b6 now adds `managed` only;
the last_curated_at migration is dropped and the unique-index migration
repointed. Single alembic head preserved.
- API: KnowledgeNode/CreateFolderRequest/UpdateNodeRequest lose `mission`;
PATCH node handles name/parent_id only.
- Control plane: sidebar leads with Knowledge Base (before Memories); remove the
mission field, edit-mission dialog, and mission display from the KB view.
- Delete the curator tests; regenerate OpenAPI + SDK clients.
Re-point hindsight-fs at the knowledge base so it projects a bank's folder/page
hierarchy as nested directories + .md files, instead of a flat list of mental
models.
- client: fetch GET /knowledge-base/tree + /export (two calls, any bank size)
and join by page id; replaces the paginated mental-models list.
- format: planMirror() walks the tree into folder dirs + page files at nested
paths (slug per segment, collision-safe); pages render the page's OKF doc.
- sync: create folder dirs, write pages at nested paths, prune removed pages and
emptied folders; state keyed by relative path + tracked dirs.
- config/cli: drop the mental-model `detail` flag; `list` prints folders+pages;
help/README updated. Tests rewritten for the tree/export model.
Verified live against a bank's knowledge base: the `people` folder mirrors to
people/anna.md + people/marco.md with OKF frontmatter.
Add @vectorize-io/hindsight-fs, a CLI under hindsight-tools/ that mirrors a
Hindsight bank's mental models as real markdown files (YAML frontmatter + body)
in a local directory, refreshed from the API on an interval. Once mounted,
ordinary shell tools (ls, cat, grep, find, ...) work against current memory.
- Pull-based sync engine: full list each tick, write changed/new/tampered
files, skip unchanged (content-hashed), prune deleted models. Atomic writes;
a transient API error never wipes the mirror.
- One-way mirror enforced two ways: files are read-only (0444) so agent edits
fail with EACCES, plus a tamper-revert backstop that compares on-disk bytes
and overwrites drift on the next pass. --writable opts out.
- Commands: mount/start/stop/restart/sync/status/list/logs/unmount. Background
daemon via detached process + pidfile; per-mount config is remembered.
- status doubles as a healthcheck: --json report and a non-zero exit when the
mount is dead/failed/stale (--stale-after overrides the threshold).
- Tests: unit (sync engine, frontmatter, health) + e2e that spawns the real
CLI against a mock API and exercises real bash commands. 26 tests.
Server-side knowledge base: a hierarchy of folders and pages over mental
models, projected to the Open Knowledge Format, with a mission-driven curator
that maintains pages automatically after each consolidation.
- knowledge_pages table (PG + Oracle): parent_id tree, kind folder/page,
mission, managed, last_curated_at; partial unique index on (folder, name)
for concurrency-safe dedup; added to BACKUP_TABLES.
- api/okf.py: OKF serializer (frontmatter + body, index/log, constellation graph).
- engine/knowledge_curator.py: folder curator (LLM op plan + safe apply); reads
new memories since last curation (delta, not recall); ops create/merge/delete
page + spawn sub-folder (bounded depth<=3, <=8). Runs as an async curate_folder
task on folder/mission create and after consolidation. Curator pages use an
observation-only delta trigger with exclude_mental_models.
- MemoryEngine: folder/page CRUD, tree, curate, async submit + worker handler.
- /v1/default/banks/{bank}/knowledge-base/* endpoints.
- Control plane: knowledge-base tree view + constellation toggle, missions,
OKF page panel + bundle export; proxies, client, sidebar, i18n.
- Tests: okf unit, knowledge-base HTTP, curator apply + dedup guard, hs_llm_core e2e.
- Regenerated OpenAPI + SDK clients + docs-skill.
* feat(stats): distributed (table-backed) bank_stats cache on PostgreSQL
get_bank_stats aggregates over memory_links/unit_entities — a multi-second scan
on large banks. It was cached per-process (in-memory), so every API worker
recomputed once per TTL and the first caller after expiry stalled.
Add a bank_stats_cache table and a DistributedBankStatsCache that shares one
worker's computation across all workers. Same get_or_load/invalidate contract as
the in-memory cache, so the hot path is a single PK SELECT on a hit; only a miss
runs the existing _compute_bank_stats loader and UPSERTs the row (ON CONFLICT,
no lock — concurrent misses recompute, last write wins). All DB touches are
best-effort: an unreachable/missing cache table degrades to computing uncached
rather than failing the endpoint. PostgreSQL only; Oracle keeps the in-memory
cache (selected by dialect at construction).
* feat(stats): add ?refresh query param to force fresh /stats (default off)
Adds force_refresh to get_bank_stats (and both cache backends): when set, the
cached value is bypassed and recomputed, and the fresh result refreshes the
cache for subsequent callers. Exposed on GET /stats as ?refresh=true (default
false). Regenerated OpenAPI spec + clients.
* test(perf): add stats benchmark suite + huge prod-sim scale
New 'stats' perf suite measures get_bank_stats: uncached aggregation latency
(node/link counts + entity rollup) vs cached, run with the result cache disabled
so the headline numbers are the real per-poll cost. Adds a 'huge' prod-simulation
scale that bulk-loads ~500k units / ~17.8M physical memory_links via COPY (entity
links derived from unit_entities, not stored).
* test(stats): exclude bank_stats_cache from backup guard + HTTP refresh test
- bank_stats_cache is a derived TTL cache (no FK to banks, repopulates on
demand), so exclude it from test_backup_tables_covers_entire_schema rather
than back up stale cache rows — a restore starts it cold.
- Add a ?refresh=true assertion to the /stats HTTP integration test.
* fix(cli): pass refresh arg to get_agent_stats after ?refresh param
The new /stats ?refresh query param adds a positional arg to the progenitor-
generated get_agent_stats; the CLI reads the cached value, so pass None.
* test(consolidation): fix dedup merge-path tests missing text-search config
The dedup merge/update path builds a search_vector UPDATE clause from
config.text_search_extension (+ _native_language) since #2425, but the
_dedup_reconcile_create / _dedup_reconcile_update test configs only set
consolidation_dedup_threshold, so the two merge-path tests raised
AttributeError: 'types.SimpleNamespace' object has no attribute
'text_search_extension' on main.
Add the two fields (production defaults native/english) to those configs.
The clause reuses $1, so the existing positional-arg assertions are unchanged.
* test(fact-extraction): pass Vertex AI settings when building LLMConfig
Regression: LLMConfig was refactored to use vertexai_project_id/region/
service_account_key as-passed (the caller resolves the global-config fallback),
but the llm_config fixture never forwarded them. So with the CI provider set to
vertexai, LLMConfig raised "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID is required"
even though the env var was set — the test errored in the test-api job.
Forward the three Vertex settings from config (mirroring MemoryEngine's own
LLMConfig construction). Verified: LLMConfig(provider="vertexai", ...) now
constructs with project_id passed, and still raises when it is omitted.
* test(llm-provider): forward provider-specific settings in _make_llm
_make_llm() built an LLMProvider from the env-selected provider without
forwarding provider-specific settings, so the vertexai and litellmrouter
acceptance-matrix jobs failed at construction ("VERTEXAI_PROJECT_ID is required"
/ "litellmrouter requires a config object"). LLMProvider uses these as-passed
(it does not resolve them from global config), so forward
vertexai_project_id/region/service_account_key and litellmrouter_config.
* test(llm-trace): drop leaked span recorders after each test (#2229)
Root cause of the flaky test_llm_trace::test_disabled_writes_no_rows:
MemoryEngine.__init__ registers its LLM-trace recorder in a process-global
registry, and only close() removes it. Tests that construct an engine directly
(test_per_operation_llm_config, test_llm_reasoning_effort_env, etc.) never
close it, leaking an ENABLED recorder. Locally those recorders' writes fail
(uninitialized backend), but in CI a leaked recorder with a live backend
records a later test's LLM calls into the shared DB — so test_disabled_writes_
no_rows sees rows for its bank even though its own recorder is disabled
(assert N == 0). Reproduced: after test_per_operation_llm_config the registry
holds 8 enabled recorders.
Add an autouse fixture that snapshots the registry and removes anything a test
leaked. Verified: the registry drops from 8 leaked recorders back to 1.
_teardown_memory_engine already guards the fixtures; this guards direct
constructions. 53 trace + leak-risk tests pass together under -n2.
Hindsight already honors CODEX_HOME (openai-codex LLM + embeddings), but it
was only mentioned in the 0.8.3 changelog. Long-running services sharing
~/.codex/auth.json with another Codex process can get their refresh token
rotated out, leaving /reflect broken while /health stays green.
Add a 'Isolating Codex auth for long-running services' section to the Models
docs and a pointer next to the openai-codex snippet in configuration.
Refs #2476
Lazy reranker init was the only mode in which CrossEncoderReranker.ensure_initialized()
could double-load the model: its check-then-act over the `await` is a real race, but
in the default (eager) path init_cross_encoder() runs at startup — single-threaded,
before any request — so the per-request guard always short-circuits and the window
never opens (see PR #2445 discussion).
Rather than guard the lazy path with a lock, drop the flag entirely. The cross-encoder
is now always initialized eagerly at startup, which removes the race by construction and
the first-recall latency cliff. The only thing the flag bought was skipping an ~80MB
model load for retain-only deployments — not worth the extra config surface and the
concurrency footgun.
- Remove ENV_LAZY_RERANKER, the config field, and from_env() wiring
- Remove the lazy_reranker constructor param; always append init_cross_encoder()
- Drop the now-dead kwarg/env from tests; rename the ensure_initialized timeout tests
- Update docs + regenerate the docs skill mirror
ensure_initialized() is kept as a cheap idempotent guard on the recall path.
* fix(retain): honor configured LLM temperature in batch fact-extraction
#2469 de-hardcoded the streaming path but the batch _build_request_body still
sent temperature=0.1 unconditionally, so HINDSIGHT_API_LLM_TEMPERATURE=none was
ignored and Azure GPT-5.5 batch retain kept rejecting requests. Omit the field
when the configured retain temperature is None, mirroring LLMProvider.call.
* test(retain): cover batch _build_request_body temperature threading
* fix(llm): make per-operation temperature configurable (#2459)
Internal LLM calls used hardcoded temperatures (verification 0.0, fact
extraction 0.1, reflect thinking 0.9, consolidation 0.0, bank mission 0.3).
Models like Azure gpt-5.5 reject any explicit temperature other than their
default, breaking retain/reflect/verification.
Expose each as an env knob with a global override:
- HINDSIGHT_API_LLM_TEMPERATURE (global) + _VERIFICATION/_RETAIN/_REFLECT/
_CONSOLIDATION/_MISSION (per-operation override).
- Resolution: per-operation env -> global env -> historical default.
- A value of none/default/off/empty omits the temperature parameter entirely,
so HINDSIGHT_API_LLM_TEMPERATURE=none fixes gpt-5.5 in one variable.
call() already drops temperature=None across providers, so the None config
value naturally omits the param. Defaults preserve prior behavior exactly
(fully backwards compatible). Server-level/static config.
* test(llm): verify per-operation temperature reaches the LLM call
MockLLM now records the temperature it receives, and a new pipeline test
drives the real engine: retain forwards 0.1 to fact extraction, the reflect
thinking path forwards 0.9, and HINDSIGHT_API_LLM_TEMPERATURE=none omits the
parameter (None) on a live call.
* test(llm): set llm_temperature_retain on the fact-extraction retry mock config
The retry tests build a MagicMock(spec=HindsightConfig); dataclass
annotation-only fields aren't in the spec, so the new llm_temperature_retain
field (now read at the extraction call site) must be set explicitly.
The per-operation LLM request settings were resolved into HindsightConfig but
never reached the provider that uses them, so configuring them was a silent
no-op:
- *_llm_timeout (retain/reflect/consolidation) and the global llm_timeout never
reached the provider impl; it fell back to HINDSIGHT_API_LLM_TIMEOUT/120s, so
HINDSIGHT_API_RETAIN_LLM_TIMEOUT=300 did nothing ("LiteLLM call exceeded
timeout=120.0s").
- reflect_llm_max_retries/initial_backoff/max_backoff and
consolidation_llm_initial_backoff/max_backoff were never consumed; reflect and
consolidation used the hardcoded call()/call_with_tools() defaults (10/5),
ignoring the documented "falls back to llm_max_retries" contract.
Fix: resolve each operation's effective request defaults (per-op override else
global) in MemoryEngine and carry them on the LLMProvider:
- timeout is threaded config -> LLMProvider -> create_llm_provider -> provider
impl for the providers that honour a configurable request timeout (LiteLLM,
LiteLLM Router, OpenAI-compatible, Nous). None preserves each provider's own
default, so Anthropic/Gemini keep their bespoke timeouts and the no-config
path is byte-identical.
- max_retries/initial_backoff/max_backoff become LLMProvider instance defaults
that call()/call_with_tools() use when the per-call arg is omitted. Explicit
per-call args (retain's resolved values, reflect's fast structured-extraction
path) still win; providers built without config (from_env, tests) keep the
10/5 method fallback.
The four operation scopes (default/retain/reflect/consolidation) and multi-LLM
chain members all share their operation's resolved values via a small
_LLMCallDefaults bundle.
max_concurrent is intentionally left as-is (process-global semaphores read from
env at startup, server-level only); the docs are clarified to call out that
distinction.
Also fixes a pre-existing breakage in test_llm_router_provider's __new__-based
helper (missing _default_headers after #2466) so the suite is green.
Tests: tests/test_llm_timeout_propagation.py covers provider-impl timeout
threading, the call() retry-policy fallback/override, and per-op
resolution/fallback in MemoryEngine.
* fix: skip synthetic tool_result user messages in sliceLastTurnsByUserBoundary
OpenClaw normalizes tool_result blocks into role:"user" messages with a
tool_result content block. The sliceLastTurnsByUserBoundary function used
to count every role:"user" message as a turn boundary, causing synthetic
tool_result messages to fill the retention window and exclude actual user
input from retained transcripts.
This change adds a hasRealTextContent guard that skips user messages
containing only tool_result blocks, ensuring only genuine user text is
counted as turn boundaries for both retain and recall window slicing.
Fixes: retained transcripts missing user input when tool calls are present
* fix: skip synthetic tool_result user messages in sliceLastTurnsByUserBoundary
* fix: skip synthetic tool_result user messages in sliceLastTurnsByUserBoundary
* style(openclaw): prettier-format hasRealTextContent block
---------
Co-authored-by: Kumaxs <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(cursor-cli): parse Cursor 3.x role-nested agent transcripts
Cursor CLI writes agent-transcripts/*.jsonl as
{role, message: {content: [blocks]}} without a top-level type field.
The retain hook's transcript reader only handled flat and type-nested
SDK envelopes, so real transcripts parsed to zero messages and retain
appeared to succeed while storing nothing.
Port the third parser branch from the Cursor editor integration and add
a regression test. Closes the gap flagged as "Should fix#4" during
review of #1975.
Co-authored-by: Cursor <[email protected]>
* feat(cursor-cli): gate text-mode tool markers behind includeTools (default off)
The shared transcript parser surfaced [tool_use]/[tool_result] markers in
the plain-text view, changing what lands in recall queries and light retain.
Gate those markers behind a new includeTools config flag (default off), so
the default light read keeps only natural-language text as before.
Also collapse the now-dead user/assistant event_type branches in the rich
reader (handled by _parse_transcript_entry) and drop the redundant
_extract_text_from_blocks helper, folding the three text/rich finalization
paths into a single _finalize_entry.
---------
Co-authored-by: mutex <[email protected]>
Co-authored-by: Cursor <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(openclaw): apply configured defaults to dynamic banks
Co-authored-by: Cursor <[email protected]>
* fix(openclaw): route knowledge tools through identity resolution for user-scoped banks
Knowledge tool factories now use resolveAndCacheIdentity before deriving bank IDs,
matching auto-recall/retain so PluginToolContext sessions hit the correct per-user
bank. Unresolved user identity returns a clear tool error instead of querying
anonymous/openclaw fallbacks, and bank defaults are applied before execution.
Co-authored-by: Cursor <[email protected]>
* fix(agent-sdk): stop mapping max_results to recall max_tokens
NemoClaw passed max_results=25 expecting a result-count cap, but the SDK
used it as max_tokens=25 and starved recall. max_tokens now defaults to
1024 from max_tokens only; max_results slices the results array (1-50).
Co-authored-by: Cursor <[email protected]>
* refactor(openclaw): drop dead alias exports + tighten entityLabels shape
- Remove unused @deprecated hasConfiguredMissions/applyConfiguredMissions
aliases (new exports nothing imports).
- normalizeEntityLabels now only accepts the server's shapes (a list, or a
{ attributes: [...] } object); a plain keyed object is dropped client-side
instead of being sent and silently ignored by parse_entity_labels.
- Update docs (types.ts, plugin.json, README) and tests to match.
* fix(agent-sdk): drop unsupported max_results from recall tool
The recall tool's max_results was previously aliased to the recall token
budget (a no-op for result count). Rather than make it a real cap, remove
it entirely — the tool accepts only max_tokens; use recallTopK for an
auto-recall count cap.
Also document the new per-user dynamic bank defaults (retainExtractionMode,
enableObservations, enableAutoConsolidation, dispositions, entityLabels) on
the docs-site OpenClaw page and fix its stale max_results guidance.
---------
Co-authored-by: DK09876 <[email protected]>
Co-authored-by: Cursor <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(config): add env var overrides for retain and recall options
Add missing environment variable overrides for configuration options
that were only settable via plugin options or config file:
- HINDSIGHT_RETAIN_EVERY_N_TURNS
- HINDSIGHT_RETAIN_OVERLAP_TURNS
- HINDSIGHT_RECALL_TAGS / HINDSIGHT_RETAIN_TAGS
- HINDSIGHT_RECALL_TAGS_MATCH
- HINDSIGHT_RECALL_PROMPT_PREAMBLE
- HINDSIGHT_RECALL_CONTEXT
* feat(config): add HINDSIGHT_BANK_ID_PREFIX env override
* fix(opencode): rename HINDSIGHT_RECALL_CONTEXT to HINDSIGHT_RETAIN_CONTEXT
The env var HINDSIGHT_RECALL_CONTEXT mapped to retainContext, which
breaks the naming convention where RECALL_* maps to recall* properties
and RETAIN_* maps to retain* properties.
* fix(llm): wire default_headers into LiteLLM-backed providers (#2458)
HINDSIGHT_API_LLM_DEFAULT_HEADERS is documented and parsed but only wired
into the Anthropic provider, so it silently no-ops for the litellm /
litellmrouter / bedrock providers -- the proxy-routing providers where
custom headers (auditing, policy, request-tracing) matter most. The
create_llm_provider docstring even noted "other providers may opt in as
needed"; this opts the LiteLLM-backed providers in.
Forward the configured headers to litellm.acompletion via the extra_headers
kwarg, mirroring the existing Anthropic default_headers wiring. setdefault
keeps any explicit per-call extra_headers authoritative, and the dict is
defensively copied on construction and per call to avoid cross-request
contamination. LiteLLMRouterLLM inherits this through its **kwargs forward
to the shared LiteLLM base.
Adds regression tests covering storage, the acompletion extra_headers path,
the no-headers omission, router forwarding, and copy-isolation.
Closes#2458
* fix(llm): forward default_headers from LiteLLM Router call path
The Router subclass overrides _build_common_kwargs without calling super(),
so stored default_headers never reached acompletion for the litellmrouter
provider. Inject extra_headers in the override too, and replace the
storage-only router test with call()-driven coverage.
* style: apply ruff format to migrations.py (pre-existing lint drift)
Newer ruff collapses two multi-line log strings that now fit the line
length. The file was byte-identical to main; this brings it in sync with
the lint gate so verify-generated-files passes.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
`test_extraction_failure_at_retry_cap_fails_terminally` (added in #2418,
guarding the recovered-worker path from #2413) asserts that when fact
extraction fails terminally, the original exception message survives
into `async_operations.error_message` so an operator can tell apart a
structured-JSON parse failure from a rate-limit reset from a network
5xx — all of which can surface as the same exception types in different
code paths.
The formatter was joining only `type(err).__name__`, producing rows like
"chunk 0: RuntimeError". The exception message was discarded, leaving
worker failures unactionable and silently defeating the test. The test
ran for the first time on this branch (its original PR's test-api job
was skipped) and surfaced the bug.
Add the message to the summary: "chunk 0: RuntimeError: structured JSON
parse failed after all retain_extract_facts attempts". Same shape, just
the field the test was added to enforce.
Drive-by: pre-existing, unrelated to the include_entity_links work in
this PR — but the test is wired in now and CI won't go green without it.
Co-authored-by: Chris Latimer <[email protected]>
* fix(llm-trace): stash litellm tool-call usage so token cost survives arg-parse failures (completes #2396)
* test(llm-trace): cover litellm tool-call arg-parse usage stash
Add a real-provider regression test for the fix in this PR: the existing
wrapper-level tools test uses a provider that already stashes, so it does
not guard LiteLLMLLM.call_with_tools. This drives the real provider with a
billed response whose tool arguments are malformed JSON and asserts the
error trace keeps the provider-reported tokens (input/output/cached). The
LiteLLMRouterLLM subclass inherits call_with_tools, so it is covered too.
Verified it fails (input_tokens=None) when the stash line is removed.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(langgraph): resolve tool bank IDs from config
* review(langgraph): rename injected config param to avoid shadowing
Rename the injected RunnableConfig tool parameter to runnable_config so it
no longer shadows the outer Hindsight config = get_config().
---------
Co-authored-by: Nicolò Boschi <[email protected]>
#2422 added the public RecallRequest.min_scores (per-stage score floors) to
the HTTP/MCP API and the generated clients, but the hand-maintained
high-level Python wrapper (hindsight_client.recall/arecall) never got it, so
high-level SDK users can't use the feature without dropping to the raw
generated client.
Thread an optional min_scores dict through recall()/arecall() into
RecallRequest, mirroring the existing tag_groups dict->from_dict pattern.
Unknown keys raise ValueError so a misspelled floor fails loud instead of
silently applying no filter. Parity test mirrors
tests/test_recall_prefer_observations.py.
Follow-up to #2422.
Update generated hindsight-docs skill references with Requesty provider
entries that are already present in the source documentation.
This keeps the generated skill bundle in sync with the docs generator so
pre-commit no longer rewrites these files.
Add PrecheckOperation, BankReadOperation, and BankWriteOperation
StrEnum types for operation validator hook contexts. Use them at
every precheck and validate_bank_read/write call site while
preserving string comparison compatibility for existing extensions.
Tests:
- uv run pytest tests/test_extensions.py -q
- ./scripts/hooks/lint.sh
Remove accidentally committed Playwright MCP logs, page snapshots, and
root-level screenshot artifacts.
Ignore future Playwright MCP output so local browser debugging does not
show up as repository changes.
HINDSIGHT_API_LLM_GROQ_SERVICE_TIER (default "auto") and
HINDSIGHT_API_LLM_OPENAI_SERVICE_TIER (OpenAI Flex, "50% cheaper") are parsed
into HindsightConfig but were never threaded into any constructed LLM provider.
The per-operation LLMConfig builds in memory_engine.py and LLMProvider.from_env
thread bedrock_service_tier and gemini_service_tier from config, but omitted
groq/openai, so setting either knob was a silent no-op. groq is the default
provider, so the cost-tier control was dead on the default path.
The constructor already accepts both fields and the providers already consume
them (gated on provider == "groq"/"openai"), so this only wires the missing
feed-in from config, mirroring the existing bedrock/gemini lines.
HINDSIGHT_API_LLM_GROQ_SERVICE_TIER (default "auto") and
HINDSIGHT_API_LLM_OPENAI_SERVICE_TIER (OpenAI Flex, "50% cheaper") are parsed
into HindsightConfig but were never threaded into any constructed LLM provider.
The per-operation LLMConfig builds in memory_engine.py and LLMProvider.from_env
thread bedrock_service_tier and gemini_service_tier from config, but omitted
groq/openai, so setting either knob was a silent no-op. groq is the default
provider, so the cost-tier control was dead on the default path.
The constructor already accepts both fields and the providers already consume
them (gated on provider == "groq"/"openai"), so this only wires the missing
feed-in from config, mirroring the existing bedrock/gemini lines.
markitdown samples only the first chunk for charset detection, so a UTF-8
file (e.g. a JSON transcript) with a long ASCII-only prefix is mis-detected
as ASCII. Its JSON/ipynb converter then reads the whole file with the wrong
charset and crashes on the first multibyte byte during converter selection,
before the plain-text converter can run.
Pass an explicit UTF-8 charset hint to markitdown for text-like files whose
bytes are valid UTF-8, sidestepping the faulty detection. Binary and genuinely
non-UTF-8 files fall back to markitdown's own detection.
The top feature bullet of both primary published packages (hindsight-api
and hindsight-api-slim) says 'World facts, bank actions, and formed
opinions', but the live recall taxonomy is world/experience/observation:
'opinion' was removed (recall now 422-rejects it) and 'bank' was renamed
to 'experience'. Sync the bullet to VALID_RECALL_FACT_TYPES so the first
thing a PyPI/GitHub visitor reads matches the actual API contract.
Scoped to the taxonomy bullet only; opinion *formation* as a behavior is
unchanged.
The `MemoryFact.fact_type` field description still advertises 'opinion' as a
valid value, but it was removed from the fact-type enum: the DB CheckConstraint
and VALID_RECALL_FACT_TYPES now allow only 'world', 'experience', and
'observation', and the API hard-rejects 'opinion'. An SDK/API consumer reading
the response schema is misled into thinking 'opinion' is a real fact_type.
Drop 'opinion' so the schema description matches what the API actually returns
and accepts. Follow-up to the opinion-fact-type cleanup in #2198/#2302/#2335.
* fix: populate search_vector on observation INSERT/UPDATE in consolidator
The consolidator creates and updates observations without populating the
search_vector tsvector column. Under the native text search extension,
this means observations are invisible to BM25 full-text retrieval - the
BM25 arm returns 0 candidates regardless of query content.
Four code paths write observation text to memory_units:
1. _dedup_reconcile_create (merge into existing twin)
2. _dedup_reconcile_update (drift-merge into different twin)
3. _execute_update_action (LLM rewrite of existing observation)
4. _create_observation_directly (new observation INSERT)
None populated search_vector. This patch adds conditional tsvector
generation gated on config.text_search_extension == 'native', matching
the existing pattern in ops_postgresql.insert_facts_batch. Non-native
backends (pg_textsearch, pgroonga, pg_search) continue to leave
search_vector NULL as they index base text columns directly.
The INSERT path (Site 4) splits the existing else branch into an
explicit elif/else to avoid applying native tsvector logic to backends
that don't use it.
Fixes: observations invisible to BM25 retrieval arm.
* Implement test for search vector population in observations
Add test for observation creation with native search vector
* style: run lint
* fix(consolidation): backfill search_vector for existing native observations
The writer fix only populates search_vector for observations created or
updated after deploy. Observations already written under the native
backend keep a NULL search_vector and stay invisible to BM25 until
re-consolidated. Add migration c3f7a1b9d2e4 to backfill them, gated on the
native tsvector column type and scoped to fact_type='observation' with a
NULL search_vector (idempotent). Matches the writer's text-only tsvector
and the configured native language.
* chore: remove accidentally committed git-lfs hooks
post-checkout/post-commit/post-merge/pre-push were git-lfs stubs picked
up from the contributor's local hookspath and committed by mistake. They
are unrelated to this change; the project's real .githooks/pre-commit is
left intact.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* Add entity resolution deep-dive blog post
Technical deep-dive on entity resolution in agent memory, grounded in
Hindsight's implementation: name similarity + a co-occurrence graph +
temporal recency (no embeddings/LLM for resolution), the 0.6 merge
threshold, and the conservative-merge design.
From real-app integration testing:
- aider: close the Hindsight client when the wrapper owns it, so aiohttp no
longer prints 'Unclosed connector' warnings after aider exits. Test-injected
clients are left to the caller. Bump 0.1.1.
- openhands: document that the OpenHands Docker app loads MCP from UI settings
(not the project config.toml), and that the server must be added as a
Streamable HTTP server (not SSE) reachable via host.docker.internal. Same hint
printed by 'init'. Bump 0.1.1.
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* feat(devin-desktop): rename windsurf integration to Devin Desktop
Cognition rebranded Windsurf to Devin Desktop (June 2026); Cascade is EOL
July 1. Rename the (unreleased) windsurf integration to devin-desktop before
first publish:
- Package hindsight-windsurf -> hindsight-devin-desktop (module
hindsight_devin_desktop, CLI hindsight-devin-desktop, DevinDesktopConfig,
bank default 'devin-desktop', HINDSIGHT_DEVIN_DESKTOP_BANK_ID)
- Rule now writes to .devin/rules/hindsight.md (preferred path) instead of
the legacy .windsurf/rules/; trigger: always_on unchanged
- MCP config path stays ~/.codeium/windsurf/mcp_config.json (Devin Desktop's
on-disk data dir, unchanged by the rebrand)
- Official Devin logo; docs + integrations.json + README refreshed with the
'formerly Windsurf' framing
- Registries updated: test.yml job, release-integration.sh, generate_changelog,
integrations.json (strict JSON), docs page
26 unit tests + gated live-MCP E2E pass; ruff check+format clean; real-app
smoke against local Hindsight verified (init writes both files; live recall
returns seeded facts).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* fix(continue): resolve a fresh Hindsight client per request (thread-safe)
The adapter runs on a ThreadingHTTPServer (one worker thread per request) but
shared a single Hindsight client across all of them. The client's aiohttp
session is bound to the thread/event-loop that first used it, so the first
@hindsight recall worked and every one after threw 'Timeout context manager
should be used inside a task' — Continue then showed an error context item and
the model answered with no memory.
Resolve the client per request (test-injected clients still used as-is), and
close per-request clients in a finally so the fresh aiohttp session doesn't leak
a connector each call. Bump to 0.1.1.
Found via a real in-editor VS Code test. Adds a regression test asserting
per-request client resolution across the threaded server.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Replace the recall result's single `score` with a `scores` object exposing the
scores from each pipeline stage, and replace the `min_score` request param with
`min_scores`, a per-stage filter that operates at two levels.
Response — each result carries `scores`:
- final : the value results are ranked by
- reranker : cross-encoder normalized relevance (null for passthrough rerankers)
- semantic : raw vector cosine similarity (null if not surfaced semantically)
- text : raw keyword/BM25 score (null if not surfaced by keyword search)
Per-arm semantic/text scores are aggregated across retrieval arms during RRF /
interleave fusion (ArmScores on MergedCandidate), since fusion otherwise keeps
only the first-seen arm's score per doc.
Request — `min_scores` floors (inclusive, AND-ed, opt-in; default no filtering):
- semantic / text : retrieval-level cutoffs pushed into the SQL arms, overriding
the global similarity / BM25 minimums for the request (prune before fusion)
- reranker / final: post-query filters on the scored results
There is deliberately no default threshold: the cross-encoder's absolute scores
are reliable for ordering but not calibrated across queries (a clearly-relevant
match can score ~0.001 on one query and ~1.0 on another), so a fixed cutoff would
silently drop good results.
Also surfaces proof_norm in the search trace and reworks the control-plane trace
view to render scores at full precision (no rounding) and show the per-stage
`scores` breakdown; relabels the trace's "CE" column to "reranker score".
Threaded through engine, HTTP, MCP (both recall tools), and the control-plane
proxy; OpenAPI spec, Python/TS/Go/Rust clients, and the docs-skill mirror
regenerated; docs updated.
* fix(retain): merge JSON arrays in append mode to preserve conversation-aware chunking
When update_mode=append prepends existing document text as a second
content item, combined_content is built with "\n".join(...). For
conversation-format content (flat JSON arrays of message dicts), this
produces "[...]\n[...]" which is not valid JSON.
On subsequent append cycles, chunk_text() fails to parse the corrupted
original_text. _chunk_jsonl() also rejects it (lines are arrays, not
dicts). The text falls through to RecursiveCharacterTextSplitter, which
splits on sentence boundaries with no awareness of conversation turn
structure. This produces chunks that begin mid-sentence without speaker
attribution, causing the extraction LLM to misattribute statements.
Fix: after the append-mode block assembles contents_dicts with the
existing and new content items, detect when all items are JSON arrays
of dicts and merge them into a single flat array. Non-conversation
content (plain text, JSONL) is unaffected.
close#2409
* Enhance chunking tests for JSON array formats
Add tests for chunking newline-joined and merged JSON arrays.
* Add test for valid JSON in append mode
This test ensures that appending conversation arrays maintains the original_text as a valid flat JSON array after multiple append cycles, preventing degradation of the data structure.
* add missing json import to test_retain_append_mode
Render in-flight and failed file uploads in the Documents view by deriving
them from the server's file_convert_retain operations — no client-side store
or client-generated document ids.
- surface document_id + original_filename on the operations list endpoint
(already stored in the operation's result_metadata)
- documents-view derives pending/failed rows from those operations, deduped
against the real document list by document_id, and polls while in-flight
- bridge the brief window where an operation reports completed before the
document becomes visible in listDocuments, so the row never flickers
Supersedes #2346 (client-side sessionStorage approach). Closes#2314.
* Add Zapier persistent memory blog post
Adds the integration walkthrough for the Hindsight Zapier app: persistent
memory for any Zap via Retain/Recall/Reflect actions plus REST-Hook
triggers that start Zaps from memory events.
Adds a third, independent way to refresh a mental model — on a cron schedule —
alongside the existing auto (refresh_after_consolidation) and manual paths,
driven by the background MaintenanceLoop ticker.
API/engine:
- trigger.refresh_cron (UTC 5-field cron, croniter-validated); mutually
exclusive with refresh_after_consolidation.
- PG-only discovery routine public.mental_models_with_cron() (migration
f4d1c2b3a5e6); cron due-ness evaluated in Python, refresh only when stale.
- HINDSIGHT_API_MENTAL_MODEL_REFRESH_TICK_SECONDS check cadence.
- One timing line logged per maintenance sweep.
Control plane:
- Single "Refresh trigger" choice (Manual / On new memories / On a schedule)
with per-option sub-labels; cron input shown only when scheduled.
- Live cron schedule preview (human-readable + next/upcoming runs, UTC+local).
- "Next refresh" shown next to "last refreshed" in list, dashboard, and dialog.
- Fixed an app-wide off-by-one in formatRelativeTime.
Regenerated OpenAPI + clients + bank-template schema; i18n across all locales.
The constructor previously reached into global HindsightConfig (via get_config /
_get_raw_config) to backfill any None argument: default_headers,
gemini_safety_settings, gemini_service_tier, prompt_cache_enabled,
litellmrouter_config, and the vertexai project/region/service-account key. That
hidden global read is exactly what made indexed multi-LLM members hard to
configure independently — each #2384/#2401 fix was "thread one more field so an
explicit value can win over the constructor's global fallback."
Remove all of it. The constructor now uses its arguments verbatim (plus pure
normalizations: the Gemini tier parse, the non-Gemini tier reset, the google/
model-prefix strip, and the us-central1 region default). Resolving the
server-level default for an omitted field is the caller's responsibility:
- MemoryEngine's four per-op base builds pass the global LLM config explicitly
(gemini_safety_settings comes from the raw config since the StaticConfigProxy
blocks that one bank-configurable field; the rest are static).
- _member_to_llm resolves member-value-or-global for each field, preserving how a
chain member inherits global defaults.
- LLMProvider.from_env reads the remaining fields straight from os.getenv, staying
a lightweight env-only loader (no full-config build).
This makes a provider's effective settings a pure function of its arguments,
which is what lets each member of a multi-LLM chain be configured independently.
Behavior is unchanged for single-LLM, member, and from_env paths.
Tests: update the vertexai/gemini-safety unit tests to the explicit-args contract
(they previously fed the constructor via env), and add two tests asserting the
constructor ignores global config for headers/prompt-cache/safety-settings.
Follow-up to #2384. That PR let an indexed multi-LLM member carry its own
Vertex AI project/region, but two parity gaps remained vs the primary provider:
- A `litellmrouter` member had no per-member router config, so it silently fell
back to the global `HINDSIGHT_API_LLM_LITELLMROUTER_CONFIG` — a chain could not
fail over between differently-routed LiteLLM routers (same bug class #2384 fixed
for Vertex).
- A `vertexai` member used only the global service-account key, so cross-project
failover with distinct credentials was impossible (project/region alone weren't
enough).
Adds `litellmrouter_config` and `vertexai_service_account_key` to
`LLMMemberConfig`, reads `{prefix}LLM_{n}_LITELLMROUTER_CONFIG` /
`_VERTEXAI_SERVICE_ACCOUNT_KEY` in `_parse_llm_members`, threads both through
`_member_to_llm`, and lets `LLMProvider.__init__` take a per-instance Vertex SA
key (explicit wins, else global fallback). Single-LLM/global behavior unchanged.
Tests: parse (incl. per-op prefix + invalid-JSON), and build-path proving the
member's own values reach `litellm.Router` and the Vertex SDK client. Docs table
updated with the new per-member keys.
* fix(llm-trace): keep provider token usage on parse/validation failures (#2387)
When an LLM call succeeds and returns usage but local JSON parsing or
structured-output validation then fails, the failure trace was recorded
with input_tokens=0/output_tokens=0 because response.usage was out of
scope by the time the exception reached the wrapper. Providers still
charge for those tokens, so error rows lost real cost data.
Providers now stash provider-reported usage (LLMResponseUsage) into a
contextvar as soon as a response is in hand, before parse/validate; the
wrapper attaches it to the error trace. Codex/Claude Code (no SDK token
counts) stash the same char/4 estimate their success path already traces.
* test(llm-trace): drive real provider parse/validation failure with mocked SDK
Add tests that exercise the actual OpenAICompatibleLLM structured-output
path through the LLMProvider wrapper with a mocked SDK client returning a
successful usage-bearing response but bad output: a non-JSON body (parse
failure) and schema-mismatched JSON (validation failure) both record the
provider usage on the status=error retain_extract_facts trace. A success
case asserts the same usage flows on the happy path.
PR #2378 added reasoning-token accounting in OpenAICompatibleLLM that
subtracts thoughts_tokens from output/total. Several tool-call tests build
their mock response with MagicMock() and set only prompt/completion/total
tokens, leaving usage.completion_tokens_details as a truthy auto-MagicMock.
The new code then does arithmetic on a MagicMock and raises TypeError,
failing all test-api shards. Set completion_tokens_details = None in the
affected mock helpers (matching the explicit-field convention already
documented in test_openrouter_null_content).
The Claude Code plugin ships via the marketplace manifest, not a package
registry. The integration release (release-integration.sh claude-code) already
bumps plugin.json, but the marketplace manifest carried no version and was
never bumped — so the published catalog never reflected new releases (e.g.
#2066 on Windows).
- add a "version" field to the root .claude-plugin/marketplace.json
- release-integration.sh now bumps it in lockstep with the plugin version when
releasing claude-code, and commits it
- remove the redundant hindsight-integrations/.claude-plugin/marketplace.json:
`claude plugin marketplace add vectorize-io/hindsight` only ever reads the
root manifest (even with --sparse), so the second manifest was never consulted
- drop the stale --sparse install hint from the release-integration workflow
The claude-code release flow is otherwise unchanged — release it as before.
Indexed multi-LLM members previously carried only provider/api_key/model/
base_url, so a 'vertexai' member could not initialize (its client requires a
project id, and the region defaults to us-central1). That made vertexai
unusable as a member of a failover/round-robin chain.
Add optional vertexai_project_id / vertexai_region to LLMMemberConfig, parse
them from {prefix}LLM_{n}_VERTEXAI_PROJECT_ID / _VERTEXAI_REGION (global and
per-op prefixes), thread them through the member build path, and accept them on
LLMProvider so an explicit per-instance value wins while existing single-LLM
setups still fall back to the global config.
Treat PATCH /v1/default/banks/{bank_id} as update-only by using a
non-creating bank profile lookup and returning 404 when the bank is
missing.
Add a regression test proving the endpoint does not create a bank as a
side effect.
Use the non-creating bank-profile lookup when dry-run extraction
resolves the optional narrator name. A preview endpoint promises no
persistence, so probing a missing bank must not insert a bank row.
Add a regression test that calls dry-run extraction against a missing
bank and verifies the bank still does not exist afterwards.
Run the pre-commit uv sync and workspace uv run commands with
--frozen so linting uses the checked-in lockfile without rewriting it
during ordinary code changes.
This avoids local uv resolver freshness checks producing unrelated
uv.lock diffs while preserving explicit dependency update workflows.
* fix(openai): propagate reasoning_tokens into TokenUsage for OpenAI-compatible providers
Follow-up to merged #2356, which shipped TokenUsage.thoughts_tokens but only
wired the gemini provider. The OpenAI-compatible backend (the most-used class:
OpenAI o-series/gpt-5, groq, deepseek-r1, plus NousLLM/FireworksLLM subclasses)
never read completion_tokens_details.reasoning_tokens and never passed
thoughts_tokens, so it reported 0 for every OpenAI-compatible reasoning model.
Extract reasoning_tokens with a 0-safe getattr chain (mirroring the existing
cached_tokens extraction and the gemini wiring) in both call() and
call_with_tools(), and pass thoughts_tokens (plus cached_tokens for
call_with_tools) into TokenUsage / LLMToolCallResult. Providers without
completion_tokens_details (non-reasoning models, Ollama native) keep 0.
Scoped to the OpenAI-compatible provider; anthropic_llm.py folds thinking into
output_tokens with no separate reasoning sub-count, left as optional follow-up.
Adds provider-level regression tests for call() and call_with_tools().
* fix(openai): make output_tokens visible-only so it doesn't double-count reasoning
OpenAI-compatible completion_tokens INCLUDES reasoning_tokens (verified live:
o4-mini completion=83, reasoning=64), but the TokenUsage contract and the
Gemini provider treat output_tokens/total_tokens as visible-only with
reasoning surfaced separately in thoughts_tokens. Subtract thoughts_tokens
from output_tokens (and total_tokens in call()) so cost attribution doesn't
double-count reasoning. Add a convention test pinning the invariant.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
test-api shard 2/3 intermittently failed collection of dozens of tests
with 'RuntimeError: function _has_torch_function already has a docstring'.
Root cause: the first import torch in a worker process happened lazily
from inside concurrent/async code (embeddings.initialize() ->
sentence_transformers -> transformers -> torch, and cross_encoder's
ThreadPoolExecutor). torch/overrides.py's C-level _add_docstr is not
re-entrancy-safe, so under concurrency torch/overrides.py could execute
twice and raise, failing collection of every test on the shard.
Fix: import torch once at conftest import time (single-threaded, before any
event loop or thread pool), so the registration happens exactly once per
xdist worker. Guarded for slim/no-torch environments.
* feat(eve): add Eve agent-framework MCP connection helper
Add @vectorize-io/hindsight-eve: a thin helper that wraps Eve's
defineMcpClientConnection to wire an Eve agent into a Hindsight MCP
server in one line, pre-filling the endpoint, model-facing description,
and bearer auth with env-var defaults (HINDSIGHT_MCP_URL,
HINDSIGHT_API_KEY, HINDSIGHT_MCP_BANK_ID).
* feat(windsurf): add Windsurf (Codeium) integration via MCP
Config-only CLI that wires the Hindsight MCP server into Windsurf's
~/.codeium/windsurf/mcp_config.json (mcpServers, remote serverUrl + auth
header) and writes an always-on recall/retain rule to
.windsurf/rules/hindsight.md (trigger: always_on). Cascade then has
recall/retain/reflect and uses them automatically.
- hindsight_windsurf: config, mcp_config (strict-JSON parse-or-print),
rules (dedicated sentinel-marked file), cli (init/status/uninstall)
- 25 unit tests + gated live-MCP-endpoint E2E
- CI job, release + changelog registries, docs page, icon, README row
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* style(windsurf): apply ruff format to cli.py
lint.sh runs 'ruff format'; collapse the --rules-path add_argument to one
line so verify-generated-files passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* fix(windsurf): use official Windsurf logo for the integration icon
Replace the placeholder abstract mark with the official Windsurf logo
(simple-icons, CC0), matching the real-brand-logo convention used by the
other integration icons.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* blog(retain): structuring chat logs for optimal ingestion
Add a concept guide on shaping conversation transcripts for Hindsight's
retain: one item per conversation (document_id upsert / append), speaker
labels, context-driven world-vs-experience attribution, timestamp
anchoring, and dropping system prompts / injected memories. Grounded in
the retain API docs and de-facto integration conventions.
* blog(retain): add length/latency, streaming, and links/attachments guidance
Incorporate real user Q&A: document length isn't the constraint (the tail
of long transcripts isn't dropped), segment by recall latency not size,
buffer a few turns when streaming (per-user ingest limit), and set
expectations on links (reference text, not fetched) and attachments
(no file ingest; store in S3 and link).
Adds hindsight-copilot: long-term memory for GitHub Copilot in VS Code, using
Copilot agent mode's native MCP support (HTTP servers) — no bridge.
`hindsight-copilot init`:
- merges a Hindsight HTTP MCP server into .vscode/mcp.json (servers.hindsight),
JSON-safe (prints a snippet if the file is JSONC), and
- writes a recall/retain rule into .github/copilot-instructions.md, which
Copilot applies to every chat in the workspace.
Resolves the ask in #1588. Mirrors the Zed/OpenHands MCP-config pattern.
- hindsight_copilot package: config, mcp_config (.vscode/mcp.json writer),
instructions (copilot-instructions.md rule), cli (init/status/uninstall)
- 25 deterministic tests (mcp.json merge incl. preserving servers/inputs +
JSONC fallback, instructions rule block) + gated requires_real_llm MCP
handshake E2E
- CI job, release registration (VALID_INTEGRATIONS + changelog generator),
docs page, registry entry, icon (octicons), README row
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* blog: Persistent Memory for the Vercel AI SDK in Five Tools
Add a dedicated integration post for @vectorize-io/hindsight-ai-sdk.
Covers the five memory tools (retain, recall, reflect, getMentalModel,
getDocument), the semantic-vs-infrastructure input split, setup, and
generateText/streamText/ToolLoopAgent/Next.js usage.
Default worker_id falls back to socket.gethostname(), which inside Docker/
Kubernetes is the random container hostname and changes on every container
recreation. recover_own_tasks() only reclaims tasks whose worker_id matches
the current worker, so tasks left in 'processing' under the old hostname are
never recovered — consolidation and other async ops can get stuck forever.
Add detect_container_runtime() and log a prominent warning at worker start
when HINDSIGHT_API_WORKER_ID is unset and a container runtime is detected,
pointing operators to set a stable worker id.
_search_with_retries only recorded ~10-15% of total_duration_seconds as
named phase metrics; the rest sat in un-instrumented blocks (backend
acquisition, combined scoring, chunk/source-fact/entity enrichment,
result serialization). Add a phase metric for each, and split the
combined-scoring work out of the reranking metric (which captured its
duration before scoring ran).
Mark the per-method retrieval splits, pool waits, and trace_finalize as
diagnostic (they overlap parallel_retrieval or fall outside the total
window) so they are excluded from the coverage sum.
Adds test_trace_phase_coverage asserting the non-diagnostic phases sum to
total without exceeding it.
* feat(llm): multi-LLM failover & round-robin via indexed config
Configure extra LLMs by index (HINDSIGHT_API_LLM_<n>_*) alongside the
unindexed primary, then route across them with HINDSIGHT_API_LLM_STRATEGY
(JSON): {"mode":"failover"} or {"mode":"round-robin"} with optional
per-member "weights" for unbalanced rotation. Each operation can override
the global chain with a RETAIN_/REFLECT_/CONSOLIDATION_ prefix.
A general, provider-agnostic alternative to the LiteLLM Router and a more
extensible replacement for the single-secondary failover approach.
- config.py: LLMMemberConfig/LLMStrategyConfig dataclasses, indexed-member
+ strategy parsing, new HindsightConfig fields (credential, server-level).
- engine/multi_llm.py: MultiLLMProvider mirrors the LLMProvider surface so it
drops into with_config()/ConfiguredLLMProvider and _provider_impl passthrough;
smooth weighted round-robin; failover passes through OutputTooLongError and
cancellation; strict-primary/soft-secondary verify_connection.
- memory_engine.py: _build_llm wraps each of the 4 LLM slots; no-config path
returns the plain LLMProvider unchanged.
Batch retain runs on the primary member only (documented).
* docs: regenerate hindsight-docs skill reference for multi-LLM config
The Atlas Cloud provider entries were added to the repo-root .env.example
but not re-copied to the embed bundle, failing the
test_bundled_template_matches_repo_root sync test.
The Rust client was regenerated with limit/offset typed as Option<u64>
(unsigned, minimum 0 in the OpenAPI spec), but the api.rs wrappers still
passed Option<i64>, breaking `cargo build` (and the test-rust-cli /
test-doc-examples CI jobs). Cast the values to u64 at each call site
(list_documents, list_memories, list_entities, get_graph, list_tags),
matching the existing pattern already used for list_documents.
The Atlas Cloud LLM provider was added to the docs but the generated
docs-skill references were not regenerated, leaving verify-generated-files
red on main. Regenerate models.md and faq.md.
Deterministic, DB-level regression guard for the deadlock fixed in #2353.
Two concurrent transactions insert overlapping graph_maintenance_queue keys in
opposite order (with a barrier between the two per-row locks) and Postgres
aborts one with DeadlockDetectedError; the sorted-order companion test shows a
shared lock order eliminates the cycle. Unlike #2353's tests — which only assert
the Python list handed to execute() is sorted — this exercises the actual lock.
These per-entity methods have no live callers — the retain/PATCH paths all go
through the batched resolve_entities_batch + flush_pending_stats, which already
sort their writes for consistent lock ordering. The dead _create_entity carried
an unsorted 'entities ON CONFLICT ... DO UPDATE' that looked like a concurrent
deadlock site (it isn't, since it's unreachable). Removing the dead code so it
stops misleading readers/reviewers.
_update_cooccurrence is removed too — its only caller was the dead
link_unit_to_entity.
* feat(tokens): propagate cached + thoughts tokens through return contexts
The Gemini 2.5+ family (and any future provider that combines prompt caching
with reasoning tokens) reports four distinct token counts on every response:
- prompt_token_count (total input)
- candidates_token_count (visible output)
- cached_content_token_count (subset of input served from prompt cache)
- thoughts_token_count (reasoning tokens, billed at output rate)
The provider already records the last two on the Prometheus
``hindsight.llm.tokens.{cached_input,thoughts}`` counters, but the values
stop at the metrics layer — every return context (TokenUsage,
LLMToolCallResult, TokenUsageSummary, RetainResult) only exposes the
top-level input/output split. As a result:
* a downstream metering extension can't attribute prompt-cache hit-rate
per operation (only globally via Prometheus aggregates), and
* reasoning-token spend is invisible to ``output_tokens`` because the
provider keeps it out of candidates_token_count. A workload that
"looks cheap" by visible output can be silently expensive if the
model is doing long reasoning chains.
This change threads the two fields through end-to-end:
- ``TokenUsage`` gains ``thoughts_tokens`` (cached_tokens already
existed); ``__add__`` sums it so multi-iteration agentic-loop
aggregation works.
- ``LLMToolCallResult`` gains ``cached_tokens`` + ``thoughts_tokens``.
- ``TokenUsageSummary`` (returned by ``run_reflect_agent``) gains
both fields and ``run_reflect_agent`` accumulates them at every
call site (main tool loop + structured-output extraction + 4
edge-case completion branches).
- ``_generate_structured_output`` now returns a 5-tuple
``(output, in, out, cached, thoughts)``; the 6 unpack sites in the
reflect agent are updated together.
- ``RetainResult`` gains optional ``llm_cached_input_tokens`` and
``llm_thoughts_tokens`` fields; ``memory_engine`` populates them
from the aggregated ``TokenUsage``. Defaults stay ``None`` for
engines that don't surface the data so existing metering extensions
are unaffected.
- The Gemini provider — which was already reading the four token
counts from the SDK response — now returns ``thoughts_tokens`` on
both the ``call`` and ``call_with_tools`` paths, and the existing
``cached_input_tokens`` value reaches ``LLMToolCallResult``.
Backward compatibility: every new field defaults to 0 (or None for the
RetainResult dataclass), so any caller built before this change keeps
working. Provider impls that don't surface these counts simply propagate
zeros — the structured Prometheus counters were already optional in
``record_llm_call``.
Adds focused tests (``test_token_usage_cached_thoughts.py``, 6 cases)
pinning the propagation through every return type and the aggregation
behavior. Existing reflect-agent + Gemini provider tests (87 cases) pass
unchanged.
This is a pure plumbing change — no metrics are renamed, no behavior is
gated, no flags are added.
* chore: regenerate clients + openapi spec for thoughts_tokens field
Picks up the new TokenUsage.thoughts_tokens field added in the parent
commit. Generated by:
./scripts/generate-openapi.sh
./scripts/generate-clients.sh
Plus ``ruff format`` over the two reflect/ source files to match the
project's enforced formatting style.
No hand edits in any generated file.
* chore: regenerate skills/hindsight-docs/references/openapi.json
* fix(reflect): return StructuredOutputResult instead of widened tuple
_generate_structured_output's return contract had drifted: the success
and no-fields branches returned a 5-tuple while the except branch still
returned a 3-tuple. All six call sites unpack five values, so any
structured-output failure would crash reflect with a ValueError instead
of degrading gracefully.
Replace the multi-item tuple return with a typed StructuredOutputResult
(per project rule: no multi-item tuple returns), making the arity
mismatch impossible and the failure path safe. Add a regression test.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Atlas Cloud (https://www.atlascloud.ai) exposes an OpenAI-compatible
chat/completions endpoint, so it slots into the existing
OpenAICompatibleLLM path exactly like deepseek / zai / opencode-go.
Set `HINDSIGHT_API_LLM_PROVIDER=atlas` to route fact extraction,
reflection and consolidation through Atlas Cloud. The base URL defaults
to https://api.atlascloud.ai/v1 and the default model is
deepseek-ai/deepseek-v4-pro (a reasoning model — give it enough
max_tokens, >= 512).
Changes:
- engine/llm_wrapper.py: register "atlas" in create_llm_provider(),
LLMProvider.valid_providers, and the default base_url map
- engine/providers/openai_compatible_llm.py: register "atlas" in
valid_providers, default base_url, and the API-key-required check
- config.py: PROVIDER_DEFAULT_MODELS["atlas"] = deepseek-ai/deepseek-v4-pro
- hindsight-embed control center: add Atlas Cloud to the provider wizard
- docs: add Atlas Cloud to llmProviders.json (drives the providers grid
and table) and a config example in developer/models.mdx
- README + .env.example: document the new provider
Verified end-to-end: instantiated the atlas provider through Hindsight's
own create_llm_provider() and made a live call() to
deepseek-ai/deepseek-v4-pro (HTTP 200, valid content + token usage).
Co-authored-by: Claude Opus 4.8 <[email protected]>
* fix(http): reject negative limit/offset on list endpoints with 422 instead of 500
Several user-facing GET list endpoints declared limit/offset without ge
constraints, so a negative value flowed straight into Postgres LIMIT/OFFSET
(emitted with no max(0, ...) clamp), which raises 'LIMIT/OFFSET must not be
negative'. The generic `except Exception -> HTTPException(500, str(e))` then
turned a client input error into a 500 that also leaked the raw Postgres error
string.
Add Query(ge=...) constraints (limit ge=0, offset ge=0) on the affected
endpoints (graph, memories/list, documents, tags, entities, entities/graph),
matching the ge constraints already enforced on the sibling list endpoints
(document-chunks, directives, async-ops, audit) so FastAPI returns a clean 422
at the boundary. ge=0 rejects only negatives and preserves limit=0 (a valid
empty page), so there is no behavior change for any previously-valid request.
* chore: regenerate OpenAPI spec and clients for ge=0 pagination constraints
Adds minimum:0 to limit/offset params across openapi.json, docs-skill spec,
Go openapi.yaml, and Python clients; lint reformats the new test.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
`enqueue_graph_maintenance` is called inside the same transaction as the
mutation that produced its `unit_ids` list (see `enqueue_relink_victims`
after a memory update, document delete, etc.). The INSERT it issues takes
a short-lived row-level lock per `(bank_id, unit_id)` for the
unique-key check (`ON CONFLICT DO NOTHING` on Postgres, the
`IGNORE_ROW_ON_DUPKEY_INDEX` hint on Oracle).
Under load, two concurrent transactions on the same bank can produce
overlapping `unit_ids` sets in different orders — most easily reproduced
by two concurrent `PATCH /v1/default/banks/{bank_id}/memories/{id}`
requests where the victim sets (surviving units linking to the patched
unit) intersect. When the two transactions try to acquire their per-row
locks in opposite orders, Postgres detects the cycle and aborts one
transaction with `asyncpg.exceptions.DeadlockDetectedError`, which the
FastAPI layer surfaces as an opaque 500.
Fix: sort `unit_ids` inside both `PostgreSQLOps.enqueue_graph_maintenance`
and `OracleOps.enqueue_graph_maintenance` before issuing the INSERT.
With a total order over the lock set, deadlock is mathematically
impossible — both transactions queue cleanly on the first conflicting
row, then proceed in lockstep.
The only public caller (`enqueue_relink_victims` in
`hindsight_api/engine/graph_maintenance.py`) doesn't rely on insertion
order, so this is a pure correctness improvement with no API-visible
effect. The abstract contract docstring already said "Order is
unspecified" — implementations now happen to pick a deterministic
order, but that's an internal invariant, not part of the public
contract.
Tests:
- `tests/test_enqueue_graph_maintenance_ordered.py` (new):
- `test_pg_enqueue_graph_maintenance_inserts_in_sorted_order` —
captures the array passed to `conn.execute` from a deliberately
shuffled input and asserts it is sorted.
- `test_oracle_enqueue_graph_maintenance_inserts_in_sorted_order` —
same assertion against `conn.executemany`'s tuples.
- Two empty-input tests pin the early-return short-circuit (no INSERT
when `unit_ids == []`).
- Verified existing `tests/test_graph_maintenance.py` still passes
(14/14) — the relink-victim enqueue and drain semantics are unchanged.
Compatibility: identical on both dialects. No schema changes. No
externally-visible behavior change beyond the deadlock no longer
firing.
Recalling `observation` alongside `world`/`experience` can return the same
information twice — once as a raw fact and once folded into an observation
consolidated from it. The opt-in `prefer_observations` flag drops any raw fact
that a returned observation lists in its `source_memory_ids`, so the observation
supersedes it. Dedup is by provenance (exact id membership), not semantics, and
runs before recall truncation so freed slots backfill — keeping the result count
at the requested budget.
Disabled by default (opt-in). Internal callers — notably consolidation, which
needs the raw facts it folds into observations — leave it off.
Exposed on the full client surface: the maintained Python (`recall`/`arecall`)
and TypeScript (`recall`) wrappers, the Rust CLI (`--prefer-observations`), the
regenerated OpenAPI + low-level Python/TS/Go/Rust SDKs, the control-plane proxy +
types, and the generated docs skill. Includes docs and deterministic
provenance-based tests (engine + both wrappers).
* fix(recall): allow exact filtering of untagged/global observations (#2295)
An empty tag set with tags_match="exact" now selects only untagged
(global-scope) observations — the scope that observation_scopes="shared"
consolidation writes to. Previously empty/absent tags meant "no filter"
in every mode, so there was no way to recall only global observations
when mixing shared and tagged scopes.
- tags.py: in exact mode, empty/absent tags emit an untagged-only clause
(tags IS NULL OR tags = '{}') with no bind param, across the flat SQL
builders, Python post-filter, and compound tag-group leaves. All other
modes keep treating empty/absent tags as "no filtering".
- link_expansion_retrieval.py: always run filter_results_by_tags so the
exact-empty/global scope is applied (it's a no-op otherwise).
- http.py + regenerated clients/docs: document the exact-empty scope.
- Tests: SQL builders (flat + compound, param-offset preserved), Python
post-filter, and a recall API test asserting only untagged memories
return for tags=[] + tags_match="exact".
* chore(docs-skill): regenerate references for untagged exact-scope recall
Regenerated skills/hindsight-docs/references via generate-docs-skill.sh so the
docs-skill mirror matches the updated recall/observations docs (and the canonical
configuration table). Unblocks verify-generated-files.
`_submit_async_operation` always INSERTs into `async_operations`, which has
an FK to `banks(bank_id)`. Callers that race against bank deletion, or that
derive bank IDs before creating the bank (an integration that submits
`/consolidate` on a freshly-named bank before its CREATE has been issued),
hit `asyncpg.exceptions.ForeignKeyViolationError` out of the INSERT. The
FastAPI endpoints' generic `except Exception` then surfaces it as an opaque
500 — but the root cause is a client misuse, not a server fault.
Add a bank-existence precheck at the top of the INSERT path in both branches:
- `dedupe_by_bank=True` already runs `SELECT 1 FROM banks WHERE bank_id = $1
FOR NO KEY UPDATE` (for serialization, issue #1842). Switch it from
`execute` to `fetchval` so the rowcount also gates existence — preserves
the lock semantics, just adds a check on the returned value.
- `dedupe_by_bank=False` (scoped submits) previously had no lock and no
check; add a plain `SELECT 1 FROM banks` for existence only.
When the bank is missing, raise `OperationValidationError(404)`. The
endpoint's existing `except OperationValidationError` clause already
converts that to `HTTPException(status_code=e.status_code, detail=e.reason)`
— no API-layer changes needed.
Tests:
- 2 regression tests for `submit_async_consolidation` (unscoped + scoped)
against a missing bank — assert OperationValidationError with status_code=404.
- 1 pin test for `submit_async_graph_maintenance`, which has its own
pre-INSERT short-circuit (empty queue → no_work=True) that already
avoided the FK error.
Verified that the existing dedup atomicity tests
(`test_consolidation_submit_atomic_dedup.py`,
`test_consolidation_retry_dedup_by_bank.py`) still pass — the lock
semantics on the dedupe branch are unchanged.
PATCH /v1/{tenant}/banks/{id}/config validated field names only, never
scalar type/range, so an out-of-contract disposition_skepticism/literalism/
empathy (float, 0-1 scale, or int outside 1-5) was json.dumps-ed into JSONB
and later injected into a strict DispositionTraits(int, ge=1, le=5) -- a
single malformed bank 500s GET banks for the whole tenant. Add a write-side
_validate_disposition_updates raising ValueError (route maps ValueError->400),
mirroring _validate_recall_budget_updates, plus a unit test. None is allowed
as the clear-override sentinel (overlay falls back to the legacy column, so
null can't poison the list).
Closes#2348.
* fix(mcp): omit reflect directives_applied with tool_trace/llm_trace by default
directives_applied is built by the engine 'for the trace' and carries full
directive text, but the include_trace pop block (added in #2242) only removed
tool_trace/llm_trace, so it leaked unconditionally with no opt-out. The REST
API never serializes it. Gate it behind the same include_trace flag to complete
#2242's default-omit-trace contract.
* test(mcp): assert reflect omits directives_applied unless include_trace
The in-process engine builds based_on with keys world, experience,
opinion, observation, "mental-models" (hyphen), directives
(memory_engine.py). ReflectResult's Field description named the key
"mental_models" (underscore) and omitted "observation", and the
json_schema_extra example had the same drift — so a consumer doing
based_on["mental_models"] hits KeyError and never learns the
"observation" bucket exists. The maintainer's own http.py comment
already notes the key is hyphenated.
Fixes the description and example to the real keys. Leaves the dead
'opinion' key untouched (handled by #2323/#2335). The separate wire
model ReflectBasedOn is unaffected.
* fix(stats): invalidate bank stats cache on unit/document deletes and observation clears
delete_bank invalidates the 60s-TTL BankStatsCache after mutating counts,
but delete_memory_unit, delete_document, clear_observations, and
update_document (on tag-change observation deletion) did not, so
get_bank_stats served pre-mutation counts for up to a minute.
Follow-up to #2315 which hardened the cache primitive but left the
mutation call sites untouched. Invalidation is best-effort (guarded),
matching the other post-commit side-effects in these methods.
Adds tests/test_bank_stats_cache_invalidation.py covering the deletion
paths with a pinned long TTL so the regression is deterministic.
* style: apply ruff format to satisfy verify-generated-files
The verify-generated-files CI job was red because `ruff format` reformats two lines that were committed unformatted:
- wrap the long `logger.warning(...)` call in memory_engine.py
- collapse the `test_delete_document_invalidates_stats_cache` signature
No logic change; this is purely the `uv run ruff format` output. Thanks to @koriyoshi2041 for the precise diagnosis.
---------
Co-authored-by: r266-tech <[email protected]>
* fix(claude-code): use realpath for directoryBankMap symlink resolution
os.path.normpath does not resolve symlinks, so a cwd reached via a symlink
silently fails to match a directoryBankMap entry and falls through to the
fallback bank. Replace normpath with realpath on both sides of the comparison
so that a symlinked cwd correctly matches its canonical directory.
Fixes#2312
* test(claude-code): add symlink regression test for directoryBankMap
v0.8.0 (#1917) removed the 'opinion' fact type; the recall()/arecall()
docstrings still listed it while reflect()/areflect() in the same file
were already corrected.
* feat(recall): configurable recency decay function (linear/exponential/none)
The recency boost in apply_combined_scoring hard-coded a linear decay over an
arbitrary 365-day window. Make the age->freshness curve configurable:
- linear (default, unchanged): straight decay to a 0.1 floor over a window now
exposed as HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS (365).
- exponential: 0.5 ** (days_ago / halflife); half-life is the age at which the
signal is neutral. Smooth, no hard cutoff.
HINDSIGHT_API_RECENCY_DECAY_HALFLIFE_DAYS (90).
- none: disables the recency boost entirely.
Selected via HINDSIGHT_API_RECENCY_DECAY_FUNCTION. Static config (read via
get_config() at the recall call site, mirroring recall_strategy_boosts).
* fix(test): accept new recency-decay kwargs in scoring stub; regen docs skill
The 'opinion' fact type was removed in v0.8.0 (#1917). The recall API now rejects it:
- response_models.py: VALID_RECALL_FACT_TYPES = frozenset(['world', 'experience', 'observation'])
- http.py (recall + reflect): fact_types: list[Literal['world', 'experience', 'observation']] | None
- models.py: CheckConstraint("fact_type IN ('world', 'experience', 'observation')")
Ten integration SDK packages still advertised 'opinion' as a valid recall_types/fact_types
value in public tool docstrings, one inline comment, and two README tables, so an agent
copying them passes a value the API 422-rejects. Completes the ripple started by #2198 /
#2302 / #2323 across the hindsight-integrations/* tail (text only, no logic change).
instructor 1.12.0 hard-depended on diskcache <=5.6.3, which has an
unpatched pickle-deserialization RCE (CVE-2025-69872 / GHSA-w8v5-vhqr-4h9v;
no fixed version exists). instructor 1.13+ moved diskcache behind an
optional `diskcache` extra, so upgrading to 1.15.3 removes it from the
resolution entirely.
- instructor 1.12.0 -> 1.15.3
- diskcache 5.6.3 removed from the lock
The runtime default for the anthropic provider is the self-updating alias
`claude-haiku-4-5` (config.py PROVIDER_DEFAULT_MODELS, enforced by
tests/test_provider_default_models.py), but the Models docs advertised the
date-pinned snapshot `claude-haiku-4-5-20251001`. A pinned snapshot and a
self-updating alias differ for pricing/retirement, and the page contradicted
hermes.md (which already says `claude-haiku-4-5`).
Sync the canonical sources (llmProviders.json default-model table +
models.mdx examples) to the alias and regenerate the docs skill mirror.
Mirror the XPU device-detection block #2260 added to LocalSTEmbeddings into
the byte-identical LocalSTCrossEncoder twin, so the local reranker also uses
Intel Arc XPU instead of silently falling back to CPU. Guarded by
hasattr(torch, 'xpu') + is_available(); no-op on CUDA/MPS/CPU.
The run-db-migration Options table listed only `--schema`, but the command
also exposes two operator-facing flags (hindsight_api/admin/cli.py):
- `--embedding-dimension` — enforce an expected embedding dimension after
migrations (omit to skip the dimension sync).
- `--skip-extension-reconcile` — added in #2309; skip the post-migration
vector/text-search index reconcile to speed up no-change re-migrations across
many tenant schemas when the backend is unchanged.
Add both rows to the canonical Options table and regenerate the docs skill
mirror.
The Next.js auth middleware buffers proxied request bodies and truncates
anything over its default 10MB limit before /api/files/retain can parse
the multipart form, so single uploads >10MB silently fail with
"Failed to parse body as FormData".
Set experimental.proxyClientMaxBodySize, defaulting to 100MB to match the
dataplane's HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE_MB default and
overridable via the new HINDSIGHT_CP_MAX_UPLOAD_SIZE env var (size string
or byte count).
Split the desktop-app setup into its own integration: a new 'Hermes
Desktop' gallery card + page (/sdks/integrations/hermes-desktop) covering
the in-app config flow (select Hindsight in Settings, fill Mode/API key/
API URL/Bank ID/Recall budget) with the two UI screenshots. Cross-linked
with the CLI/plugin Hermes page; the Hermes page keeps a tip pointing to
the desktop guide.
LangSmith SDK TracingMiddleware arbitrary server-side file read (HIGH),
fixed in 0.8.18; current >=0.6.3 floor permits vulnerable 0.6.3-0.8.17.
Same Transitive-dependency-security-fixes block as the urllib3/cryptography/
authlib/python-multipart floors; no uv.lock in this dir so no re-resolve.
* blog(openhands): add OpenHands persistent memory post
Walkthrough of the Hindsight OpenHands integration: native Streamable-HTTP
MCP server wired into config.toml (recall/retain/reflect tools) plus a
recall/retain rule written into AGENTS.md so the agent recalls at task
start and retains durable facts. Covers Cloud + self-host setup, the CLI
commands (init/status/uninstall), and per-project banks via --bank-id.
Co-branded cover image.
Expose --skip-extension-reconcile on run-db-migration (gates the per-tenant ensure_* reconcile, default off) and stop ensure_vector_extension from creating the unused global memory_units vector index for per-bank backends (verified via EXPLAIN; scann unaffected).
* fix(tests): reset config cache after vchord vector-extension tests to stop cross-test contamination
The ANN tests in test_link_utils.py monkeypatch
HINDSIGHT_API_VECTOR_EXTENSION (e.g. to "vchord"). That env var is read
through the process-global config cache (get_config()), and monkeypatch
reverts only the env var on teardown — not the cache. Once get_config()
caches "vchord", it persists for the rest of the xdist worker.
Every subsequent bank-creating test on that worker then builds per-bank
vector indexes with `USING vchordrq` against the pgvector-only test DB
and fails with:
asyncpg.exceptions.UndefinedObjectError: access method "vchordrq" does not exist
cascading across dozens of unrelated tests in the test-api shard
(test_list_documents, test_maintenance_routines, test_mental_models,
test_observations, ...). Because the leak depends on which worker first
populates the cache, the failure looked like a flaky, shard-specific
infra problem.
Fix: add an autouse fixture to the class that clears the config cache
before and after each test, so the cache is rebuilt from the current
env per test and "vchord" can't leak out.
* fix(tests): create multi-tenant maintenance schemas atomically
test_maintenance_multitenant provisions 100 tenant schemas by running
CREATE SCHEMA + 5×CREATE TABLE per schema. Each statement autocommitted,
so there was a window where a schema existed with only some of its
tables. The global maintenance routines (public.schemas_with_expired_rows
/ banks_needing_consolidation) discover schemas by table presence and are
exercised concurrently by test_maintenance_routines on another xdist
worker against the shared test DB. They would query a not-yet-created
table in a half-built schema and fail with:
asyncpg.exceptions.UndefinedTableError: relation "mt<hash>_NNN.memory_units" does not exist
Wrap the whole provisioning in a single transaction so the schemas
become visible to other connections only once fully built.
* fix(maintenance): skip schemas that vanish mid-scan in maintenance routines
public.banks_needing_consolidation() and public.schemas_with_expired_rows()
snapshot the schemas owning a target table from pg_class, then run a dynamic
query against each schema in turn. That is a TOCTOU race: a schema (or its
tables) can be dropped between the snapshot and the per-schema query — a tenant
being deleted, a tenant migration recreating tables, or (in the test suite) the
multi-tenant maintenance test creating/dropping ~100 schemas concurrently with
test_maintenance_routines on the shared DB. The query then aborts the whole
routine with:
relation "<schema>.memory_units" does not exist
relation "<schema>.audit_log" does not exist
Forward migration c7e9f1a3b5d2 redefines both routines (CREATE OR REPLACE,
public/base-run gated, PG-only) so each per-schema query runs in its own
subtransaction that skips the schema on undefined_table / invalid_schema_name /
undefined_column instead of failing the scan.
Adds a deterministic regression test (schema with memory_units but no banks
table) for the skip path.
* fix(tests): clear config cache after none-provider engine build to stop chunks-mode leak
test_memory_defense._make_minimal_engine() builds a MemoryEngine inside a
patch.dict that sets HINDSIGHT_API_LLM_PROVIDER=none. Constructing the engine
calls get_config(), repopulating the process-global config cache from the
patched env — and provider="none" forces retain_extraction_mode="chunks". When
patch.dict restores the env, the cache still holds the "none"/chunks config.
It then leaks to every later test on the same xdist worker: their retains run
in chunks mode (raw text, NO entity extraction), so unrelated assertions fail —
notably the test_observations entity tests ("John/Alice/Nexora entity should
exist"), which presented as a flaky, shard-specific failure (whichever entity
test landed on the poisoned worker).
Drop the config cache after the patched env is restored so the next get_config()
rebuilds from the real env. Reproduced deterministically:
pytest test_memory_defense.py::test_engine_memory_defense_shares_ext_ctx \
test_observations.py::test_entity_extraction_on_retain
# before: entity test FAILED (Insert unit_entities: 0 pairs)
# after: passed
The 'opinion' fact type was removed (alembic
g2h3i4j5k6l7_remove_opinion_fact_type; models.py CheckConstraint now allows
only 'world', 'experience', 'observation'), but a couple of agent-facing
surfaces still advertised it:
- hindsight-api-slim/hindsight_api/mcp_tools.py: the list_memories and
clear_memories docstrings tell agents to filter `type` by 'world',
'experience', or 'opinion'. An agent following the docstring now passes an
invalid fact-type filter.
- hindsight-docs cookbook quickstart: the "Memory Types" list still presents
'Opinion' as a current type ("four networks").
Replace 'opinion' -> 'observation' in the four MCP docstrings and drop the
removed Opinion entry from the quickstart memory-types list (four -> three
networks).
Setting HINDSIGHT_API_RETAIN_STRUCTURED_CHUNK_SIZE above
HINDSIGHT_API_RETAIN_CHUNK_SIZE and retaining a JSONL/conversation doc
with a line/turn over the chunk size crashed with:
asyncpg.exceptions.CardinalityViolationError:
ON CONFLICT DO UPDATE command cannot affect row a second time
The streaming retain pipeline pre-chunks each document once (one
chunk_index per piece) and then re-chunks every piece during extraction,
stamping all sub-chunks of a piece with that one chunk_index. When the
structured cap exceeds the chunk size, a pre-chunk could legitimately
exceed the re-chunk budget, so it re-split into several sub-chunks that
all derived the same chunk_id = {bank}_{doc}_{index} and collided in a
single upsert batch.
Fix makes chunk_text idempotent — re-chunking any chunk it returns is a
no-op:
- A lone JSON object (one JSONL line handed back) is kept whole up to the
structured limit instead of falling through to plain-text splitting.
- Oversized turns/lines are fragmented within min(structured_limit,
max_chars) so no fragment exceeds the re-chunk budget.
Adds idempotency unit tests and an end-to-end regression test.
hindsight-aider wraps the aider CLI: recalls project memory before each session (injected via --read) and retains the transcript after. Bank per git repo.
* fix(docs): use GitHub icon for agrasandhany integration
The agrasandhany gallery entry reused the Obsidian logo. Its repo lives
on GitHub, so point it at a GitHub mark instead.
* fix(docs): mark agrasandhany as community integration
It's authored by external contributor yugandhar-maram, not the Hindsight
team — switch type official->community and credit the author.
* test(retain): serialize multichunk sub-batch coverage test on worker_tests xdist group
test_subbatch_multichunk_coverage.py's async case submits via
submit_async_retain, which inserts parent/child rows into async_operations.
test_worker.py drives its own WorkerPoller.claim_batch() against the same pool,
so on different xdist workers the two files steal each other's pending rows.
Add the shared xdist_group("worker_tests") marker (matching
test_async_batch_retain.py and the other async-queue tests) so they serialize
on one xdist process. Follow-up to #2269.
* test(worker): scope claim_batch count assertions to the test's own bank
The xdist_group("worker_tests") marker only serializes the tagged
async-queue test files among themselves. It cannot stop test_retain.py
(not tagged) from scheduling a 'consolidation' async_operation in the
public schema while a worker poller test runs — WorkerPoller.claim_batch()
scans the whole schema, so that stray op gets claimed and the global
'assert len(claimed) == N' counts it (observed: assert 3 == 2 in
test_poller_discovers_tenants_dynamically).
Filter claimed tasks to the test's own bank_id before counting, matching
the existing 'my_claims' convention already used by ~10 tests in this
file. Covers the remaining global-count assertions in the public-schema
poller tests; the max_slots cap test and the isolated custom-schema test
are unaffected (their global counts are robust by construction).
* Instrument async worker completion path with operation metrics
The async worker never emitted hindsight_operation_operations_total /
_duration_seconds — record_operation() was only called from the synchronous
API layer. In prod, retain/reflect/consolidation run through the async worker,
so the Operations dashboard showed no retain activity and there was no
Prometheus signal for async throughput, latency or success/failure.
Emit operation metrics from the worker on terminal outcomes:
- Add MetricsCollector.record_operation_result(): direct (non-context-manager)
recording with an explicit success label, for paths that need success control
rather than the exception-based record_operation() CM. The CM now delegates
to it (no behaviour change, no duplication).
- In WorkerPoller._execute_task_inner, record source="worker" with success=true
on normal completion and success=false on failure. Deferrals (DeferOperation)
and retries (RetryTaskAt) are not terminal and are deliberately not counted.
- Normalise the retain operation_type variants (batch_retain,
file_convert_retain) onto operation="retain" so worker completions share the
API path's series, which the Operations dashboard keys off.
This makes async retain visible on the dashboard and gives a Prometheus signal
for async worker throughput and success/failure.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Harden worker metric: record outside executor scope + cover defer/retry
W1: recording the success metric inside the executor try meant a metrics
failure could be caught by the broad except Exception and mark a completed
task as failed. Record on terminal outcomes outside the exception scope and
guard the call so instrumentation can never flip terminal task state.
W2: add no-DB tests for _execute_task_inner asserting completion/failure emit
the metric (with success true/false, retain normalised) and that
DeferOperation/RetryTaskAt do not.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* style: apply ruff format
Satisfy verify-generated-files: blank line after _metric_operation_label and
single-line record_operation_result test call, per ruff format.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* docs: correct reflect coverage in worker metric comment
reflect runs only on the synchronous API path (execute_task has no reflect
branch), so operation="reflect" never emits with source="worker". Reword the
comment to list retain/consolidation and the other worker task types instead.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* metrics(worker): scope success label to completion-throughput, not failure-rate
Address review: the worker success label infers success from raise/no-raise, but
memory_engine.execute_task swallows deterministic failures (file_convert_retain,
non-retryable errors) — it marks the op failed and returns normally — so those
record success=true. Rather than re-engineer execute_task to thread status back,
narrow this metric's documented meaning to a completion-throughput signal and
defer authoritative failure visibility to the now-merged
hindsight_async_operations{status="failed"} gauge (#1987), which reads each
operation's final DB status.
- Reword the poller comment: success=false means the task raised to the poller
(unexpected / retry-exhausted); deterministic self-handled failures are not
captured here — point operators at the failed gauge.
- Add test_executor_self_handled_failure_records_success_by_design to lock the
intentional behavior so any future change to the inference is deliberate.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* test(worker): fold self-handled-failure case into the completion test
The separate test_executor_self_handled_failure_records_success_by_design
asserted nothing the completion test didn't: at the poller boundary a
self-handled failure is indistinguishable from a clean completion (both return
normally), and with the executor mocked there is no real mark-failed / DB status
to observe. Remove the duplicate and document the intentional scoping in the
renamed test_executor_returning_normally_records_success docstring instead.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Restore HINDSIGHT_API_MCP_INSTRUCTIONS for HTTP MCP servers.
Append the extra guidance only to retain and recall tool
descriptions, matching the original local MCP behavior without
changing reflect or other management tools.
Long-term memory for OpenHands via native Streamable-HTTP MCP: hindsight-openhands init wires the Hindsight MCP server into config.toml + a recall/retain rule in AGENTS.md.
* blog(freshness): add freshness-aware memory post
Concept deep-dive on how Hindsight tracks belief currency: the per-observation
freshness trend (new/strengthening/stable/weakening/stale, computed from evidence
timestamps over 30/90-day windows by density ratio) and the consolidation-lag
signal (up_to_date/slightly_stale/stale from pending memories), plus how the
reflect loop uses both to verify stale beliefs against raw facts.
The last entry had a trailing comma, so build-docs' 'Check integrations'
step (strict JSON.parse) failed on main and every PR. Drop it.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
These new integrations were added to VALID_INTEGRATIONS / CI but not to the
generate-changelog registry, so release-integration.sh failed at the changelog
step. Add their package names so releases can be cut.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
MCP-only Zed integration: hindsight-zed init wires the Hindsight MCP server into Zed's settings.json (via mcp-remote) plus a recall/retain rule in AGENTS.md. Validated end-to-end in real Zed.
The "computed freshness trend (stable/strengthening/weakening/new/stale)"
described across the developer docs maps to code in
reflect/observations.py that is unreferenced — not wired into recall,
reflect, or the API, and absent from the OpenAPI schema. It is not a
surfaced feature, so the docs overstated it.
Replace those claims with the freshness behavior that IS shipped: when
newer memories haven't been consolidated yet, reflect treats the affected
observations as stale and verifies them against raw facts. Touches
developer/index, observations, configuration, api/recall, and
best-practices, plus the regenerated skills/hindsight-docs mirror.
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Ingesting a large single document (~88k chars) dropped most of its body — and
any fact past the first slice — when retained. Two bugs, both only triggered when
an oversized item is split into sequential sub-batches whose slices each re-chunk
into several extraction chunks (the default config: batch tokens 10k → ~30k-char
slices, re-chunked at 3k → ~10 chunks/slice):
1. chunk_index offset (sync + async). retain_batch_async advanced the
per-document chunk_index cursor by re-chunking item["content"] AFTER the
orchestrator had consumed (popped) it. chunk_text("") returns [""] (count 1),
so the cursor moved by 1 per sub-batch instead of by the real chunk count;
later slices restarted ~1 slot in, colliding chunk_id = {bank}_{doc}_{index}
and overwriting earlier chunks via upsert. Fix: count the slice's chunks
before handing it to the orchestrator, while content is still present.
2. whole-document recovery skip (async only). All sub-batches of one submitted
operation share one operation_id; the first slice stamps the document into
result_metadata.facts_committed_document_ids. The crash-recovery fast-path
then saw every later slice's document already "committed" and skipped
extraction entirely, so only the first slice survived. Fix: only take the
whole-document skip when the call starts the document at chunk 0
(chunk_index_offset == 0); a non-zero offset means this call continues a
document another sub-batch already started. Per-chunk hash recovery
(existing_chunk_hashes) still provides crash-safety for those chunks.
The existing #1888 coverage tests use RETAIN_BATCH_TOKENS=100 (a ~300-char
budget, under the chunk size) so every slice collapses to ONE chunk, which masks
both bugs. New test_subbatch_multichunk_coverage.py sizes the body so each slice
fans out to ~6 chunks, with globally-unique tokens (no chunk-hash dedup), and
asserts full coverage + contiguous chunk_index + a needle planted in a late slice
across BOTH the sync (retain_batch_async) and async (submit_async_retain) paths.
extract_facts_from_text reads config.retain_structured_chunk_size (passed
to chunk_text), but the test's SimpleNamespace mock only set
retain_chunk_size, so the test raised AttributeError instead of exercising
the quota-defer path. Add the field (None = plain chunking) to fix it.
#1968 moved routing metadata out of the transcript (it no longer prepends a
'[context]' system message) and into the retain API context field, but left
three agent_end integration assertions on the old shape:
- transcript no longer starts with a {role:'system', '[context]...'} entry
- message_count reflects the structured turn length without the system pad
(1 for a single-user turn, 2 for the last user+assistant turn)
Updates index.test.ts's sibling integration tests to match.
Extend local device detection so sentence-transformers can use an Intel
XPU (e.g. Arc A770) when a torch XPU build is loaded, falling back to CPU
otherwise. Split out from #2233.
Co-authored-by: Sveinbjörn Geirsson <raudbjorn@github>
The MCP `reflect` tool returned the full `reflect_async` result, which
includes `tool_trace` and `llm_trace` — the entire internal agent loop,
including full mental-model text. A default reflect response measured
59,657 chars (text 5,987 + tool_trace 52,711), silently consuming tens
of KB of MCP-client context on every call, while the REST API omits the
trace by default.
Add a symmetric `include_trace: bool = False` flag (mirroring the
existing `include_based_on`); the trace becomes opt-in for debugging.
Applied to both the multi-bank and single-bank reflect registrations,
with a regression test covering both.
* feat(openclaw): pass retain context guidance to prevent routing metadata misattribution
Hindsight's fact extraction LLM was misinterpreting routing identifiers
(sender open_id, bank ID, channel, provider) as semantic actors, project
names, or organizations. After many conversation turns, the bank name
(e.g. saber-prod) would override the actual project being discussed
(e.g. x-power-cli).
This adds interpretation guidance via the retain API 'context' field:
- New DEFAULT_RETAIN_CONTEXT constant explains that [context] block
sender/channel/provider are routing identifiers, not human names
- Bank IDs, session keys, agent IDs, thread IDs, and tags are also
marked as operational routing identifiers, not project names
- Assistant-role first-person statements are attributed to the AI
- Context is passed through the full chain: buildRetainRequest →
scopeClient.retain → Hindsight SDK API
- RetainQueue persists and flushes context correctly
- Backfill CLI also passes context
- New 'retainContext' config option allows customization
includeSenderContext behavior is unchanged; the [context] block remains
in transcript content, but extraction LLM now knows how to interpret it.
7 files changed, 97 insertions(+).
* fix(openclaw): remove platform-specific examples from DEFAULT_RETAIN_CONTEXT
* test(openclaw): harden retain context handling
* fix(openclaw): strip runtime metadata from memory content
* refactor(openclaw): remove dead session-context surface
Following the removal of transcript context-prepending, drop the now-unused
formatRetentionSessionContext / RetentionSessionContext and the ignored
prepareRetentionTranscript session-context parameter (and the discarded
object built at the live call site). Remove the inert includeSenderContext
config option (no longer read) from the type, manifest schema, and UI label.
Collapse the session-context tests to two regression guards asserting that
retained JSON/text content carries no context header.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
list_banks now overlays resolved bank config (reflect_mission + disposition_*) on top of the legacy banks.disposition/banks.mission columns, matching get_bank_profile so the list and get paths agree for a bank.
Overlay extracted into a shared helper returning a ResolvedDispositionMission dataclass. Config is resolved in one batch (single banks.config query + one tenant resolve) via ConfigResolver.get_bank_configs(), avoiding an N+1 of per-bank config resolves.
Co-authored-by: Timur Khairutdinov <[email protected]>
* feat(metrics): expose async-operation queue + consolidation backlog as gauges
The bank-stats endpoint already computes operations_by_status,
pending_consolidation and failed_consolidation, but only as a point-in-time
HTTP response per bank. There's no way to trend or alert on "is the worker
keeping up?" / "is the knowledge base caught up?" from Prometheus.
This adds three observable gauges, fed by a 30s background-refresh cache (the
same pattern as the existing db-pool gauges, so the /metrics scrape path stays
synchronous):
- hindsight_async_operations{operation_type,status} -- worker queue depth for
non-terminal states. pending = queued backlog (e.g. retain / consolidation),
processing = in-flight, failed = stranded. Terminal states (completed,
cancelled) are deliberately excluded: a gauge of finished work grows without
bound and says nothing about current load. The processing series is the only
signal that surfaces a hung operation holding a worker slot.
- hindsight_consolidation_backlog -- source memories (experience/world) not yet
consolidated into observations (pending_consolidation).
- hindsight_consolidation_failed -- source memories whose consolidation
permanently failed, recoverable via the consolidation recovery endpoint
(failed_consolidation).
The SQL is lifted from the bank-stats endpoint and is index-backed
(idx_async_operations_status, idx_memory_units_unconsolidated). Per-bank labels
are gated behind the existing metrics_include_bank_id flag (off by default);
when off, counts aggregate per tenant/schema, bounding cardinality to a handful
of series. All queries are PostgreSQL-specific (FILTER, information_schema),
consistent with this collector already being bound to an asyncpg pool.
* review: address feedback on backlog metrics
- Split the consolidation backlog into two separate COUNT(*) queries, each with
a WHERE matching a partial-index predicate exactly (idx_memory_units_
unconsolidated / idx_memory_units_consolidation_failed), instead of one
aggregate with two FILTERs that seq-scans the whole memory_units table on
every 30s refresh across every schema. GROUP BY bank_id still composes
(bank_id is each index's lead column).
- Type the gauge cache keys as NamedTuples (_AsyncOpKey, _BacklogKey) instead of
raw tuples.
- Hoist `import asyncio` to module scope (was imported inside two methods).
- Document that _backlog_task is process-lifetime and intentionally not
cancelled (no teardown hook to hang it on).
- Add tests for the per_bank=True path (bank_id in the cache key + GROUP BY
bank_id in the SQL + bank_id gauge attribute) and assert the backlog queries
are index-matched, not FILTER scans.
* fix(metrics): force index scan for the consolidation backlog count
Splitting the consolidation count into two index-predicate-matched COUNT(*)
queries fixed the failed count (index-only scan) but NOT the backlog count.
Verified on a 114k-row memory_units via EXPLAIN ANALYZE: the backlog query still
seq-scans (~92 ms) because `consolidated_at IS NULL` is true for ~40% of the
table (every observation has a null consolidated_at), so the planner misjudges
selectivity and won't use idx_memory_units_unconsolidated even though the
predicate matches it exactly. ANALYZE doesn't change the plan (structural, not
stale stats); `enable_seqscan=off` confirms the index is usable (~0.1 ms).
Run the backlog count in a scoped transaction with SET LOCAL enable_seqscan=off
to force the partial-index scan (verified ~0.07 ms, transaction-scoped, no
leak). The failed count needs no nudge — consolidation_failed_at IS NOT NULL is
rare, so its index is chosen on cost.
* feat(metrics): gate consolidation backlog gauges behind config flag (off by default)
Add HINDSIGHT_API_METRICS_BACKLOG_ENABLED (default false). The
async-operation queue + consolidation backlog gauges run periodic
per-schema COUNT queries on a background task, so they are now opt-in
rather than always-on when a db pool is set.
* chore: sync embed env template + prettify paperclip README after main merge
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Add an optional `content_length: int | None` field to `PrecheckContext`
and populate it from the request's `Content-Length` header in the
`_precheck_dep` FastAPI dependency wired by the billable POST routes.
Surfacing the header lets a precheck make size-aware decisions — for
example, computing an upper-bound cost estimate (`bytes / tokens-per-byte
* per-op-rate`) and rejecting before the body is read or deserialised —
without changing the contract that the precheck runs before body parse.
The field is optional with a default of `None`, so existing
`OperationValidatorExtension` implementations and `PrecheckContext`
construction sites are unaffected. `None` also remains the value when
the header is absent (e.g. chunked transfer encoding) or unparseable;
`0` is preserved as a known empty body.
Adds three tests in `TestPrecheckHttpWiring`:
- header populated → validator sees the int
- empty POST body → validator sees `0`, not `None`
- header missing → validator sees `None`
Some LLMs return source_fact_ids as a string instead of a list when there is only one source ID. Add field_validator on both _CreateAction and _UpdateAction to auto-wrap into a single-element list.
Relates-to: #1656
* feat(mcp): add ToolAnnotations (read-only/destructive hints) to MCP tools
All MCP tools registered with bare @mcp.tool() and exposed no annotations,
so clients (claude.ai, Notion, …) could not group read vs write tools,
surface a destructive-action warning for delete_bank / clear_memories, or
auto-approve safe reads.
Add a _tool_annotations() helper that classifies each tool as read-only,
destructive, or plain write, and apply it to every registration.
openWorldHint=False throughout (closed memory store). Pure metadata — no
behavioural change.
reflect is classified as a (non-destructive) write because it can form and
persist opinions during synthesis; flip it to readOnlyHint=True if the
engine never persists on reflect.
* fix(mcp): classify reflect as read-only (engine persists nothing)
---------
Co-authored-by: Nicolò Boschi <[email protected]>
The consolidation summary log used to print only the total time per phase:
[4] Timing breakdown: recall=15.425s, llm=43.181s, embedding=0.301s
This makes it easy to misread the "recall=15s" line as a single slow query
when it is actually the sum of many sequential sub-calls (e.g. 100 internal
recalls at ~150ms each). Add a call counter to ConsolidationPerfLog and
include both the count and a per-call average when count > 1:
[4] Timing breakdown: recall=15.425s (100 calls, avg=154ms),
llm=43.181s (12 calls, avg=3598ms),
embedding=0.301s (3 calls, avg=100ms),
db_write=0.829s
Operators triaging "the recall phase took 15s" can now tell at a glance
whether the cost is one slow query or many fast ones, which leads to very
different diagnostic paths. Single-call timings keep the existing terse
format (no `(1 calls, ...)` clutter).
Backward-compatible: timing_counts is a new attribute; existing accessors
on `timings` and `llm_calls` keep their current semantics.
* fix(litellm): cap completions with asyncio.wait_for so a hung call can't block forever
The LiteLLM provider issued completions as a bare `await self._acompletion(...)`.
The only timeout was the `timeout=` kwarg handed to `litellm.acompletion()`,
which is not always honored (e.g. a connection held open with no token
progress). When that happens the coroutine awaits indefinitely, holding the
worker slot and a concurrency-semaphore permit for the lifetime of the process.
Fact extraction fans these calls out through `asyncio.gather`, so a single
hung straggler stalls the whole operation even though its sibling calls
returned — completion throughput collapses to zero while sibling calls keep
succeeding, which makes the failure mode hard to diagnose.
Wrap the request in `asyncio.wait_for(timeout=self.timeout)` in both `call`
and `call_with_tools` (mirroring the Gemini provider, which already does this)
and treat the resulting `TimeoutError` as a normal retryable attempt, so the
task can retry or fail cleanly and release its slot. The existing
`asyncio.gather(..., return_exceptions=True)` callers absorb the timeout with
no extra handling.
Also thread an optional `timeout` through `create_llm_provider` and
`LLMConfigWrapper` into the LiteLLM/Bedrock/Router providers so the cap is
configurable; `None` keeps the existing 300s default (never `None`, which
would make `wait_for` wait forever).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* fix(litellm): make the hard-timeout cap configurable and converge timeout handling
Builds on the asyncio.wait_for cap added for the LiteLLM family:
- Wire LLMProvider.from_env() to read HINDSIGHT_API_LLM_TIMEOUT (default
DEFAULT_LLM_TIMEOUT = 120s). The cap was threaded through the constructors but
never set by from_env(), so it silently defaulted to 300s and was not
configurable. This matches how the OpenAI-compatible provider already reads the
same var. Also fix the stale openai-compatible docstring that claimed 300s.
- Converge timeout handling: litellm's own Timeout and the outer wait_for
TimeoutError are armed at the same deadline but previously flowed through
different except blocks (generic vs dedicated), so which one tripped was a race
producing different log lines and backoff. Catch both in one block so they
share a retry policy and log line; log the exception class name so the firing
mechanism stays visible.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* refactor(litellm): hoist litellm Timeout import to module level
Address PR review (r3421670469): litellm is a hard dependency already imported
in __init__, so the per-call function-local `from litellm.exceptions import
Timeout` in call/call_with_tools is unnecessary. Hoist to a module-level import,
matching how gemini_llm imports its SDK.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
MarkItDown advertises image extensions, but without OCR config it can
fail screenshots or scanned images with low-level no-content errors.
Add server-level MarkItDown OCR config that is off by default and
independent from HINDSIGHT_API_LLM_*. When OCR is enabled, the OCR API
key, base URL, and model are required explicitly.
Wire those settings into MarkItDown's llm_client support with a built-in
OCR prompt. Image uploads now fail fast with actionable errors when OCR
is disabled or required settings are missing.
Docs and front-end copy explain that image OCR depends on server config
and requires an OpenAI-compatible OCR/vision endpoint.
Closes#927
http_metrics_middleware normalizes only UUID and pure-numeric path
segments, so non-numeric bank ids (e.g. user-123, tenant-acme) survive in
the /banks/<id> segment of the `endpoint` metric label. Each distinct bank
then becomes a never-evicted OTel series, growing process memory unboundedly
on every per-bank request.
Same unbounded-OTel-cardinality class as #850 (fixed in #898 for the
record_operation bank_id attribute), via a code path #898 did not cover.
Extract endpoint normalization into a pure, unit-tested normalize_http_endpoint()
helper in metrics.py (next to get_token_bucket) that also templates the
/banks/<id> segment, and call it from the middleware.
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
derive_bank_id compared os.path.normpath(cwd) against the map keys with
==, which is case-sensitive — but on Windows the drive-letter case of the
cwd a session reports depends on the launcher: PowerShell and git-bash
hand child processes an UPPERCASE drive (C:\...) while the VS Code
extension spawn reports lowercase (c:\...). cmd.exe preserves whatever
case was typed. A directoryBankMap entry can therefore silently miss for
some launchers and fall through to the default bank, with no error —
sessions quietly land in the wrong memory bank.
Fix: wrap both sides in os.path.normcase, which lowercases and normalizes
separators on Windows and is a documented no-op on POSIX — so POSIX path
matching stays case-sensitive (pinned by a new test) and Windows matching
becomes launcher-independent (pinned by a new test that fails without
this change).
Co-authored-by: Claude Fable 5 <[email protected]>
run_mcp.sh's resolve_py() probed only <venv>/bin/python and
<venv>/bin/python.exe. A standard Windows CPython venv (python.org
installer, Windows Store Python, `py -m venv`) puts the interpreter at
<venv>/Scripts/python.exe, so resolve_py returned empty, the launcher
fell through to venv re-creation, and re-creation failed whenever
python/python3 were not on the spawning process's PATH (issue #1758, 3a).
Add a Scripts/ elif branch and update the now-misleading "venv create
failed" message to mention both layouts. POSIX behaviour is unchanged.
Adds a hermetic pytest that invokes the real bash resolve_py against a
fabricated venv tree: RED on the Scripts/ layout before this change,
plus a bin/ regression guard for the POSIX path.
Co-authored-by: Claude Opus 4.8 <[email protected]>
retainDocumentScope was always meant to be 'session'; the 'turn' option
just disabled document accumulation. Remove the config field entirely so
retains always use a stable per-session document id (falling back to
per-turn ids only on legacy APIs that lack update_mode: 'append').
Codex authentication previously hardcoded ~/.codex/auth.json in several
places. Route all Codex auth/LLM/embeddings paths through a single
default_codex_auth_file() helper that honors the CODEX_HOME environment
variable (matching the upstream @openai/codex CLI), falling back to
~/.codex when unset or empty.
Adds tests for the resolution logic and hardens an existing embeddings
test against CODEX_HOME leaking in from the environment.
Co-authored-by: Nicolò Boschi <[email protected]>
Remove .github/dependabot.yml to stop Dependabot from opening
automated version-update PRs (github-actions ecosystem).
Note: Dependabot security updates are controlled by a repository
setting, not this file, and must be disabled separately in repo
settings if desired.
Adds HindsightClient.get_version()/aget_version() convenience wrappers for
the existing /version endpoint, re-exports VersionResponse for typed callers,
and tests both paths against a mocked MonitoringApi.
Python parity for #2252 (TypeScript getVersion). Fixes#2248.
The reasoning-tag strip in OpenAICompatibleLLM.call() only ran inside the
`if response_format is not None:` (structured/JSON) branch. The `else:` branch
that returns free-form, non-structured output (e.g. consolidated mental-model
markdown) returned the raw provider content with no strip at all. Reasoning
models that emit their chain-of-thought in the response body — confirmed with
MiniMax-M3 — therefore leaked `<think>...</think>` verbatim into stored mental
models.
Additionally, every existing strip regex used the lazy `<tag>.*?</tag>` form,
which requires a closing tag. When output is truncated mid-thought the closing
tag never arrives, so a dangling `<think>` slipped through even on the JSON path.
Fix:
- Factor a module-level `_strip_reasoning_tags(text)` helper covering the full
tag set (think, thinking, thought, reasoning, |startthink|...|endthink|).
- For each tag, strip closed blocks (`<tag>...</tag>`, DOTALL) and then any
remaining unclosed block (`<tag>.*` to end-of-string).
- Call it from BOTH branches: the structured path (replacing the inline regex
block) and the free-form path (which previously had no strip).
Adds tests/test_strip_reasoning_tags.py covering closed/unclosed blocks, all
tag styles, multi-line and multi-block input, and the real-world mental-model
markdown contamination case.
Co-authored-by: Claude Opus 4.8 <[email protected]>
* feat(composio): add Composio integration (Hindsight memory as custom tools)
Exposes Hindsight retain/recall/reflect as Composio in-process custom tools via
register_hindsight_tools(). The Hindsight bank for each call is the Composio
session's user_id, so one registered tool set isolates memory per user
automatically. Also ships memory_instructions() for pre-recall system-prompt
injection (Composio doesn't auto-inject context).
- hindsight_composio/: tools.py, config.py (dataclass + env fallback), errors.py.
- tests/: 50 tests using a FakeComposio (mirrors the real tool decorator +
SessionContext) + mocked Hindsight client — exercises the framework wiring.
- CI: test-composio-integration job (uv build/sync/ruff/pytest) + path filter.
- Gallery card + doc page + official Composio icon; release-integration.sh entry.
* fix(composio): register in changelog generator + test memory_instructions
- Add composio to generate_changelog.py INTEGRATIONS dict (release would
otherwise fail at the changelog step; it was only in release-integration.sh).
- Add TestMemoryInstructions covering formatting, max_results cap, empty/error
fallback, tag passthrough, and missing-config error.
* address review: Literal config types, typed generics, debug log, real-LLM E2E
- Type budget as Literal[low|mid|high] and tags_match as Literal[any|all|
any_strict|all_strict] across config + tools (matches autogen/continue)
- Parameterize bare list -> list[Any] on register_hindsight_tools
- _ensure_bank: logger.debug the swallowed create_bank failure so a real
auth/network error is visible rather than only surfacing later on retain
- Add requires_real_llm E2E bucket exercising retain/recall/reflect through
the (input, ctx) tool call path against a live Hindsight server; exclude
from PR CI via -m 'not requires_real_llm'
* blog(obsidian): add Obsidian persistent memory post
Walkthrough of the Hindsight Obsidian plugin: one-way vault sync into a
memory bank, grounded chat panel backed by reflect with note citations
and a reasoning disclosure, implicit vault/folder/date scoping, and the
"vault stays the source of truth" design rule. Includes a beta/BRAT
install callout (plugin v0.1.2) and Cloud vs self-hosted setup.
* fix(control-plane): expose "shared" observation scope in the Add Document UI
#2202 added the 'shared' observation-scopes mode and synced it across the server,
HTTP model, retain types, and every client (incl. the control-plane client type in
api.ts), but missed the GUI component itself, so users could not select 'shared'
from the Add-Document form. Wire it through bank-selector.tsx: state union, dropdown
item, request build, and a dedicated preview line ('shared' is tag-independent and
maps to a single global scope [[]] server-side). No locale/generated-file changes.
* fix(control-plane): translate shared observation scope copy
---------
Co-authored-by: r266-tech <[email protected]>
Reverts the stale-routine fallback added in #1666. That change re-ran the
per-schema EXISTS scan whenever the default schema was absent from the
routine result — i.e. on every idle poll, since public is almost always in
scope and usually has no pending work. The scan covered ALL schemas, so it
reintroduced the exact N-query storm the routine exists to avoid, precisely
in the large multi-tenant deployments the optimisation targets.
The routine is now trusted wholesale: any schema it does not return is
treated as having no work this cycle (its documented contract). The #1555
concern (an operator routine scoped to tenant_% starving a single-tenant
public deployment) is addressed by guidance instead: do not install the
routine in single-schema deployments — the per-schema fallback is a single
cheap EXISTS check that covers public correctly and cannot starve.
The only piece kept from #1666 is the harmless public->None normalisation
of the routine's output, so a returned 'public' still counts as work.
LLM-trace recorders live in a process-global registry and providers fan every
call out to ALL registered recorders. The engine test fixtures' teardown gated
`mem.close()` — the only thing that unregisters the recorder — on
`mem._pool and not mem._pool._closing` and swallowed exceptions, so when close()
was skipped or raised before the unregister step, the recorder leaked. A leaked,
still-enabled recorder from an earlier test then recorded a later test's LLM
calls into the shared DB, making test_disabled_writes_no_rows flaky
(`assert 6 == 0`).
Route all four engine fixtures through a `_teardown_memory_engine` helper that
always unregisters the recorder in a `finally` (idempotent — no-op when close()
already did it). Add a fast regression test asserting the registry is left clean
even when close() is skipped.
#2209 (d4f6a8c2e1b3, drop archive embedding column) and #<links-index>
(2071c7518f88, add memory_links index) were authored off the same parent and
merged in parallel, leaving the DAG with two heads. `alembic upgrade head`
is ambiguous in that state and CI's test_single_head fails for everyone.
Add a no-op merge revision unifying both heads.
The `exact` set-equality match mode landed in the API + generated clients
in #2149 but was never exposed in the control plane, documented, or added
to the hand-maintained SDK wrappers. This completes the feature.
Control plane: add `exact` to the TagsMatch type/unions and to the
tags_match dropdowns in think-view, search-debug-view, and both
mental-model trigger forms; add translated labels to all 10 locales.
Docs: document `exact` in the recall tags_match table + tag_groups,
the reflect tags value list, and the observations scope-listing guide;
regenerate the docs skill mirror.
Clients: add `exact` to the hand-maintained Python and TypeScript wrapper
Literals/unions and docstrings (generated clients already had it; Rust is
generated from openapi.json at build time).
Supersedes #2159.
Add a vitest guard that walks every src .ts/.tsx file, resolves each
useTranslations("ns") binding, and asserts every static t("key") /
t.rich("key") reference maps to a leaf key in en.json. This closes the
gap between the two existing i18n checks: messages.test.ts only compares
locale catalogs against each other (a key missing from *every* catalog,
en included, passes parity), and find-untranslated.ts does the inverse
(flags strings *not* wrapped in t()). Neither walked from a t() call
site back to the catalog, so a missing key only surfaced as a runtime
next-intl error in the browser.
Runs under the existing `npm test` step in the build-control-plane CI
job, so no workflow change is needed.
The guard immediately surfaced 14 keys referenced by the curation
feature (#1976) but missing from all 10 catalogs (filterActive,
filterInvalidated, invalidatedHint, invalidatedFactsTitle, and the
memoryDetailPanel curation*/editField* set). Add translations for all
locales so the suite is green. Supersedes #2226, which patched only
filterActive.
* fix(mcp): give update_memory/invalidate_memory non-empty descriptions
update_memory and invalidate_memory (added in #1976) used an f-string as
their docstring:
f"""{_EDIT_DOC}
Args:
...
"""
An f-string is an expression, not a string literal, so Python never assigns
it to the function's __doc__ (it stays None). FastMCP derives a tool's
description from __doc__, so both tools — and their bank_id variants — were
registered with an empty description.
Amazon Bedrock's Converse API rejects any toolSpec whose description is an
empty string, so every Bedrock request that advertised these tools failed
mid-stream (surfacing to clients as a generic 'internal error occurred while
processing the stream'). Providers that tolerate empty descriptions were
unaffected, which is why this only showed up on Bedrock.
Fix: pass the shared doc constant explicitly via @mcp.tool(description=...),
matching how retain/recall already register, and keep a plain-literal
docstring for the Args section. Add a regression test asserting every
registered tool exposes a non-empty description (both registration paths).
* test(mcp): statically reject @mcp.tool definitions without a description
AST-parse mcp_tools.py and fail if any @mcp.tool-decorated function
lacks both a description= kwarg and a real string-literal docstring
(an f-string docstring leaves __doc__ None). Complements the runtime
description test by also covering flag-gated tools and pointing at the
offending line; needs no engine mocking.
* chore(lint): enable ruff B021 (f-string used as docstring)
Catches the f-string-docstring footgun repo-wide at lint time — the
root cause of the empty update_memory/invalidate_memory descriptions.
Clean across hindsight-api-slim; tests/** are excluded from lint so the
static test guards that surface instead.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
test_migration_remaining_bank_id_text.py runs two tests that share a
module-scoped pg0 instance on a fixed port (5568). CI runs pytest with
`--dist loadgroup`, which — with no xdist_group on the module — can scatter
those two tests across workers that each instantiate the module fixture and
race to provision the SAME instance. That surfaced as recurring flakes:
"Instance already running", a pg_type UniqueViolation (concurrent CREATE
EXTENSION during migrate-to-head), and "server closed the connection".
Pin the module to a single worker with a shared xdist_group so the fixture
provisions the instance exactly once. Test-only change.
The memories.py API doc example ran update_memory edit → edit-fields →
invalidate → restore back-to-back on the same unit. Each edit re-embeds and
re-consolidates in the background (a tracked consolidation op), so a later
step could race that work and 404 on a unit mid-rewrite — the restore
intermittently failed with "Memory unit not found". The fixed sleep(3) after
the seed retains was also unreliable under CI load with a live LLM.
Replace the sleep with a wait_for_idle() helper that polls list_operations
until the bank has no pending/processing operations, and drain between each
curation step. All waits sit outside the [docs:...] blocks, so the rendered
documentation snippets are unchanged.
POST .../memories/dry-run-extract (added in #2205, enabled by default) makes a
real LLM call but was the only enabled-by-default LLM-billable route with no
OperationValidator gating. Wire Depends(precheck_for("dry_run_extract")) like
retain/recall/reflect/mental_model_*/files_retain, and move the feature-flag
check into a dependency declared before the precheck so a disabled route still
returns 404 first. No behavior change when no validator is configured.
* perf(api): index memory_links.bank_id on PostgreSQL
bank_id was added to memory_links in c5d6e7f8a9b0 so bank-scoped reads could
filter the link table directly instead of joining memory_units (an 18s+ JOIN on
large banks), but it landed without an index, so every bank_id = $1 predicate
still sequential-scans the whole table.
Add the missing btree, built CONCURRENTLY inside an autocommit_block with IF NOT
EXISTS for idempotency across retries and re-migrated tenant schemas. The Oracle
baseline (o1a2b3c4d5e6) already creates idx_ml_bank_id on memory_links(bank_id);
this brings the PostgreSQL dialect in line. PG-only by design, so the Oracle
slot is intentionally absent.
* fix(migration): drop invalid leftover index before recreating bank_id index
CREATE INDEX CONCURRENTLY can leave an INVALID index behind if a prior
build is interrupted (lock conflict, disk pressure, signal). IF NOT EXISTS
would then skip recreation, leaving bank_id queries on a seq scan forever.
Drop only an invalid leftover of this name (never a healthy index) before
the concurrent (re)build, mirroring b8c9d0e1f2a3.
* perf(api): composite (bank_id, link_type) index + drop dead entity filter
The stats endpoint's bank-scoped link query is
SELECT link_type, COUNT(*) ... WHERE bank_id = $1 GROUP BY link_type
A composite (bank_id, link_type) index serves the filter, grouping and
count as an index-only scan, vs a bank_id-only index that still heap-reads
every row to recover link_type. link_type is low-cardinality so the extra
column barely grows the index.
Also remove the now-dead 'link_type <> entity' predicate from the stats and
graph-expansion queries: entity edges were deleted from memory_links and are
no longer written (migration e9b2c7d1f3a4); they're derived on demand from
unit_entities. Removing the predicate also lets the composite index cover
the stats query.
---------
Co-authored-by: zommiommy <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
Move explicit period extraction out of DateparserQueryAnalyzer. The analyzer
now delegates range parsing to temporal_periods, which keeps the public API and
non-Chinese rules while Chinese-specific rules and boundary handling live in
chinese_temporal_periods.
Handle simplified and traditional Chinese expressions for relative days,
weeks, months, years, weekends, half-year periods, Chinese month names,
quarters, and rolling past/future windows.
Separate precise point expressions from fuzzy range expressions so phrases such
as 两天前, 前两天, 几天前, and 一两周前 map to the intended constraint shape
instead of relying on dateparser fallback behavior.
Keep open future starts such as 明天起, 下周起, and 三天后开始 unconstrained
because the API only represents closed ranges.
Guard Chinese matching so non-CJK queries skip the Chinese regex path, while
Chinese substring checks avoid treating ordinary names and words as temporal
constraints.
* fix(curation): drop embeddings from invalidated_memory_units archive (#2209)
Invalidating a memory copied the live row — including its embedding —
into the invalidated_memory_units archive via INSERT … SELECT. After an
embedding-model switch, the live tables are re-dimensioned but the
archive is not, so the move failed with "expected 384 dimensions, not
1536".
The archive is cold storage and never a recall surface, so it has no
business keeping an embedding. Instead of also migrating its dimension,
stop storing the embedding there at all:
- invalidate: project NULL into the embedding slot on the move
- revert: recompute the embedding from text/dates/entities (mirroring
how an edit re-embeds) so the reverted unit is searchable again
This makes the archive's embedding-column dimension irrelevant, so a
model switch can no longer trip a dimension mismatch. A forward
migration clears any embeddings earlier versions already stored.
* refactor(curation): drop the archive embedding column instead of NULLing it
Make "the invalidated_memory_units archive holds no embedding" a
schema-enforced invariant rather than a convention the move queries must
remember. The embedding column is dropped (migration d4f6a8c2e1b3, PG +
Oracle), so:
- invalidate moves every memory_units column EXCEPT embedding into the
archive
- revert moves them back (live embedding defaults to NULL) and recomputes
the embedding from text/dates/entities
This structurally prevents #2209 — there is no archive vector to fall out
of sync with the live model's dimension, so a model switch can't reintroduce
the dimension mismatch via a future code change. DROP COLUMN is metadata-only
on both dialects.
The archive's readers (get_memory_unit/list enumerate columns; export does
SELECT * then strips derived columns) never referenced embedding, so nothing
breaks.
* refactor(curation): never create the archive embedding column
Remove the embedding column at its creation sites rather than creating it
and dropping it afterward:
- PG: c9a1b2d3e4f5 drops the LIKE-inherited embedding right after cloning
invalidated_memory_units from memory_units
- Oracle: the baseline CREATE TABLE no longer lists the embedding column
The forward drop migration (d4f6a8c2e1b3) stays as a no-op (DROP … IF EXISTS /
Oracle ORA-00904 swallow) on fresh databases and does the real drop on
databases created before the column was removed here.
The MDX→skill converter in scripts/generate-docs-skill.sh only handled
:::tip / :::warning / :::note, and each rule required an inline title.
So :::info and :::caution admonitions — and any title-less opener (e.g.
a bare :::note) — were left as raw `:::` markdown in the CI-enforced
agent-facing skill mirror (skills/hindsight-docs/references/**), where the
generic `:::\s*\n` cleanup then ate the closing fence and the admonition
body bled into the following section.
Most visibly, #2202 added a :::caution "shared vs [[]] vs []" warning to
retain.mdx, which now renders as broken raw markdown in retain.md.
Teach the converter every supported keyword (tip/note/warning/info/caution)
with an optional inline title, mapping each to a blockquote (title-less
openers fall back to the capitalized keyword). Regenerated the skill mirror;
this also repairs pre-existing :::info/:::caution/title-less leaks across the
core API reference docs.
Note: source files that are plain .md (e.g. configuration.md) are copied
verbatim by the generator rather than run through this converter, so their
admonitions are unaffected here — happy to extend the converter to that
copy path in a follow-up if desired.
Adds hindsight-continue: Hindsight memory for Continue.dev via its native http context provider (@hindsight recall) plus an optional MCP-server + rules setup. Includes the adapter package, tests against Continue's HTTP contract + a gated E2E, CI job, release registration, docs, and registry entry.
* feat(zapier): add Hindsight Zapier app (actions + REST Hook triggers)
A Zapier Platform CLI app that brings Hindsight memory into Zaps.
Actions:
- Retain Memory (create) -> POST /v1/default/banks/{bank}/memories
- Recall Memories (search) -> POST .../memories/recall
- Reflect (search) -> POST .../reflect
Triggers (instant, via Hindsight's webhook API — subscribe POSTs /webhooks,
unsubscribe DELETEs it):
- Retain Completed, Consolidation Completed, Memory Defense Triggered
Auth: API key as Bearer token, Cloud default with self-hosted override; the
Bank field is a dynamic dropdown from GET /v1/default/banks.
Built on zapier-platform-core 19; 'private': true so the npm release path can
never publish it (Zapier publishing is manual via zapier push/promote, not
release-integration.yml — and zapier is intentionally NOT in VALID_INTEGRATIONS).
Adds test-zapier-integration CI job (npm install -> zapier validate -> npm test)
and a repo README row. 15 mocha/nock unit tests; 'zapier validate' is
structurally clean.
Docs-site gallery card + doc page + icon are a follow-up (need the official
Zapier brand asset; omitted here to keep build-docs green).
* fix(zapier): make apiKey optional for no-auth self-hosted + prettier-clean
- authentication.js: apiKey now optional (required: false). The middleware only
adds the Bearer header when a key is present, so you can connect to a
self-hosted instance running without auth by leaving it blank; Cloud still
requires a working key (blank -> 401 fails the connection test).
- README: document self-hosted / localhost usage, the optional key, and correct
the CLI binary name to 'zapier-platform' (v19 renamed it from 'zapier'); show
the .env approach so 'zapier invoke' needs no global install.
- Run prettier across the integration (fixes pre-existing format drift that was
failing verify-generated-files on this branch).
zapier validate still structurally sound; 15 tests pass.
* fix(zapier): correct reflect answer field + recall output shape (found via live test)
Extensive live testing against Hindsight Cloud surfaced two response-shape bugs
the mocked unit tests missed (they mocked the wrong shapes):
- reflect: the synthesized answer is in the response's `text` field, not
`answer`. searches/reflect read `data.answer` (undefined), so a Zap got no
answer. Now reads `data.text` and surfaces it as `answer`. Test mock fixed to
use the real `text` field so it actually guards this.
- recall: results carry no numeric `score`, and the fact-type field is `type`
(not `fact_type`). Corrected the sample + outputFields so the Zap editor only
advertises fields that actually populate; test mock made realistic.
Verified live end-to-end: auth, bank dropdown, retain (full + minimal), recall
(real fact extraction), reflect (now returns the grounded answer), and the
webhook subscribe/list/delete lifecycle. 15 unit tests pass; zapier validate clean.
* docs(zapier): correct .env auth-field prefix to authData_ in README
zapier invoke reads .env auth fields with the authData_ prefix (e.g.
authData_apiKey, authData_apiUrl), not bare apiKey/apiUrl. Confirmed against a
working local .env during live testing.
* docs(zapier): add integrations gallery card + doc page
- gallery entry in integrations.json (id zapier, official, category framework)
- doc page docs-integrations/zapier.md (actions + REST Hook triggers, setup)
- official Zapier logo at static/img/icons/zapier.png
check-integrations passes (forward: entry → doc page); JSON valid; prettier-clean.
* feat(zapier): verify webhook HMAC signatures + optional async retain (review notes 2 & 4)
#2 — Webhook signature verification (was: relying only on Zapier's unguessable URL):
- performSubscribe now generates a random 32-byte secret and registers it with
the webhook; the secret is stored in subscribeData.
- perform verifies the X-Hindsight-Signature: sha256=<hmac> header (HMAC-SHA256
of the raw body) and rejects mismatches. (Corrected the header name — the API
sends X-Hindsight-Signature, not X-Webhook-Signature; body is delivered
byte-for-byte via content=, so the recomputed HMAC matches.)
#4 — Optional 'Process asynchronously' toggle on Retain (default false). Lets
users with very large content avoid Zapier's action timeout; pairs with the
Retain Completed trigger.
17 unit tests pass (added valid/invalid signature cases); zapier validate clean.
* blog(gemini-spark): add Gemini Spark persistent memory post
Walkthrough of the config-only Hindsight + Gemini Spark integration:
agent-initiated recall/retain over MCP (no plugin host, no hooks),
Hindsight Cloud direct path vs self-hosted OAuth proxy, setup for both
the Antigravity desktop mcp_config.json and the antigravity.yaml manifest.
Add POST /v1/default/banks/{bank_id}/memories/dry-run-extract — a
read-only tool that previews what the retain step would extract from
text WITHOUT changing the bank: extraction only, no entity resolution,
links, embeddings, or persistence. The "dry-run-extract" path makes the
non-mutating nature explicit.
Returns a dedicated DryRunExtractionResult: the candidate facts plus the
aggregated LLM token usage. Each fact (ExtractedFact) is a subset of the
memory-unit shape — only what a fresh extraction produces: text,
fact_type, occurred_start/end, entities[] (raw, unresolved names).
Every prompt-affecting setting is overridable per call (retain_mission,
extraction_mode, custom_instructions, chunk_size, entity_labels,
entities_allow_free_form, llm_output_language) plus the narrator
(agent_name), so a candidate config can be A/B'd against the bank's
current one. The reference date field is named `timestamp` to match the
retain item payload. The engine authenticates the tenant before reading
any bank-scoped config.
Gated by a static server-level flag HINDSIGHT_API_ENABLE_DRY_RUN_EXTRACT
(default true). Since extraction makes a real LLM call, set it to false
to remove the endpoint (returns 404) on cost/abuse-sensitive deployments.
Control plane: a "Dry-run extraction" dialog opened from the Memory Bank
actions menu (text input + raw JSON output, side-by-side).
Regenerated OpenAPI spec + Python/TypeScript/Go client SDKs.
Add retain_structured_chunk_size as an explicit retain chunking knob
for structured inputs. When unset, structured inputs follow the
effective retain_chunk_size instead of the hidden 1.5x overflow factor.
Thread the setting through retain extraction, append/prepend chunking,
bank config resolution, templates, MCP docs, maintained clients,
generated OpenAPI artifacts, the control-plane retain strategy UI, and
the Rust CLI set-config command.
Validate retain_chunk_size and retain_structured_chunk_size as positive
integers while allowing either value to be smaller. Keep the existing
retain_max_completion_tokens check scoped to retain_chunk_size.
Preserve upstream validation details for client errors through the
control-plane proxy so UI alerts and toasts can show concrete
configuration errors without exposing server-side failure details.
Update chunking, config, hierarchical config, template, MCP, client
payload, control-plane serialization, SDK-response, API-client, and
retain UI validation tests for the new behavior.
* feat(api): omit null fields from JSON responses where wire-safe
API responses included every optional field as `"x": null`. Install a
custom route class (ExcludeNoneRoute) that enables response_model_exclude_none
for routes whose response model has no required-and-nullable field, so those
nulls are dropped.
Routes whose model carries a required-nullable field (e.g. DocumentResponse
.content_hash, OperationResponse.error_message) keep emitting nulls — omitting
a key the OpenAPI `required` set declares would break strict generated clients
(the Rust progenitor client decodes those without serde defaults). Detection is
recursive over nested models/generics, so it stays correct as models evolve.
The OpenAPI schema is unchanged (exclude_none is runtime-only), so the spec and
all generated clients are byte-identical and existing clients remain compatible.
Verified the published 0.8.2 client deserializes recall/retain/reflect/list
responses against a server running this change.
* test(api): tolerate omitted null fields in response assertions
Responses now omit null optional fields (ExcludeNoneRoute). Update the four
tests that read these keys via direct indexing to use `.get(...) is None`,
which holds whether the key is absent or explicitly null:
- operations progress (OperationStatusResponse / OperationsListResponse)
- bank-health latency_ms (when LLM not configured)
- reflect based_on (null when facts not requested)
- bank export bank/mental_models/directives (empty bank)
* fix(api): shrink mental model delta LLM prompts for provider limits
Delta refresh (scope mental_model_delta_ops) was sending the full
structured document, reflect synthesis, and every fact ever merged into
based_on. That payload grew on each refresh and triggered Z.ai HTTP 400
code 1261 (Prompt exceeds max length).
- Send only facts from the current reflect to the structured-delta LLM;
accumulated based_on remains stored for audit.
- Budget and truncate user prompt sections (~24k cl100k tokens default).
- Use compact JSON for the current document block.
- Keep normal APIStatusError retries for 1261.
Tests: prompt budget, retry behavior, delta plumbing assertion update.
* chore(control-plane): knip ignore react-dom (Next.js peer, no direct import)
* fix(api): delegate with_config on ConfiguredLLMProvider
Consolidation calls _consolidation_llm_config.with_config(...) after an
initial with_config bind; without delegation, Python raised TypeError for
bank_id/operation kwargs on the wrapper class.
Add regression test for re-bind trace attribution.
* fix(api): robust mental model delta JSON + lint sync
- parse_delta_operation_list: parse_llm_json + balanced-object extract
- Prompt: JSON escaping rules for glm-style invalid output
- Ruff format on touched files (verify-generated-files)
- Tests: test_delta_operation_parse.py
* fix(api): skip invalid delta ops instead of full-synthesis fallback
When the model omits required fields (e.g. replace_block without index),
validate operations one-by-one and apply the rest. Tighten structured-delta
prompt on index requirement.
* fix(api): drop dead with_config, guard delta facts + all-invalid ops
- Remove redundant ConfiguredLLMProvider.with_config: the __getattr__ proxy
already forwards to LLMProvider.with_config (which accepts bank_id), and
every caller (_retain/_reflect/_consolidation_llm_config) is an LLMProvider,
so the method was never reached. Drop its test (passed against main too).
- Add regression test locking the delta supporting-facts fix: only THIS
refresh's facts go to the structured-delta prompt, while based_on still
accumulates all facts for grounding. Fails on the pre-fix code.
- Harden parse_delta_operation_list: when the model emits ops but every one
fails validation, raise DeltaAllOpsInvalidError so the caller falls back to a
full rewrite instead of applying zero ops and silently dropping new facts.
A genuine empty operations array stays a valid no-op.
- knip.json: restore trailing newline (prettier).
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(db): widen remaining live bank_id columns to TEXT on PostgreSQL (#2106 follow-up)
* fix(db): drop mental_model_versions from bank_id widen migration
mental_model_versions is created in j5e6f7g8h9i0 but dropped (DROP TABLE
... CASCADE) in o0j1k2l3m4n5 and never recreated on the upgrade path, so
it does not exist at head. ALTER TABLE mental_model_versions therefore
raised UndefinedTable and -- because migrations run inside the
lifespan-startup transaction -- rolled the whole migration back, bricking
API startup (the exact failure class this repair targets).
Widen only the live tables that exist at head and still carry VARCHAR(64)
bank_id: directives and mental_models. Update the test accordingly (it
previously could not pass: the head migration crashed before any
assertion, and the now-removed FK insert referenced the dropped table).
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(consolidation): add "shared" observation_scopes keyword
Add a "shared" value for observation_scopes that resolves to a single
global, untagged scope ([[]]). Memories consolidate into one observation
regardless of their tags, while the tags stay on the source facts for
recall filtering.
This is the supported way to deduplicate observations across volatile
per-call provenance tags (e.g. per-session ids): with combined/per_tag,
a unique session tag puts every retain in its own scope, so near-identical
facts never dedup and accumulate one observation per session. "shared"
keeps recall and the dedup probe on the same (empty) scope, fixing
consolidation quality rather than only the duplicate count.
- consolidator: _resolve_obs_tags_list -> [[]], _resolve_write_scopes -> [frozenset()]
- API/engine type literals + OpenAPI + regenerated Python/TS/Go/Rust clients
- CP client type kept in sync
- docs: retain.mdx 'shared' section (+ shared vs [[]] vs [] caveat),
observations.mdx dedup pointer; regenerated hindsight-docs skill mirror
- tests: unit scope-resolution + e2e parallel-consolidation scope correctness
* chore(opencode): apply prettier formatting to plugin.test.ts
Pre-existing lint drift unrelated to this PR — CI's verify-generated-files
job reformats all integrations (LINT_ALL_INTEGRATIONS) and flagged this file.
Folding the one-line reflow in here to get the gate green.
The docstring listed a 'learn: Create/update mental models with new insights'
step that is not wired into the reflect agent. reflect_async only hands the
agent read tools (search mental models, recall, search observations, expand),
so reflect synthesizes an answer from stored memories and persists nothing.
Update the docstring to match the actual implementation.
Co-authored-by: Kuba Odias <[email protected]>
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
run_cancellable_on_disconnect (added in #2127/#2131 for #2122) converts the
engine's OperationCancelledError into HTTPException(499), which propagates out
through record_operation's blanket `except Exception: success = False`, so every
abandoned recall/reflect was counted as a failure on hindsight.operation.total.
Exclude a client cancellation from the counter entirely (neither success nor
failure), detecting it via the exception's __cause__ chain so an unrelated 499
is still recorded as a failure. Adds regression tests.
OpenCode's legacy plugin loader (getLegacyPlugins) iterates Object.values(mod)
and calls every function export as a Plugin factory. It deduplicates by
reference, so default and HindsightPlugin (same fn) are fine. But the entry
also re-exported loadConfig and deriveBankId, which the loader invokes as
plugins and registers as hooks — returning a string and a config object
respectively, neither of which is a valid hooks object.
Earlier versions of the dist (e.g. 0.2.1) additionally exported
DEFAULT_HINDSIGHT_API_URL as a string constant, which the loader would call
as a function and crash on with 'Plugin export is not a function'. That was
fixed in 0.2.2 by dropping the string re-export, but the function re-exports
remained and would still produce silently-wrong hook objects on every session.
The plugin itself imports loadConfig and deriveBankId directly from their
submodules, so removing the re-exports is backwards-compatible: no internal
callers change, no public API is removed (these were undocumented
convenience re-exports), and the default export remains a callable function
for direct import.
Add a regression test that asserts the entry has exactly two function
exports, both pointing at the same reference. This is the legacy-loader
invariant: anything else will be incorrectly invoked.
Closes the use case for the local plugins/hindsight.js wrapper required to
load the package as an npm plugin.
Co-authored-by: mdbenito <[email protected]>
* fix(search): use effective-time fallback for recency scoring
* test(search): cover mentioned_at/occurred_end recency fallback
* style: apply ruff format (collapse multi-line ternaries within 120c)
Clears verify-generated-files CI: ruff format collapses the recency
effective-time fallback (reranking.py) and a main-drift one-liner in
consolidator.py that both fit the 120-char line length.
* docs(litellm): replace removed opinion fact-type with observation
* style: apply ruff format to consolidator.py (CI generator-sync)
verify-generated-files requires committed files match ruff format output;
collapses a main-drift multi-line ternary that fits the 120-char limit.
#2102 added the native Nous Portal provider to config.py
PROVIDER_DEFAULT_MODELS and the models.mdx prose, but not to
hindsight-docs/src/data/llmProviders.json -- the single source of truth
that renders the Models page provider grid, default-models, and
capabilities tables -- so Nous is documented in prose but invisible on
the canonical Models grid.
Add the nous entry and regenerate the CI-enforced skill mirror via
scripts/generate-docs-skill.sh. Same pattern as #1911 (fireworks).
Co-authored-by: r266-tech <[email protected]>
* blog: add Cursor persistent memory post covering both integrations
One post covers both new integrations:
- hindsight-cursor (editor, first-party): plugin hooks + MCP server,
with the Cursor 3.x additionalContext workaround via workspace
rules-file fallback
- hindsight-cursor-cli (CLI, community-built by @Korayem): four
lifecycle hooks (sessionStart, beforeSubmitPrompt, stop, sessionEnd)
The angle of the post is that both surfaces can share a single bankId
and switch between editor and CLI mid-task without losing context.
Every claim sourced from the integrations' README files:
- Editor: install commands, sessionStart/stop hooks, MCP config, the
Cursor 3.x bug + rules-file workaround, useRulesFileFallback flag,
bankId default = "cursor"
- CLI: four-hook table, install command, ~/.cursor/hooks.json shape,
Cursor CLI v0.45+ requirement, bankId default = "cursor-cli",
dynamicBankGranularity including gitProject
Test stamps from both integrations on current main:
- hindsight-cursor: 82 passed, 4 skipped
- hindsight-cursor-cli: 87 passed, 0 skipped
Cover is a placeholder (Codex art) for now; swap before merging.
* blog(cursor): swap placeholder cover for Hindsight x Cursor card
* fix(control-plane): stop double-fetching graph data on bank view
The DataView component had two effects that each loaded graph data — one
keyed on factType/bank/document/chunk, one on tag/scope filters. Both run
on initial mount, so every bank/tab view fired /api/graph twice (issue
2158).
Collapse them into a single auto-loader. When the context changes we drop
the now-meaningless observation scope and feed the cleared value straight
into the same reload, guarding the setSelectedScope(null) echo render with
a ref so the reset never produces a second fetch.
Refs #2158
* fix(control-plane): make graph auto-load idempotent
Add a fetch-signature guard so identical consecutive auto-loads collapse
to a single /api/graph request. This defeats React's mount-effect
double-invoke (dev StrictMode, client-side navigation) and any redundant
re-render that would otherwise re-issue the same query — verified with
Playwright that switching fact-type tabs now fires exactly one request
per view (was two on tab clicks in dev).
Manual reloads (search, load-more, consolidation poll) call loadData
directly and intentionally bypass the guard.
Refs #2158
The per-scope observation limits added in #2140 document 0 as 'no new
observations', but the two call-site guards used '> 0', so a configured limit of
0 left remaining_observation_slots=None and _build_response_model(None) built an
unconstrained model -- limit:0 behaved like unlimited, the inverse of intent.
Make the guards '>= 0' (matching the truncation guard which already uses '>= 0'),
short-circuit the count query for the 0 case, and add a regression test asserting
a scope cap of 0 creates no new observations.
The event_types field description said 'Currently supported: consolidation.completed',
but the API actually emits and accepts all three events:
- retain.completed (memory_engine.py)
- consolidation.completed (memory_engine.py)
- memory_defense.triggered (retain/orchestrator.py)
Update the description accordingly and propagate through the regenerated OpenAPI
spec + the embedded copies in the go/python/typescript clients. Description-only
change; no behavior change.
transformers' dtype context manager (entered by SentenceTransformer /
CrossEncoder / from_pretrained) does a non-thread-safe save/restore of the
process-global default dtype. When an fp16 embedding model and an fp32
reranker/query-analyzer load in parallel during MemoryEngine.initialize(), an
unlucky interleave can leave the global default stuck at float16. Every later
encode() then emits NaN vectors that pgvector rejects ("NaN not allowed in
vector") on MPS, or raises "c10::Half != float" on CPU -- non-deterministically
across restarts.
Keep the model loads fully parallel and, once asyncio.gather() has joined every
load thread, normalize the global default dtype back to float32 -- the inference
state a healthy boot already converges to. The reset is race-free (all threads
have finished) and only touches torch if a local provider actually loaded it.
Fixes#2162
* chore(ci): enforce unused imports/vars + advisory dead-code scan
Enable ruff F401 (unused imports) and F841 (unused variables) -- previously
ignored as "too noisy" -- across hindsight-api-slim, hindsight-dev, and
hindsight-embed, and clean up the resulting violations. These are now blocking:
lint.sh auto-removes them and the verify-generated-files CI job fails on any
leftover diff.
Add an advisory dead-code scan for what the linter cannot see -- whole unused
Python functions (vulture) and orphaned files/exports/dependencies in the
control plane (knip):
- scripts/hooks/check-unused.sh runs both locally
- new non-blocking check-unused-code CI job surfaces findings on PRs
- hindsight-control-plane/knip.json tunes out toolchain false positives
vulture stays advisory because its function/argument heuristics false-positive
on FastAPI/SQLAlchemy/Pydantic patterns; knip can be flipped to blocking once
the control-plane dead code (PR #2135) lands.
* chore(ci): make knip blocking on unused files/deps; remove dead deps
#2135 deleted tooltip.tsx but left @radix-ui/react-tooltip in package.json, and
react-chrono / three were never imported. Remove all three, and declare
@radix-ui/react-visually-hidden (used in directive-detail-modal but unlisted).
With the control-plane tree now clean, the check-unused-code job runs
`knip --include files,dependencies,unlisted` as a BLOCKING step. vulture and
knip's unused-exports check (the shadcn/ui surface is kept intentionally) stay
advisory.
Adds five optional fields to MemoryDefenseEventData so downstream extensions
(e.g. hindsight-cloud) can surface the per-decision context SIEM operators
need to act on a leaked-secret webhook: severity, the API key that submitted
the retain, fingerprinted hit previews for correlation against credential
inventories, and pointers into the audit trail.
Backward-compatible: all five fields default to None and OSS's built-in
regex defense leaves them unset, so existing OSS receivers see no shape
change. Receivers should treat absence as "not provided" rather than "no
match" — the OSS path still populates matched_types as before.
The hit preview is wrapped in a new MemoryDefenseHit model whose docstring
pins the rule that preview must be a fingerprinted rendering of the value,
never the raw secret. Validates that both detector and preview are present
to guard against extensions accidentally posting the raw value as the only
field.
Closes the gap that motivated keeping a separate memory_defense.violation
event in cloud before the recent consolidation: cloud can now ship the
same SIEM-actionable payload through the canonical memory_defense.triggered
envelope.
feat(webhooks): populate hits[] with fingerprinted previews on OSS
Builds on the schema added in the previous commit by populating the
SIEM-relevant hits field from the OSS regex defense. SIEM receivers
now get a per-match preview (e.g. ghp_AAAA...AAAA) for every redaction
the OSS extension fires, in addition to the existing matched_types list.
Three changes:
1. New _fingerprint_value helper produces a length-aware redaction-
identifiable rendering of a matched value:
- length < 6: returns "[redacted]" (avoid leaking material on
short matches like an isolated -----BEGIN... marker)
- length 6-15: first-2 + ellipsis + last-2
- length > 15: first-4 + ellipsis + last-4
The raw value never appears in the output.
2. apply_redaction returns a hits list alongside matched_types - one
entry per matched substring (so two GitHub tokens produce two hits
rather than collapsing into a single label). Hits threaded through
RedactionResult -> DefenseDecision -> MemoryDefenseEventData via the
orchestrator's fire helper.
3. _fire_memory_defense_webhook translates the decision's raw hit dicts
into MemoryDefenseHit entries. None when the decision carries no
per-hit data so receivers can distinguish "no preview info" from
a hypothetical empty list.
Test plan:
- New unit tests for _fingerprint_value across all three length
buckets (parametrized) plus apply_redaction shape: per-match
fingerprinted previews, raw value never present, multiple matches
of the same pattern produce multiple hits.
- Extended test_screen_redacts_secret to assert the regex extension
passes hits onto DefenseDecision.
- Extended test_retain_fires_webhook_on_redact to assert the wire
payload carries hits[].
- Helper _memory_defense_webhook_events now orders most-recent-first
so events[0] always reflects the latest delivery.
- Full test_memory_defense.py + test_webhooks.py: 100 passed.
- ruff + ty: clean.
feat(webhooks): more useful message
#2140 (per-scope observation limits) added observation_scope_limits to
_CONFIGURABLE_FIELDS but didn't bump the count tripwire in
test_hierarchical_fields_categorization, so it asserts 38 while the real count
is 39 — failing test-api deterministically on every open PR.
The field is correctly configurable (a per-bank behavioral override). Bump the
count to 39 and add an explicit assertion for the field, matching the test's
documentation pattern.
* blog: add Haystack persistent memory integration post
Walkthrough of hindsight-haystack — two integration modes:
- create_hindsight_tools() returning a list[Tool] for an Agent
- HindsightMemoryWrapper, a Toolset subclass with auto_recall and
auto_retain that runs the memory work before/after each turn.
Plus the three memory primitives (retain/recall/reflect) and the
include_* flags to drop any subset.
Every concrete claim verified against the README and
hindsight_haystack/tools.py:
- Package name + version (0.1.0)
- Python >= 3.10, haystack-ai >= 2.12.0, hindsight-client >= 0.4.0
- Exported names from __init__.py
- create_hindsight_tools() and HindsightMemoryWrapper signatures
- "Use toolset.run(agent, ...) not agent.run(...) for auto behavior"
- configure() shape and acceptable kwargs
Underlying integration unit tests: 83/83 passing (3 e2e skipped for
lack of API keys in CI sandbox).
Cover is a placeholder (Codex art) for now; swap before merging.
* feat(agent-framework): add Hindsight memory integration via context provider
Persistent memory for Microsoft Agent Framework (the successor to Semantic
Kernel) without MCP. HindsightProvider is a ContextProvider whose before_run
recalls relevant memories and injects them into the agent's instructions, and
whose after_run retains the conversation. Reuses the LlamaIndex integration's
client/config pattern and the hindsight-client Python SDK.
Targets the agent-framework-core 1.x before_run/after_run + SessionContext
contract (verified against the installed package since the API has churned).
15 unit tests subclass the real ContextProvider so drift fails loudly, plus a
gated e2e. Includes CI job, release + changelog + docs wiring, and an icon.
* chore(agent-framework): refresh lock to agent-framework-core 1.8.1 (verified no API drift)
* fix(agent-framework): drop unused per-op timeout constants
TIMEOUT_RETAIN/TIMEOUT_RECALL/TIMEOUT_BANK were defined but never used: the
hindsight-client SDK sets one timeout on the constructor and has no per-call
timeout argument, so per-op values can't be wired in. Keep the single
constructor-level TIMEOUT_DEFAULT and document why. Addresses review feedback.
The Gemini Spark gallery card showed the generic MCP paperclip icon
(/img/icons/mcp.png). Every other named-product integration uses its
own brand mark, so swap in the official Google Gemini 2025 sparkle
(public-domain logo from Wikimedia Commons, {{PD-textlogo}}).
* docs(superagent): add prerequisites to integration quick start
The quick-start example calls Superagent guard/redact on the first
retain (both on by default), so it fails immediately without the
required keys. The page documented none of them. Add a Prerequisites
section covering SUPERAGENT_API_KEY and OPENAI_API_KEY, clarify the
hindsight_api_url endpoint (self-hosted vs Cloud), and note that
Superagent's hosted guard-model endpoints are currently unreliable.
* docs(superagent): default the quick start to Hindsight Cloud
Drop the explicit localhost URL so the example uses the package's
default Cloud endpoint (https://api.hindsight.vectorize.io), add
HINDSIGHT_API_KEY to the prerequisites, and show self-hosting as the
opt-in alternative.
* feat(observations): enumerate + filter observations by scope
Add an exact (set-equality) tag match mode, a list_observation_scopes
engine method + GET /observations/scopes endpoint, and a scope filter in
the control-plane Observations tab (list + graph views). A scope is the
exact tag set an observation was consolidated under; the empty set is the
global/untagged scope. Regenerated OpenAPI + clients + docs skill.
* fix(i18n): add missing memoryDetailPanel curation* keys
invalidate-memory-dialog.tsx references memoryDetailPanel.curationInvalidateTitle/
Explain/ReasonPlaceholder/Cancel/Invalidate, but these keys were never added to any
locale (the parity test passed because all 10 locales lacked them equally), so the
invalidate dialog logged IntlError: MISSING_MESSAGE and rendered raw key names.
Add all five strings across the 10 locales. Pre-existing gap, unrelated to scopes.
* fix(observations): keep scope-filter trigger single-line for long/multi tags
The scope dropdown trigger relied on SelectValue, which clones the selected
item's wrapping pill layout; a multi-tag or long-tag scope (e.g. [session:2,
user:nicolo]) wrapped to two lines and overflowed the fixed-height control.
Render a compact, single-line, truncating summary in the trigger instead,
keeping the full pills only in the open dropdown list.
* feat(documents): capture observation_scopes in retain_params, show in detail dialog
observation_scopes passed at retain time was only persisted per source fact
(memory_units), never on the document, so the document detail dialog couldn't
show which scoping was requested. Capture it into documents.retain_params in
_build_retain_params (alongside context/event_date/metadata) and surface it as
a top-level field on the get_document response. The control-plane document
detail dialog now shows an 'Observation scopes' row (mode badge or scope chips).
New-documents-only by design: existing docs have no captured value and show
nothing. Note: this also clarifies that all_combinations on 2 tags correctly
creates 3 scopes — the transient '2' is async consolidation still in flight.
* feat(observations): live consolidation refresh + scope clusters on the constellation
Two UX improvements to the observations view:
1. Live refresh while consolidating. The 'In Sync' badge previously read a
one-shot, up-to-60s-cached stat, so it could show green while observations
were still materializing (each scope is a separate consolidation pass). The
view now polls every 4s while pending_consolidation > 0, silently refreshing
the observations, scope list, and badge in place until consolidation settles.
2. Group-by-scope clustering on the Constellation. A new 'Group by scope' toggle
lays observations out around per-scope centroids (instead of the id-hash ring),
colors each scope distinctly, and wraps each scope's nodes in a translucent,
labeled convex-hull blob — so overlapping tag scopes read as visual clusters.
Adds clusterKeyFn/clusterColorFn/clusterLabelFn props to Constellation and an
inline monotone-chain convex hull; suppresses the heat legend while clustering.
* fix(observations): cap scope dropdown height to the viewport
With many scopes the scope filter dropdown grew past the bottom of the screen.
Cap its height at min(60vh, --radix-select-content-available-height) so it fits
the space below the trigger and scrolls for the rest, instead of overflowing.
* feat(observations): make the scope filter a searchable combobox
Replace the plain Select with a Popover + Command (cmdk) combobox so scopes can
be searched by typing — matching the tag filter's search UX — which matters once
a bank has many scopes. Uses a substring filter over each scope's tags (not
cmdk's fuzzy default, which over-matches scattered letters). Keeps the compact,
single-line, height-capped trigger; selection still applies exact-scope filtering.
* chore(cli): mark list_observation_scopes UI-only in coverage manifest
The new scope-enumeration endpoint powers the control-plane scope filter/clusters
and isn't a useful end-user CLI command, so add it to the [skip] list (matches
the other UI-only endpoints) to satisfy check-cli-coverage.
* fix(tests): import TokenUsage from response_models
#2135 removed the TokenUsage re-export from llm_wrapper, but test_load_large_batch
and test_retain still imported it from there, breaking test collection across the
API test jobs. Import it from response_models (where it's defined), matching every
other test.
Add an `observation_scope_limits` config field that overrides the bank-wide
`max_observations_per_scope` on a per-scope basis. Each rule maps a scope
pattern (a list of fnmatch tag-globs) to a limit; a consolidation scope
matches under *exact cover* — every tag matched by a glob and every glob
matched by a tag — so `["shared"]` caps the `{shared}` scope without affecting
`{run_1, shared}`, and `["run_*", "shared"]` caps the combined scope only.
The first matching rule wins; scopes matching no rule fall back to
`max_observations_per_scope`.
- config: new `HINDSIGHT_API_OBSERVATION_SCOPE_LIMITS` (JSON), hierarchical
(per-tenant/bank overridable)
- consolidator: resolve the cap per scope at slot computation; wildcards live
only in the resolution layer so the SQL count stays exact and indexed
- exposed on `BankTemplateConfig`; regenerated OpenAPI + clients
- unit tests for rule parsing, exact-cover matching, and resolution
The enterprise discovery panel used an empty-string en.json value as a
"render nothing for English" sentinel, but the locale catalog guard
(tests/messages/messages.test.ts) bans empty leaf values. Remove the
memoryDefenseEnterpriseMeetingNote key from all locales and the conditional
render — it was low-value copy (a language disclaimer on a demo CTA) and the
source of the build-control-plane / test-hindsight-all failures.
The parser no longer gates rules[*].on against a hardcoded detector list.
Unknown detectors are silent no-ops in the OSS extension anyway (only
sensitive_data is screened), so pinning the OSS roster to cloud's just forced
an OSS bump for every new cloud detector to avoid 422-ing a write it never
interprets. on now only has to be a non-empty string; dispatch and
entitlement stay the loaded extension's job.
Also soften the enterprise discovery panel's emerald styling to a more
refined low-saturation tint.
Remove unreferenced backend helpers, stale UI/docs components, and
unused imports across the API, control plane, clients, and integrations.
Drop obsolete consolidated-observation helpers and unused scoring code,
clean orphaned React/docs components, and remove stale Radix dependencies.
Align release scripts, Helm docs, lockfiles, generated clients, and
current API examples with the package and endpoint surface still in use.
A persistent, localhost-only control center web app bundled in hindsight-embed:
LLM config wizard, raw .env editor (with effective-only view), daemon +
control-plane Start/Restart/Stop with live API/UI health, editable per-profile
API/UI ports + component versions, daemon + control-plane log tail, profile
delete, deep-linking, token-gated /api/* (CSRF-safe), localhost everywhere.
UI built with Preact + Tailwind (Vite), output committed to static/ and served
by the embed's stdlib http.server (no Node at runtime, offline). Ports moved
from metadata.json into each profile's .env (HINDSIGHT_API_PORT /
HINDSIGHT_EMBED_CP_PORT). CI job verifies the bundle builds + is wired.
The gitcgr.com SSL certificate has expired, so the code-graph badge
image (added in #648) renders as a broken-image icon in the README for
all visitors. Remove it since the third-party service appears defunct
and we don't control the cert.
The OSS regex extension still only enforces sensitive_data, but the parser
should accept the full known detector vocabulary so cloud-shape policies
(prompt_injection, size_anomaly, protected_keys, detect_secrets,
base64_decode, llm_screen) pass through the OSS PATCH layer unchanged.
Dispatch + entitlement enforcement happen in the loaded extension; an
on-name the active extension doesn't implement is a silent no-op.
Adds test_parse_policy_accepts_full_detector_union covering all 7 names.
The reject-unknown-detector test still passes for unrelated values like
"nope".
The Cursor CLI integration was contributed by Salem Korayem (@Korayem) in
PR #1975, but the integrations gallery listed it as official/Hindsight Team.
Flip it to a community entry attributed to the author.
The cancellation merged in #2127 never fired in production. Live testing
(curl --max-time against a real server) showed abandoned recall/reflect
requests still ran to completion; 0 cancellations under a 4000-request storm.
Two root causes, both found by black-box testing + ASGI probes:
1. Request.is_disconnected() is broken behind BaseHTTPMiddleware. This app
installs two @app.middleware("http") handlers (BaseHTTPMiddleware), which run
the route in a child task behind anyio memory streams, so http.disconnect
never reaches the route's Request and is_disconnected() returns False forever.
The #2127 watcher therefore never tripped. (Reproduced in isolation: one
no-op @app.middleware("http") flips detection from working to broken.)
Fix: ClientDisconnectCancellationMiddleware, a pure-ASGI middleware installed
OUTSIDE the BaseHTTPMiddleware layer where it owns the real receive channel.
It drains receive in a background pump, trips a CancellationToken on
http.disconnect, and stashes it on the ASGI scope. Only wraps recall/reflect
(small JSON bodies); everything else passes straight through.
2. Even once the token tripped, recall did not cancel: _search_with_retries
wraps its whole body in a broad except Exception and re-raises as RuntimeError,
burying OperationCancelledError. Fix: re-raise OperationCancelledError ahead of
the broad handlers (both the search body and the connection-retry loop).
Kept OperationCancelledError as a plain Exception (not BaseException) on
purpose: BaseException dodges the broad handlers but also slips past the reflect
agent's isinstance(result, Exception) gather handling and crashes it.
run_cancellable_on_disconnect now just reads the scope token onto RequestContext;
the polling is_disconnected() watcher is gone.
Verified live (real server, real corpus): RECALL CANCELLED and REFLECT CANCELLED
fire; a 30s socket-closing storm produced 397 recall + 80 reflect cancellations
with 40/40 canary recalls served, health all 200, 0 errors, full recovery.
Reflect cancellation is best-effort between agent iterations (a disconnect during
the final-answer LLM call is not interruptible), analogous to the rerank stage.
* chore(embed): remove unused HINDSIGHT_EMBED_BANK_ID config var
`HINDSIGHT_EMBED_BANK_ID` was collected (env + interactive/non-interactive
configure), persisted to the profile .env, printed, and round-tripped through
config dicts, but never consumed: the daemon env-builder and run_cli ignore
the `bank_id` key, the memory commands (`memory retain|recall|reflect <bank>`)
take the bank as a required positional arg, and hindsight-api only reads
`HINDSIGHT_API_*` vars. The only reader was a test assertion.
Removes the prompt/read/persist sites in cli.py, the doc rows in the embed
README and sdks/embed.md, and updates the two tests that referenced it.
* chore(embed): fix HINDSIGHT_EMBED_LLM_* docs to the real HINDSIGHT_API_LLM_*
The embed docs/README documented `HINDSIGHT_EMBED_LLM_API_KEY` (marked
Required), `_PROVIDER`, and `_MODEL` as the user-facing LLM config, but no
code reads those names — the CLI honors `HINDSIGHT_API_LLM_*` / `OPENAI_API_KEY`,
`configure` writes the `HINDSIGHT_API_` prefix, and the daemon env-builder
forwards `HINDSIGHT_*` keys verbatim (no EMBED→API rewrite). A user following
the docs literally got "LLM API key is required".
Renames every `HINDSIGHT_EMBED_LLM_*` occurrence to the working
`HINDSIGHT_API_LLM_*` in sdks/embed.md, the embed README, and the two profile
tests (which only assert .env round-trip). Also drops a leftover "memory bank
ID" mention from the README configure description.
* feat(retain): chunk JSONL at line boundaries
Newline-delimited JSON (e.g. session logs) now chunks the same way as
JSON conversation arrays: whole lines are packed into chunks so no line
is split mid-object. This lets JSONL be ingested with mode `append`
without manual coercion to a JSON array.
A single line/turn that overflows the budget is kept whole only up to
1.5x (_CHUNK_OVERFLOW_FACTOR); beyond that it is split as text. The
extractor has no second re-chunk pass, so an unboundedly oversized chunk
would just error at the LLM — this caps the overflow for both the new
JSONL path and the existing conversation-array path.
Closes#2113
* test(retain): assert exact chunk output across text/JSONL/conversation modes
* docs: flag Intel (x86_64) macOS as slim-only in supported-platforms grid (#2115)
`pip install hindsight-all` on Intel Macs silently backtracks to a
months-old release: every release since 0.4.18 pulls hindsight-api-slim[all],
whose local-ML extra requires torch>=2.6.0 and mlx, neither of which ships
x86_64 macOS wheels. The docs' supported-platforms grid claimed Intel macOS
bare-metal pip was "fully supported", which is false.
- Split the macOS grid row into Apple Silicon (fully supported) and
Intel/x86_64 (Docker + pg0 ✅, bare-metal pip ⚠️ slim only).
- Mirror the grid into README.md.
- Point Intel-Mac users to hindsight-all-slim / hindsight-api-slim plus a
hosted embeddings/reranker provider or the in-process ONNX backend
(which has x86_64 macOS wheels).
- Replace the ad-hoc warnings with one-line pointers to the grid.
Refs #2115
* docs: move Supported Platforms grid to bottom of README
* docs: simplify README platform table to icons, link docs for details
* fix(api): cancel abandoned HTTP recall via cooperative cancellation token
Recall ran to completion even after the client disconnected, burning ~2 CPUs
for 60-95s per abandoned request and accumulating toward RECALL_MAX_CONCURRENT
until the instance starved (issue #2122).
Approach: a CancellationToken carried on RequestContext (already threaded into
every engine operation) that the engine checks at recall pipeline stage
boundaries (pre-retrieval, pre-rerank, pre-enrichment), aborting before
dispatching the next expensive stage. The HTTP layer attaches a token that
fires when the client disconnects and maps the resulting OperationCancelledError
to 499.
This is cooperative: it cannot interrupt work already inside a worker thread
(the cross-encoder rerank runs via run_in_executor and cannot be cancelled
once dispatched), but it stops an abandoned recall from progressing into - or
past - that work. The token lives on RequestContext so reflect/consolidation/MCP
and a deadline-based driver can adopt the same checkpoints later.
Scoped to HTTP recall; internal recalls pass no token so checkpoints are no-ops.
* fix(api): extend disconnect cancellation to reflect; share HTTP wiring
Reflect has the same abandoned-work problem as recall (agentic LLM loop +
nested recalls). Thread the same RequestContext cancellation token through it:
the agent loop checks between iterations and the nested recall tool already
checks at its stage boundaries, so an abandoned reflect stops instead of
running every remaining LLM round-trip (issue #2122).
Factor the HTTP wiring into a shared run_cancellable_on_disconnect() helper
used by both the recall and reflect handlers: it attaches the disconnect-driven
token and maps OperationCancelledError to 499, so neither handler duplicates
the try/except.
run_reflect_agent gains an optional cancel_check hook (default None -> inert),
so internal/non-HTTP reflect callers are unaffected.
command.upgrade() never raises ResolutionError directly — alembic's
ScriptDirectory._catch_revision_errors wraps it in CommandError, so the
newer-bank rolling-deployment handler never fired and startup died with
a raw traceback. Catch the wrapped form (cause-checked) and route it to
the same warn-and-skip path; unrelated CommandErrors still propagate.
Fixes#2114
The class subclasses Haystack's `Toolset` but is used as an automatic
memory wrapper (auto_recall / auto_retain around an Agent), not a tool
collection. Reusing the `Toolset` name was confusing next to Haystack's
own `Toolset` abstraction — flagged by deepset DevRel in review of the
haystack-integrations gallery entry (deepset-ai/haystack-integrations#505).
Pure rename across the package, tests, README, and docs pages. The class
still subclasses `haystack.tools.Toolset`. No backward-compat alias — the
package is at 0.1.0 with no adoption yet, so the rename is clean.
Co-authored-by: DK09876 <[email protected]>
memories.py listed memories, then ran edit -> invalidate -> restore on a fact.
Any update_memory call re-consolidates the bank and recreates derived
observations with new ids, so the observation id from the earlier listing was
stale by the time the example called get_observation_history — which the engine
correctly 404s on (NotFoundException), failing test-doc-examples (python) on
every PR.
Move the observation-history read to immediately after list_memories, before
the curate operations, so it uses a live id. No re-consolidation timing
dependency. The existing `if observation is not None` guard still covers the
no-observation case.
* blog: add Flowise persistent memory integration post
Walkthrough of the Hindsight Flowise integration — three Tool nodes
(Retain, Recall, Reflect) plus a shared Hindsight API credential.
Every claim verified against source in hindsight-integrations/flowise:
zod schemas, default budget = "mid", default URL, category, the
exposed tool names (hindsight_retain/recall/reflect), and the
DynamicStructuredTool return shape.
Install section is honest about Flowise's distribution model
(upstream monorepo PR, not npm install) rather than promising a
package that doesn't ship that way today.
Underlying integration tests: 17/17 passing (vitest).
Cover is a placeholder (Codex art) for now — swap before merging.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
* blog(flowise): fix install-section wording — no upstream PR is open
Searched FlowiseAI/Flowise for any open or closed PR matching
"hindsight" / "vectorize" or authored by any Hindsight contributor
(benfrank241, chrislatimer, cdbartholomew, nicoloboschi, DK09876,
fabioscarsi) — zero results. The draft's phrasing implied a PR was
already open and pending merge. Reword to "the eventual distribution
path is an upstream contribution; until those nodes ship in a Flowise
release..." so the post doesn't promise a PR that doesn't exist yet.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
* blog(flowise): drop the "eventual distribution path" sentence
Tighten the install-section preamble per reviewer feedback. The post
now just tells readers how to install today, without speculating on
where the nodes will eventually live.
Install procedure verified end-to-end:
- Cloned FlowiseAI/Flowise 3.1.2 (commit f4e2794)
- Copied the three Hindsight tool nodes and credential
- pnpm add @vectorize-io/hindsight-client (resolved to 0.8.1)
- pnpm install at the root
- pnpm --filter flowise-components build → SUCCESS
- tsc completed, gulp finished, no type errors
- dist/nodes/tools/Hindsight{Retain,Recall,Reflect}/*.{js,d.ts} all emitted
- dist/credentials/HindsightApi.credential.{js,d.ts} emitted
- Compiled JS correctly requires @langchain/core/tools,
@vectorize-io/hindsight-client, and zod
The install path in the post is now build-verified, not just
copy-faithful to the README.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
* blog(flowise): fix broken link to /developer
The build-docs and verify-generated-files CI jobs failed because the
post linked to /developer, but the developer-docs landing page has
slug: / (it's the docs root, not /developer).
Repoint the "Hindsight API reference" item to /developer/api/quickstart,
which is the actual API entry point and the link other recent posts
use.
The split-history migration a7b8c9d0e1f2 declared observation_history.bank_id
(and mental_model_history.bank_id) as VARCHAR(64) on PostgreSQL, but the
backfill source memory_units.bank_id is TEXT (unbounded), as are banks,
documents and entities. Any deployment with a bank_id over 64 chars aborts the
backfill with StringDataRightTruncation; because the migration runs in lifespan
startup inside a transaction, the whole thing rolls back and the API never
comes up — unrecoverable from the running container.
The Oracle path is unaffected (both sides are VARCHAR2(256)), so the fix is
PostgreSQL-only.
- Correct a7b8c9d0e1f2 to create bank_id as TEXT. This recovers deployments
that *failed*: the migration rolled back, so re-running the fixed DDL
succeeds. Inert for deployments that already succeeded.
- Add forward-repair migration c3e5a7b9d1f4 (new head) that widens the column
in place for deployments that already succeeded with the narrow column;
no-op on already-TEXT columns, so all upgrade paths converge. Mirrors the
b2d4f6a8c1e3 repair pattern.
- Add a regression test seeding the 78-char bank_id shape from the issue.
Fixes#2106
The `hindsight memory get` command deserialized the API response into a
local `MemoryUnitDetail` struct whose shape had drifted from what
`GET /memories/{memory_id}` (MemoryEngine.get_memory_unit) actually
returns:
- `entities` is a flat list of canonical-name strings, but the struct
expected a list of `{id, name}` objects, so serde failed whenever a
memory had entities — surfaced to users as the misleading
"Invalid API response format".
- the fact type is exposed as `type`, but the struct renamed it to
`fact_type`, so the Type line always printed UNKNOWN.
The endpoint returns an untyped JSON body in the OpenAPI spec, so the
generated client never validates it and the mismatch only blew up in the
CLI handler. These commands had no test coverage (docs use curl).
Fix the struct to match the response and add regression tests.
Edit (text/context/dates/fact_type/entities), invalidate (move to a separate
invalidated_memory_units archive, reversible), and revert raw memory units via
PATCH /memories/{id}. Tracks user edits with edited_at. Control-plane UI, docs
(Memories API page), and multi-language examples included. RFC #1951.
Obsidian community-store automated review (v0.1.1) flagged three errors and a
warning; this clears them and adds build-provenance attestations.
Errors:
- Manifest description must not include the word 'Obsidian' → reworded to
'...cites the source notes. Your vault stays the single source of truth.'
- no-static-styles-assignment (chat-view.ts): el.style.height = ... →
el.setCssStyles({ height }) per the plugin guidelines.
- no-unsupported-api (main.ts): Workspace.revealLeaf requires Obsidian v1.7.2 →
bump minAppVersion 1.5.0 → 1.7.2 (matches the obsidian@^1.7.2 types we build
against). versions.json 0.1.2 → 1.7.2.
Warning:
- builtin-modules dep → Node's built-in module.builtinModules in esbuild config;
dependency removed.
Recommendation (build-provenance attestations for main.js/styles.css):
- Add actions/attest-build-provenance for the Obsidian assets in
release-integration.yml (+ attestations: write). Assets release in the
dedicated repo while the build runs here, so verify at owner scope:
gh attestation verify main.js --owner vectorize-io.
Bumps manifest to 0.1.2. Verified with the bot's own linter
(eslint-plugin-obsidianmd): both code errors clear. build + tsc + 46 tests pass.
`hindsight-embed configure` and profile creation wrote a bare four-key
file. Seed them from the same `.env.example` shipped in the repo so users
get the full documented option set as commented references.
- Bundle a copy of the repo-root `.env.example` into the package
(`hindsight_embed/env.example`) so installed/uvx users have the template
at runtime; a sync test guards against drift.
- Add `env_template.render_config()`: everything is commented out by
default — only the keys the user explicitly set are active, replaced in
place (unknown keys appended). This keeps the active config byte-for-byte
backwards compatible with the old bare file and prevents the template's
api-server defaults (PORT=8888, OpenAI base URL, gpt-4o-mini, HOST) from
leaking in and colliding profile ports / forcing the wrong base URL.
- Wire into both `configure` paths and `create_profile`.
Also document that new config flags must update `.env.example` (and re-sync
the bundled embed copy) in the config-addition checklist (CLAUDE.md) and the
code-review checklist.
The hindsight-api side already seeds `.env` from `.env.example`
(`scripts/dev/setup.sh`), so no change there.
The release script bumps package.json but not manifest.json/versions.json, and
the community store requires the release tag to equal manifest.json's version.
Bump both ahead of the v0.1.1 release so the dist-repo mirror + BRAT tag match.
Addresses chat-UX feedback:
1. 'Notes retrieved' showed the agent's whole scratchpad (every note any tool
call touched — ~10 for a one-fact answer). Now shows only the notes the answer
is grounded on: join based_on.memories (cited facts, no doc id) to the trace's
recall results (id + document_id) by fact id, deduped by note in citation
order. Capped at 3 visible with a 'Show all (N more)' toggle. Falls back to the
full retrieved list only when nothing resolvable was cited (never empty).
2. Notes disclosure now defaults to collapsed (was always-open and noisy).
3. Both disclosures (notes + reasoning) remember the user's last open/closed
state across sessions via two new persisted settings.
4. Chat depth (reflect budget) is now settable inline in the chat filter bar and
written back to the persisted default, so the choice sticks.
No API change — match % is intentionally deferred (the score isn't exposed by the
API today). reflect-util.groundedNotes covered by new unit tests; 46 tests pass.
* feat(api): per-bank provider cost attribution via OpenAI user field
Lets operators attribute Hindsight's provider spend per bank.
- Add a `_current_bank_id` engine ContextVar (mirroring the existing
`_current_schema` pattern) bound in recall_async, retain_async,
retain_batch_async, and execute_task, with a `get_current_bank_id()`
accessor. Bindings use a token + finally reset.
- Add `HINDSIGHT_API_LLM_SEND_BANK_AS_USER` (bool, default off). When on,
outbound OpenAI-compatible LLM and embedding calls are tagged with
`user=<bank_id>` so downstream cost gateways (OpenRouter usage
accounting, LiteLLM, Helicone) can key spend per bank. Injection is
centralized per call_params construction site and never overrides a
`user` the caller already set.
- Propagate the bank ContextVar into the embedding executor thread:
generate_embeddings_batch now copies the current context before the
run_in_executor offload (run_in_executor does not inherit contextvars),
preserving the existing exception wrapping and 1:1 length validation.
- Make the OpenRouter reranker base URL configurable via
`HINDSIGHT_API_RERANKER_OPENROUTER_BASE_URL` (default unchanged:
https://openrouter.ai/api/v1/rerank) so rerank can route through a
metering gateway. The URL is a credential field (not bank-configurable).
Tests cover ContextVar set/reset including on exception, user injection
gated on flag + bank presence + no caller override (chat and tool-calling
paths plus embeddings), real-executor context propagation, and the
configurable rerank base URL.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* refactor(engine): bind the bank ContextVar via decorator, not inline try/finally
The inline token/try/finally wraps re-indented the entire bodies of
execute_task, retain_batch_async, and recall_async — ~1,130 lines of
indentation-only churn in the diff for a ~40-line feature.
Replace the four inline bindings with a @_bind_bank_id decorator that
binds _current_bank_id from the method's bank_id argument (or a key in
a dict argument, for execute_task's task_dict) with the same token +
finally-reset semantics. Method bodies return to their original
indentation, shrinking the memory_engine.py diff to +51/-1.
Behavior is unchanged and now directly unit-tested: the decorator gets
its own tests for positional/keyword binding, dict-key extraction,
reset-on-exception, and non-string fallback to None.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* refactor(api): dedupe bank-attribution helper into shared module
Collapse the two identical _apply_bank_attribution copies (embeddings + OpenAI-compatible
LLM) into engine/bank_attribution.apply_bank_attribution. Add a docs note that the bank id
is transmitted to the provider as the end-user identifier, and de-pad the new config rows.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(providers): add native Nous Portal provider (codex-style OAuth, no hermes_cli dep)
Adds a 'nous' provider that speaks the OpenAI-compatible wire format (thin
subclass of OpenAICompatibleLLM) and authenticates with the rotating,
inference-scoped JWT from a 'hermes portal' login — read natively from
~/.hermes/auth.json, exactly mirroring the Codex provider. No dependency on
the hermes_cli package.
- nous_auth.py: NousAuthManager reads providers.nous OAuth state, decodes the
JWT exp for proactive refresh, and refreshes via POST {portal}/api/oauth/token
(x-nous-refresh-token header). Atomic write-back of rotated tokens. Because
the Hermes auth store is shared with a possibly-running Hermes agent, refresh
takes the same ~/.hermes/auth.lock flock Hermes uses and re-reads the latest
refresh_token from disk before exchange (single-use RT reuse-detection safety).
- nous_llm.py: thin subclass; proactive refresh offloaded to a thread so the
event loop never blocks; one reactive refresh + retry on a 401.
- llm_wrapper.py: register nous in dispatch, validator, no-key set, base-url default.
- tests: auth-store load/refresh/persist/terminal-error + provider wiring (no
Hermes install or network needed).
* docs(providers): document nous provider + add default model
- config.py: add nous to PROVIDER_DEFAULT_MODELS (deepseek/deepseek-v4-flash)
so omitting HINDSIGHT_API_LLM_MODEL doesn't fall back to gpt-4o-mini.
- configuration.md: add nous to the provider list + an env example block.
- models.mdx: add a nous example + a 'Nous Portal Setup (Hermes)' section
covering the 'hermes portal' login, the no-API-key flow, and automatic
JWT refresh that coordinates with a running Hermes agent.
- skills/hindsight-docs: regenerated bundle from the docs sources.
* Implement Memory Guard Lite for OSS
Allow users to prevent token and secret leakage in agent memory.
feat(memory-defense): reject quarantine action in policy parser
refactor(retain): drop quarantine branch from orchestrator
test(retain): remove quarantine-path tests
refactor(memory-defense): remove DefenseAction.QUARANTINE enum value
refactor(api): remove include_quarantined query parameter
refactor(recall): drop include_quarantined parameter from memory engine
test(memory-defense): replace stale parser-reject test with full-union accept test
The previous parametrized test asserted parse_policy() should 422 on any
detector name other than sensitive_data. That contract was deliberately
widened on 2026-06-07 so cloud-style policies pass through api-slim's
parser unchanged. The test was stale; the runtime is correct.
Replaced with test_parse_policy_accepts_full_detector_union, which proves
the actual contract: all 7 detector names are valid in the parser, with
dispatch and entitlement enforcement deferred to the loaded extension.
Memory defense UI
* i18n labels
* Fix tests
* Client changes to fix breaking tests
* Test fixes
* chore: regenerate API clients via generate-clients.sh
The clients were previously hand-generated in a way that diverged from the
project's tooling — including a non-standard hindsight-clients/typescript/client/
directory the generator never produces (the standard output is typescript/generated/),
plus ~150 spurious files.
Revert the entire hindsight-clients/ tree to main and regenerate from the
OpenAPI spec using ./scripts/generate-clients.sh (Rust via progenitor build.rs,
Python/Go via openapi-generator, TypeScript via @hey-api/openapi-ts). The spec
itself is unchanged (a code-regenerated spec is byte-identical to what was
already committed).
Net result is the real API delta only: the new nullable MemoryItem.receipt_uri
field propagated to the Python, TypeScript and Go models.
* refactor(memory-defense): per-bank regex defense, webhooks, drop dead surface
Review cleanup of the memory-defense feature:
- Rename the OSS extension Lite -> Regex (MemoryDefenseRegexExtension,
memory_defense_regex.py). It is pure regex redaction now.
- Drop the agent_memory_guard (OWASP) dependency entirely — the
SensitiveDataDetector fallback and to_owasp_policy are gone; nothing
cloud-tier remains in api-slim.
- Trim the policy to what OSS enforces: { enabled, rules:[{on:sensitive_data,
action}] }. Removed default_action, protected/immutable namespaces,
detector_overrides, min_severity, and the unused
memory_defense_enabled_default server default. Per-bank override stays
(memory_defense is a configurable field) and the UI writes the trimmed shape.
- Fire a memory_defense.triggered webhook on every non-allow decision (redact
and block) when one is configured, via the retain orchestrator. Adds
WebhookEventType.MEMORY_DEFENSE_TRIGGERED + MemoryDefenseEventData. Replaces
the no-op record_violation hook.
- Block is now actually enforced (drop item / 422 when all blocked) instead of
being silently downgraded to redact.
- Remove the unused 'status' lifecycle: the add_status migration + its two
merge migrations, the recall quarantine filter, the status column reads in
search, and MemoryFact.status. Branch now adds zero migrations (single head).
- Remove receipt_uri from the API (MemoryItem) and clients — it was always
None and carried no value.
Tests updated/renamed accordingly; OWASP smoke + enabled-default tests removed.
* fix(memory-defense): address code-review findings
- Delete test_migration_status.py (asserted the removed status column/constraint).
- Remove receipt_uri from the Rust CLI (memory.rs + integration_test.rs) — the
generated client struct no longer has the field, so it wouldn't compile.
- Type the blocked-violations as a BlockedViolation dataclass instead of raw
dicts (serialized via asdict() in the 422 body); type the webhook helper's
decision param as DefenseDecision.
- Add an end-to-end test asserting a redact decision queues a
memory_defense.triggered webhook delivery.
- Drop the unrelated docs/ entry from .gitignore (local scratch, not this PR).
* test(memory-defense): consolidate into a single test_memory_defense.py
Merge the 10 scattered memory-defense test modules (policy parser, regex
engine/screen, redaction benchmark, extension loader, extension-context
wiring, bank-config validation, and the three retain e2e files) into one
test_memory_defense.py, deduping the overlapping unit screen tests and the
duplicated retain redact e2e. 36 tests, same coverage.
* docs(memory-defense): document memory_defense.triggered webhook + block action
- Add memory_defense.triggered to the control-plane webhook event-type selector
(it was firing but wasn't selectable in the UI).
- Document the memory_defense.triggered event (payload + data fields) on the
webhooks API page, and link it from the Memory Defense page.
- Document the block action (the page only described redact) and add a
Notifications section. Regenerate the docs skill copies.
* docs: remove Memory Defense page from version-0.7 (unreleased feature)
The feature was snapshotted into the 0.7 versioned docs by mistake — 0.7 never
shipped Memory Defense. Remove the page and its (sole) Security sidebar category.
* test(memory-defense): assert webhook payload fields + cover block path
- test_retain_fires_webhook_on_redact now parses the queued delivery and
asserts the MemoryDefenseEventData payload (action/detector/matched_types/
message + event status), not just that the event type was queued.
- Add test_retain_fires_webhook_on_block: a block decision fires the webhook
(before the 422 is raised) with action=block. Confirms the delivery persists
despite the blocked retain returning 422.
- Factor out _memory_defense_webhook_events() helper.
* fix(control-plane): render structured API error details as a string
A blocked retain returns 422 with detail {violations: [{message, ...}]}; the
proxy forwards it as `details` and the client passed that object straight into
the sonner toast, crashing with "Objects are not valid as a React child".
Add describeErrorDetails() to reduce details to a string — joining violation
messages when present (so a Memory Defense block shows e.g. "Sensitive data
pattern matched: aws_access_key"), else JSON-stringifying.
* docs(webhooks): clarify WebhookEvent.status covers the memory_defense action
* feat(memory-defense): record redact/block actions in the audit log
Emit a fire-and-forget 'memory_defense' audit entry for each non-allow decision
(alongside the webhook), with the action/detector/document_id/matched_types in
metadata. Threads the engine's AuditLogger into retain_batch like the webhook
manager; gated by the existing audit_log_enabled switch (off by default).
- Add the memory_defense option to the audit-logs UI action filter + the
actionMemoryDefense i18n key across all locales.
- Document it on the Memory Defense page and the audit-logging config section.
- Test: a redact retain writes a memory_defense audit row with the expected
metadata (audit enabled on the test engine).
---------
Co-authored-by: Chris Latimer <[email protected]>
Silences the Docusaurus build warning about untruncated blog posts.
Marker placed after the lead paragraphs so the blog index shows a
clean preview.
Co-authored-by: Claude Opus 4.7 <[email protected]>
Adds POST /v1/default/banks/{bank_id}/health/llm so operators can verify the LLMs a
bank uses for retain / consolidation / reflect actually connect — instead of
consolidation silently stalling when the LLM is unconfigured or unreachable.
- Deliberate (non-polled) probe: one minimal real call per unique LLM config —
operations sharing a configuration are probed once and the result fanned out.
- Status only per operation: connected / not_configured / auth_failed (rejected —
usually a wrong or expired API key, the most common failure) / unreachable / timeout.
Never returns the provider, model, endpoint, API key, or raw provider error (the
detailed error is logged server-side; the auth category is derived from a 401/403 or
known auth markers in the error, and leaks nothing).
- Off by default (it makes a real provider call); enable with
HINDSIGHT_API_ENABLE_BANK_LLM_HEALTH=true. Exposed as features.bank_llm_health on
/version so the UI hides the action when disabled.
- Engine returns typed dataclasses; the handler holds no SQL and auth is enforced
in the engine. The probe reuses the bank's per-operation LLM clients.
- Control plane: a "Health" item in the bank Actions menu opens an "LLM connectivity"
dialog that probes on open (with a re-test button) and shows per-operation status,
including a clear "Invalid API key" label for auth failures.
- Regenerated OpenAPI + Python/TS/Go clients; i18n across all 10 locales; tests in
tests/test_bank_health.py.
A broader per-bank GET /health endpoint (#747) was explored but dropped as redundant
with the existing bank stats; only the connectivity probe is net-new.
The reflect final answer is a separate LLM call whose system prompt dropped the language rule and the bank's directives (they lived only in the agent/reasoning prompt), so weaker models intermittently drifted to English — the mechanism behind flaky multilingual reflect tests. build_final_system_prompt now re-injects the directives section + reminder and a default language rule; HINDSIGHT_API_LLM_OUTPUT_LANGUAGE stays the hard override. Deterministic prompt tests pin the behaviour; real-LLM language tests pass on gemini-2.5-flash and CI-tier gemini-3.1-flash-lite.
* feat: add HINDSIGHT_API_LLM_BEDROCK_SERVICE_TIER env var
Adds support for setting Bedrock service tier (flex/priority/reserved)
via environment variable, following the same pattern as the existing
Groq and OpenAI service tier support.
- config.py: env constant, default, dataclass field, os.getenv() load
- llm_wrapper.py: bedrock_service_tier param plumbing
- litellm_llm.py: inject service_tier kwarg for bedrock/ models
- configuration.md: table entry + Bedrock example block
- models.md/mdx: Bedrock tip block update
Closes#2072
* Add validation + tests for HINDSIGHT_API_LLM_BEDROCK_SERVICE_TIER
- validate() rejects invalid values (e.g. 'standard') with clear error
- Empty string treated as unset (matching llm_output_language pattern)
- Tests: default, flex, priority, reserved, invalid value, empty string
* fix(api): thread bedrock_service_tier from config into LLM providers
The new HINDSIGHT_API_LLM_BEDROCK_SERVICE_TIER flag was plumbed through
LLMProvider/create_llm_provider/LiteLLMLLM but nothing ever constructed
an LLMProvider with the resolved config value, so the env var was inert
(service_tier was never injected into the Bedrock call).
- memory_engine.py: pass bedrock_service_tier=config.llm_bedrock_service_tier
to all four LLMConfig constructions (default/retain/reflect/consolidation)
- llm_wrapper.py: LLMProvider.from_env() reads the env var too, so ad-hoc
constructions honor it
- test_bedrock_service_tier.py: plumbing tests asserting the tier reaches
the LiteLLM call kwargs for bedrock/ models, is omitted otherwise, and
is guarded off non-Bedrock models
* style(test): ruff format test_config_validation.py (fix verify-generated-files)
---------
Co-authored-by: Hermes Agent (Rob) <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
Adds Gemini Batch API support for retain fact extraction (50% discount, 24h SLA) via the existing HINDSIGHT_API_RETAIN_BATCH_ENABLED flag. GeminiLLM overrides the 4 LLMInterface batch methods, adapting Gemini's upload->create->poll->download flow to the OpenAI-batch shapes the consumer expects (same pattern as FireworksLLM). Gemini-only (Vertex unsupported). Threads usageMetadata into the result body. Live-verified end-to-end. Gemini portion of #1144; consolidation batch is a follow-up.
Add a Share button to the constellation toolbar that downloads the
whole graph as a self-contained SVG poster: dark night-sky background
with a soft glow and plus-grid, the Hindsight logo inlined top-left,
and the nodes/links drawn with the exact canvas formulas (solid heat
dots + hub halos, thin faint colored links) — no labels. Fits the full
graph independent of the live pan/zoom.
Adds exportSvgTitle/exportSvgLabel to all locale message files.
* fix(ci): treat npm provenance 409 (tlog) as already-published in release-integration
When a release tag is re-pointed and the workflow re-runs, npm publish --provenance
fails with TLOG_CREATE_ENTRY_ERROR / (409) 'equivalent entry already exists in the
transparency log' because the identical artifact was already logged by the prior run.
The package is already published, so this is benign — widen the already-published
guard to swallow it (alongside the existing 'cannot publish over').
* chore(obsidian): add MIT LICENSE for community-store submission
The Obsidian community-store review bot requires a LICENSE file at the plugin
repo root. The dist repo (vectorize-io/hindsight-obsidian) is mirrored from this
directory via the release workflow, so adding it here propagates on next release.
The cursor integration test files were committed without ruff formatting,
causing verify-generated-files to fail on every PR branched off main. Run
the formatter to bring them in sync (no logic changes).
* blog: Hindsight is the fastest-growing open-source AI memory project ever
Equal-age GitHub star analysis (per-star timestamps) plus third-party
validation from OSSCAR (#10 fastest-growing OSS org, ahead of Mem0) and
dope.security (#1 MCP server in enterprise traffic). Adds cdbartholomew
to blog authors.
* blog: add truncate marker, featured image, fix Slack invite link
- Add <!-- truncate --> after the lead (fixes the build warning addressed
repo-wide in #2065)
- Add featured/social image and hero image
- Replace workspace login URL with the canonical join.slack.com invite
* blog: clean up featured image (remove curve overlapping the headline)
* blog: add captured star-history chart (Hindsight steepest slope); align featured image to brand palette
- Embed a static capture of the overlaid star-history graph in the
'still accelerating' section; Hindsight shows the steepest slope of
any project. Replaces the unreliable live-URL embed (rate-limited).
- Recolor the featured/OG card to the Hindsight brand palette
(#0074d9 -> #009296 gradient, #09090b background) instead of off-palette mint.
* blog: add star-history chart to featured image (text left, chart right)
* fix(ci): override git auth header with OBSIDIAN_DIST_TOKEN for mirror push
The previous fix (unsetting the checkout extraheader) wasn't enough: the runner
also authenticates github.com via a git credential helper, so the subtree push
still ran as github-actions[bot] (403 on the dedicated repo). Override the
Authorization header with the dist token via `git -c` — an explicit header
beats both the checkout header and the helper, and propagates to subtree's
internal push via GIT_CONFIG_PARAMETERS.
* fix(ci): unset bot extraheader before overriding with dist token
http.extraheader is multi-valued, so adding our -c header on top of the
checkout's bot header sent two Authorization headers → GitHub 400. Unset the
checkout header first so only the OBSIDIAN_DIST_TOKEN header is sent.
* fix(ci): reset credential helper so only the dist-token header is sent
The runner's git credential helper was injecting the bot Authorization on top
of our extraheader → 'Duplicate header: Authorization' (400). Reset the helper
chain with -c credential.helper= so only the OBSIDIAN_DIST_TOKEN header remains.
* fix(ci): isolate git context for the obsidian mirror push + diagnostics
Push kept sending a duplicate Authorization from a config scope local --unset
didn't reach. Split locally and push from an isolated context (global/system
config nulled, helper disabled, local extraheader unset) with the token in the
push URL → a single Authorization. Also dump auth-config origins for diagnosis.
* fix(ci): reset the inherited extraheader to push as OBSIDIAN_DIST_TOKEN
Diagnostic showed the runner injects the bot token as an http.extraheader via
an *included* config file (no credential helper), which --unset-all can't touch.
Reset the extraheader list with an empty -c value (read last → clears it at
request time) and auth via the push URL → a single dist-token Authorization.
actions/checkout sets an http extraheader for the default GITHUB_TOKEN that
overrode the token embedded in the subtree-push URL, so the push ran as
github-actions[bot] (no access to the dedicated repo → 403). Unset that header
before the push so OBSIDIAN_DIST_TOKEN is used.
* fix(obsidian): stop creating a GitHub Release per plugin version
Per-integration GitHub Releases pollute the repo's release list (meant for
the core Hindsight product) and steal the 'Latest' badge — the obsidian
v0.1.0 release displaced v0.8.0. BRAT / the community store also can't target
a tag inside a multi-release monorepo (they read a repo's *latest* release),
so the step never gave working BRAT distribution anyway.
- Remove the 'Attach Obsidian release assets' step from release-integration.yml
(replaced with a comment explaining why; npm publish is unchanged).
- Point BRAT install instructions at the dedicated repo
vectorize-io/hindsight-obsidian in the integration README and docs page.
- Add a 'Distribution & maintainers' section documenting the two-repo setup so
plugin updates are released to both (monorepo = source of truth + npm,
dedicated repo = BRAT / community-store releases).
* ci(obsidian): mirror plugin to dedicated repo via subtree on release
Instead of manually maintaining two repos, the release workflow now mirrors
hindsight-integrations/obsidian/ to the root of vectorize-io/hindsight-obsidian
(git subtree push --prefix) and cuts the BRAT / community-store GitHub Release
there — the monorepo stays the single source of truth.
- Add the 'Mirror Obsidian plugin to its dedicated repo' step to
release-integration.yml (unshallow → subtree push → idempotent release).
Needs secret OBSIDIAN_DIST_TOKEN (contents:write on the dedicated repo).
- Drop the now-unused 'contents: write' permission (no releases are created in
this repo anymore).
- Rewrite the README 'Distribution & maintainers' section: the mirror is
automatic, the dedicated repo is generated, don't edit it directly.
* feat(cursor): add Hindsight memory plugin for Cursor
Adds a complete Cursor integration using the plugin architecture
(hooks, skills, rules). Automatically recalls relevant memories
before each prompt and retains conversation transcripts on task
completion. Modeled after the claude-code integration with
Cursor-specific adaptations.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* docs(cursor): add integration docs, blog post, and sidebar entry
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* docs(cursor): clarify plugin vs MCP modes, add hook diagnostics
- Add plugin-vs-MCP comparison table near top of integration doc
- Add "Verifying Plugin Hooks" section with state file commands
- Add troubleshooting note: visible tool calls = MCP, not plugin
- Write last_retain.json state file in retain.py for diagnostics
- Add mode: plugin and query_length to recall state file
- Fix test_settings_file_loaded to isolate from user config
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(cursor): install path, always-write diagnostics, Cloud snippets
- Add mkdir -p before cp -r in all install examples (first-run fix)
- Add "fully quit and reopen Cursor" note to all setup flows
- Recall/retain hooks now write status on every invocation
(success, empty, skipped, error) not just on success
- Fix docs to show ~/.hindsight/cursor-state/ default path
- Add concrete Hindsight Cloud config snippet to Quick Start
- Add Cloud option to blog post setup section
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(cursor): add session field to dynamic bank IDs, add changelog
- Support "session" in dynamicBankGranularity for per-conversation banks
- Add changelog page for cursor integration
- Add test for session-based dynamic bank ID
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(cursor): sync integration README with cookbook/blog setup guidance
- Add mkdir -p for plugin install path
- Add "fully quit and reopen Cursor" instruction
- Show Cloud as Option A, local as Option B, daemon as Option C
- Match the setup flow documented in the cookbook and blog
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* feat(cursor): add pip/uvx installer, fix review findings
- Add hindsight_cursor package with CLI `init` and `uninstall` commands
- Add pyproject.toml for PyPI publishing via existing release pipeline
- Update README install path: `pip install hindsight-cursor && hindsight-cursor init`
- Fix rule/skill files to describe plugin behavior instead of MCP tools
- Add diagnostics on get_api_url failure paths in both hooks
- Remove missing assets/avatar.png reference from plugin manifest
- Add Cloud token retrieval guidance (Settings > API Keys)
- Add test_cli.py with 8 tests for init/uninstall commands
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(cursor): daemon timeout, config defaults, full config docs
- Set daemonIdleTimeout default to 300s (was 0/infinite with no cleanup hook)
- Fix retainEveryNTurns fallback from 1 to 10 in retain.py
- Fix DEFAULTS: hindsightApiUrl="" and bankId="cursor" to match settings.json
- Document all config settings in README (was missing ~15 entries)
- Fix pytest version discrepancy in pyproject.toml
- Fix plugin.json author to "Vectorize" for consistency
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* docs(cursor): streamline setup with init flags, add Docker instructions
- Restructure Quick Start around Cloud vs Local as two clear paths
- Use hindsight-cursor init --api-url/--api-token for one-command setup
- Add Docker run command for users without a local Hindsight server
- Remove separate "configure" step that contradicted init behavior
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* refactor(cursor): replace beforeSubmitPrompt with sessionStart + MCP
beforeSubmitPrompt does not support additionalContext in Cursor's hook
system — the old recall.py was silently ignored. This rewrites the
architecture to use Cursor's native mechanisms:
- sessionStart hook for ambient project-level recall (supports additionalContext)
- MCP integration for on-demand recall/retain/reflect tools mid-session
- stop hook for auto-retain (unchanged, works correctly)
Also fixes Python floor (3.9 -> 3.10, pytest 9 requires it) and
updates docs/blog to match the new architecture.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(cursor): workaround broken sessionStart additionalContext
Cursor's sessionStart hook accepts additionalContext output but silently
drops it before the agent's composer handle is ready — a race condition
acknowledged by Cursor staff in 2026-04, still present in 3.6.31
(verified 2026-06-02 with a marker-emitting test hook). Without a
workaround the plugin's "auto-recall memories at session start" feature
silently does nothing in every install.
Per Cursor staff guidance (Dean Rie, thread 158452), the documented
escape hatch is to write a workspace .cursor/rules/<file>.mdc with
alwaysApply: true — the rules engine injects those reliably. Plugin-
local rules dirs (~/.cursor/plugins/local/...) are NOT reliable per
thread 159101.
Implementation:
- scripts/lib/rules_file.py (new): owns the workaround. Three helpers:
* rotate_session_rules() — deletes any prior rules file at the top
of each sessionStart so an empty recall doesn't leave stale
memories from a previous session.
* write_session_rules() — writes the .mdc with alwaysApply: true,
an HTML comment that explains what the file is and links to the
Cursor bug, and the recalled memories inside a
<hindsight_memories> block (same wrapper the broken native path
used, so the static rules guidance is unchanged).
* ensure_gitignored() — idempotently appends the file path to
<workspace>/.gitignore when the workspace is a git repo. No-ops
otherwise. Matches both /-anchored and bare relative forms so we
don't double-add against an existing entry.
- scripts/session_start.py: rotates at the top, writes the fallback
file after recall succeeds, gates both behind config flags
(useRulesFileFallback, appendToGitignore, both default True). Still
emits additionalContext to stdout below — when Cursor fixes the
upstream bug, dropping the workspace write is the only code change
needed; the same plugin works on the native path with no protocol
rev.
- scripts/lib/config.py: two new config keys + HINDSIGHT_USE_RULES_
FILE_FALLBACK / HINDSIGHT_APPEND_TO_GITIGNORE env overrides.
- rules/hindsight-memory.mdc: tells the agent where recalled memories
now appear (the new .cursor/rules/hindsight-session.mdc file) and
notes that the file is plugin-generated and safe to delete.
- tests/test_rules_file.py: 18 tests pinning the on-disk shape:
frontmatter, alwaysApply, bug link, rotation, idempotent gitignore
with both anchor forms, falsy workspace handling, write-error
degradation.
Why this design (vs. alternatives):
- Just shipping MCP-only and documenting the limitation would repeat
the OpenAI Agents notebook-10 Pattern-1 failure mode: the agent has
to choose to call recall, and small models reliably skip it. Auto-
inject doesn't depend on tool-call choice.
- Reverting to beforeSubmitPrompt would mean a recall per turn instead
of per session, and Cursor staff have signalled additional_context
on that hook is unimplemented (forum 150707).
- The workspace file is the price of Cursor's bug being open with no
ETA. Mitigations: auto-rotate, auto-gitignore, in-file explanatory
comment, config opt-outs.
Verification:
- Full suite: 74 passed (56 prior + 18 new).
- Smoke end-to-end against a fresh git repo: rules file written with
correct frontmatter, .gitignore appended cleanly with both an
explanatory comment and the path entry, no duplicate-add on re-run.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(cursor): adopt requires_real_llm bucketing + live E2E + lockfile + docs
Aligns cursor with the standing test-bucketing convention from PR #1469
("Split test suite into deterministic mock and real LLM buckets") that the
other eight Python integrations already follow.
Changes:
- pyproject.toml: register the `requires_real_llm` marker so the live
E2E suite is selectable as a discrete bucket (and excluded from the
deterministic CI path via `pytest -m "not requires_real_llm"`). Add
hindsight-client as a dev dep — the E2E driver needs it to seed and
verify banks; the runtime plugin scripts still use stdlib only.
- tests/test_e2e.py (new): four-test gated suite that drives the actual
hook scripts the way Cursor does — JSON on stdin, env vars for config
— against a live Hindsight server. Covers:
1. session_start writes the rules-file workaround with recalled
content, appends `.gitignore`, and emits the forward-compat
`additionalContext` to stdout.
2. empty-bank case: hook succeeds without writing a rules file.
3. opt-out: `useRulesFileFallback=false` produces no `.cursor/` or
`.gitignore` mutations even when recall surfaces content.
4. retain end-to-end: drives `retain.py` with a JSONL transcript
(the on-disk shape Cursor actually emits, not an inline messages
array), then verifies the bank holds the fact via direct recall.
Two non-obvious fixtures the suite needs:
- `HOME` / `CURSOR_PLUGIN_DATA` redirected to tmp so the test doesn't
touch the developer's real `~/.hindsight/cursor.json` or state.
- `HINDSIGHT_BANK_MISSION` overridden to a focused mission that aligns
with the seeded fixtures — the production default mission is broad
boilerplate, fine for real users but too diffuse to reliably
surface targeted test content within a deadline.
- `HINDSIGHT_RETAIN_EVERY_N_TURNS=1` because retain.py batches every
N turns (10 by default) and a single-shot test only has one turn.
- uv.lock: committing per the convention every other Python
integration follows. 258 KB, 29 packages resolved, `uv lock --check`
clean.
- README.md: new "How session memory reaches the agent" section
documenting why the plugin writes `<workspace>/.cursor/rules/
hindsight-session.mdc` (Cursor's native `additionalContext` channel
is broken, forum thread 158452, still open in 3.6.31). Captures the
empirically-verified behaviour: Cursor blocks prompt submission
until sessionStart returns, so every new agent's first prompt has
memories, the rules file is regenerated each session, and the file
is auto-gitignored. Two new config knobs (`useRulesFileFallback`,
`appendToGitignore`) added to the Session Recall table.
Verification:
- Deterministic bucket: 74 pass / 4 deselected (the new gated E2E).
- Live bucket (HINDSIGHT_API_URL=http://127.0.0.1:8888): 4 pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(cursor): default to hosted backend + give each retain a distinct document_id
V2 audit (2026-06-02) caught two real bugs in cursor that were missed by
the V1 pass:
1) Goal-5 (Default to Cloud) FAIL — settings.json shipped
hindsightApiUrl='' and the daemon path treated empty as "fall back to
local daemon at 127.0.0.1:9077". Users following the docs ("just enable
the plugin") never reached the hosted backend without explicitly
passing --api-url. Every other integration's empty-config path lands on
https://api.hindsight.vectorize.io.
2) The retain path used document_id=session_id in full-session mode,
which silently upserts the same Hindsight document on every retain.
The audit's 5-turn distinct-fact driver exposed this as "5-turn cloud
→ 1 topic surfaced" — earlier turns got overwritten because each
retain rewrote the single per-session document with whatever
transcript snapshot was current.
Both are addressed below; the live test suite still passes against the
local server and the new deterministic tests pin the cloud-default
resolution + the unique-document-id derivation.
Changes:
- scripts/lib/config.py — add ``DEFAULT_HINDSIGHT_API_URL`` constant
(``https://api.hindsight.vectorize.io``). Add ``useLocalDaemon`` flag
(default ``False``) so self-hosters can opt back into the auto-managed
daemon path. New env override ``HINDSIGHT_USE_LOCAL_DAEMON``.
- scripts/lib/daemon.py — rewrite ``get_api_url`` resolution:
1. Explicit ``hindsightApiUrl`` wins.
2. A locally-running server on the configured port is used (preserves
the "developer already started a daemon" path).
3. ``useLocalDaemon=True`` AND ``allow_daemon_start=True`` (retain
path) triggers the auto-managed daemon. Recall path never starts a
daemon on its own.
4. Otherwise → ``DEFAULT_HINDSIGHT_API_URL``. A failed daemon-start
under (3) also falls back here rather than hard-erroring, so the
plugin keeps working when ``hindsight-embed`` isn't on PATH.
- scripts/retain.py — every retain now derives
``document_id = f"{session_id}-{int(time.time() * 1000)}"`` regardless
of retainMode. The chunked-vs-full-session distinction at the doc-id
layer was always a misfeature; full-session mode now means "the
transcript ingested per retain may span the whole session", not "every
retain writes the same document".
- tests/test_daemon.py (new) — pin the four-tier resolution + env
override + the source-shape of retain.py's document_id derivation.
Verification:
- Deterministic bucket: 81 pass / 4 deselected (74 prior + 7 new).
- Live bucket: 4 pass / 0 fail against 127.0.0.1:8888.
- Manual smoke for empty-config → returns ``DEFAULT_HINDSIGHT_API_URL``.
- Live server still resolves to ``http://127.0.0.1:8888`` when healthy.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(cursor): parse Cursor 3.x role-nested transcript format
retain.py's read_transcript only recognized two transcript shapes:
- Flat: {role, content}
- Type-nested: {type: "user"|"assistant", message: {role, content}}
Cursor 3.6.31 writes a third shape to its stop-hook transcript:
{"role":"user","message":{"content":[
{"type":"text","text":"..."},
{"type":"tool_use","name":"...","input":{...}}
]}}
Top-level has `role` (not `type`), and `content` lives under `message`
as a list of typed blocks (not at the top level as a string). The old
parser's two branches both missed every line: `entry.get("type")` was
None and `"content" in entry` was False. read_transcript silently
returned [] for every Cursor 3 transcript, and retain.py bailed with
status=skipped reason=empty_transcript on every stop hook.
Visible symptom: auto-retain silently stops working under Cursor 3
even though the stop hook fires correctly and transcript_path points
at a real, populated file (verified by reading
~/Library/Application Support/Cursor/logs/.../cursor.hooks.*.log —
the input JSON includes a valid transcript_path that the parser then
ignores). End users see recall continue to work (sessionStart writes
the rules-file workaround) but new turns never get retained.
Fix:
- Add _normalize_blocks_to_text to flatten typed-block lists to a
single string, inlining a compact [tool_use:<name>] marker so
downstream Answer:/Thought: handling still sees coherent structure.
- Recognize the role-nested Cursor 3 shape explicitly.
- Keep flat and type-nested handling intact.
Verified end-to-end against a real Cursor 3.6.31 transcript captured
from ~/.cursor/projects/.../agent-transcripts/<conv>/<conv>.jsonl:
read_transcript now returns the 15 messages it should (1 user + 14
assistant turns) instead of 0.
Regression tests (3 added):
- test_read_transcript_parses_flat_format pins the flat shape.
- test_read_transcript_parses_type_nested_format pins the type-nested
shape.
- test_read_transcript_parses_cursor3_role_nested_with_block_content
is the regression: fails on the pre-fix parser (returns []), passes
now. Also asserts the [tool_use:Shell] marker survives.
14/14 tests in test_hooks.py pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(docs): drop missing image refs in cursor blog post
The 2026-04-03 cursor-persistent-memory blog references
/img/blog/cursor-persistent-memory.png in both frontmatter and
inline markdown, but the image was never added to the repo. build-docs
fails MDX compilation with "Markdown image with URL
/img/blog/cursor-persistent-memory.png couldn't be resolved to an
existing local image file".
Strip the two references so the post renders. The prose stands on its
own without an illustration; an image can be added in a follow-up PR
if/when one is produced.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(cursor): sync openapi.json with main
Branch carried an older snapshot of hindsight-docs/static/openapi.json
that pre-dated main's addition of the OperationProgress schema.
check-openapi-compatibility flagged the missing 'progress' field on
GET /v1/default/banks/{bank_id}/operations/{operation_id} as a
backwards-incompatible removal.
Re-checkout main's openapi.json onto the branch.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(cursor): drop cursor-persistent-memory blog post
The blog post was added as marketing for the Cursor integration but
the accompanying illustration was never produced. Earlier commit
0e4b2568 stripped the missing image references so build-docs would
pass; user prefers the blog post itself be dropped from the integration
PR and authored separately.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(cursor): ruff format scripts + generate docs-skill changelog
verify-generated-files CI flagged drift in three cursor scripts
(scripts/lib/daemon.py, scripts/retain.py, scripts/session_start.py)
and a missing skills/hindsight-docs/.../integrations/cursor.md.
- scripts: applied ruff format/check (3 files reformatted, all checks
pass).
- generate-docs-skill.sh produced the integrations/cursor.md changelog
mirror.
Format-only + a generated file regeneration; no behaviour changes.
All cursor tests pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* ci: re-trigger CI
A previous push to this branch silently did not trigger a pull_request
event in GitHub Actions, leaving the PR without a CI run for the latest
HEAD. Push an empty commit to force a new event.
* ci: empty commit to attach pull_request CI check to the PR head
(Previous pushes did not auto-trigger pull_request workflow events for
reasons internal to GitHub Actions; manual workflow_dispatch runs passed
green but their checks don't roll up onto the PR. Re-poking the head
to surface the green state on the PR.)
* ci: trailing newline to force CI retrigger
* fix(cursor): address review — drop dead code, register changelog + gallery
- Remove compose_recall_query / truncate_recall_query from scripts/lib/content.py
(ported from openclaw but unused — cursor only recalls at sessionStart) and
their test; slice_last_turns_by_user_boundary stays (used by retain.py).
- Add cursor to the INTEGRATIONS map in generate_changelog.py so the release
changelog step resolves the slug.
- Add the integrations.json gallery entry + icon and rely on the existing
docs-integrations/cursor.md so check-integrations.mjs passes.
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Ben <[email protected]>
Co-authored-by: DK09876 <[email protected]>
Closes#1139. The gemini-embedding-2 multimodal models aggregate a multi-input request into one embedding, breaking 1:1 input->vector alignment. Force batch size 1 (one input per call) for that family, keep batching for gemini-embedding-001, and raise a clear error on misaligned counts. Adds unit tests + a real Vertex integration test that skips when the preview model isn't enabled.
The docs told users to run `python /path/to/.../install.py` with no way to
obtain that file (no pip package, no clone step) — effectively unusable. Bring
cline in line with roo-code and cursor-cli by shipping it as a pip package.
pip install hindsight-cline
hindsight-cline install --api-url ... --api-token ...
hindsight-cline uninstall
- Move the install logic into a hindsight_cline package with an argparse CLI
(install/uninstall subcommands) exposed via a console_scripts entry point.
- Bundle the hook payload (4 hook scripts + lib/ + settings.json) as package
data under hindsight_cline/hooks/, read via importlib.resources.
- Add pyproject.toml (hatchling), LICENSE, py.typed, uv.lock.
- Switch the CI job to uv build + uv sync --frozen + uv run pytest.
- Update README, docs page, and the launch blog post to the pip flow.
The changelog generator already maps cline -> hindsight-cline. Detecting a
pyproject.toml, the release workflow now publishes hindsight-cline to PyPI
(first release needs a PyPI pending publisher).
Convert the Cursor CLI integration from a git-clone + ./scripts/install.sh
flow to a pip-installable package with a `hindsight-cursor-cli install` CLI,
matching roo-code and the other Python integrations.
- Add pyproject.toml (name: hindsight-cursor-cli) and console script
- Add hindsight_cursor_cli/ package: cli.py + install.py, a Python port of
the old install.sh/uninstall.sh
- Bundle the hook payload (scripts/, settings.json, hooks.json) as package
data under hindsight_cursor_cli/hooks/; the installer deploys it to
~/.cursor/hooks/cursor-cli/ and merges the hook registry
- pyproject is the single source of truth for the version; the installer
stamps it into the deployed settings.json (used by client.py's User-Agent)
- Remove scripts/install.sh and scripts/uninstall.sh
- Add test_install.py + test_cli.py; retarget existing hook tests
- Switch the CI job to the uv build/sync/test flow
- Update README + docs to `pip install hindsight-cursor-cli`
The existing cline.svg was a hand-drawn placeholder — dark rounded
box with two blue eyes and an antenna — that doesn't match Cline's
actual logo. Swap it for the official Cline AI mark (black squircle
with two pill cutouts and a small knob on top).
Source: uxwing.com/cline-ai-icon — licensed for commercial use
without attribution.
* blog: add Cline persistent memory integration post
Walkthrough of the new Hindsight + Cline integration that wires up
persistent memory via Cline's lifecycle hooks (no MCP). Covers the
four hooks, install + config, per-project and team memory patterns,
and tradeoffs.
Cover is a placeholder (Codex art) for now — swap before merging.
* blog(cline): replace em-dashes with contextual punctuation
Targeted sweep replacing 21 em-dashes with the appropriate punctuation
(commas / semicolons / periods / colons) given each surrounding clause.
The table-cell placeholder on the "Model tool-calling needed" row
becomes "n/a" so the column still reads as "not applicable for the
default."
Code blocks, URLs, file paths, and the ASCII flow diagram (which uses
U+2500 box-drawing characters, not em-dashes) are untouched.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
* blog(cline): explain why Cloud matters for the Cline workflow
Expand the Cloud-section intro to cover the Cline-specific wins:
multi-machine VS Code sync, no LLM key in the hook environment, and
no local hindsight-api to keep running while doing dev work.
* blog(cline): swap placeholder cover for Hindsight x Cline card
Clears the verify-generated-files drift: CI lints all integrations
(LINT_ALL_INTEGRATIONS) and reformats these recently-added test files,
which were committed without CI-mode formatting and so showed as drift
on every PR.
* docs: changelog and blog post for v0.8.1
* docs(blog): drop integrations section; add hs-release skill
* docs(hs-release): make changelog worktree a fallback, not a required step
* docs(blog): fix broken 0.8.0 cross-link (date-based blog URL)
* feat(api): add HINDSIGHT_API_STORE_DOCUMENT_TEXT flag to skip raw text storage
When set to false, the retain pipeline runs unchanged (chunking, fact
extraction, embedding, entity linking) but drops the raw source text:
documents.original_text is stored as NULL and chunks.chunk_text as empty.
content_hash is still computed from the real text so delta-retain dedup is
unaffected, and recall is unaffected because it reads from memory_units.
Closes#2061
* feat(api): reject append + drop source-text reads in privacy mode
Follow-up to the HINDSIGHT_API_STORE_DOCUMENT_TEXT flag, covering the
features that read raw document/chunk text back:
- retain update_mode='append' is now rejected when text storage is
disabled (it rebuilds the document from the stored original_text, which
is NULL, and would silently drop prior content).
- reflect no longer offers the 'expand' tool (get chunk/document source),
gated via get_reflect_tools(include_expand=...); the hallucination guards
no longer hardcode 'expand' as always-allowed.
- reflect's recall step no longer attaches empty source chunks.
Other read sites (get-document/list-chunks/get-chunk endpoints + MCP,
export/import, public recall include_chunks) already degrade gracefully to
empty/None and are documented.
* fix(api): get-document 200 with null text + 400 on append in privacy mode
Caught while testing the flag live against a running server:
- DocumentResponse.original_text was a non-optional str, so the GET
document endpoint raised ResponseValidationError -> HTTP 500 when the
text is NULL. Made it str | None.
- The retain handler mapped all exceptions (including the append-rejection
and duplicate-document_id ValueErrors) to HTTP 500. Map ValueError to 400,
matching the convention used by the other endpoints.
Adds an HTTP-level regression test (the engine-level test passed because
get_document returns a dict, bypassing response-model validation).
* feat(ui): warn when document text storage is disabled
Surface the store_document_text flag so the control plane can warn users
that raw source text isn't persisted:
- /version feature flags now include store_document_text (regenerated
OpenAPI spec + SDK clients; also picks up the earlier DocumentResponse
original_text optional change).
- features-context exposes it (defaults true, so the warning only shows
when the server explicitly reports privacy mode).
- Document detail dialog: the Content tab shows a small notice instead of
an empty body when text isn't stored.
- Add Document dialog: a small notice that raw text won't be kept.
- i18n strings added across all locales.
Adds an API test asserting /version reports the flag.
* refactor: drop "privacy mode" wording; reposition document-text warnings
- Remove the "privacy mode" phrasing I had introduced from comments,
docstrings, test names, docs, and UI labels. The flag is described by
what it does (skip storing raw document text) instead.
- Add Document dialog: move the warning to just above the action buttons.
- Document dialog: also show the warning on the Chunks tab.
* fix(cli): handle optional document original_text
original_text is now Option<String> in the generated client (it can be
null when document text storage is disabled), so the CLI can't print it
with {} directly. Show "(not stored)" when absent.
Hindsight set a session-level vchordrq.probes override (10/30) for the
vchord backend, but VectorChord requires the probes value to match each
index's build.internal.lists hierarchy. Hindsight's built-in vchordrq
index clause does not set lists, so it is listless and expects 0 probes;
the session GUC supplies 1, and every query on that pooled connection
fails with "need 0 probes, but 1 probes provided".
On vchord deployments this rejects retain completions after extraction
succeeds, so the worker retries forever and the queue fills with stuck
retain ops that block consolidation.
Drop the vchord entries from the ANN tuning dispatcher so no session
probe override is applied; deployments that partition vchordrq indexes
should attach probes via index storage fallback parameters (VectorChord
1.1) instead. pgvector hnsw.ef_search tuning is unchanged.
Refs #1667.
Bank selection was lost on refresh for non-default locales because the
locale prefix (e.g. /es/banks/x) defeated path parsing in bank-context.
Switch next-intl to localePrefix "never" so the locale is resolved from
the NEXT_LOCALE cookie and never appears in the URL. Paths stay clean
(/banks/x) for every language, so the existing ^/banks/ parsing works.
Also removes the now-dead stripLocalePrefix() helper in middleware.
Supersedes #2070.
Tests were excluded from both ruff lint and format via the top-level
[tool.ruff].exclude in hindsight-api-slim, hindsight-embed and the shared
ruff.toml. As a result test files drifted from the formatter's style and
every PR that touched a test (or ran format-on-save) carried large
formatting-only churn.
Move the tests exclude into [tool.ruff.lint].exclude (and [lint].exclude in
ruff.toml) so the formatter now covers tests while lint rules — too noisy for
test code (unused imports/vars, import ordering) — stay excluded. Then run
ruff format across all test directories.
Note: lint.exclude is a post-traversal path filter, so it needs the glob form
'tests/**' rather than the directory form 'tests/' used by top-level exclude.
* feat(obsidian): add Obsidian plugin integration
Sync an Obsidian vault into a shared Hindsight bank and chat with an agent
grounded on your notes (citations link back to the source note). Obsidian
stays the source of truth: one-way sync, conversation memory off by default.
- TS plugin (esbuild → main.js): requestUrl HTTP client, incremental sync
engine (hash/mtime gate, upsert/delete/rename, reconcile + orphan prune),
reflect-backed chat view with citations + reasoning, settings + commands.
- One shared bank ("obsidian") across vaults; implicit scoping via auto tags
(vault:, folder: ancestors, created:/updated: date buckets) so recall can
scope by any combo from the UI or an automation. document_id is
vault-prefixed to avoid cross-vault collisions.
- Tests (vitest, mocked obsidian module): sync upsert/delete/rename/hash-gate,
auto-scope tags, client request shapes, and the §0.5 guard (no conversation
retain when the toggle is off).
- Wiring: test-obsidian-integration CI job + aggregate gate, VALID_INTEGRATIONS,
changelog generator, integrations.json + docs page + changelog page + icon.
Out of scope for v1: rename-proof frontmatter identity; BRAT/community-store
release-asset attachment (release-integration.yml only npm-publishes today).
* feat(obsidian): scoped chat filters, retrieved-notes, debug logging, branding
- Chat scope filters (vault + folder dropdowns above the ask bar) build
tag_groups (all_strict) passed to reflect; folder tags are hierarchical.
- "Notes retrieved" list + per-step reasoning: reflect's based_on omits
document_ids, so harvest them from the recall/expand tool outputs (incl.
nested observation source_facts). New reflect-util with a unit test.
- Debug logging toggle: logs the reflect request (with scope) and the
retrieved note ids to the console for verifying filters.
- "New chat" view action + command to reset the conversation.
- Branding: real Hindsight logo (favicon) embedded as a data URI for the
ribbon, chat header, empty state, and tab icon (via an SVG <image>).
* feat(obsidian): chat output extras — copy, snippet previews, wikilink resolution
- "Copy" action under each answer.
- "Notes retrieved" now shows the matched text snippet per note (from the
recall/expand tool outputs + observation source_facts), so you can see why a
note was pulled without opening it. New retrievedNotesDetailed() + test.
- Answers render with the active note as sourcePath, so [[wikilinks]] resolve.
* feat(obsidian): auto-grow chat composer + frontmatter/client edge tests
The composer textarea now grows with multi-line input up to a 240px cap,
then scrolls. Adds unit coverage for the two previously untested pure
layers: frontmatter.normalizeNote (no/blocklist/inline-flow frontmatter,
created/date precedence, scalar metadata, unterminated block) and client
edge paths (transport rejection, reflect tag_groups-vs-tags branch, retain
tag omission).
* ci(obsidian): attach BRAT install assets to the GitHub release
Obsidian plugins install from GitHub release assets (main.js, manifest.json,
styles.css), not npm. The release-integration workflow only npm-published
the package, leaving the plugin uninstallable. Add an obsidian-only step
that creates/updates the release for the tag and uploads the three files
(idempotent on re-run), and grant the job contents:write.
* chore(obsidian): fix generated-files drift (prettier + docs-skill mirror)
Run prettier over the integration (README.md table/emphasis formatting and
the new frontmatter.spec.ts array wrapping) and regenerate the agent-skill
changelog mirror that generate-docs-skill.sh produces. Resolves the
verify-generated-files CI check.
* feat(obsidian): persistent sync-status indicator in the status bar
Background, edit-triggered sync previously ran silently — only the manual
'Sync vault now' surfaced a Notice. Add an always-visible status-bar item
that shows synced/syncing/error state plus a live 'last synced x ago' time,
notes the pending-edit count, and triggers a sync on click. All sync paths
(reconcile, debounced flush, single-note ingest, delete, rename) route
through it. Pure label/tooltip logic is unit-tested (9 cases).
* feat(obsidian): mirror sync status in the chat header
Surface the same sync state in the chat panel's header (right-aligned),
reusing renderSyncStatus with no brand prefix since the Hindsight wordmark
is already shown. The plugin pushes updates to any open chat view whenever
sync state changes, and clicking the pill triggers a sync.
* feat(obsidian): show note count + pending in the sync indicator
Replace the bare check mark with the tracked-note count and either the
pending-edit count or the last-sync time (e.g. '✓ 412 notes · 2m ago',
'✓ 412 notes · 3 pending'). Tooltip carries the full breakdown. Count comes
from the local sync index; singular/plural handled.
* feat(obsidian): explicit refresh button for sync (spins while syncing)
The sync status was clickable text with no obvious affordance. Split it into
an informational status label plus a dedicated refresh icon button (in both
the chat header and the status bar) that triggers a sync on click and spins
while a sync is in flight.
* docs(obsidian): document the sync-status indicator in the README
* feat(integrations): add oh-my-openagent (OMO) integration
Cloud-first Hindsight memory integration for the OMO agent harness.
Provides automatic recall/retain via lifecycle hooks with support
for both Hindsight Cloud (api.hindsight.vectorize.io) and self-hosted.
- 5 lifecycle hooks: SessionStart, UserPromptSubmit, Stop, SubagentStop, SessionEnd
- Always-apply rule for memory guidance
- Config hierarchy: settings.json → ~/.hindsight/omo.json → HINDSIGHT_* env vars
- Bearer token auth for cloud mode (hsk_* keys)
- Interactive demo script for local dev testing
- Full test suite (29 tests)
* chore(ci): add OMO integration test job
- Add test-omo-integration job to test.yml (pip + pytest pattern)
- Add detect-changes output and path filter for omo
* fix: apply lint formatting to OMO integration files
* fix: fix demo importlib.util import and add mkdir to setup instructions
- Import importlib.util explicitly (importlib alone doesn't expose .util)
- Add mkdir -p for ~/.omo/hooks and .omo/rules in README copy instructions
- Default demo API URL to localhost:8888 to match Docker compose port
* docs: rewrite OMO README with cloud-first setup as default
Simplify setup to 4 numbered steps with cloud as the primary path.
Move self-hosted to an optional section. Add testing section.
Clarify that rules are per-project while hooks/scripts are global.
* chore: add omo to VALID_INTEGRATIONS in release script
* fix: address release-blocking issues for OMO integration
- Remove pyproject.toml (causes release workflow to mis-classify omo as
a Python package and fail uv build). Move pytest config to pytest.ini.
- Add IntegrationMeta entry in generate_changelog.py
- Add integrations.json entry with internal doc link
- Add docs page at docs-integrations/omo.md
- Add omo.svg icon
- Add "version": "0.1.0" to settings.json
* feat(cline): add Hindsight memory integration via lifecycle hooks (no MCP)
Gives Cline persistent long-term memory without MCP, using its lifecycle
hooks. TaskStart/UserPromptSubmit recall relevant memories and inject them
via contextModification; TaskComplete/TaskCancel retain the task transcript.
Cline hands hooks no transcript, so prompts are accumulated per-task in
local state and retained at task end. Reuses the agent-agnostic core from the
Codex integration (HTTP client, config, bank derivation, state, content
helpers). Includes an install.py, 34 tests, CI job, and release/docs wiring.
* refactor(cline): typed HindsightClineConfig instead of raw dict (review)
Address the code-review should-fix: replace the raw `config` dict (known,
enumerated keys) with a HindsightClineConfig dataclass per SKILL §5. load_config
maps the camelCase settings.json/env keys onto snake_case fields; consumers
read typed attributes. Also tighten type hints flagged in the review:
ensure_bank_mission (client: HindsightClient, debug_fn: Callable[..., None] |
None), _cast_env(typ: type) -> Any, debug_log(... ) -> None, parse_hook_input
(raw: dict[str, Any]), and client _headers/_request dict parameterization.
retain_metadata stays a dict (genuinely user-defined dynamic keys).
* refactor(cline): parameterize retain() metadata dict type
* blog: How oh-my-pi Built Persistent Codebase Memory on Hindsight
Adoption case-study post on oh-my-pi (10k-star terminal coding agent
by @can1357) using Hindsight as its memory backend. All technical
details and code snippets pulled verbatim from the public repo at
github.com/can1357/oh-my-pi.
Covers: their three-mode bank-scoping policy (global / per-project /
per-project-tagged with the default being tag-based with `any` match);
the mental-model seed file (user-preferences, project-conventions,
project-decisions, each with delta-mode refresh_after_consolidation);
the debounced retain queue (16-item batch / 5s interval) and the
full-session auto-retain path; the auto-recall pipeline with the
exact preamble they use; and the reason they replaced
@vectorize-io/hindsight-client with a minimal fetch client.
Closes by tying the pattern back to other Hindsight-backed coding
agents (Hermes, Claude Code, OpenClaw) — same shape, different
implementations.
Cover image is a placeholder reusing the Hermes coding-assistant
card; final Hindsight x oh-my-pi art is a follow-up.
* blog(oh-my-pi): drop irrelevant Python-client aside
* blog(oh-my-pi): swap placeholder for omp + Hindsight branded cover
* blog(oh-my-pi): add Can Bölük (can1357) as co-author
* blog(oh-my-pi): apply final-revised draft
* blog(oh-my-pi): swap cover for retain/recall/reflect cycle diagram
* blog(oh-my-pi): bump date to 2026-06-08
* feat(integrations): add Haystack integration for persistent agent memory
Add hindsight-haystack package providing Haystack Tool instances backed
by Hindsight's retain/recall/reflect APIs. Uses async client methods with
event-loop-safe sync wrapper to work correctly inside Haystack's agent
runtime.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(haystack): use persistent event loop for async client calls
aiohttp binds its session to the creating event loop, so asyncio.run()
(which creates/destroys a loop per call) breaks on sequential calls.
Switch to a persistent daemon-thread event loop with
run_coroutine_threadsafe. Also removes unused per-operation timeout
constants and adds _run_sync tests.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* feat(haystack): add HindsightToolset with auto-recall/retain, fix review issues
- Add HindsightToolset(Toolset) with auto_recall and auto_retain flags
that automatically inject recalled memories into the system prompt
before each turn and retain user/assistant messages after each turn
- Fix _ensure_bank to retry on transient errors instead of permanently
disabling bank creation
- Fix reflect_on_memory to return structured_output JSON when
response_schema is set
- Truncate error messages to avoid dumping raw HTTP responses to agents
- Extract _build_backend_kwargs() and _build_tools() as shared helpers
- Add 20 new tests (60 -> 80 total) covering toolset, auto-recall,
auto-retain, structured output, and bank creation retry
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(haystack): address review round 2 — max_recall_results, role metadata, _run_sync cleanup
- Add max_recall_results param to HindsightToolset (default 10) to cap
auto-recall prompt injection size, matching Pydantic AI pattern
- Auto-retain now includes role + source metadata on messages, matching
LlamaIndex's metadata pattern for distinguishable conversation turns
- _recall_for_prompt now calls the API directly with result cap instead
of going through the formatted string from recall_memory
- Serialize/deserialize max_recall_results in to_dict/from_dict
- Add tests for max_recall_results and role metadata (82 total)
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(haystack): default to Cloud without configure(); add gated E2E + bucketing
- resolve_client() now falls back to DEFAULT_HINDSIGHT_API_URL and the
HINDSIGHT_API_KEY env var when configure() was never called (it previously
raised "No Hindsight API URL configured"). Updated the unit test to assert
the cloud-default + env-key behavior. Satisfies the "default to Cloud" goal.
- Add a gated tests/test_e2e.py (retain/recall/reflect tools against a live
Hindsight server), marked requires_real_llm; register the marker in
pyproject; the test-haystack-integration CI job now runs the deterministic
bucket (-m "not requires_real_llm").
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(haystack): close owned clients at exit; run E2E client I/O on the bridge loop
The tools run async client calls on a persistent background event loop. aiohttp
sessions bound to that loop were never closed, surfacing as "Unclosed client
session/connector" warnings. Track module-owned Hindsight clients (those created
when the caller didn't pass client=) and close them on the loop via an atexit
hook, then stop the loop. The live E2E now performs all client I/O through that
same loop (acreate_bank/adelete_bank/aclose via _run_sync) and logs cleanup
failures instead of swallowing them — zero unclosed-connector warnings.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(haystack): sync openapi.json with main
Branch carried an older snapshot of hindsight-docs/static/openapi.json
that pre-dated main's addition of OperationProgress. Re-checkout main's
openapi.json so check-openapi-compatibility passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(haystack): strip api_key from to_dict() so it doesn't leak to YAML
_build_backend_kwargs was emitting the api_key in the serializable dict
that to_dict() returns. Haystack pipelines get dumped to YAML for
inspection, checkpointing, and sharing — a serialized key leaks into
every dump. Reviewer (benfrank241) flagged this on #1256.
Drop the api_key from the serialized backend_kwargs. resolve_client()
already reads HINDSIGHT_API_KEY from the env var as a final fallback,
so a redeployed pipeline picks the key back up from the host's
environment rather than from the YAML.
The test_tools_round_trip_serialization_with_client test previously
asserted the leak — flipped it to assert the key is NOT present
and added a json.dumps probe asserting the literal key value also
doesn't appear under any other field name. Pre-fix, the test fails:
AssertionError: api_key must not appear in serialized backend_kwargs
— would leak to YAML pipeline dumps
assert 'api_key' not in {'api_key': 'client-key', ...}
86/86 tests pass post-fix.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* ci: re-trigger CI
A previous push to this branch silently did not trigger a pull_request
event in GitHub Actions, leaving the PR without a CI run for the latest
HEAD. Push an empty commit to force a new event.
* ci: empty commit to attach pull_request CI check to the PR head
(Previous pushes did not auto-trigger pull_request workflow events for
reasons internal to GitHub Actions; manual workflow_dispatch runs passed
green but their checks don't roll up onto the PR. Re-poking the head
to surface the green state on the PR.)
* ci: trailing newline to force CI retrigger
* fix(haystack): register in changelog/gallery + docs page + tidy tools
Review follow-ups for the Haystack integration:
1. Add haystack to the INTEGRATIONS map in generate_changelog.py so the
release script's changelog step resolves the slug (was missing, which
would fail the release).
2. Add the integrations.json gallery entry, a doc page at
docs-integrations/haystack.md, and an icon — required by
check-integrations.mjs (forward: entry needs a doc page; reverse: a
released integration must appear in the gallery).
3. Drop the inaccurate 'Raises: HindsightError' clause from
create_hindsight_tools — resolution always succeeds (URL defaults to
Cloud) so it never raises; the error type stays exported as the
conventional public catch type.
4. Replace the _TOOL_DEFS dict-of-3-tuples with a frozen _ToolDef dataclass
and drop the redundant method-name field (it equalled the dict key).
* fix(haystack): use official Haystack logo for gallery icon
Replace the placeholder glyph with the real deepset Haystack mark (teal
#0EAF9C rounded square + white symbol), extracted as vector from deepset's
own website source (deepset-ai/haystack-home site-logo partial).
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: DK09876 <[email protected]>
The rotating integrations banner referenced /img/icons/grok-build.png,
but the asset is grok-build.svg (the gallery already uses the .svg). The
missing .png rendered as a broken-image placeholder in the marquee. Point
the banner at the existing .svg.
Drop Docusaurus versioned snapshots for 0.3, 0.4, and 0.5
(versioned_docs + versioned_sidebars) and remove their entries from
versions.json. Keeps 0.6, 0.7, and 0.8.
docusaurus.config.ts reads versions.json dynamically, so no config
changes are required.
The maintenance-routines migration (e5f6a7b8c9d0) only created the shared
public.banks_needing_consolidation() / public.schemas_with_expired_rows()
routines when the run had no target_schema at all. But the single-tenant
runtime always migrates an explicit schema, defaulting to public, so on
every default PostgreSQL deployment the migration was stamped applied while
the functions were never created. Background maintenance then logs
"function public.schemas_with_expired_rows(...) does not exist" and
"function public.banks_needing_consolidation() does not exist".
Since e5f6a7b8c9d0 is already stamped on affected 0.8.0 databases, editing
it would not re-run there. This adds a forward repair migration that
idempotently (CREATE OR REPLACE) reinstalls the routines on the run that
targets the shared public schema (base run, or explicit target_schema=public),
self-healing already-upgraded deployments and covering fresh upgrades.
Non-public tenant runs still skip it to avoid concurrent CREATE on the same
pg_proc row.
Fixes#2056
The cursor-cli release (integrations/cursor-cli/v0.1.0, #1975) created a
release tag but never added the integration to the docs single source of
truth. check-integrations.mjs enforces that every released integration tag
has an entry in src/data/integrations.json with a matching doc page, so the
build-docs job has been failing on every PR (e.g. #866) — not from those PRs'
changes, but from the missing cursor-cli entry on main.
Add the gallery entry, the docs-integrations/cursor-cli.md page, and an icon.
Both invariants now pass locally.
* fix(deps): cap tokenizers<=0.23.0 for local-ML extras (#2055)
transformers (incl. 5.x) hard-requires tokenizers<=0.23.0 via a runtime
check, but tokenizers 0.23.1 is the latest on PyPI. Without a lockfile, an
in-place upgrade to 0.8.0 can resolve tokenizers 0.23.1 and break local
embeddings/reranker startup with an ImportError. Pin the compatible range
in the local-ml and local-onnx extras.
* chore(deps): update uv.lock for tokenizers cap (#2055)
* Add .worktrees to .gitignore
* feat(integrations): add Cursor CLI integration
Four Cursor CLI hooks keep memory in sync automatically:
- sessionStart — health check + daemon pre-start
- beforeSubmitPrompt — recall relevant memories and inject as
`additional_context`
- stop — read the on-disk transcript, retain the
conversation (fire-and-forget, async retain)
- preCompact — surface which memories will survive the next
context-window compaction
The integration follows the same shape as the existing codex
integration (Python hook scripts reading JSON from stdin, writing
JSON to stdout) and the same config schema, so users with a
codex setup can drop in cursor-cli with no new concepts.
Project resolution prefers Cursor's `CURSOR_PROJECT_DIR` env var
(common field in the hook runtime), then `workspace_roots[0]`,
then `cwd` — avoiding the codex `session` default granularity
since Cursor's `stop` hook is fire-and-forget.
CI:
- new `test-cursor-cli-integration` job in .github/workflows/test.yml
- `cursor-cli` added to VALID_INTEGRATIONS in scripts/release-integration.sh
Docs:
- new top-level hindsight-integrations/README.md indexing every
integration, with cursor-cli highlighted under "Coding agents & CLIs"
72 tests cover the four hook scripts, the bank-id derivation, the
HTTP client, the cursor transcript reader, and the chunked-retain
logic. All pass under `python -m pytest tests/ -v`. Ruff and
shellcheck are clean.
Co-Authored-By: opencode minimax-m3 high <[email protected]>
* fix(cursor-cli): derive bank id in session_start banner
The session banner used a static `config.get("bankId") or "cursor-cli"`
fallback, while recall.py / retain.py / pre_compact.py all called
`derive_bank_id(hook_input, config)`. With `dynamicBankId: true` and
`dynamicBankGranularity: ["project"]`, the banner reported the static
default ("cursor-cli") while the other hooks targeted the derived
bank (e.g. "korayem-cli-agents-hindsight"). Users and agents that
trusted the banner then called `hindsight memory reflect cursor-cli`
against an empty bank, while the hooks themselves were writing to
the correct one.
Mirror recall.py's pattern: import derive_bank_id, call it with the
parsed hook_input, surface the resolved bank in debug logs so users
can confirm parity with the other hooks.
Tests cover all four acceptance criteria:
- dynamicBankId true → derived bank in banner
- dynamicBankId false + explicit bankId → static bank in banner
- HINDSIGHT_BANK_ID env override → resolved through config loader
- regression: previous tests still pass
Co-Authored-By: opencode minimax-m3 high <[email protected]>
* refactor(cursor-cli): align implementation with codex/claude-code
The cursor-cli implementation shipped several invented surfaces and
patterns that drifted from the codex/claude-code reference. This
commit removes the inventions and brings the script bodies back
to near-parity with the references so future divergence stands
out in a diff.
Removed — invented user-facing surfaces:
- session_start.py: the "Hindsight memory integration is active
for this session. Bank: <id>" additional_context banner.
The references' sessionStart is fire-and-forget with no
additional_context. Banner output is where the bank-id
display-mismatch bug lived, and the only consumer that "saw"
the banner was the agent, which never asked for it.
- pre_compact.py and its TestPreCompactHook class entirely.
preCompact is observational in Cursor's spec — it cannot
influence the compaction itself. The actual mechanism that
preserves memory through compaction is the beforeSubmitPrompt
recall that fires after compaction finishes. The "Hindsight
preserved N memories" user_message was invented value with
no reference equivalent.
Restored — patterns from codex that were dropped:
- session_start.py: debug_log for "Hindsight not running" path
(was changed to a noisier print).
- recall.py: import time, import write_state, LAST_RECALL_STATE
const, and the write_state(...) block that drops the most
recent recall payload to ~/.hindsight/cursor-cli/state/.
Dead code in codex, but matching the reference for now keeps
the diff focused on actual cursor-specific differences.
- recall.py: `prompt = (hook_input.get("prompt") or
hook_input.get("user_prompt") or "")` — kept the user_prompt
fallback for defense in depth.
- retain.py: "Exit codes" section in the docstring and the
inline comments / blank lines that codex uses for
readability.
- lib/__init__.py: removed the cursor-cli-specific docstring
to match codex's empty file.
Kept — true Cursor-specific differences (justify in PR review):
- session_start.py / retain.py / recall.py: docstrings mention
Cursor, not Codex.
- debug log key: conversation_id (Cursor's term) instead of
session_id (codex's term). Cursor's `stop` hook carries
conversation_id; codex's carries session_id.
- session_id fallback chain: hook_input.get("conversation_id")
or hook_input.get("session_id") or "unknown" — accepts both
payload shapes.
- template_vars includes conversation_id alongside session_id
so retainTags / retainMetadata templates work either way.
- retainTags default: ["{conversation_id}"] (codex is empty list)
— convention is to tag the document with the source-of-truth id.
- retainContext default: "cursor-cli" (was "codex").
- agentName default: "cursor-cli" (was "codex").
- bankMission / retainMission defaults: full text matching the
Cursor CLI audience (codex leaves them empty).
- USER_AGENT: "hindsight-cursor-cli/<version>" (was
"hindsight-codex/<version>").
- PROFILE_NAME: "cursor-cli" (was "codex") in daemon.py —
controls the hindsight-embed profile name.
- bank resolution: CURSOR_PROJECT_DIR env var → workspace_roots[0]
→ cwd (codex only uses cwd). Cursor sets CURSOR_PROJECT_DIR
on every hook.
- VALID_FIELDS in bank.py adds "gitProject" as an alias for the
project resolution.
- recall output schema: Cursor's beforeSubmitPrompt wants
{continue, additional_context}, not codex's
{hookSpecificOutput: {hookEventName, additionalContext}}.
Tests:
- Removed TestSessionStartHook tests that asserted on the
deleted banner.
- Removed TestPreCompactHook class entirely.
- test_session_start.test_no_output_when_server_reachable is
the new mirror of codex's expectations: sessionStart emits
nothing on stdout.
Net: -296 lines, 68 tests passing, ruff + shellcheck clean.
Co-Authored-By: opencode minimax-m3 high <[email protected]>
* fix(cursor-cli): flush memory at session end
Add a Cursor sessionEnd hook that forces a final retain so short sessions are stored even when retainEveryNTurns skips per-turn retention. Also remove stale preCompact/banner docs and align the daemon idle-timeout fallback with the shipped config.
Co-Authored-By: OpenAI GPT-5 Codex High <[email protected]>
* fix(cursor-cli): register integration in changelog generator
cursor-cli was added to VALID_INTEGRATIONS and CI but missing from the
INTEGRATIONS map in generate_changelog.py, which the release script reads
when generating the changelog entry. Without it, the release would fail at
the changelog step.
---------
Co-authored-by: opencode minimax-m3 high <[email protected]>
Co-authored-by: OpenAI GPT-5 Codex High <[email protected]>
Turn the Roo Code integration into a pip-installable package so users can:
pip install hindsight-roo-code
hindsight-roo-code install [--api-url ...] [--project-dir ...] [--global]
- Move install logic into a hindsight_roo_code package with an
argparse-based CLI exposed via a console_scripts entry point
- Ship the rules file as package data, read via importlib.resources so it
resolves from the installed wheel
- Add pyproject.toml (hatchling), LICENSE, py.typed
- Add CLI tests; update install/rules tests to import from the package
- Switch the CI job to uv build + uv sync + uv run pytest
- Map roo-code -> hindsight-roo-code in the changelog generator
- Update README and docs to the pip install + CLI flow
* fix(opencode): fold recall into the first system section, not a new one
OpenCode emits each system[] entry as a separate system message, and some
providers/LLMs only honor the first — so pushing recall as a new section can be
silently dropped. Append it to system[0] instead so recall is always seen.
Ports the approach from #1988 (@sdrobov) onto current main: applies it to the
order-independent system.transform recall path and the OpenCode-routed logger,
with a test that an existing system[0] is appended to (not pushed alongside).
Verified live: real recall folds into a single system entry containing both the
agent prompt and the memories block.
Co-authored-by: sdrobov <[email protected]>
* chore(opencode): sync package-lock
---------
Co-authored-by: sdrobov <[email protected]>
* fix(consolidation): set output token budget
* fix(consolidation): default max_completion_tokens to unset for full backwards compat
A 64k default still passes a raw value through to models LiteLLM does not
have a registry cap for (e.g. non-registered models on OpenAI/Gemini),
which is not a guaranteed no-op. Leaving it unset omits the key entirely
so every provider keeps its current implicit output budget — byte
identical to prior behaviour. Operators on providers with a low hidden
cap (notably Bedrock imported models) set the env var to fix#1939.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Forum report (related to GH-1558): a user configures an 'application' entity
label (map type, tag=True) with multi-value 'id' and 'name' fields, marks up
source text with [[Matched Text (name, id)]] notation, and expects a consistent
{application:name:X, application:id:Y} pair per tagged element. They observe
inconsistent results: often only one half of the pair, sometimes neither, worse
when several tags share a chunk.
Adds a focused reproduction harness in test_entity_labels.py:
- two deterministic tests pinning the map post-processing mechanics (emits the
full pair when the LLM returns both fields; faithfully drops half when it
doesn't -- there is no backfill, so pairing must come from the model)
- one map-config end-to-end test (hs_llm_core): three tags in one chunk with
non-canonical surface forms, asserting every element yields a complete pair
Finding: on gemini-2.5-flash the map config is robust -- complete pairs across
all runs (including denser/larger documents tried during investigation). The
reported inconsistency did not reproduce on this model, pointing to model
capability / much larger real documents as the likely driver. The harness is
parameterized so a weaker model can be plugged in to reproduce.
* docs(integrations): single source of truth for sidebar + guardrails
Make src/data/integrations.json the single source for the Integrations
sidebar across every docs version, and add build-time guardrails so it
can't drift.
- Inject the Integrations sidebar category at render time from
integrations.json via a DocRoot/Layout/Sidebar swizzle. Every docs
version (current + frozen 0.3-0.7) now shows the same list, and adding
one JSON entry is all it takes - no per-version sidebar edits. The
sidebar files keep only a positional placeholder category (a link to
the gallery), which the swizzle replaces.
- check-integrations.mjs, wired into `npm run build`:
- forward: fail if a JSON entry has no docs-integrations/<slug> page
(the injected sidebar isn't covered by Docusaurus link-checking).
- reverse: fail if a released integration tag is missing from the JSON
(skips gracefully without tags; excludes private cloudflare-oauth-proxy).
- Add the released-but-undocumented integrations to the JSON so the
gallery + sidebar show them: claude-agent-sdk and superagent (with new
doc pages) and paperclip.
- CI: fetch tags (fetch-depth: 0) in the docs build jobs so the reverse
check can see them.
One name + one icon per integration come straight from the JSON; display
order is the JSON array order (manual, most-interesting-first).
* docs(code-review): require integrations.json entry + doc page for integrations
Add a review rule: every added/released integration must have an entry in
hindsight-docs/src/data/integrations.json (single source of truth for the
gallery + sidebar) and a docs-integrations/<slug> page, enforced by
check-integrations.mjs. Also note the changelog generator keeps its own
INTEGRATIONS list that must be updated for releases.
* docs(integrations): sidebar on (unversioned) integration pages + alphabetical order
- Give the integration doc pages their own sidebar without versioning them:
point the unversioned `integrations` plugin at sidebars-integrations.ts,
generated from integrations.json (doc items so each page associates with the
sidebar and renders it). Previously these pages had sidebarPath: false (no
sidebar at all).
- Sort integrations alphabetically by name in all three surfaces — the
Integrations Hub gallery, the main docs sidebar, and the new integration-page
sidebar — via a shared src/lib/integrations.ts helper (gallery + swizzle) and
an inline sort in the config-loaded integration sidebar. JSON array order is
no longer significant for display.
- The swizzle now only fills the main-docs placeholder category, leaving the
generated integration-page sidebar untouched.
* docs(integrations): replace placeholder/wrong icons with official brand icons
Fetch real brand icons from each integration's official site (apple-touch-icon
/ high-res favicon) and point integrations.json at them, replacing
self-generated, generic, or reused placeholders:
- New brand icons for claude-agent-sdk, superagent, paperclip, codex, grok-build,
ai-sdk, chat, local-mcp, openclaw, langgraph, autogen, opencode, n8n, pipecat,
smolagents, dify, strands, outsystems, pydantic-ai, and refreshed many others
(litellm, crewai, perplexity, llamaindex, vapi, flowise, hindclaw, agno,
hermes, agentcore, google-adk, openai-agents, roo-code, skills, claude-code).
- claude-agent-sdk now uses the Claude/Anthropic brand (was reused claude-code
icon); context-forge uses the MCP logo (it's an MCP gateway); superagent uses
its pyramid logo (was generic package icon); paperclip its paperclip mark.
- Kept the existing real marks for nemoclaw (NVIDIA NeMo) and right-agent — no
official brand favicon exists for those, and the auto-fetched candidates were
wrong (a letter favicon / the repo author's avatar).
- Removed 7 now-orphaned icon files.
* ci(docs): add explicit integrations check step to build-docs
Run scripts/check-integrations.mjs as a named, fail-fast step before the docs
build (the build runs it too, but this surfaces it clearly and fails before the
slow build). Pure Node, no npm install; uses the tags already fetched via
fetch-depth: 0.
* ci(docs): trigger build-docs (integrations check) on integration changes
Add hindsight-integrations/** to the docs path filter so the integrations
single-source check runs on integration-only PRs (which can add/rename an
integration without touching hindsight-docs/**).
Nearly all hs_llm_core flakiness comes from the judge: a single temperature-0
call to the judge model occasionally flips its verdict on borderline phrasing,
failing a test whose system output was actually fine.
Harden the shared judge (used by ~49 assertions across 24 files) so every
judge-based test benefits at once:
- When the primary (temp-0) verdict is 'not met', collect N independent
higher-temperature second opinions and uphold the failure only if the majority
still agrees. Verdicts that pass on the first call return immediately, so
passing tests are unchanged in cost and behaviour, and genuine failures (all
judges agree) still fail. Tunable via HINDSIGHT_TEST_JUDGE_CONFIRMATIONS /
_CONFIRM_TEMPERATURE.
- Retry transient judge-call errors (rate limits, 5xx) so judge-infra hiccups
don't fail the test under evaluation (HINDSIGHT_TEST_JUDGE_CALL_ATTEMPTS).
Also add the standard @pytest.mark.flaky backstop to the mental-model
tag-security test, which lacked one.
* fix(opencode): call OpenCode app.log as a method so logging actually works
0.2.3 routed logs through client.app.log but extracted it to a detached
reference (const log = client.app.log; log(...)). OpenCode's app.log is a class
method that uses `this` internally, so the detached call threw
'this._client is undefined' — swallowed by the try/catch, and the console
fallback was skipped because the reference was truthy. Net effect: 0.2.3 logged
nothing in real OpenCode (no resolved-endpoint line, no surfaced errors).
- Call app.log as a method on app so `this` is preserved.
- On synchronous failure, fall through to the console.error fallback instead of
swallowing.
- Regression test with a this-dependent app.log (mirrors OpenCode's client).
Verified live against OpenCode 1.16.2: 'service=hindsight ... Hindsight plugin
initialized' and 'Injected recall context' now appear in the log stream.
* chore(opencode): sync package-lock version to 0.2.3
* fix(opencode): make autoRecall independent of session.created ordering (#1758)
autoRecall keyed off session.created marking recalledSessions and
system.transform consuming it — which silently disabled recall if
system.transform fired first (the relative order is an undocumented OpenCode
detail that has differed across versions; #1758 item 2).
Recall now runs on the first system.transform per session, using
recalledSessions purely as a dedup marker for sessions already recalled into.
session.created no longer participates. Behaviour is identical on 1.16.2 (where
created fires first) but no longer breaks if the order flips.
Verified order-independence with unit tests (recall before/after/without
session.created) and a built-plugin harness.
* test(ci): de-flake TEI parallelism timing + disposition judge reruns
Two pre-existing flaky tests that failed unrelated to their subject:
- test_tei_cross_encoder::test_parallel_requests asserted absolute elapsed
< 0.08s to prove parallelism; CI scheduling jitter pushed it to 0.10s.
Widen the simulated latency and assert comfortably below the serial time
(max_concurrent_observed > 1 remains the deterministic parallelism proof).
- test_quality_integration::test_high_skepticism_response_is_more_hedged_than_low
is a judge-evaluated disposition comparison that exhausted its 2 reruns in CI;
bump to 3 (matching the heaviest LLM tests).
* fix(ci): prettier-format opencode plugin.test.ts (verify-generated-files)
CI runs prettier --write across all integrations and found opencode/src/
plugin.test.ts drifted from the shared .prettierrc.json (it was last hand-edited
in #2038), failing verify-generated-files on every PR. Apply the formatting the
generator expects (collapses a wrapped .toBe(...) to one line).
The existing recall suites only exercise the temporal retrieval arm
incidentally. This adds a dedicated 'recall-temporal' suite that stamps
all memories with one event_date and augments every query with a 1-day
window on it, so the temporal entry-point scan matches (near-)all rows —
the dense-temporal-zone regime from #1958 that #1983 bounded.
- _populate_bank gains an optional event_date for the clustered regime
- registered in SUITES; runs by default in the daily all-suites job
- added to the workflow_dispatch suite choices for manual single runs
Results flow to the perf dashboard automatically (publish script keeps
the full suites[] array); a matching 'Recall + temporal' page has been
added there.
* fix(opencode): observable logging — config-only debug, resolved-endpoint log, surfaced errors
OpenCode users (notably on Windows) could see tool calls register but no
memories land, with zero signal as to why: every retain/recall failure was
swallowed via debugLog, the resolved API URL/bank was only logged when debug
was on, and HINDSIGHT_DEBUG is unreliable to set for OpenCode's plugin runtime.
- Add a Logger that routes through OpenCode's server log stream
(client.app.log, service=hindsight) — TUI-safe, visible via --print-logs and
the OpenCode log files. Falls back to console.error when no client.
- error/warn/info are always emitted; debug is gated on config.debug.
- Always log the resolved endpoint + bank at init (a common 'memories aren't
saving' cause is silently defaulting to Hindsight Cloud).
- Surface retain/recall/hook failures as errors instead of swallowing them;
hooks still never throw, so OpenCode is not affected.
- Drop the HINDSIGHT_DEBUG env override; 'debug' is now a config-only option
(opencode.json plugin options or ~/.hindsight/opencode.json).
- Tests for the logger; update config tests; document the change.
Refs #1758
* style(opencode): prettier-format plugin.test.ts (pre-existing drift)
* docs(opencode): document config-only debug + default error/endpoint logging
* feat(consolidation): periodic reconcile + cross-tenant retention via maintenance loop (#1969)
Add a single background MaintenanceLoop (engine/maintenance.py) started in
MemoryEngine.initialize(), replacing the two per-recorder retention sweep tasks.
One ~60s tick runs each job on its own interval:
- Consolidation reconcile (HINDSIGHT_API_CONSOLIDATION_RECONCILE_INTERVAL_SECONDS,
default 300, 0=off): re-schedules consolidation for banks with eligible-but-
unscheduled facts and no in-flight consolidation, recovering facts stranded
when a consolidation operation failed terminally (#1969).
- Retention sweeps (hourly) for audit_log and llm_requests, now across ALL tenant
schemas (the old sweeps only swept the base schema).
Cross-tenant discovery uses server-side PL/pgSQL routines (migration
e5f6a7b8c9d0): public.banks_needing_consolidation() and
public.schemas_with_expired_rows(table, ts_col, days) — one round-trip each
instead of a per-schema query storm at scale. Config gating resolves the full
hierarchy per returned bank (global/tenant/bank); Tenant gains an optional
tenant_id so tenant-layer overrides are honored.
* fix(consolidation): gate maintenance loop to PostgreSQL
The retention sweeps target PG-only tables and the reconcile relies on PG-only
PL/pgSQL routines, so on Oracle every tick would call non-existent functions and
spam warnings. Skip starting the loop when the backend is Oracle (mirrors the
PG-only migration).
* test(consolidation): 100-tenant maintenance loop targeting test
Provisions 100 tenant schemas (cloning the five tables the loop touches) and
verifies each job affects only the tenants it should: audit-log and llm-request
retention purge expired rows only in schemas that have them (recent rows kept
everywhere), and the consolidation reconcile enqueues only the eligible banks
into their own schema — skipping auto-consolidation-disabled, in-flight, and
already-consolidated banks.
* fix(migration): chain maintenance routines after the split-history head
After rebasing onto main, the maintenance-routines migration and #2007's
split-history migration (a7b8c9d0e1f2) both pointed at d3e4f5a6b7c8, creating two
alembic heads (test_single_head failed). Re-point down_revision to a7b8c9d0e1f2
so the tree is a single linear head again.
* fix(maintenance): create public routines once + stop loop racing tests
Two CI failures from the maintenance work:
1. Migration ran CREATE OR REPLACE FUNCTION public.* on every per-schema
migration; concurrent tenant provisioning collided on the pg_proc catalog
('tuple concurrently updated'). Create the shared public routines only on the
base-schema run (target_schema unset); tenant runs skip them.
2. The maintenance loop auto-starts in every test engine (llm-trace retention is
on by default), and its background sweep deleted llm_requests rows that
test_maintenance_multitenant had just inserted. Disable llm-trace retention in
the test env too, so with reconcile already off and audit retention off by
default no job is enabled and the loop never starts; tests drive it directly.
* feat(recall): make semantic threshold configurable
* refactor(recall): rename semantic_threshold to semantic_min_similarity
Align the new semantic gate with its sibling BM25_MIN_SCORE: per-strategy
prefix, and 'min_similarity' since the value is a cosine similarity. Renames
the env var (HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY), config field, and the
build_semantic_arm parameter (min_similarity).
---------
Co-authored-by: Nicolò Boschi <[email protected]>
The prompt template used **what**, **when** etc. as field labels.
This Markdown bold syntax leaked into LLM outputs causing non-JSON
responses across all tested models (GPT-4, Ollama models: gemma4,
kimi-k2, llama3.2, qwen3.5, glm-5.1).
Replaced **field** with "field" — same visual emphasis for the model
but no Markdown syntax to confuse JSON output parsing.
Fixes#1138
Co-authored-by: Claude Opus 4.8 <[email protected]>
* docs(models): sync gemini + vertexai default models to 3.x matching config.py
* docs(models): regenerate skills mirror default-model table (gemini+vertexai 3.x)
* docs(models): sync Vertex AI walkthrough + gemini examples to 3.x (complete #2030 scope)
The defaults table fix (#2030) left the env-var examples and Vertex AI
setup walkthrough still handing users the retired gemini-2.0-flash-001
(404 on Vertex) and stale gemini-2.0-flash. Sync the prose surface:
- Vertex AI examples + google/ prefix note -> gemini-3.1-flash-lite (vertexai default)
- Gemini AI Studio example -> gemini-3.5-flash (gemini default)
Regenerated the CI-enforced skills mirror.
FireworksLLM overrides supports_batch_api()->True (fireworks_llm.py:106),
and provider=="fireworks" dispatches to FireworksLLM (llm_wrapper.py:424),
but the base OpenAICompatibleLLM grants batch only to openai/groq
(openai_compatible_llm.py:1236) so the override is load-bearing. The
capabilities matrix in llmProviders.json was missing the fireworks
batchApi flag, rendering it as '-' (not supported) and understating the
provider. Regenerated the CI-enforced skills mirror (models.md).
OpenCode >=1.16 iterates every plugin-entry export and throws on any
non-function value; the re-exported DEFAULT_HINDSIGHT_API_URL string
bricked plugin load. Drop it from the entry (still exported from
./config) and add a regression test that the entry is function-only.
PR #2013 added a durable progress snapshot (OperationProgress: stage/at/
processed/total/detail) plus an updated_at heartbeat and an include_payload
query param yielding task_payload to GET .../operations/{operation_id}, but
the 'Get operation status' docs had no response-field prose for any of them
(the example even passes include_payload without explaining it). Added a
response-fields subsection sourced from http.py. Regenerated the skills mirror.
* feat(integrations): add Superagent safety middleware for Hindsight memory
Adds hindsight-superagent integration that wraps Hindsight retain/recall/reflect
with Superagent Guard (prompt injection detection) and Redact (PII removal).
- SafeHindsight middleware class with configurable guard + redact pipeline
- Global configure() / per-instance config with env var fallbacks
- CI job and release script entry
- 54 unit tests + 10 e2e tests (all passing)
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(superagent): default to Hindsight Cloud URL when no URL is configured
Matches the pattern used by all other integrations — falls back to
https://api.hindsight.vectorize.io instead of erroring.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(superagent): require superagent_api_key, update README defaults
- resolve_safety_client now raises HindsightError if no API key is
provided, matching actual safety-agent behavior (create_client()
requires a key)
- README: document superagent_api_key as required, hindsight_api_url
defaults to Hindsight Cloud URL
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(superagent): disable broken fallback by default, add env var key resolution
The safety-agent SDK's default fallback endpoint (superagent.sh/api/fallback)
returns a 307 redirect that httpx doesn't follow for POST requests, causing
all guard() calls to fail on cold starts. This change:
- Defaults enable_fallback=False so the primary Cloud Run endpoint is used
directly (60s timeout is sufficient)
- Exposes enable_fallback and fallback_timeout in config/SafeHindsight for
users who want to opt back in
- Adds os.environ fallback for SUPERAGENT_API_KEY in resolve_safety_client
so it works without calling configure() first
- Fixes e2e redact test that was blocked by guard on recall query
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(superagent): require explicit guard_model, increase client timeout
Superagent's hosted guard endpoints (Cloud Run Ollama) currently serve
empty model lists, making the default superagent/guard-1.7b unusable.
Update all examples to use guard_model="openai/gpt-4o-mini" and document
the self-hosting alternative. Increase Hindsight client timeout from 30s
to 120s to accommodate reflect's server-side LLM call.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(superagent): disable guard on retain, fix e2e tests for OpenAI guard
General-purpose LLMs (gpt-4o-mini) over-classify PII content as security
violations, blocking retain before redact runs. Disable guard on retain
in all examples and default test helper. Fix e2e tests to use explicit
guard_model and OpenAI provider instead of broken hosted endpoints.
All 10 e2e tests now pass against live APIs.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* feat(superagent): switch guard/redact model to gpt-4.1-nano
gpt-4.1-nano correctly distinguishes prompt injection from legitimate
content (including PII), eliminating the need to disable guard on retain.
Re-enables full Guard → Redact → Retain pipeline.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(superagent): add typed return values and py.typed marker
Replace Any return types on recall() and reflect() with
RecallResponse and ReflectResponse from hindsight-client.
Add py.typed marker for PEP 561 type checker support.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* style(superagent): fix ruff line-length formatting in _client.py
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* feat(superagent): add enable_redact_on_recall + lazy SafetyClient
Two gaps surfaced by code review:
1. `enable_redact_on_recall` was missing. Guard was configurable on every
op (retain/recall/reflect) but redact was wired only into retain. A
memory like "John's SSN is 123-45-6789" stored from a non-safe path
would come back verbatim through `recall()`. Added the option to
redact each result's text on the read path.
Default is False rather than True because every result triggers its own
redact call (N results → N round-trips), unlike retain which is always 1
call. Callers who care about read-path PII opt in.
2. SafetyClient was resolved eagerly in `SafeHindsight.__init__`, raising
if SUPERAGENT_API_KEY was missing even when every safety hook was
disabled. Moved resolution behind a `_get_safety()` getter that
constructs on first guard/redact call. Explicit `safety_client=` still
wins and is stored directly, so the "supply your own client" path is
unchanged.
Tests: 62 pass (56 original + 3 redact-on-recall + 3 lazy-resolution).
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(superagent): address review-agent findings — env fallback, race, concurrency, scope
Addresses the 1 blocker + 8 should-fixes from the review-agent pass.
Blocker:
- resolve_hindsight_client() now reads HINDSIGHT_API_KEY env directly. The
base hindsight_client.Hindsight doesn't fall back to the env var on its
own, so the constructor-only path (no prior configure() call) was silently
dropping the key. Fix: read os.environ.get(HINDSIGHT_API_KEY_ENV) as the
third precedence step after explicit api_key and config.api_key.
Should-fix:
- Safety client config is now snapshotted at __init__ via snapshot_safety_config()
and built lazily via build_safety_client() on first guard/redact call.
A later configure() call cannot silently change what an already-constructed
SafeHindsight will see.
- Redact-on-recall (and the new retain_batch / redact-on-reflect paths) run
under an asyncio.Semaphore bounded by `redact_concurrency` (default 5).
Wide recalls no longer stampede the Superagent rate limit.
- Added `enable_redact_on_reflect` — reflect's synthesised text is also LLM
output derived from possibly-PII memories, so the same opt-in shape as
redact-on-recall applies. Off by default.
- Added `SafeHindsight.retain_batch(items)` wrapping aretain_batch with
per-item guard + redact under the concurrency cap. Any item's GuardBlocked
aborts the whole batch before any store.
- Added `aclose()` + async context manager. Closes owned underlying clients
(Hindsight, SafetyClient) but leaves caller-passed clients alone.
- Pinned safety-agent to >=0.1.5,<0.2.0 and hindsight-client to >=0.4.0,<1.0
so a pre-1.0 minor upstream bump can't silently change the API.
- Switched config-resolution precedence from `or`-chains to `_kw()` helper
using `is not None`. Explicit empty list / 0 / False kwargs now override
global config instead of being treated as "unset".
- Tag merge in retain() now uses `dict.fromkeys(...)` instead of `set(...)`
so order is preserved (call-tags first, then default tags, deduped).
E2E tests:
- TestE2EGuard block tests now actually assert that Guard blocks (with 3
retries to absorb model variance). Previously they silently passed if
Guard returned "allow" — defeating the purpose.
- Same fix for the bare-Superagent `test_guard_blocks_injection`.
- Added E2E coverage for redact-on-recall, redact-on-reflect, retain_batch,
and global-config-vs-per-instance-override precedence.
Unit tests:
- 15 new unit tests across 5 new test classes: TestSafetyConfigSnapshot,
TestRedactConcurrencyCap, TestRedactOnReflect, TestRetainBatch,
TestLifecycle, TestTagMergeOrder, TestEnvFallback. All passing; total
77 unit tests up from 62.
README updated with new options, lazy-resolution clarification, batch and
lifecycle sections.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(superagent): round-3 review-agent findings — E2E rigor, validation, observability
Addresses 5 should-fixes, 2 nits, and 1 question from the round-3 review pass.
E2E rigor (should-fix):
- test_redact_strips_pii_from_stored_memory: previously passed silently if
recall returned no results. Now polls via _recall_until_nonempty() so
empty results fail the test. Same polling helper applied to every E2E
that retains-then-recalls (redact-on-recall, redact-on-reflect,
retain_batch, config precedence) so a non-indexed retain no longer
silently turns an assertion into a non-assertion.
- test_recall_clean_query / test_reflect_clean_query: now assert the
stored memory's content actually surfaces in recall/reflect output,
not just that the response shape is valid.
- cleanup_banks fixture: extended suffix list to include every test class's
bank (-redact-recall, -redact-reflect, -batch, -precedence) so the new
E2Es don't leak banks.
Code correctness (should-fix):
- Validate safety_concurrency >= 1 in both SafeHindsight.__init__ and
configure() — asyncio.Semaphore(0) would deadlock _redact_many() and
the guard-batching path in retain_batch. Raises ValueError early.
- Expand retain_batch to pass through every per-item field
Hindsight.aretain_batch supports (metadata, document_id, entities,
observation_scopes, strategy) and accept top-level document_id /
document_tags kwargs. Previous narrow surface forced callers to fall
back to the raw client for any of those fields.
Naming + docs (nit):
- Rename `redact_concurrency` → `safety_concurrency`. The same cap
bounds both redact-many and the guard-batching loop in retain_batch,
so the name "redact-only" was misleading. Public kwarg, config field,
and internal attr all renamed; tests + README updated.
- Align README requirements list with pyproject bounds: safety-agent
>=0.1.5,<0.2.0 and hindsight-client >=0.4.0,<1.0.
Observability (question → resolved):
- Add `on_guard(scope, result)` callback invoked for every guard verdict
(pass and block) so callers can log/observe non-block decisions without
changing core flow. Scope is one of "retain"/"recall"/"reflect"/
"retain_batch". Sync or async callable accepted; async is awaited.
Callback fires before GuardBlockedError raises on block, preserving
observability for the block path too.
Tests added: 12 new across TestSafetyConcurrencyValidation,
TestOnGuardCallback, TestRetainBatchFieldPassthrough. Total: 87 unit
tests (was 77 → +10 net after the renames). All passing.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(superagent): round-4 polish — update_mode, retain_async, on_guard error containment
Addresses 2 should-fixes and 1 nit from the round-4 review.
retain_batch surface (should-fix):
- Added "update_mode" to _BATCH_PASSTHROUGH_KEYS. Hindsight.aretain_batch
reads item.get("update_mode") per item, so dropping it forced callers
who wanted controlled upserts to fall back to the raw client.
- Added top-level `retain_async: bool = False` kwarg. Hindsight supports
background-processing the batch after the safety pipeline is done; the
wrapper now exposes that knob. Guard + Redact still run synchronously
before the call returns — only the underlying store is deferred. When
the default False is used, the kwarg isn't forwarded so the client's own
default wins.
on_guard error containment (nit):
- The callback is documented as observability "without changing the core
flow," but a raised exception inside the callback previously took down
the memory op. Wrapped the call in try/except with a WARNING log so
observability failures stay observable instead of fatal. The log
includes the scope and the exception type/message so an operator can
spot a misbehaving callback. Block-path behaviour is unaffected — if
Guard says block, GuardBlockedError still raises after the callback
attempt.
Tests: 93 unit tests pass (was 87; +6 net). New cases cover update_mode
per-item passthrough, retain_async forwarding (and the don't-forward-on-
default case), sync and async on_guard exception containment, and that
a callback exception doesn't suppress a real block verdict.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* test(superagent): make E2E suite merge-clean — natural-language anchors, lifecycle
Live E2E run with the Superagent key surfaced two reproducible failures
plus aiohttp connector leaks. Fixes:
1. test_redact_strips_pii_from_stored_memory — previously queried for
"What is Bob's contact info?", which deterministically misses after
redact strips Bob's name and email from the stored content. A first
attempt added a synthetic canary ("redact-pii-canary alpha bravo")
alongside the PII, but Hindsight's fact extraction treats opaque
identifier phrases as noise and drops them, so the canary itself
didn't surface in recall either. Fix is to use natural-language
project context ("Project Phoenix client onboarding") as the anchor
— fact extraction materialises it as a real fact, vector search
handles it cleanly, and the assertion verifies (a) the anchor is
retrievable and (b) the PII is absent from the result.
2. test_redact_on_reflect_scrubs_synthesis — same root cause, same fix.
Anchor on "Project Tango payment notes" instead of a synthetic
canary or PII-laden query. The credit card sits secondary in the
memory but isn't relied on for retrieval.
3. Unclosed aiohttp ClientSession / TCPConnector warnings — every test
instantiated a SafeHindsight via _make_client() but never called
aclose(). Added an autouse fixture that tracks every safe created
via _make_client() and aclose()s them on test teardown. Idempotent;
exceptions during cleanup are swallowed so they don't mask the
test's own result.
Result: 14/14 E2E pass in 74s (down from 127s due to fewer rerun
attempts on the previously-failing paths) with no unclosed-session
warnings. 93/93 unit tests still pass.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* style(superagent): apply ruff format (fixes verify-generated-files CI)
Same formatter drift as the other integrations: ruff check passed but ruff
format (run by the verify-generated-files job via scripts/hooks/lint.sh)
reflows manually-wrapped lines that fit within 120 cols. Formatting only —
no behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(superagent): bucket E2E as requires_real_llm; PR CI runs deterministic only
Mark the live E2E suite (real Superagent Guard/Redact + OpenAI + Hindsight)
with a module-level requires_real_llm marker, registered in pyproject,
mirroring the core test split from #1469. The test-superagent-integration job
now runs -m "not requires_real_llm" (deterministic bucket: 93 tests); the
real-LLM bucket (14 tests) is selectable via -m requires_real_llm.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(superagent): add deterministic retain->recall->reflect round-trip (mock bucket)
Drives SafeHindsight end to end with mocked Hindsight + Superagent clients,
asserting guard/redact-then-forward across all three ops — the in-CI / no-keys
analog of the live round-trip.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(superagent): remove dead resolve_safety_client
resolve_safety_client at _client.py:87 was a convenience wrapper around
snapshot_safety_config + build_safety_client, with a docstring saying
"kept for backwards compatibility — combines snapshot + build into one
call". As reviewer (benfrank241) flagged on PR #1128: there's nothing
to be backwards compatible with — this is a new package. The middleware
(SafeHindsight) uses snapshot_safety_config + build_safety_client
directly. The function had no real callers.
Drop:
- The function itself from _client.py.
- TestResolveSafetyClient class from tests/test_client.py (its 6 tests
only exercised the dead wrapper).
- The corresponding import.
test_middleware.py::test_unsafe_path_does_not_resolve_safety_client
stays — the "resolve" there is a generic verb describing whether the
middleware needs to construct a safety client at all, not a reference
to the deleted function. That test still verifies the lazy-construction
semantics it always did.
Test suite: 88 passed, 14 skipped (down from 88+6 = 94 passed; the 6
removed were the wrapper-only tests). Middleware coverage unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(superagent): ruff format/check fixes for verify-generated-files CI
verify-generated-files flagged _client.py drift (2 trailing blank
lines after the resolve_safety_client removal) plus 3 additional
small lint findings ruff check could autofix. Running the full
ruff format + ruff check --fix pipeline brings the diff to zero
against what CI expects.
No behaviour changes; format-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: DK09876 <[email protected]>
* fix(opencode): default to Hindsight Cloud + gated live E2E
Aligns OpenCode with the cloud-default convention adopted across the
Python integrations (LangGraph, Haystack, OpenAI Agents, LlamaIndex,
AutoGen).
Changes:
- config.ts: introduce DEFAULT_HINDSIGHT_API_URL =
"https://api.hindsight.vectorize.io". Set DEFAULTS.hindsightApiUrl to
it so the plugin works out-of-the-box against Hindsight Cloud (API key
via HINDSIGHT_API_TOKEN). Self-hosters override hindsightApiUrl. Also
re-export the constant from index.ts.
- index.ts: drop the "No API URL configured" branch that returned empty
hooks. The URL always resolves now (default = Cloud), so the plugin
always returns its full tool + hook surface. Requests fail at call
time with a clear server error if no key is configured against Cloud,
matching the framework's goal-5 contract ("API key not required at
construction; fails at call time if missing").
- tools.ts: add an index signature to HindsightTools so the object is
assignable to OpenCode's Hooks.tool (Record<string, ToolDefinition>)
without losing the three concrete keys. Fixes a pre-existing dts
build error that was previously masked by the now-removed empty-hooks
return branch.
- README.md: restructure Quick Start so Cloud is the primary path
("enable plugin + set HINDSIGHT_API_TOKEN"); move self-hosted under a
secondary heading; update the env-var table to show the new default.
- e2e.test.ts (new): gated live test (skipped unless
HINDSIGHT_LIVE_E2E=1) covering the three contract surfaces — agent
tool path (retain → server-side extraction → recall), session.idle
auto-retain, session.created + system.transform inject. TS equivalent
of the `requires_real_llm` pytest marker used by the Python
integrations. Exposed as `npm run test:e2e`.
- plugin.test.ts: replace the "returns empty hooks when no URL" test
with "defaults to Hindsight Cloud" — asserts the client is constructed
with DEFAULT_HINDSIGHT_API_URL and the full hook surface is returned.
- config.test.ts + test-helpers.ts: update default-value expectations to
the new cloud-default constant.
- package.json: version 0.2.0 → 0.2.1; add `test:e2e` script.
Verification:
- Deterministic vitest: 6 files / 101 tests pass, 1 file / 3 tests
skipped (the gated E2E).
- Live vitest (HINDSIGHT_LIVE_E2E=1, against a local Hindsight server):
7 files / 104 tests pass.
- `npx tsc --noEmit`: clean.
- `npm run build` (tsup): ESM + DTS both succeed.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(opencode): reword 'Hindsight Cloud' in test files for OSS-clean (V2 audit)
V2 audit (2026-06-02) flagged two 'Hindsight Cloud' strings in TS test
files under a strict reading of Goal-4 (which says shipped source — .py
and .ts — should not name the cloud product):
- src/e2e.test.ts:14 (file-header comment): 'For Hindsight Cloud:
HINDSIGHT_API_TOKEN' → 'When pointing at the hosted backend:
HINDSIGHT_API_TOKEN'
- src/plugin.test.ts:44 (test description): 'defaults to Hindsight Cloud
when no API URL' → 'defaults to the hosted backend URL when no API URL'
Test behaviour unchanged. The README and PR descriptions can still
name the product.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(opencode): pass HINDSIGHT_API_TOKEN to live e2e direct client
The live e2e suite's direct (non-plugin) HindsightClient was constructed
with only { baseUrl: URL }, no apiKey. Against `127.0.0.1:8888` that's
fine — local has no auth. Against `api.hindsight.vectorize.io` the test's
own retain/recall/deleteBank calls 401, masking the fact that the plugin
path itself works against Cloud.
The plugin already reads HINDSIGHT_API_TOKEN from env via its config
resolution. Have the test mirror it: when TOKEN is present, construct
with apiKey. When absent (local-only run), keep the previous shape.
Verified:
- HINDSIGHT_LIVE_E2E=1 against LOCAL (no token): 104/104 pass
- HINDSIGHT_LIVE_E2E=1 against CLOUD (with token): 104/104 pass
- npm test deterministic (no env): 101/101 + 3 skipped
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(opencode): prettier format README + e2e.test.ts
verify-generated-files CI flagged drift in:
- hindsight-integrations/opencode/README.md
- hindsight-integrations/opencode/src/e2e.test.ts
Both are pure prettier formatting (line wrapping in README, single
quoted -> double quoted spacing in e2e.test.ts). Running
`npx prettier --write` brings the diff to zero.
No behaviour changes.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(opencode): sync openapi.json with main
Branch carried an older snapshot of hindsight-docs/static/openapi.json
that pre-dated main's addition of OperationProgress. Re-checkout main's
openapi.json so check-openapi-compatibility passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
* fix(openai-agents): default to Cloud without configure(); add gated E2E + bucketing
- resolve_client() now falls back to DEFAULT_HINDSIGHT_API_URL and the
HINDSIGHT_API_KEY env var when configure() was never called (it previously
raised). Updates the tools + memory_instructions raise-tests to assert the
cloud-default + env-key behavior. Satisfies the "default to Cloud" goal.
- Add a gated tests/test_e2e.py covering retain/recall/reflect via
await tool.on_invoke_tool(...) and memory_instructions(), all against a live
Hindsight server. Marked requires_real_llm; register the marker in pyproject;
the test-openai-agents-integration CI job now runs the deterministic bucket
(-m "not requires_real_llm").
- Fix version drift: _version.py was "0.1.0" while pyproject said "0.1.1".
Sync to 0.1.1 + update the User-Agent assertions in test_tools.py.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* ci(openai-agents): wire test-openai-agents-integration into aggregate-gate
Audit finding (2026-06-02): the test-openai-agents-integration job is
defined (test.yml L3019) and runs successfully, but is missing from the
report-pr-status job's `needs:` list. That means a failure of this
specific integration job does not block the aggregate pass on
pull_request_review. Pre-existing oversight — the omission predates this
PR — but it's worth closing now so the OpenAI Agents integration's CI
matters for merge gating.
One-line addition: add `- test-openai-agents-integration` to the needs
list, grouped with the other Python integrations.
Verification: YAML parses; no other change needed — the job definition
itself was already correct.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(openai-agents): sync openapi.json with main
Branch carried an older snapshot of hindsight-docs/static/openapi.json
that pre-dated main's addition of OperationProgress. Re-checkout main's
openapi.json so check-openapi-compatibility passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: DK09876 <[email protected]>
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
Co-authored-by: Ben <[email protected]>
* feat(litellm): expand recall/reflect/hindsight_memory APIs and fix default URL
- recall(): add include_entities, trace, recall_tags, recall_tags_match params
(previously only supported via the callback/enable() path, not the manual API)
- reflect(): add recall_tags, recall_tags_match params (same gap)
- hindsight_memory(): default URL now matches configure()/wrap_openai()/wrap_anthropic()
instead of hardcoding localhost; add session_id, use_reflect, reflect_context,
tags, recall_tags, recall_tags_match params
- Document that enable() and HindsightCallback are mutually exclusive injection
paths to prevent accidental double injection
- Add 17 tests covering all new behaviour
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(litellm): strip hindsight_bank_id from kwargs before LiteLLM call and add sync param to aretain
- hindsight_bank_id kwarg was leaking into LiteLLM as extra_body, causing
OpenAI 400 errors; now popped in completion(), _wrapped_completion(),
_wrapped_acompletion() and propagated as bank_id_override throughout
injection and storage paths
- _inject_memories() accepts bank_id_override to honour per-call bank
without mutating globals
- _store_conversation() and _store_conversation_from_text() accept
bank_id_override for consistent per-call storage routing
- _LiteLLMStreamWrapper and _LiteLLMAsyncStreamWrapper carry
bank_id_override so streamed responses store to the right bank
- aretain() now accepts sync=True, forwarding it to retain()
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(litellm): design review fixes — injection_mode, context manager restore, validation, error consistency
- config.py: remove DEFAULT_BANK_ID footgun (configure() without bank_id now
leaves bank_id=None; is_configured() and enable() correctly require explicit
bank_id). Add _restore_config() for atomic state restoration. Add
budget/recall_tags_match validation in configure() and set_defaults().
Emit DeprecationWarning for document_id usage.
- __init__.py: _inject_memories() now respects injection_mode
(PREPEND_USER prepends to last user message; SYSTEM_MESSAGE keeps existing
behaviour). Wire up defaults.query as fallback recall query. Fix
ValueError → HindsightError for missing bank_id. hindsight_memory()
finally block now calls _restore_config() to atomically restore all settings
(previously lost: sync_storage, tags, recall_tags, recall_tags_match,
reflect_context, reflect_response_schema). Add _enabled_lock and _debug_lock
for thread safety on shared mutable state.
- callbacks.py: ValueError → HindsightError in log_pre_api_call and
async_log_pre_api_call for missing bank_id, consistent with __init__.py.
- tests: update tests that relied on DEFAULT_BANK_ID behaviour; add
TestValidation, TestInjectionMode, TestQueryField, TestHindsightErrorConsistency,
TestContextManagerFullRestore (83 tests, all passing).
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(litellm): run ruff format and update test_config.py for no-default-bank-id behaviour
- Run ruff format on __init__.py and wrappers.py to match CI lint expectations
- test_config.py: update test_configure_with_no_arguments to assert bank_id is None
(not DEFAULT_BANK_ID) and rename test_is_configured_true_with_defaults to
test_is_configured_false_without_explicit_bank_id with corrected assertion,
matching the removed DEFAULT_BANK_ID footgun
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(litellm): declare hindsight-client dep, add E2E suite, implement set_bank_mission
Addresses PR review blockers and one user-facing should-fix:
1. **hindsight-client missing from dependencies** — the package imports
`hindsight_client` and `hindsight_client_api` in 11+ places but never
declared the dep, so `pip install hindsight-litellm` from PyPI raised
ModuleNotFoundError on any retain/recall/reflect path. Add explicit
`hindsight-client>=0.4.0` to project deps.
2. **E2E suite was out-of-tree** — moved the 23-test live-API suite into
`tests/test_e2e.py` with env-var-based `HINDSIGHT_API_URL` and
skip-on-missing-keys markers (`requires_hindsight`, `requires_openai`,
`requires_all`) matching the sibling integrations' layout. Tests
collect cleanly; skip when no live server / OpenAI key is available.
3. **set_bank_mission() was documented but never implemented** —
README.md showed `hindsight_litellm.set_bank_mission(mission=..., name=...)`
as a public API, but no such function existed. Implement it as a thin
wrapper around `Hindsight.create_bank()` that resolves bank_id /
url / api_key from the configured defaults, with HindsightError on
missing bank_id or underlying client failure. Add 4 unit tests.
4. Add `Python :: 3.13` to package classifiers.
Unit tests: 113 passed (was 109, +4 new set_bank_mission tests).
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(litellm): dual-injection guard, LRU dedup cache, excluded_models in enable() path
Three correctness should-fixes from the PR review:
1. **Dual-injection footgun guard** — when both enable() and a
HindsightCallback registered on litellm.callbacks were active,
memories would be injected twice (once by the monkeypatch, once by
the callback running inside the original litellm.completion).
- enable() now scans litellm.callbacks at install time and emits a
RuntimeWarning if a HindsightCallback is already present.
- HindsightCallback.log_pre_api_call / async_log_pre_api_call now
short-circuit when is_enabled() returns True, so registering a
HindsightCallback after enable() no longer double-injects.
2. **Dedup cache LRU + thread safety** — _recent_hashes was a Set[str]
without a lock; set.pop() evicted an arbitrary entry rather than the
oldest, and the cache was mutated from both the sync log_success_event
and the async executor path with no synchronization. Replace with
OrderedDict + threading.Lock, move_to_end on hits for true LRU, and
popitem(last=False) on eviction.
3. **excluded_models honored in enable() monkeypatch path** — the
excluded_models config was previously only checked by the
HindsightCallback path; _wrapped_completion / _wrapped_acompletion
would inject memories on every model regardless. Add an early-out
that calls the original litellm function untouched when the model
matches any excluded_models glob.
Unit tests: 119 passed (was 113, +6 new tests covering each fix).
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(litellm): close wrapper clients + own one event loop; test hygiene
wrap_openai()/wrap_anthropic() wrappers gain close()/context-manager support
so the cached Hindsight client (and its aiohttp session) is released; this
eliminates the unclosed client-session/connector ResourceWarnings.
Replace the per-call `new_event_loop()` bridges with a single owned per-thread
loop (hindsight_litellm/_async.py), set as the thread's current loop so the
client reuses it and the `asyncio.get_event_loop()` deprecation (which becomes
an error on 3.14) no longer fires from our sync paths. The loop is
deliberately NOT closed in cleanup(): a shared loop closed under a live client
raises "Event loop is closed", so close_loop() is a documented manual-only
shutdown helper.
Test hygiene: add pytest-asyncio to the dev dependency group (fixes the
"Unknown config option: asyncio_mode" warning), close clients in the E2E
fixtures, and add unit tests for wrapper close() and the _async bridge.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* style(litellm): sort _async import before config (ruff I001)
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(litellm): own loop in wrap bank-setup + correct loop-lifecycle docs
- ensure_loop() now runs before wrap_openai()/wrap_anthropic() create the
bank/mission setup client, matching _get_client and the config bank paths
(no orphaned loop / get_event_loop deprecation on that path).
- Correct stale comments + module docstring that claimed cleanup() closes the
owned loop — it does not; close_loop() is a documented manual-only helper.
- Convert the flaky context-manager E2E test from a fixed sleep to polling.
- Add unit coverage for wrap bank-setup loop ownership.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* style(litellm): apply ruff format (fixes verify-generated-files CI)
ruff check passed but ruff format (run by the verify-generated-files job via
scripts/hooks/lint.sh) reflows manually-wrapped lines that fit within the
120-col limit. Formatting only — no behavior change.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(litellm): bucket E2E as requires_real_llm; PR CI runs deterministic only
Mark the live E2E suite (real Hindsight + provider calls) with a module-level
requires_real_llm marker, registered in pyproject, mirroring the core test
split from #1469. The test-litellm-integration job now runs
-m "not requires_real_llm" (deterministic bucket: 134 tests); the real-LLM
bucket (23 tests) is selectable via -m requires_real_llm for a dedicated or
nightly job.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(litellm): add deterministic full inject-flow test (mock bucket)
Mocks the Hindsight client's recall and spies litellm.completion to assert the
recalled memory is injected into the messages the LLM receives — the in-CI /
no-keys analog of the live enable()/completion tests. Runs in the deterministic
bucket.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(litellm): thread api_key into _get_client on the inject path
Audit finding (2026-06-02): hindsight_litellm/__init__.py:311 constructs the
Hindsight client via _get_client(config.hindsight_api_url) without forwarding
config.api_key. The retain path threads the key correctly via wrappers.py
(L177/355/471), but the recall/reflect injection path doesn't — so Hindsight
Cloud writes succeed while reads return 401 "Authentication failed: API key
required". The earlier review pass missed this because it tested only against
a local self-hosted server; an out-of-session audit ran the user-perspective
driver against api.hindsight.vectorize.io with an hsk_ key and caught the
asymmetry.
Fix: forward config.api_key as the second positional argument. Single-line
behavioral change.
Regression pin: TestInjectionPathPassesApiKey — configures the integration
with a Cloud-shaped URL + key, patches _get_client to capture call args,
runs _inject_memories, asserts the configured key was forwarded. Tolerates
positional and keyword call forms.
Other audit-suggested callsites (587/643/1343/1425) were _inject_memories
invocations, not _get_client; they don't carry api_key directly. wrappers.py,
config.py, and the cached-client paths in HindsightOpenAI / HindsightAnthropic
already pass the key.
Verification:
- Deterministic bucket: 136 pass (135 prior + 1 regression).
- Live bucket: 12 pass / 11 skipped / 0 failed (skips are
provider-key-conditional, not affected by this change).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(litellm): reword 'Hindsight Cloud' references for OSS-clean (V2 audit)
V2 audit (2026-06-02) caught two 'Hindsight Cloud' literals introduced by
the cloud-injection 401 fix (commit 3083a4a2):
- __init__.py:309 (comment): 'Hindsight Cloud rejects un-keyed recall/reflect'
→ 'the hosted backend rejects un-keyed recall/reflect'
- tests/test_integration.py:1423 (assertion message): 'breaks Hindsight Cloud
reads' → 'breaks reads against the hosted backend'
Goal-4 (OSS-clean) of the integration-review rubric: shipped .py source
should not name the cloud product. The README and PR descriptions still
can. This restores compliance — behaviour and the regression test pin
itself are unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(litellm): forward sync=True to retain() in sync_storage path
When configure(sync_storage=True) was set, _store_conversation() and
_store_conversation_from_text() called the package-level retain() without
passing sync=True. retain()'s own default is sync=False (background daemon
thread), so the storage POST was dispatched off-thread and the function
returned immediately. The 'Stored conversation to bank' INFO log was
emitted before the HTTP request had actually been sent.
In long-lived processes (Jupyter notebooks, the cookbook flow) this was
invisible because the daemon thread had time to complete. In short-lived
processes — a writer CLI that exits after a single completion() call —
the daemon thread was killed at process exit and the POST never landed
on the server. A second process recalling against the same bank a few
seconds later observed zero memories, even with sync_storage=True.
Cross-process drop-in is the most basic real-app pattern users try after
the cookbook, so this silent data loss had to be fixed before merge.
Reproduction (pre-fix):
Process A: configure(sync_storage=True) + litellm.completion(...)
→ logs "Stored conversation to bank: BANK"
→ process exits
Wait 10s.
Process B: Hindsight(...).list_memories(BANK)
→ 0 memories
Post-fix: Process B sees the extracted memories as expected.
Adds two regression tests that mock retain() and assert sync=True is
forwarded in both the non-streamed and streamed sync_storage branches.
Both fail on the prior code; both pass now.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(litellm): remove dead _debug_lock
_debug_lock at __init__.py:165 was never used — there's no `with _debug_lock:`
anywhere in the codebase and every _last_injection_debug write is unguarded.
Reviewer (benfrank241) flagged this on PR #1711. Drop the unused variable.
threading is still imported (used by _enabled_lock at line 158,
_storage_error_lock at line 1035, and two threading.Thread spawns at 1190 +
1263), so the import stays.
105/105 tests in test_integration.py pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(litellm): sync openapi.json with main
Branch carried an older snapshot of hindsight-docs/static/openapi.json
that pre-dated main's addition of OperationProgress. Re-checkout main's
openapi.json so check-openapi-compatibility passes.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: DK09876 <[email protected]>
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
* feat(claude-agent-sdk): add Claude Agent SDK integration with memory tools and hooks
Adds hindsight-claude-agent-sdk package providing:
- In-process MCP server with retain, recall, and reflect tools
- Automatic memory hooks (auto-recall on prompt, auto-retain on stop)
- Tool output retention via PostToolUse hooks
- Global configuration and per-call overrides
- 74 unit tests, CI job, and release script entry
- Cookbook recipe for docs site
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(claude-agent-sdk): default to Cloud without configure(); add gated E2E + bucketing
- resolve_client() now falls back to DEFAULT_HINDSIGHT_API_URL and the
HINDSIGHT_API_KEY env var when configure() was never called (it previously
raised). Updated the tools + hooks unit tests to assert the cloud-default +
env-key behavior. Satisfies the "default to Cloud" goal for both
create_hindsight_tools and create_memory_hooks.
- Add a gated tests/test_e2e.py (retain/recall/reflect MCP tools against a live
Hindsight server, stdlib urllib health check — no requests dep), marked
requires_real_llm; register the marker; the test-claude-agent-sdk-integration
CI job now runs the deterministic bucket (-m "not requires_real_llm").
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(claude-agent-sdk): assert create_memory_hooks reads HINDSIGHT_API_KEY from env
Mirrors the tools env-key test so hook construction's cloud-default + env-key
path is covered, not just the no-key default.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: DK09876 <[email protected]>
* docs: add langgraph.py example snippets for integration docs
Adds embeddable code snippets covering all three LangGraph integration
patterns: tools (ReAct agent), memory nodes, BaseStore, and constructor
options. Follows the same [docs:section] pattern as ai-sdk.ts.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* LangGraph integration: add memory_instructions, fix nodes, remove BaseStore
- Add memory_instructions() for standalone LangChain use without a graph
- Add recall_types, recall_include_entities to create_recall_node()
- Add metadata, document_id to create_retain_node()
- Nodes now raise HindsightError instead of silently swallowing errors
- Remove HindsightStore (BaseStore adapter) — leaky KV abstraction over
semantic memory (get unreliable, delete no-op, list session-scoped)
- Update README: cloud-first examples, add memory_instructions section
- Update docs example: replace base-store with memory-instructions snippet
- Fix pre-existing test failures (user_agent mock mismatch)
- 52 unit tests pass, 13 E2E tests pass
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* style(langgraph): run ruff format on tools.py
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* docs(langgraph): keep cloud product unnamed in module docstring
The docstring example said "Uses Hindsight Cloud by default" — names the
cloud product in OSS source. Per the integration review's OSS-clean rule,
the cloud should be reachable by overriding hindsight_api_url but not
explicitly named in core code. Rephrased to "Uses the default API URL"
and "Or point at a different instance".
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* chore(langgraph): address PR review polish items
- __version__ now derived from package metadata (was stale 0.1.0 vs pyproject 0.1.2)
- pyproject description no longer references the removed store adapter
- create_hindsight_tools return type tightened from `list` to `list[BaseTool]`
- memory_instructions docstring now documents the deliberate silent-fallback
on Hindsight error (vs nodes which raise) — load-bearing API contract
- create_retain_node docstring now notes ToolMessage / FunctionMessage
content is intentionally skipped
No behaviour change; 52/52 unit tests still pass.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* fix(langgraph): default to Cloud without configure() + add gated E2E suite
resolve_client() now falls back to DEFAULT_HINDSIGHT_API_URL and the
HINDSIGHT_API_KEY env var when configure() was never called, matching the
Superagent pattern and satisfying the "default to Cloud" goal. Previously
create_hindsight_tools(bank_id=...) raised without an explicit URL/config.
Also add an in-tree, pytest-gated tests/test_e2e.py covering the tools,
graph-node, and memory_instructions patterns (skips when no live Hindsight),
update unit tests to assert the Cloud-default behavior, and close the
Hindsight clients in the manual smoke scripts to avoid unclosed-session
warnings.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(langgraph): drop "Hindsight Cloud" product name from tools docstring
Keeps the OSS source product-agnostic — cloud naming belongs in the
cookbook/blog, not the package. Behavior unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(langgraph): bucket E2E as requires_real_llm
Mark the live E2E suite (drives a live Hindsight server) with a module-level
requires_real_llm marker, registered in pyproject, mirroring the core test
split from #1469. Deterministic bucket (-m "not requires_real_llm") = 53 unit
tests; real-LLM bucket (-m requires_real_llm) = 6 E2E.
Note: there is no test-langgraph-integration CI job yet, so this marker is not
wired into CI; adding that job is tracked as a follow-up in the review log.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* test(langgraph): add deterministic compiled-graph flow test (mock bucket)
Wires a real compiled StateGraph (recall -> agent -> retain) backed by a mocked
Hindsight client, asserting the recall node injects memory and the retain node
stores the human turn — the in-CI / no-keys analog of the live graph test.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* ci(langgraph): add test-langgraph-integration job + 3 supporting wiring places
Audit finding (2026-06-02): hindsight-langgraph has zero CI presence in
.github/workflows/test.yml — no detect-changes output, no path filter, no
job definition, no aggregate-gate entry. The prior review-log called this
PR MERGE-READY based on "green at time of audit"; the audit caught that
green was consistent with "no job exists to fail" — changes to the package
silently bypassed CI.
This commit adds the missing wiring, mirroring the AutoGen #1868 pattern
that added the same scaffold for that package's integration job:
1. L41 detect-changes output: integrations-langgraph
2. L126 path filter: hindsight-integrations/langgraph/**
3. L2914 job def: test-langgraph-integration
- timeout-minutes: 30 (matches autogen/openai-agents)
- runs uv build + uv sync --frozen + pytest with the
`-m "not requires_real_llm"` exclusion so the deterministic
bucket runs in PR CI while the live bucket is reserved for
the dedicated/nightly job (the standing convention from
PR #1469).
4. L3911 aggregate gate entry: test-langgraph-integration
Verification:
- YAML parses (python -c 'yaml.safe_load(...)').
- Deterministic bucket unchanged: 55 pass / 6 deselected.
The PR's existing integration code is unchanged — this is purely test-yml
scaffolding.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: DK09876 <[email protected]>
* blog: Mental Models in Hindsight — A Code-Level Deep Dive
Definitive technical reference for the mental-models feature. Every
claim is grounded in the docs or the implementation, with file paths
and line numbers cited inline.
* feat(operations): durable progress snapshot for consolidation and batch retain
Long-running consolidation could look identical whether healthy or stuck:
updated_at was only touched on claim/complete, with no mid-run progress, so
operators couldn't tell a slow job from a frozen one without DB access (#1840).
Add a best-effort heartbeat that writes a coarse {stage, processed, total,
detail} snapshot into async_operations.result_metadata (top-level jsonb merge so
sibling keys survive) and bumps updated_at, at phase/batch boundaries:
- consolidation: scanning -> processing_batch (per round, with observation
counters) -> refreshing_mental_models
- batch retain: processing_sub_batch per sub-batch (split loop + small-batch path)
Each call mirrors the same stage into the existing set_stage() so live worker
logs and the durable row tell one story.
Surface it as a typed `progress` field on the operation list/status API
(OperationProgress model); null when no snapshot was recorded. Regenerate
OpenAPI spec + Python/TS/Rust/Go clients.
Scope is visibility only: no staleness classification or auto-kill.
Tests: helper merge-without-clobber + updated_at bump, API surfacing on
get/list, null-when-absent, and real-run wiring for consolidation (processed
advances to total) and batch retain.
* feat(control-plane): show operation progress snapshot in operations view
Surface the new `progress` field (stage + processed/total + per-phase counters)
that the dataplane writes for running consolidation/batch-retain operations.
- Type `progress` through api.ts (listOperations + getOperationStatus) via a
shared OperationProgress interface.
- bank-operations-view: render a compact stage + processed/total bar under the
status badge on processing rows, and a full progress block (with detail
counters) in the operation details dialog. Refreshes via the existing poll.
- Add the `field.progress` label to all locale message files.
UI half of #1840; pairs with the dataplane progress snapshot.
* fix(operations): make retain progress reach total on completion; hide on terminal ops
A finished single-sub-batch retain was frozen at a pre-run "processing_sub_batch
0/1" snapshot: it was written *before* the sub-batch ran and never updated, so a
completed operation looked stuck. The control-plane details dialog also rendered
that leftover heartbeat regardless of status, so a completed op showed an
in-progress bar.
- Write the retain progress snapshot *after* each sub-batch commits (processed=i
for the split loop, 1/1 for the small-batch path), so the last snapshot reaches
total/total and reflects completion instead of a stale pre-run count.
- Control plane: only render the progress section while status is "processing";
for terminal operations the status badge + completed_at are the source of truth.
Update the retain progress test to assert the snapshot reaches total/total and
the durable row reflects completion.
* fix(operations): per-LLM-batch consolidation progress + live heartbeat in UI
Consolidation progress was written only at the outer DB-fetch round boundary, but
a whole batch of memories is processed inside a single round's LLM dispatch — so
the snapshot sat at "scanning 0/N" for the entire (often minutes-long) LLM phase
and only jumped at the very end, looking stuck even while healthy.
- Write the snapshot per LLM batch using the cumulative processed count that the
per-batch log already tracks, with cumulative observation counters in detail.
processed now climbs 8/42, 16/42, … as batches commit. Drop the now-redundant
round-boundary write.
- Control plane: show a live "last heartbeat · Ns ago" line under the progress
bar, ticking every second (only while an operation is processing) so a frozen
heartbeat on an active job is visible at a glance. Add heartbeat/lastHeartbeat
labels to all locales.
* fix(operations): clearer consolidation stage, compact progress row, faster poll
Address operator-feedback on the progress UI:
- Collapse consolidation's "scanning" + "processing_batch" into one self-explanatory
"consolidating" stage that advances 0/N -> N/N, instead of an opaque scan->process
hop nobody could interpret.
- Control plane: render the in-row progress as a single compact line (bar + count +
heartbeat age) so the status column no longer stacks three rows; the full breakdown
(stage, counters, labelled heartbeat) stays in the details dialog.
- Poll the operations list every 2s while something is processing (was a flat 5s) so
the bar and heartbeat feel live, backing off to 5s when everything is terminal.
* feat(operations): chunk-level retain progress; cap consolidation total; drop detail badges
- Retain now reports "storing N/total chunks" from the streaming pipeline as each
consumer batch commits (threaded via a progress_callback so the engine stays
decoupled and operation_id/total_chunks are already in scope). Replaces the coarse
per-sub-batch tick — a long document now shows chunks committing live.
- Consolidation: treat total as an estimate that grows with processed
(max(total_count, processed)) so the bar never reads >100% (e.g. 58/51) when memories
are retained mid-run.
- Control plane: drop the per-counter detail badges from the progress dialog (noisy);
the bar + stage + heartbeat carry the signal.
* feat(control-plane): inline progress + heartbeat on the status badge row
Put the compact progress (bar + count + heartbeat age) on the same line as the
status badge instead of stacking a second row under it, so a processing row reads
"⟳ processing ▓▓░ 8/42 · 5s" on one line.
* feat(operations): Updated column, fixed-width status, snappy completion flash
Operator-feedback polish on the operations table:
- Add an "Updated" column (relative time, absolute in tooltip). Required surfacing
updated_at on the operations *list* endpoint (it was only on the detail endpoint);
regenerated OpenAPI + clients.
- Give the status column a fixed width so the row no longer shifts left when the
inline progress appears/disappears as an operation starts or finishes.
- Flash a row briefly (emerald on completed, red on failed/cancelled) when it
transitions to a terminal state, with a 700ms color transition, so a completion
landing on a poll reads as a deliberate change instead of a silent badge swap.
- Refresh the relative-time clock on every poll so the Updated column stays accurate
while idle (not just while the per-second heartbeat ticker runs).
* feat(control-plane): label and fix the Actions column width
The Actions column had no header and no fixed width, so it grew when a pending/failed
row's Cancel/Retry button appeared — shifting the whole table. Give it an "Actions"
label (added to all locales) and a fixed 110px width on header and cell so the layout
stays put regardless of which rows show an action button.
* feat(operations): update consolidation total by re-counting instead of clamping
Replace the max(total, processed) clamp (which pinned the bar at 100% once processed
caught the start-of-job estimate) with a real re-count: once processed passes the
initial estimate, report total = processed + still-pending. Guarded so the extra
COUNT only runs after the estimate is exhausted (≈the final batch normally, or
repeatedly only if memories keep arriving mid-run) — no per-batch query in the common
case.
Also explain it in the UI: the consolidation progress section notes that the total is
an estimate from job start and can grow if new memories arrive while it runs.
* fix(control-plane): label file_convert_retain as "Convert File"
vLLM (--enable-auto-tool-choice), LM Studio and Ollama advertise
tool_choice="required" but silently ignore it: instead of forcing a tool
call they return finish_reason "stop"/"tool_calls" with an EMPTY tool_calls
array and no HTTP error. Reflect's agent loop forces its retrieval tools via
named tool_choice dicts (normalized to "required" + a single filtered tool),
so on these endpoints the agent calls zero tools, synthesis runs with no
retrieval, and reflect answers "I don't have information" even when the bank
holds the answer.
Downgrade "required" to auto (None/omitted) for these self-hosted endpoints
so the model still gets to call a tool. Named dicts already narrow the tools
list to one entry, so forced calls stay practically forced under auto. The
real OpenAI API (no base_url override), llama-server (which honors
"required", per #1179) and cloud providers are left untouched.
Fixes#1877. Same bug class as #1563 (LM Studio) and #1179 (LM Studio +
Qwen), both of which this also resolves.
Model/connection initialization had no wall-clock cap: if embeddings, the
cross-encoder, or LLM verification blocked (e.g. an offline HuggingFace
download or an unreachable provider), `asyncio.gather` in
`MemoryEngine.initialize()` never returned and the daemon hung in a third
state — neither started nor errored. The lazy reranker path
(`CrossEncoderReranker.ensure_initialized()`) had the same problem on the
first request.
Wrap both with `asyncio.wait_for` capped by a new static config
`HINDSIGHT_API_MODEL_INIT_TIMEOUT` (default 300s, generous enough for
first-time model downloads). On timeout, raise a clear RuntimeError that
names the likely cause and points at the env var — no silent fallback.
Fixes#1897
Retain reserves max_completion_tokens (~64k) up front, and Groq's free-tier
8k TPM limit counts that reservation at admission, so every retain call is
rejected with HTTP 413 'Request too large' even for a one-line message.
Document that the free tier is unsuitable and a paid tier / other provider
is required. Refs #1573.
* fix(reflect): let a fresh mental model short-circuit forced retrieval
Reflect forced the full hierarchical path
search_mental_models -> search_observations -> recall via a named
tool_choice on the first iterations. Because a named tool_choice forbids
the model from emitting `done`, the agent could never answer off a fresh,
directly-relevant mental model — it always paid for the lower layers too
(issue #1971).
Fix: after the forced search_mental_models result, decide deterministically
(no extra LLM call) whether to keep forcing. If the call is low/mid budget
and every retrieved mental model is explicitly fresh (is_stale is False)
with non-empty content, stop forcing from the next iteration on. That
iteration — which happens regardless — now runs under `auto`, so the agent
either answers directly or, having just read the mental model, issues its
own targeted search_observations/recall. Stale, empty, or missing mental
models keep the full forced path; high budget always keeps it.
This reuses the agentic step that already occurs instead of adding a
separate sufficiency-classifier LLM call, so the sufficient path saves two
forced rounds and no path ever adds a round.
* test(reflect): add real-LLM e2e coverage for mental-model short-circuit
Two hs_llm_core end-to-end tests drive the real agent loop (stubbed
search functions, real llm_config) to verify behaviour the deterministic
MockLLM tests cannot:
- fresh + sufficient mental model: the released agent answers off it and
never calls search_observations/recall (judge-verified grounding);
- stale mental model: no short-circuit, lower layers stay forced, and the
agent corrects the stale summary using the freshly retrieved raw fact.
The stale case (forcing is deterministic) is used rather than a
"fresh-but-incomplete model retrieves deeper on its own" case, because
whether a released model chooses to dig deeper is model-dependent and not
something the fix guarantees — only release-to-auto is guaranteed.
Both histories accumulated in a single JSONB/CLOB `history` column, appended
to on every update. Observations had NO cap at all, so a frequently-reinforced
observation grew until it crossed Postgres's 256MB jsonb limit (SQLSTATE 54000)
and the row got stuck. Mental models capped by entry COUNT (not size) and
rewrote the whole array + TOAST per refresh, defeating HOT updates.
Now one row per change in mental_model_history / observation_history, indexed
on (item, changed_at DESC, id DESC). Each row stores its snapshot as a single
JSONB `content` blob (per-row, so it stays small) plus changed_at; the cap is
enforced at write time as a bounded DELETE of the oldest over-cap rows, for
both histories (new per-observation cap:
HINDSIGHT_API_OBSERVATION_HISTORY_MAX_ENTRIES, default 50).
- migration a7b8c9d0e1f2: create tables, backfill from the JSONB/CLOB arrays
(PG jsonb_array_elements / Oracle JSON_TABLE), drop the legacy columns
- write paths: insert-then-trim in consolidator (observations) and
memory_engine (mental models); also stop writing the dropped column in the
create-observation INSERT
- read paths: get_observation_history / get_mental_model_history read the new
tables; observation list/get no longer select the column
- export/import: mental_model_history carried (parent keeps a stable id, the
surrogate id is dropped so the target reassigns it); observation_history is
derived (observations regenerate with fresh ids on import) and not carried
- tests: deterministic observation-history coverage + MM-history export/import
round-trip
* fix(docker): clear diagnostic for pg0 bind-mount permission failure (#1483)
The standalone image runs rootless (UID 1000). A host bind mount whose
directory isn't owned by UID 1000 — the default on macOS Docker Desktop and
most non-1000 Linux hosts — makes embedded pg0 fail with the opaque
"Permission denied (os error 13)". Auto-chowning the volume would require
running as root, which we deliberately avoid.
Instead:
- Recommend a Docker named volume in the README/installation docs; named
volumes are seeded with the image's UID-1000 ownership, so they work with
zero setup and stay rootless.
- Add a pg0 writability pre-check in start-all.sh that prints an actionable
message (named volume, or --user) and exits cleanly instead of letting pg0
emit os-error-13. Skipped when an external database is configured.
- Add regression tests for the new check in test-start-all.sh.
* docs(readme): drop bind-mount explanation, keep named-volume fix
* fix(openapi): keep binary upload fields as format:binary; regen spec+clients
The #1982 dep bump (FastAPI 0.136 / Pydantic 2.12) serializes binary upload
fields as OpenAPI-3.1 {"type":"string","contentMediaType":"application/
octet-stream"}. openapi-generator v7.10.0 (generate-clients.sh) does NOT
treat contentMediaType as a file upload, so it regenerated the Files `files`
and document-transfer `file` params as plain strings — silently breaking
multipart upload in the Go/Python/TypeScript clients ([]*os.File -> []string,
StrictBytes -> StrictStr, Blob|File -> string).
generate_openapi.py now post-processes the exported schema to restore the
prior `format: binary` representation (still valid under openapi 3.1.0, and
what the generator understands) for application/octet-stream string fields,
scoped to binary uploads only. Regenerated the spec and clients: the upload
signatures are back to the file-upload form (identical to main); the only
remaining delta vs main is ValidationError dropping its `url` field, a real
Pydantic 2.12 change (error metadata, harmless).
* test(embeddings): give zeroentropy routing mocks a dimension attribute
PR #1670 added post-encode dimension validation to generate_embeddings_batch
— it now reads embeddings_backend.dimension, which the EmbeddingsBackend
Protocol already requires. The pre-existing QueryAwareEmbeddings/
DocumentAwareEmbeddings routing mocks (#1770) omit it, so the two routing
tests started failing with AttributeError on main.
The mocks return single-element vectors, so declare dimension = 1 to satisfy
the Protocol and let validation pass. Pure test fix; no behavior change.
* test(openapi): lock _restore_binary_format binary-upload rewrite
Regression guard for the file-upload break: asserts octet-stream string
fields are rewritten to format:binary (incl. nested/array-item schemas) and
that other content media types are left untouched.
All bank-scoped write paths lazily create the bank (the FK target) before
their first insert. That logic was duplicated across create_mental_model,
create_webhook, submit_async_retain, and the import paths as a bare
get_or_create_bank_profile + best-effort default-template apply, and it ran
on its own connection — so a freshly-created bank could outlive a write that
ultimately failed.
Introduce a single MemoryEngine._ensure_bank_exists() entry point:
* Pass conn (with an open transaction) to run the bank INSERT + per-bank
vector index creation on the caller's connection, so the bank row commits
or rolls back atomically with the caller's write. Used by
create_mental_model, create_webhook, and submit_async_retain (whose
parent+child inserts already share one transaction).
* Omit conn for paths with no single write transaction to join (retain and
import write later across many per-document transactions); the bank is
created on a dedicated connection as before.
The HINDSIGHT_API_DEFAULT_BANK_TEMPLATE hook is best-effort, opens its own
connections, and can itself create pinned models, so it is never run inside
the caller's transaction — it stays a post-commit step, applied only when the
bank was freshly created. Add get_or_create_bank_profile_on_conn() in
bank_utils as the connection-bound variant.
Both get_or_create_bank_profile and its _on_conn variant now return a typed
BankProfileResult dataclass instead of a (profile, created) tuple.
Tests: add txn-rollback atomicity coverage for create_mental_model (a failing
insert rolls the new bank back) and submit_async_retain (new bank rolls back
with the operation rows), plus missing-bank coverage for webhooks and batch
retain. Update test_async_retain_tags to stub _ensure_bank_exists (the method
submit_async_retain now calls).
VectorChord BM25 registers its objects in dedicated schemas
(vchord_bm25 -> bm25_catalog, pg_tokenizer -> tokenizer_catalog). The
BM25 distance operator <&> resolves its operand types via the session
search_path, so a connection that lacks these schemas fails recall with
'type "bm25vector" does not exist' and retain with
'function tokenize(...) does not exist'.
The official vchord-suite Docker image masks this by shipping the
catalogs in search_path; an external Postgres does not. Set the same
search_path on each connection when the vchord text-search backend is
configured. Qualifying the SQL is insufficient: the <&> operator's type
resolution cannot be schema-qualified and still requires bm25_catalog on
the path. Tenant tables are always accessed via fq_table(), so this does
not affect schema isolation.
Structured-output calls (retain fact extraction, consolidation observation
merge) use a soft "schema-in-prompt + json_object" path by default: the schema
is appended to the prompt and the model must voluntarily emit valid JSON. Strong
hosted models comply, but weaker self-hosted instruction-followers (small
Qwen/Llama/Mistral GGUF via llama.cpp/vLLM) return prose preambles, markdown
fenced blocks, or invalid JSON that fails to parse — retain/consolidation then
retry forever and wedge.
#1986 added a HINDSIGHT_API_LLM_STRICT_SCHEMA flag but wired it into only the
OpenAI-compatible provider, leaving LiteLLM and the batch retain path ignoring
it. Resolve the flag once in LLMProvider.call (OR-ed with the per-call
strict_schema arg) and pass it down instead, so every json_schema-capable
provider honours it through its existing strict_schema handling:
- OpenAI-compatible (+ llama.cpp delegate, Fireworks subclass) and LiteLLM:
json_schema strict instead of soft json_object.
- Gemini already grammar-enforces its native response_schema (no-op).
- Batch retain path builds its request body directly (bypasses .call()), so it
reads the flag itself and sets json_schema strict.
Providers without a strict mode (Anthropic, Claude Code, Codex) ignore the flag
and keep the soft path — unchanged.
Default false, so no behavior change for existing deployments. Corrects the
stale "OpenAI only" docstrings, documents the env var in configuration.md, and
adds tests/test_llm_strict_schema.py (config parsing, wrapper resolution,
openai/litellm/batch mappings).
extra_body was only threaded into the OpenAI-compatible (and Fireworks)
providers. Extend it to Anthropic, Gemini/VertexAI and LiteLLM (incl. the
Bedrock alias and the LiteLLM Router) so the same env-configured knob
(temperature, top_p, max_tokens, ...) tunes every provider with no code
changes — closing the gap reported in #1227.
Each provider merges the params in its own native space:
- Anthropic: Anthropic SDK extra_body kwarg (call + call_with_tools)
- Gemini/VertexAI: seeded into GenerateContentConfig (explicit per-call
values win); Gemini nests generation params in the body
- LiteLLM/Bedrock/Router: top-level acompletion kwargs via setdefault so
LiteLLM normalizes/drops them per-provider
Stays server-level (env) only — not per-bank configurable.
The docs-skill regen also syncs a small pre-existing drift (Fireworks AI
in the provider/integration lists).
Refs #1227
* docs(performance): add Tuning for Local & Small Environments section
Supersedes #1721. Keeps the local-LLM concurrency guidance from that PR
(HINDSIGHT_API_LLM_MAX_CONCURRENT, saturation symptom + diagnostics) and
expands it into a dedicated section covering the other knobs that matter
on laptops, single-GPU boxes, and local LLM servers:
- per-operation concurrency caps to reserve reflect headroom
- timeouts/retries for slow local generation
- smaller per-operation models + low reasoning effort + LLM=none
- built-in llama.cpp tuning (gpu layers, context size, threads, grammar)
- CPU reranker knobs (fp16, bucket batching, max concurrent, flashrank)
- CPU embeddings (force_cpu)
* docs(performance): drop saturation symptom + diagnostics block
* docs(performance): drop LLM_PROVIDER=none chunk-mode note
* docs(performance): add reranker candidate-set + consolidation batch-size levers; drop CPU embeddings note
* fix(oracle): make recall and mental-model history work on the Oracle backend
Two code paths emitted PostgreSQL-specific SQL that has no Oracle equivalent
and is not handled by the PG→Oracle query rewriter, so they raised hard
errors on the Oracle 23ai backend:
1. Recall — `retrieve_temporal_combined` expands a batch of seed ids for
multi-hop temporal-link spreading with `FROM unnest($2::uuid[]) AS
src(from_unit_id)`. Oracle has no `unnest`, so recall raised
`ORA-03048` whenever the matched memories had temporal/causal links
(the common case). Fix: guard the spreading loop on the connection's
`backend_type`; on backends without `unnest` we skip only the multi-hop
spread. The temporal entry points are still returned, and the
semantic / keyword / graph retrievers are unaffected.
2. Mental-model history — `update_mental_model` trims the history array in
SQL with `jsonb_agg(... ORDER BY ...)` over
`jsonb_array_elements(...) WITH ORDINALITY`, which raised `ORA-00907`
and made mental-model creation fail (the create path triggers a refresh
that updates content). Fix: on Oracle, compute the trimmed history in
Python (we already fetch the current array) and bind it as a single JSON
value. The PostgreSQL SQL path is unchanged.
Both are instances of the dialect-asymmetry trap called out in CLAUDE.md.
Test plan:
- Oracle 23ai e2e smoke + HTTP integration: mental-model create/CRUD and
full-lifecycle (previously failing with ORA-00907) now pass.
- Full Oracle integration suite shows zero ORA-03048 occurrences.
- PostgreSQL mental-model history unit tests (including max-entries
trimming) still pass — the PG path is byte-identical.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* fix(oracle): return CLOB columns from RETURNING without a 4000-byte cap
The Oracle backend's RETURNING handler bound every non-numeric, non-timestamp
output column as DB_TYPE_VARCHAR. VARCHAR out-binds cap at 4000 bytes, so any
CLOB-backed column returned via a RETURNING clause raised
`ORA-22835: buffer too small for CLOB to CHAR conversion` once its value
exceeded 4000 bytes. This surfaced as mental-model creation failing on Oracle:
the post-create refresh UPDATEs `content` (a CLOB) with `RETURNING content`,
and a sufficiently long synthesized snapshot (>4000 bytes) aborted the update.
Fix: bind known CLOB columns (the JSON-as-CLOB set plus the large-text columns
content/text/context/structured_content/text_signals/search_vector) as
DB_TYPE_CLOB in the RETURNING var setup, and read the LOB handle back to a
string in _read_returning_values (the async pool yields AsyncLOB, whose read()
is awaited). Non-CLOB columns are unchanged.
Verified against Oracle 23ai:
- A 4277-byte CLOB now round-trips through UPDATE ... RETURNING (previously
ORA-22835); other columns (RAW(16) ids, etc.) still convert correctly.
- Mental-model create/refresh with large content succeeds.
- RETURNING-heavy Oracle integration tests (retain, tags, document/memory CRUD,
http retain/recall, full lifecycle) pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* fix(oracle): make the temporal entry-point query Oracle-compatible (no unnest)
The temporal-recall entry-point selection was rewritten on main (#1983) to gate
candidates by embedding similarity within the window. That new query expanded the
fact_types with `FROM unnest($3::text[]) AS ft CROSS JOIN LATERAL (...)`, which has
no Oracle equivalent — so after merging main, Oracle recall would again fail with
ORA-03048 on any temporal query, in the entry-point query this time (the spreading
guard added here only covers the multi-hop spread).
Rebuild the entry-point query as a UNION ALL of one similarity-ranked,
window-filtered arm per fact_type with the fact_type inlined as a literal — the
same shape retrieve_semantic_bm25_combined already uses and which the Oracle
backend runs. The `<=>` operator and `LIMIT` are translated to VECTOR_DISTANCE and
FETCH FIRST on execute; only `unnest` was untranslatable, and it's now gone.
Behavior on PostgreSQL is unchanged (each arm still hits the per-(bank, fact_type)
vector index; selection + coverage logic is identical) — verified by the existing
temporal selection tests and the recall_perf temporal benchmark (temporal arm
~0.002s on the 680k dense bank). Oracle output verified through the real
_rewrite_pg_to_oracle translator: no unnest, valid VECTOR_DISTANCE + FETCH FIRST.
---------
Co-authored-by: DK09876 <[email protected]>
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
#1903 expanded BACKUP_TABLES to all 15 tables (the 7 previously-missing ones that could be silently dropped on restore), but the "backup includes" list still reflected the old ~8-table coverage. Update it to match: mental models, directives, webhooks, file storage, plus internal operational tables for a faithful full-database snapshot. Oracle-only observation_sources stays excluded (PostgreSQL-only backup). Regenerated skills/hindsight-docs mirror.
* docs(models): register fireworks in llmProviders.json (#1860)
#1860 added fireworks to PROVIDER_DEFAULT_MODELS (config.py:535) but not to the
providers registry that renders the Models page grid + default-models table. The
registry docstring mandates it stay aligned with PROVIDER_DEFAULT_MODELS.
* docs(models): regenerate skills mirror for fireworks provider
Mirror of the generated <LLMProvidersGrid/> + <LLMProvidersTable/> output.
Replace deprecated Gemini models with their 3.x successors:
- gemini-3-pro-preview → gemini-3.1-pro-preview (shut down March 2026)
- gemini-2.5-flash → gemini-3.5-flash
- gemini-2.5-flash-lite → gemini-3.1-flash-lite
Also update default models in config.py for gemini and vertexai providers.
The create+update semantic dedup added in #1977 shipped opt-in (threshold 1.0).
Enable it by default at 0.97 so observations are deduplicated out of the box.
The merge path uses Postgres-only SQL, so consolidation skips dedup entirely on
Oracle (via _dedup_active) — it behaves exactly as before there, regardless of
the configured threshold. This is what lets the default flip without breaking
Oracle deployments.
Also fix MockLLM to return a valid keep-decision for the consolidation_dedup
scope, so mock-LLM consolidation tests (which now exercise the enabled-by-default
path) don't crash on the structured response and never spuriously merge.
* fix(recall): select temporal entry points by similarity with window coverage
retrieve_temporal_combined Phase 1 ranked the *entire* date-window match set by
COALESCE(occurred_start, mentioned_at, occurred_end) and kept the 50 most recent.
Two problems, one perf and one functional:
- Perf: on banks with dense/near-uniform date metadata (e.g. a retain pipeline
that stamps a large batch with one date) any recall window intersects
(near-)all rows, so Phase 1 degraded to a full sequential scan + disk-spilling
sort. EXPLAIN on a 680k-row bank: Seq Scan 680k + Sort 680k to keep 50
("Rows Removed by Filter: 679,950"), ~672ms Phase 1 alone (30s+ in prod).
- Functional: ranking by recency biases results toward the END of the window,
and when dates are degenerate the "50 most recent" is a near-random sample
that can drop the single most relevant in-window memory before similarity is
ever considered.
Switch the entry-point gate to embedding similarity within the window
(ORDER BY embedding <=> query, per fact_type, LIMIT pool), then narrow the pool
to N per fact_type with coverage-first round-robin across time-buckets so the
entry points span the window's range instead of clustering. Degenerate dates
collapse to plain similarity order.
The planner serves the similarity-ordered window query from the existing
per-(bank, fact_type) HNSW index when the window is broad (the dense case) and
from the existing partial date indexes + an exact sort when it is narrow — so no
new index is needed. (An earlier revision of this PR added a recency expression
index; Option A makes it unnecessary, so it's removed.)
Measured on a 680k-row dense-date bank (recall_perf): temporal arm
1.174s -> 0.009s; the arm is now both fast and returns the most relevant
in-window memories, spread across the window.
This is the alternative to #1958, which skipped the temporal arm entirely above a
planner row estimate (losing temporal recall on large banks).
- tests (no LLM): coverage round-robin + degenerate-date fallback (pure
selector); similarity-over-recency selection and window filtering (DB-backed)
- recall_perf: `generate --event-date` (dense zone) + `benchmark
--temporal-date` (forces the temporal arm) to reproduce and track this
* docs(retrieval): explain temporal selection (relevance-gated + window coverage)
The Manifest Schema example documented entity_labels as a bare string array
(`["PERSON", "ORGANIZATION"]`), but BankTemplateConfig.entity_labels is
`list[dict[str, Any]]` and each entry is parsed via LabelGroup (which requires
a `key`). A bare string fails import validation, so the documented example is
not usable. Replace it with a minimal valid label group and point the field
table at the authoritative shape already documented in memory-banks.mdx.
The Provider Default Models table advertised vertexai's default as
gemini-2.0-flash-001, which #1972 confirms is retired on Vertex AI
(404 NOT_FOUND). The live config default is google/gemini-2.5-flash-lite
(config.py:562 PROVIDER_DEFAULT_MODELS); the google/ prefix is stripped
for display. Regenerated the skills-docs mirror via generate-docs-skill.sh.
#1936 added the on-by-default HINDSIGHT_API_LLM_PROMPT_CACHE_ENABLED env var
but documented it only in models.mdx prose. Add the missing row to the
canonical LLM Provider table so operators can discover the cached-input
billing toggle from the env-var reference. Regenerated the skills mirror.
#1974 added HINDSIGHT_API_RECALL_STRATEGY_BOOSTS (named low/medium/high
per-source boosts), making retrieval.md's absolute claim 'There are no
per-strategy weight multipliers' factually wrong. Scope the equal-weight
statement to RRF fusion itself, point readers to the boost knob, and note
at the pre-filter cap stage that boosted sources are more likely to survive.
Regenerated the skills mirror.
Under load an alive-but-busy daemon (mid 30–60s LLM fact-extraction) can fail
to answer GET /health within the 2s default. That false negative makes
get_api_url() fall through to _ensure_daemon_running() →
`hindsight-embed daemon start`, whose _clear_port() then SIGTERMs the live
daemon — producing a daemon restart/kill loop under sustained traffic.
Raise the default to 10s, matching the recall hook's own budget (referenced in
get_api_url's docstring), so a busy daemon has time to respond before it is
declared dead. Callers passing an explicit timeout are unaffected. Applied to
both the claude-code and codex integrations, which share the helper verbatim.
Co-authored-by: Claude Opus 4.8 <[email protected]>
Flip DEFAULT_LLM_TRACE_ENABLED to True and DEFAULT_LLM_TRACE_RETENTION_DAYS
to 1 so LLM request traces are captured out of the box and swept after a
day. The retention sweep already enforces >0 day windows; existing tracing
tests toggle the recorder explicitly and are unaffected.
On a fresh plugin install the MCP server is registered unconditionally in
.mcp.json but exited immediately when enableKnowledgeTools was false (the
shipped default), so Claude Code reported a -32000 reconnect error on every
prompt.
- Default enableKnowledgeTools to true (settings.json + config DEFAULTS).
- When disabled, run an empty MCP server instead of exiting, so the
registered process stays alive and no reconnect error is surfaced.
Fixes#1995
* fix(python-client): expose reflect tool_calls/llm_calls trace in wrapper
The maintained high-level wrapper only exposed include_facts on
reflect()/areflect(), so there was no way to request the reflect trace
(trace.tool_calls / trace.llm_calls) without dropping down to the
generated API. The wire API and generated models already support it.
Add include_tool_calls and include_tool_call_output params to both
reflect() and areflect(), mapping them to ReflectIncludeOptions.tool_calls.
Add unit tests pinning the wrapper -> ReflectRequest.include mapping.
* fix(ts-client): expose reflect tool_calls/llm_calls trace (+facts) in wrapper
The TS wrapper's reflect() never sent an 'include' object, so the reflect
trace (trace.tool_calls / trace.llm_calls) and based_on facts were
unreachable from the convenience layer. The wire API and generated types
already support both.
Add includeFacts, includeToolCalls, and includeToolCallOutput options to
reflect(), mapping them onto ReflectRequest.include. Add mock-based unit
tests pinning the option -> include mapping.
Weak consolidation models (e.g. gemini-2.5-flash-lite) emit near-duplicate
observations even when the twin is in context, and an UPDATE that rewrites +
re-embeds an observation can drift it into a near-twin of a different existing
observation. When consolidation_dedup_threshold < 1.0, an observation that is
>= the threshold cosine to an existing one is reconciled by a focused 1-by-1 LLM
"merge or keep" call (anchored on the observation text, not the source fact, so
it is the correct obs<->obs comparison):
- CREATE path: on "merge", fold the new source facts + synthesized text into the
existing twin and skip the insert.
- UPDATE path: after the rewrite+re-embed, probe the new vector (excluding the
row itself); on "merge", fold the updated observation's sources into the twin
and delete the now-redundant updated row.
Default 1.0 disables it (no behaviour change). Postgres only. On the English
hermes obs benchmark with flash-lite at 1/4 scale, residual >=0.97 near-dups
drop from ~7% to 0-1%.
* fix(llamaindex): default to Cloud without configure(); replace dead manual test with gated E2E; bucket
- resolve_client() now falls back to DEFAULT_HINDSIGHT_API_URL and the
HINDSIGHT_API_KEY env var when configure() was never called (was raising).
Updated the raise-test to assert the cloud-default + env-key behavior.
- Replace the [email protected]'d tests/test_manual.py (dead code —
the class-level skip made it never run anywhere) with a real, gated
tests/test_e2e.py covering the create_hindsight_tools roundtrip
(retain/recall/reflect via tool.call()) AND the HindsightMemory.aget/put
roundtrip against a live Hindsight server.
- Marked requires_real_llm; register the marker in pyproject; add the missing
asyncio_mode = "auto"; the test-llamaindex-integration CI job now runs the
deterministic bucket (-m "not requires_real_llm").
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(llamaindex): give HindsightMemory.from_defaults a real cloud-default ctor
Audit finding (2026-06-02): HindsightMemory's create paths are asymmetric
with what create_hindsight_tools offers. The tools factory uses
resolve_client() so callers get the standard cloud-default + env-var
fallback for free; the memory adapter required either an explicit client
(from_client) or an explicit URL (from_url) and its from_defaults() raised
NotImplementedError. Callers wanting the same "no-config → Cloud" path
had to wire it themselves.
Fix: from_defaults(bank_id, ...) now calls resolve_client() exactly the
way the tools factory does. Falls back to DEFAULT_HINDSIGHT_API_URL when
no URL is supplied; reads HINDSIGHT_API_KEY from the environment if no
api_key is supplied; explicit `client=` still wins.
Tests pinning the new behaviour:
- from_defaults with nothing supplied → Hindsight constructed with
DEFAULT_HINDSIGHT_API_URL.
- from_defaults with api_key → constructed with the configured key.
- from_defaults with explicit client → no new Hindsight constructed.
Replaces the previous test_from_defaults_raises (which pinned the
NotImplementedError that we're removing).
Verification:
- Deterministic bucket: 86 pass / 4 deselected (84 prior + 2 new
cloud-default tests; one prior raises-test rewritten).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(llamaindex): reword 'Hindsight Cloud' in HindsightMemory.from_defaults docstring
V2 audit (2026-06-02) caught one 'Hindsight Cloud' literal introduced by
the cloud-default ctor fix (commit 92926e2c) at memory.py:126. Reworded
to drop the product name parenthetical — DEFAULT_HINDSIGHT_API_URL is
self-explanatory.
Goal-4 (OSS-clean) compliance restored. Behaviour unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(llamaindex): fall back to last user msg when aget() input is None
HindsightMemory.aget() only triggered automatic recall when called with
input=<query>. Workflow-based agents in current LlamaIndex
(llama_index.core.agent.workflow.ReActAgent, FunctionAgent, etc.) call
memory.aget() WITHOUT input= on their main path. Result: Pattern 1
(HindsightMemory as a drop-in BaseMemory) silently stopped surfacing
recalled memories — retain still fired, but the recalled facts were never
injected into the agent's context. Cross-session memory looked broken even
though the bank had the right content.
Reproduced in the canonical cookbook (notebooks/08-llamaindex-react-agent
cell 7 returned "No tengo acceso a información..." after cell 5 stored
Alice's facts) and in a real-app smoke test.
Fix: when aget()/get() is called without input, fall back to the most
recent USER ChatMessage in local history as the recall query. That message
is already populated by the workflow agent's aput(user_msg) call before
aget(). If there's no user message in history, skip recall — no
semantically meaningful query to look up.
Verified end-to-end:
S1 (write): agent.run("I'm Alice, data engineer at Acme, write Python,
use Neovim", memory=mem1)
10s wait
S2 (fresh memory + agent.run("What's my name and editor?", memory=mem2))
→ "Your name is Alice, and you use Neovim as your editor."
Regression tests:
- test_get_without_input_falls_back_to_last_user_message — asserts recall
fires with the last user msg as query
- test_get_without_input_and_empty_history_skips_recall — boundary case
- test_get_without_input_and_no_user_msg_skips_recall — only assistant
history, no recall
The existing test_get_without_input_returns_history asserted recall was
NOT called when input was None; that assertion was load-bearing on the
old (broken-for-workflow-agents) behavior and is replaced by the three
tests above. 38/38 tests in test_memory.py pass.
---------
Co-authored-by: DK09876 <[email protected]>
* blog: Long-Term Memory for Google ADK Agents with Hindsight
Introduces the hindsight-google-adk integration. Covers the drop-in
BaseMemoryService path (Runner takes care of add_session_to_memory /
search_memory automatically), the alternative FunctionTool path for
mid-turn agent-driven retain/recall/reflect, bank-scoping patterns
({app_name}::{user_id} default with overrides), and production patterns
(per-environment tagging, bootstrapped banks with a mission, self-hosted
Hindsight, recall budget).
* feat(engine): TTL + coalescing cache for get_bank_stats
The bank stats query joins memory_links to memory_units and aggregates by
(fact_type, link_type). On large banks the link side can run into millions
of rows, making each call a multi-second parallel scan. The result is
inherently approximate — it backs a UI widget and a freshness hint in
reflect — so a short result cache is safe.
Adds BankStatsCache: per-process TTL cache keyed on (schema, bank_id) with
LRU eviction and concurrent-miss coalescing, so N callers that arrive on
the same cold key produce one DB roundtrip instead of N. Wired into
MemoryEngine.get_bank_stats after auth and validation; the DB body moves
to _compute_bank_stats unchanged.
Tunable via HINDSIGHT_API_BANK_STATS_CACHE_TTL_SECONDS (default 60s,
set to 0 to disable) and HINDSIGHT_API_BANK_STATS_CACHE_MAX_ENTRIES
(default 1024).
* refactor(engine): drop unused memory_links⇒memory_units join in bank stats
get_bank_stats used to compute a (fact_type, link_type) matrix joining
memory_links to memory_units to pick up the originating unit's fact_type.
On large banks that join can take seconds — and an audit of every caller
(UIs, MCP tool, SDK clients, integrations) shows that the matrix
(`link_breakdown`) and its fact-type rollup (`link_counts_by_fact_type`)
are declared in response types but never actually read.
This refactor:
* Replaces the JOIN with a single-table GROUP BY link_type on
memory_links plus a small per-entity rollup over unit_entities. Both
are cheap with the existing indexes and stay cheap even at multi-
million-row scale.
* Keeps `links_breakdown` and `links_by_fact_type` in the response shape
(returning empty values) so SDKs and openapi-generated clients do not
break.
* Adds `MemoryEngine.get_bank_freshness(bank_id)` — a one-row aggregate
over memory_units that returns just last_consolidated_at /
pending_consolidation / failed_consolidation. Switches `reflect()` to
call it; reflect used to call get_bank_stats and discard everything
except those two scalars (and the previous hasattr-on-dict access
pattern meant it was reading None back anyway).
* Adds three tests: stats response shape, freshness method correctness,
and a regression test that reflect() never invokes the heavy stats
loader.
Together with the result cache added in the previous commit, the
expensive per-bank join is no longer on any hot path.
* docs(engine): correct bank stats comments — hindsight-cli still reads the deprecated fields
The prior comments asserted "no consumer reads" link_counts_by_fact_type /
link_breakdown. That was wrong: hindsight-cli's `bank stats` renderer
iterates both. The data still degrades gracefully there (one section
prints empty, the other is skipped by an is_empty() guard), but the
deprecation note should reflect reality so the next reader doesn't
assume the CLI was audited and rip the fields out without updating it.
* fix(engine): invalidate bank stats cache on delete_bank / clear_memories
The TTL cache was serving pre-deletion counts for up to 60s after
delete_bank() (which also backs the DELETE /memories "clear" path),
breaking the contract that callers see fresh data immediately after a
destructive op. Two http integration tests were failing on shard 2/3
because the second stats read returned the cached pre-delete value.
Wire BankStatsCache.invalidate() into delete_bank after the deletion
commits. Other write paths (retain, consolidate) only loosen counts and
remain TTL-bounded — staleness there is acceptable polling behavior.
* docs(engine): clarify get_bank_freshness keeps failed_consolidation for contract
---------
Co-authored-by: Nicolò Boschi <[email protected]>
- resolve_client() now falls back to DEFAULT_HINDSIGHT_API_URL and the
HINDSIGHT_API_KEY env var when configure() was never called (was raising).
Updated the raise-test to assert the cloud-default + env-key behavior.
- Fix two pre-existing broken tests (test_falls_back_to_global_config /
test_explicit_url_overrides_config): mock_cls.assert_called_once_with was
missing user_agent — switched to loose call_args.kwargs checks.
- Add a gated tests/test_e2e.py (retain/recall/reflect via tool.run_json) and
mark requires_real_llm; register the marker.
- ADD the missing test-autogen-integration CI job (the autogen/ package had
ZERO CI coverage — only ag2/ had a job). 4 places:
* detect-changes output integrations-autogen
* path filter hindsight-integrations/autogen/**
* test-autogen-integration job (runs -m "not requires_real_llm")
* test-autogen-integration entry in the aggregate gate
Co-authored-by: DK09876 <[email protected]>
* feat(gemini): add context-cache foundation (GeminiCacheManager + opt-in call() arg)
Wraps the google-genai SDK's CachedContent API so callers can reuse a
stable (system_instruction + response_schema) prefix across many
requests. Cached input tokens are billed at a fraction of the standard
input rate, which makes workloads with a fixed-prefix / small-user-message
shape — fact extraction, structured tagging, classification — far
cheaper to run.
This PR is foundation-only: no caller is wired up yet. Default
behaviour for every existing path is unchanged because
`cached_content_name` defaults to `None` and the cache manager is
never instantiated until a follow-up wires it in.
What's here
-----------
- `gemini_cache.GeminiCacheManager`: per-process map of prefix
fingerprint → CachedContent resource name. Thread-safe via a single
asyncio.Lock. Refreshes proactively at TTL minus a safety margin.
Stable fingerprint normalisation strips auto-generated Pydantic
schema titles so dynamically-built schema classes with identical
shape hash to the same key (relevant for callers that rebuild the
schema class on every request).
- `gemini_llm.GeminiLLM.call(cached_content_name=...)`: new optional
arg. When set, the SDK config drops `system_instruction` and
`response_schema` (those live in the cache) and instead passes
`cached_content` to GenerateContentConfig. When unset, behaviour is
byte-identical to before.
- `tests/test_gemini_cache.py`: 10 unit tests covering fingerprint
stability, dict/list/Pydantic schema cases, get_or_create
caching/recreate, "minimum token count" soft-fallback, transient
SDK error soft-fallback, failed-create-doesn't-poison-cache, and
the TTL refresh boundary.
Failure handling
----------------
- Gemini rejects creates whose prefix is below the model's minimum
cacheable size with a "minimum"-style error message. The manager
catches this, logs at DEBUG, and returns None so the caller
transparently falls back to a non-cached call.
- Any other SDK error is logged at ERROR and also returns None — a
bad create never crashes a request. Callers are required to treat
None as "cache unavailable, use the normal path".
Not in this PR
--------------
- Wiring this into the fact-extraction pipeline (or any other caller)
- A metric for cached-token volume
Both will come in a focused follow-up so the foundation can land and
be reviewed independently.
* feat(gemini): wire retain fact-extraction to context cache; surface cached + thoughts tokens
Follow-on to the foundation commit on this branch — without this, the
cache manager is unreachable and the metric ignores half the cost
surface. This commit makes the change actually do something when the
flag is flipped on.
What lands
----------
1. Retain fact-extraction (engine/retain/fact_extraction.py) opts into
the cache. The system prompt and response schema are fingerprinted
and reused across calls; the user message is the only variable
part on the wire. A cache lookup failure or "prefix too small"
response from Gemini transparently falls back to the existing
uncached path — caching is a soft optimisation, never a blocker.
2. New top-level flag HINDSIGHT_API_LLM_GEMINI_PROMPT_CACHE_ENABLED
(also exposed as ``llm_gemini_prompt_cache_enabled`` on
HindsightConfig). Defaults to False so upgrade-and-do-nothing is a
no-op. Flipping to True opts every Gemini caller (currently only
retain) into context caching.
3. Two new metrics:
- hindsight.llm.tokens.cached_input — subset of input tokens billed
at the cached rate. Lets dashboards split cache-hit vs cache-miss
volume independently of total throughput.
- hindsight.llm.tokens.thoughts — reasoning tokens emitted by
Gemini 2.5+. Billed at the output rate by the provider but
invisible to candidates_token_count, so absent from output-token
dashboards today. Surfacing this is required for honest cost
attribution.
4. Provider plumbing: GeminiLLM gains a ``gemini_prompt_cache_enabled``
kwarg and a ``get_or_create_cached_prefix(...)`` accessor that lazy-
builds a GeminiCacheManager on first opt-in. LLMProvider /
create_llm_provider / ConfiguredLLMProvider pass the flag through
the standard plumbing alongside the existing safety_settings.
Verification
------------
- ``uv run ruff check`` — clean
- ``uv run pytest tests/test_gemini_cache.py`` — 12 tests including
two new integration tests that pin (a) flag-off → cache manager
never built, and (b) flag-on → manager lazy-built, second lookup
served from in-memory cache, no extra SDK call.
- ``uv run pytest tests/test_gemini_safety_settings.py`` — 13 tests
still green (no signature drift; the NoOp metrics collector was
updated alongside the real one).
Rollout
-------
- Land this commit. With the flag default-off, behaviour is identical
to today: cache code paths exist but are never reached.
- Flip the flag per-env. The metric goes non-zero on cached_input
within a few calls.
- Watch hindsight.llm.tokens.cached_input vs hindsight.llm.tokens.input
to confirm cache-hit rate.
What's deliberately NOT in this PR
----------------------------------
- Extending caching to other Gemini callers (reflect tool-call,
consolidation). Same mechanism applies — copy two lines from the
retain path. Leave for a follow-up so this lands in one focused PR.
- Cross-pod cache sharing. Each pod warms its own cache. The cost of
one extra full-price call per pod per fingerprint per TTL window is
negligible relative to steady-state savings.
* feat(gemini): extend context caching to the tool-calling reflect loop
Adds caching support to the agentic tool-loop path. The reflect agent's
``system_prompt + tools`` is stable for the duration of a single reflect
(and across reflects against the same bank), so caching them once and
reusing the cache name across every iteration of the loop collapses the
dominant input cost — the prefix repeated on every turn.
Mechanism
---------
1. ``GeminiCacheManager.fingerprint(...)`` now accepts ``tools`` and
includes the OpenAI-style tool list in the hash. A loop that swaps a
tool gets a fresh cache automatically; a loop that doesn't, hits the
cache deterministically. The tool list is serialised with sort_keys
so upstream dict-reordering doesn't cause phantom cache misses.
2. ``GeminiCacheManager.get_or_create(...)`` accepts ``tools`` and
converts the OpenAI-style entries into Gemini ``Tool`` /
``FunctionDeclaration`` shapes inside ``CreateCachedContentConfig``.
The cached prefix now holds system_instruction + tools, so the
subsequent ``call_with_tools(cached_content_name=...)`` invocation
skips resending both.
3. ``GeminiLLM.call_with_tools(...)`` gains ``cached_content_name``.
When set, ``system_instruction`` and ``tools`` are dropped from the
per-request config (the SDK rejects re-sending them alongside
``cached_content``); ``tool_config`` (mode / allowed_function_names)
stays per-request as it must.
4. ``GeminiLLM.get_or_create_cached_prefix(...)`` accepts ``tools``
and forwards them to the cache manager.
5. ``reflect/agent.py:run_reflect_agent`` looks up (or creates) the
cached prefix ONCE per reflect — right after the ``system_prompt``
and ``tools`` are built — and reuses the returned cache name across
every iteration of the agentic loop. The lookup is wrapped in a
try/except so a cache-side failure can never block a reflect.
6. ``call_with_tools`` now extracts ``cached_content_token_count``
and ``thoughts_token_count`` from ``usage_metadata`` and threads them
through ``metrics.record_llm_call`` — same as ``call()`` already
does. Without this the new ``hindsight.llm.tokens.cached_input`` and
``hindsight.llm.tokens.thoughts`` counters would never report the
reflect-side share of cached/thinking tokens.
Tests (3 new on top of the 12 from earlier on this branch)
----------------------------------------------------------
- ``test_fingerprint_changes_with_tools``: adding a tool changes the
fingerprint so a loop that adds a tool gets a fresh cache.
- ``test_fingerprint_stable_under_dict_reordering``: dict-key order in
the OpenAI-style tools list does NOT change the fingerprint.
- ``test_get_or_create_passes_tools_to_create``: the ``caches.create``
call actually receives the tools in its config — without this the
cache would silently lack the tool definitions and the first
``call_with_tools(cached_content_name=...)`` would 400.
Verification
------------
- ``uv run pytest tests/test_gemini_cache.py tests/test_gemini_safety_settings.py``
→ 28/28 pass (15 cache + 13 safety; the safety-settings suite
doubles as regression on the ``call_with_tools`` signature change).
- ``uv run ruff check`` on changed files — clean.
Behavioural envelope
--------------------
- Flag still defaults False — no caller is opted in by default.
- When flag is True, both ``retain_extract_facts`` (from the earlier
commit on this branch) and ``reflect_tool_call`` opt in.
- A cache-side failure (transient SDK error, prefix too small, manager
uninstantiated) returns None and the caller proceeds uncached. There
is no path by which caching can break reflect or retain.
* fix(gemini): make explicit prompt caching actually work end-to-end
The caching paths could never produce a cache hit:
- CreateCachedContentConfig was given response_schema/response_mime_type,
which the google-genai SDK forbids (extra_forbidden) — so every cache
create raised and soft-fell-back to an uncached call. Cache only holds
system_instruction (+ tools); response_schema is a generation-time
constraint and stays on the per-request GenerateContentConfig.
- call() dropped response_schema when a cache was in use (assuming the
schema lived in the cache — impossible). Keep it on the request; only
system_instruction moves into the cache. Structured output is preserved.
- cached_content_name was plumbed into the leaf GeminiLLM.call /
call_with_tools but NOT through the LLMProvider wrapper, so the real call
path raised "unexpected keyword argument 'cached_content_name'". Thread it
through both wrappers, forwarding only when set (other providers untouched).
With these, retain extraction caches the ~1.7k-token prefix at ~90%.
* feat(gemini): cache consolidation prefix + gate reflect cache to auto turns
- Consolidation: split the batch prompt into a stable system instruction
(mission + rules + decision guide + output format) and a per-batch user
message (facts + existing observations + capacity note). The system prefix
is byte-identical across batches in a run, so it is cached and reused; the
variable data and the per-batch response_schema stay out of the cached
surface so it never busts. Measures ~30-40% cached/input per batch (the
remainder is irreducible per-batch data).
- Reflect: Gemini rejects cached_content alongside a per-request tool_config
("CachedContent can not be used with ... tool_config"). The forced-retrieval
iterations set tool_config, so only the `auto` iterations can reference the
cache. Gate cached_content_name on tool_choice == "auto"; forced iterations
send the prefix inline.
* test(gemini): per-operation cached-ratio test + consolidation split coverage
- New tests/test_gemini_implicit_cache_ratio.py: measures cached/input token
ratio per operation (retain, reflect, consolidation) against real Gemini via
the LLM-request tracer. Dual mode: default records the implicit-cache baseline
(~0% for this access pattern); HINDSIGHT_GEMINI_EXPLICIT_CACHE=1 asserts the
explicit cache engages (cached_tokens > 0, per-op ratio floor). Gated behind
HINDSIGHT_RUN_GEMINI_EVALS=1 + a Gemini key.
- test_consolidation.py: unit test for the system/user prompt split (cacheable
byte-stable prefix; data only in the user message). Fix the inline mock LLM
callbacks to read facts from the user message(s) rather than messages[0], now
that the stable instructions are a separate system message.
* perf(consolidation): move stable observation-format note into cached prefix
The "## INPUT FORMAT" boilerplate (the explanation of the observation JSON
shape: id/text/proof_count/occurred_*/source_memories) was re-sent in every
per-batch user message. It's stable, so move it into the cached system prefix
(build_consolidation_system_prompt); the per-batch user message now carries
only the variable facts + observations data. Lifts the cached/input ratio a
couple of points without changing what the model sees.
* feat(gemini): make cached prefix bank-agnostic (mission → user message)
The retain and consolidation system prompts embedded the per-bank mission, so
each distinct mission produced a different cache fingerprint → one CachedContent
per bank. With many banks/missions that multiplies create + storage cost and
cached-object count, and makes default-on uneconomical.
Move the mission out of the cached prefix into the per-request user message:
- retain: _build_extraction_prompt_and_schema now returns a bank-agnostic prompt;
the mission rides in the user message via _retain_mission_preamble().
- consolidation: build_consolidation_system_prompt drops the mission param; the
mission moves into build_consolidation_input (the user message).
Result: the cached prefix is identical across all banks, so a single shared
CachedContent serves every bank — cardinality drops from O(missions) to O(1) per
operation, and the cost-inversion for many-low-volume-bank workloads goes away.
Behavioral note: the mission now appears in the user turn rather than the system
prompt. Validate mission-adherence against the accuracy benchmarks before flipping
the global default on. Tests updated to assert the new location + cross-bank
prefix sharing.
* test(retain): assert different missions yield one shared cache prefix
Extend the mission-relocation test to prove the payoff directly: two banks with
different retain missions produce a byte-identical system prompt → the same cache
fingerprint → a single shared CachedContent instead of one per mission.
* test(retain): cacheable prefix invariant to per-bank free-text (concise/verbose)
Parametrized over the concise and verbose modes: the cached system prompt must be
byte-identical regardless of the retain mission (any value, incl. JSON/unicode/
long text) and custom instructions, so per-bank free-text can never fragment the
shared Gemini cache. Structural toggles (causal/labels/language) are intentionally
out of scope — they legitimately partition the cache via the fingerprint.
* refactor(llm): make prompt-prefix caching a provider-interface feature
Hoist caching out of Gemini-specific duck-typing into the LLMInterface contract,
mirroring supports_batch_api():
- LLMInterface.supports_prompt_caching() -> bool (default False) and
get_or_create_cached_prefix(...) -> str | None (default None), with docs on how
explicit-cache (Gemini handle), automatic-cache (OpenAI), and inline-marker
(Anthropic cache_control) providers each map onto the hook.
- call()/call_with_tools() gain a provider-neutral cached_prefix handle (renamed
from the Gemini-flavoured cached_content_name); the wrapper forwards it only
when set so non-caching providers' signatures are untouched.
- GeminiLLM implements supports_prompt_caching(); the retain/consolidation/reflect
call sites gate on it instead of hasattr().
The engine already decides WHAT is cacheable (bank-agnostic system prefix), so a
new provider only implements HOW — e.g. OpenAI can benefit with no code (stable
leading prefix is auto-cached) or a thin override.
* docs(models): add per-provider capability table (batch API, prompt caching)
Adds a "Provider Capabilities" table to the LLM section of the models page
showing which providers support the Batch API (OpenAI/Groq/Fireworks) and
explicit prompt-prefix caching (Gemini/Vertex via CachedContent), with notes on
OpenAI's automatic prefix caching and the bank-agnostic shared-cache design.
Includes the regenerated skills/hindsight-docs mirror.
* docs(models): drive provider capability table from llmProviders.json
Replace the hand-written capability table with a data-driven one so adding a
provider stays a single-file edit. The capability flags (batchApi, promptCaching)
live in llmProviders.json — the existing single source of truth for the provider
grid and default-models table — and a new LLMProviderCapabilities component (plus
a matching renderer in generate-docs-skill.sh) renders them. Tool-calling dropped
(not differentiating here). Keep flags aligned with supports_batch_api() /
supports_prompt_caching() on the provider classes.
* feat(llm): generic, default-on prompt caching knob
Rename the Gemini-specific opt-in flag to a provider-agnostic, default-on knob,
modelled on HINDSIGHT_API_RETAIN_BATCH_ENABLED:
- HINDSIGHT_API_LLM_GEMINI_PROMPT_CACHE_ENABLED → HINDSIGHT_API_LLM_PROMPT_CACHE_ENABLED
(config field llm_gemini_prompt_cache_enabled → llm_prompt_cache_enabled, kwarg
gemini_prompt_cache_enabled → prompt_cache_enabled), single global knob (not per-op).
- DEFAULT_LLM_PROMPT_CACHE_ENABLED = True. Safe to default on: the cached prefix is
bank-agnostic (one shared cache) and creation soft-fails to an uncached call, so
it never breaks a request. Providers that don't implement caching ignore the flag.
- Resolve the flag for every provider (drop the gemini/vertexai restriction) so any
future provider that implements supports_prompt_caching() picks it up.
Docs: models page now says "on by default; disable with
HINDSIGHT_API_LLM_PROMPT_CACHE_ENABLED=false". The per-operation ratio test sets the
flag explicitly in both modes since the default is now on. Includes the regenerated
skills/hindsight-docs mirror.
* fix(gemini): fall back to uncached on a cached-request 400
A 400 from a generate request that references a CachedContent (expired/deleted
cache, cross-project mismatch, cache+tool_config incompatibility, ...) was treated
as a generic retryable error: the same cached request was retried, 400'd again,
and the whole operation failed. The soft-fallback only covered cache *creation*,
not the call that *uses* the cache.
Now, on the first 400 while a cache is in use, call()/call_with_tools():
- drop the cache and rebuild the request inline (re-send system prefix + schema/
tools) so the request still succeeds,
- invalidate the dead cache name (GeminiCacheManager.invalidate) so the next
operation recreates it instead of reusing the bad name,
- retry immediately (no backoff — it's a config switch, not a transient error).
If the uncached retry also 400s it's a genuine bad request and errors normally.
Supporting fix: system_instruction is now ALWAYS captured from the messages (it
was skipped when cached), so the fallback has the prefix to inline; the config
builder still omits it from the request while the cache carries it. New unit test
covers the 400 → uncached-retry → invalidate path. Cached success path unchanged
(real Gemini retain still 90.8%).
* fix(gemini): bound the cache-create call with a timeout
get_or_create holds the manager lock across the caches.create network call, which
correctly dedups concurrent callers (a 10-chunk retain batch produces exactly one
create, not ten). But with no timeout, a hung create would block every waiting
chunk indefinitely. Wrap the create in asyncio.wait_for (30s default, configurable
via create_timeout_seconds); on timeout it soft-fails to None and callers proceed
uncached instead of stalling the batch. Unit test covers the timeout path.
* style: ruff-format the prompt-cache config line (fixes verify-generated-files)
* test: fix consolidation-scope-parallelism mock + metrics counter count
- test_consolidation_scope_parallelism.py: the inline mock read facts from
messages[0], which is now the (cached) system message after the consolidation
prompt split — read the user message(s) instead.
- test_metrics.py: mock_meter provided 5 counter mocks but MetricsCollector now
creates 7 (the cached_input + thoughts counters), so create_counter.side_effect
ran out (StopIteration at setup). Bump both fixtures to 7.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
2026-06-04 14:11:49 +02:00
1766 changed files with 172127 additions and 30801 deletions
If any files in `hindsight-integrations/` were added or changed, verify:
- **Tests exist** — the integration must have tests that simulate/exercise the external framework (not just pure unit tests of helpers). Check for a `tests/` directory with meaningful test files.
- **CI job exists** — check `.github/workflows/test.yml` for a corresponding `test-<name>-integration` job. If missing, flag it.
- **Release process** — check that the integration name is in the `VALID_INTEGRATIONS` array in `scripts/release-integration.sh`. If missing, flag it.
- **Release process** — check that the integration name is in the `VALID_INTEGRATIONS` array in `scripts/release-integration.sh` AND in the `INTEGRATIONS` dict in `hindsight-dev/hindsight_dev/generate_changelog.py` (the changelog generator keeps its own list; a release fails at the changelog step if the name is missing there). If either is missing, flag it.
- **Docs gallery + sidebar entry** — the integration must have an entry in `hindsight-docs/src/data/integrations.json`. This file is the **single source of truth** that drives both the integrations gallery and the docs sidebar (the sidebar category is injected from it at render time across all docs versions). The entry needs an internal `/sdks/integrations/<slug>``link` and a matching page at `hindsight-docs/docs-integrations/<slug>.md(x)`. The `hindsight-docs/scripts/check-integrations.mjs` build step enforces both directions — forward: every internal JSON entry has a doc page; reverse: every released tag (`integrations/<name>/vX.Y.Z`) appears in the JSON (private infra like `cloudflare-oauth-proxy` is in the script's `EXCLUDED` set). Flag any integration that is released (or being released) but missing from `integrations.json`, and any JSON entry without a doc page. Do **not** hand-edit `versioned_sidebars/*.json` to add integration links — they are positional placeholders filled from the JSON.
- **Code standards** — the integration code must follow all Python style rules (type hints, no raw dicts, no tuple returns, etc.).
### 10. Check MCP tool registration completeness
@@ -191,6 +192,18 @@ If a migration adds a new PostgreSQL table (look for `CREATE TABLE` / `op.create
- The guard test `test_backup_tables_covers_entire_schema` in `tests/test_admin_backup_restore.py` enforces this — flag it as a **must fix** if a new table is absent from `BACKUP_TABLES`.
- Oracle-only tables (e.g. `observation_sources`) are intentionally excluded — admin backup/restore is PostgreSQL-only.
### 11b. Check new config flags update the env template
If the diff adds a new configuration field (a new `ENV_*` / `HINDSIGHT_*` env var
in `hindsight-api-slim/hindsight_api/config.py`):
- **`.env.example`** (repo root) — must add the variable (commented if optional)
alongside the docs entry in `hindsight-docs/docs/developer/configuration.md`.
A flag added to `config.py` but absent from `.env.example` is a **should fix**.
- **`hindsight-embed/hindsight_embed/env.example`** — the bundled copy must stay
byte-identical to the repo-root `.env.example` (it seeds embed/profile configs).
The `test_bundled_template_matches_repo_root` sync test fails on drift; if the
root file changed without re-copying, flag it as a **must fix**.
### 12. Review against other coding standards
Check the diff for violations of the standards listed above:
@@ -217,6 +230,7 @@ Present a clear summary organized by severity:
- Direct DB access (raw SQL / `acquire_with_retry` / `fq_table`) in an `api/` handler instead of a `MemoryEngine` method
- Tenant-scoped data accessed without authentication enforced in the engine (`_authenticate_tenant` / `get_bank_profile`)
- New integration missing tests, CI job, or release-integration.sh entry
- Released/added integration missing from `hindsight-docs/src/data/integrations.json`, or a JSON entry with no `docs-integrations/<slug>` page (fails the docs build via `check-integrations.mjs`)
- New PostgreSQL table missing from `BACKUP_TABLES` in `admin/cli.py` (silent data loss on restore)
description:Cut a core Hindsight release (vX.Y.Z) and open the changelog + blog PR. Use when asked to cut/start a release, bump the version, or publish a new Hindsight version.
user_invocable:true
---
# Hindsight Release
Cut a **core** Hindsight release and open the accompanying changelog/blog PR. This is for the core
product version (API, clients, CLI, control plane, Helm). **Integrations are versioned
independently** — use `scripts/release-integration.sh` for those, not this skill.
The release is **irreversible and outward-facing**: it tags a version and pushes it straight to
`main`, which triggers CI that publishes packages to PyPI / npm / Helm. Confirm the version number
and that the intended fixes are already merged to `main` before you start.
## Step 0 — Pre-flight
1.**Decide the base.** A release is cut from the latest `origin/main`, never from a feature
branch. `git fetch origin --tags` first. Confirm the "couple of fixes" the user means are
actually merged to `main` (`git log v<prev>..origin/main --oneline`).
2.**Find where `main` is checked out.**`main` is often already checked out in a sibling worktree
(`git worktree list`). You **cannot** check out `main` in a second worktree — run the release in
the worktree that already holds it. If that worktree is dirty with throwaway cruft
# Optional retain chunking override for structured logs/transcripts.
# Unset uses HINDSIGHT_API_RETAIN_CHUNK_SIZE as the structured-chunk limit.
# HINDSIGHT_API_RETAIN_STRUCTURED_CHUNK_SIZE=
# Dry-run extraction preview endpoint (POST /memories/dry-run-extract). Enabled by default; it makes
# a real LLM call but stores nothing. Set to false to remove the endpoint (returns 404).
# HINDSIGHT_API_ENABLE_DRY_RUN_EXTRACT=true
# Base Path / Reverse Proxy Support (Optional)
# Set these when deploying behind a reverse proxy with path-based routing
@@ -59,6 +95,7 @@ HINDSIGHT_API_LOG_LEVEL=info
# HINDSIGHT_API_READ_DATABASE_URL= # Optional read-replica URL. When set, recall queries (semantic, BM25, graph, temporal) flow through a separate pool against this URL, offloading the primary. Typically points to a read-only endpoint (CNPG's <cluster>-ro service or Aurora reader endpoint).
# HINDSIGHT_API_MIGRATION_DATABASE_URL= # Direct PostgreSQL URL for migrations (bypasses PgBouncer). Falls back to DATABASE_URL.
# HINDSIGHT_API_DATABASE_SCHEMA=public # PostgreSQL schema name (default: public)
# HINDSIGHT_API_MIGRATION_CONCURRENCY=1 # Tenant schemas to migrate concurrently (PG only, each in its own process; per-schema work stays sequential). Each worker has ~1-2s startup cost + uses ~3 DB connections, so it only pays off with many schemas (tens+) or slow migrations; keep concurrency*3 <= spare max_connections. Default: 1 (sequential).
# Vector Extension (Optional - uses pgvector by default)
NOTES="Hindsight for Obsidian v${VERSION}. Install via BRAT (add ${DIST_REPO}) or copy main.js/manifest.json/styles.css into <vault>/.obsidian/plugins/hindsight/."
if gh release view "$VERSION" --repo "$DIST_REPO" >/dev/null 2>&1; then
(the shadcn/ui surface is kept on purpose) — surfaced, not gated.
Run both locally with:
```bash
./scripts/hooks/check-unused.sh
```
**After completing any implementation work, run `/code-review`** to verify your changes against project standards (missing tests, dead code, type safety, etc.). Fix any "must fix" issues before considering the task done.
**MANDATORY: Run `/code-review` before pushing code or creating a pull request.** Do not push or create a PR until all "must fix" issues are resolved.
@@ -315,7 +327,10 @@ Fields must be categorized as either **hierarchical** (can be overridden per-ten
You can modify the LLM provider by setting `HINDSIGHT_API_LLM_PROVIDER`. Valid options are `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio`, and`minimax`. The documentation provides more details on [supported models](https://hindsight.vectorize.io/developer/models).
You can modify the LLM provider by setting `HINDSIGHT_API_LLM_PROVIDER`. Valid options are `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `lmstudio`, `minimax`, and `atlas` ([Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=hindsight)). The documentation provides more details on [supported models](https://hindsight.vectorize.io/developer/models).
@@ -143,6 +142,8 @@ main();
pip install hindsight-all -U
```
On Intel (x86_64) Macs, install `hindsight-all-slim` instead — see [Supported Platforms](#supported-platforms).
@@ -300,6 +301,19 @@ client.reflect(bank_id="my-bank", query="What should I know about Alice?")
[](https://www.star-history.com/#vectorize-io/hindsight&type=date&legend=top-left)
---
## Supported Platforms
| Platform | Docker | Bare Metal (pip) | Embedded DB (pg0) |
⚠️ Intel Macs: use `hindsight-all-slim` — see the [installation guide](https://hindsight.vectorize.io/developer/installation#supported-platforms) for details.
"description":"Node.js programmatic lifecycle manager for Hindsight — embeds a local hindsight daemon in a Node application. Pair with @vectorize-io/hindsight-client for memory operations.",
9. KEEP DISTINCT TOPICS DISTINCT: do not merge observations about different people, entities, or unrelated topics. Merging is for the same canonical fact recurring — not for related-but-distinct claims."""
# Stable description of the input shape. For the cached split path this lives in
# the system prefix (build_consolidation_system_prompt) so it is not re-sent on
# every batch; the per-batch user message then carries only the actual data.
_INPUT_FORMAT_NOTE="""## INPUT FORMAT
Each request provides new facts and existing observations:
- New facts: one per line, each prefixed with its `[uuid]`, followed by the fact text and optional temporal fields.
- Existing observations: a JSON array pooled from recalls across the new facts. Each entry has:
- `id`: unique identifier — copy this exactly when issuing an UPDATE or DELETE
- `text`: the observation content
- `proof_count`: number of supporting memories
- `occurred_start` / `occurred_end`: temporal range of source facts
- `source_memories`: array of supporting facts with their text and dates"""
# Per-batch data section for the cached split path — the stable format
# explanation above is omitted here (it lives in the cached prefix); only the
# variable facts/observations remain. Placeholders substituted at call time.
_SPLIT_INPUT_SECTION="""## INPUT
### New facts
{facts_text}
### Existing observations
{observations_text}"""
# Data section — format placeholders {facts_text} and {observations_text} are substituted at call time
@@ -604,16 +604,44 @@ Just provide the direct answer with proper markdown formatting.
CRITICAL:ThisisaNON-CONVERSATIONALsystem.NEVERaskfollow-upquestions,offertosearchagain,suggestalternatives,orendwithanythinglike"Would you like me to..."or"Let me know if...".Theusercannotreply.Youranswermustbecompleteandself-contained."""
@@ -192,7 +193,7 @@ class ExtractedFact(BaseModel):
occurred_start:str|None=Field(default=None,description="ISO timestamp for events")
occurred_end:str|None=Field(default=None,description="ISO timestamp for event end")
fact_type:Literal["world","assistant"]=Field(
description="'world' = objective/external facts. 'assistant' = first-person actions, experiences, or observations by the speaker."
description="'world' = objective/external facts, including user preferences, rules, corrections, and constraints even when stated during a conversation. 'assistant' = actions, experiences, or observations the assistant/agent actually performed."
@@ -295,7 +296,7 @@ class ExtractedFactVerbose(BaseModel):
)
fact_type:Literal["world","assistant"]=Field(
description="'world' = objective/external facts about other people, events, general knowledge. 'assistant' = first-person actions, experiences, or observations by the speaker (e.g., 'I changed X', 'I discovered Y')."
description="'world' = objective/external facts about the user, other people, events, general knowledge, preferences, rules, corrections, or constraints. 'assistant' = actions, experiences, or observations the assistant/agent actually performed (e.g., 'I changed X', 'I discovered Y')."
)
entities:list[Entity]|None=Field(
@@ -345,7 +346,7 @@ class ExtractedFactNoCausal(BaseModel):
occurred_start:str|None=Field(default=None,description="WHEN the event happened (ISO timestamp).")
occurred_end:str|None=Field(default=None,description="WHEN the event ended (ISO timestamp).")
fact_type:Literal["world","assistant"]=Field(
description="'world' = about the user/others. 'assistant' = experience with assistant."
description="'world' = about the user/others, including user preferences, rules, corrections, and constraints. 'assistant' = actions or experiences the assistant/agent actually performed."
)
entities:list[Entity]|None=Field(
default=None,
@@ -405,64 +406,110 @@ class VerbatimFactExtractionResponse(BaseModel):
facts:list[VerbatimExtractedFact]=Field(description="List of metadata entries (one per chunk)")
-"world":Objective/externalfacts,includingtheuser's preferences, rules, corrections, constraints, plans, traits, or context. These stay "world" even when the user states them during an assistant interaction (e.g., "User prefers browser_navigate over web_search", "User corrected the project deadline").
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Nicolò Boschi