Lead README/docs/guide Quick Start with Cloud, demote self-hosted to
its own section. Updates configure() global example to Cloud default.
Includes 2-line incidental skills/hindsight-docs/ regen drift.
The openai-codex provider was a startup-only credential loader: it read
~/.codex/auth.json once at __init__ and used the cached access_token
forever. ChatGPT OAuth tokens are short-lived (hours), so any
long-running deployment 401d on every request once the cached token
expired. The only recovery was an external cron + container restart.
This change makes the provider refresh tokens itself, mirroring the
canonical @openai/codex CLI (codex-rs/login/src/auth/manager.rs):
- Loads tokens.refresh_token from auth.json (previously discarded).
- Proactive refresh: decodes the access_token JWT's exp claim and
refreshes ~60s before expiry. Cheap when the token is fresh.
- Reactive refresh: on a 401/403 from the codex backend, refreshes
once and retries the request without consuming a normal-retry budget
slot.
- Single-flight: serializes through asyncio.Lock so concurrent callers
produce one network refresh, not N. Re-checks under the lock by
comparing the cached token before/after wait to handle the case
where another coroutine rotated mid-wait.
- Atomic persistence: writes auth.json via tempfile + os.replace with
mode 0600. The upstream Rust CLI uses truncate-and-overwrite, which
a concurrent reader can catch mid-write; tempfile+rename is strictly
safer.
- Terminal error handling: refresh_token_expired/reused/invalidated
(and any 401 from the refresh endpoint) raise CodexRefreshExpiredError
with a clear "run codex auth login" remediation, and do not loop.
- No secrets in logs: refresh logs the reason and outcome but not the
token values themselves.
OAuth request shape (POST https://auth.openai.com/oauth/token, JSON
body with hardcoded client_id app_EMoamEEZ73f0CkXaXp7hrann,
grant_type=refresh_token) matches the upstream Rust CLI exactly. The
endpoint is overridable via the CODEX_REFRESH_TOKEN_URL_OVERRIDE env
var the same way the upstream CLI supports it.
Tests: 23 new in test_codex_oauth_refresh.py covering JWT exp decode,
staleness with skew, refresh_token loading, atomic persistence with
0600 mode, request shape, in-memory + on-disk update, refresh_token
rotation, terminal-error classification, network error wrapping,
no-secrets-in-logs, single-flight under 10 concurrent callers,
proactive refresh before request, reactive 401-then-retry, and the
no-refresh-when-fresh case. Existing test_codex_tool_choice.py still
passes.
Caveat: all tests are mocked. The OAuth request shape has not been
verified against the real auth.openai.com endpoint - it is grounded
in the upstream codex-rs source on github.com/openai/codex.
Reviewers with a ChatGPT Plus subscription should validate the
end-to-end path before merge.
* docs: add HINDSIGHT_API_WORKER_ID tip to API quickstart
Mirrors the tip already present in installation.md so users who follow
the API quickstart's Docker tab see the same guidance about pinning a
stable worker ID. Closes#1616.
* docs: mirror WORKER_ID tip to versioned_docs v0.6 (from #1648)
Folding in xmh1011's strict-improvement hunk from #1648: the
versioned snapshot for v0.6 should carry the same production tip
as the live doc. Same prose, same `:::tip` block. Includes the
auto-regenerated skills/ reference.
Replaces the auto-generated entry, which credited #1123 (a core-engine
consolidation config, not openai-agents-specific) to the v0.1.1 release.
The actual openai-agents-specific work in v0.1.1 was #1134 by @DK09876:
docs/test polish — corrected SDK version requirement, added
memory_instructions() to README and API reference, added Production
Patterns section, and added test_config.py.
Documents the security/maintenance release: dependency CVE bumps,
mental_models.subtype migration repair, embedding-dimension OID
handling, and integration fixes for Claude Code, Agent SDK, CLI,
and Paperclip.
Set UV_FROZEN=1 as a job-level env var so all uv commands (sync, run,
lock) respect the committed lockfile without re-resolving. This is the
idiomatic uv approach for CI and prevents spurious uv.lock diffs that
blocked every Dependabot PR.
Reverts the lint.sh CI-specific --frozen logic from #1618 since the
env var covers it globally.
Three production deployments (issue #1553, plus confirmations from
@4Lienau and @khanhduyvt0101) report `column "subtype" of relation
"mental_models" does not exist` on `create_mental_model`, despite their
alembic_version showing the current head `m3rg3h3ad5f6`.
Both h3c4d5e6f7g8_mental_models_v4 (which uses `CREATE TABLE IF NOT EXISTS`
and is a no-op on databases that came through the reflections rename) and
d5y6z7a8b9c0_backfill_mental_models_subtype were meant to ensure the
column exists, but on these specific deployments neither fired
successfully — likely a casualty of the divergent-heads reorganization
that put d5y6z7a8b9c0 on a branch the affected DBs bypassed.
Add a new migration at the current head so every stuck deployment picks
it up on next container start. Idempotent (`ADD COLUMN IF NOT EXISTS`),
guarded by an existence check on the table, and matches the canonical v4
column set and CHECK allowlist from d5y6z7a8b9c0.
PG-only: Oracle's baseline creates mental_models with a different
topology and constraint shape, so this repair does not apply there.
* fix(cli, control-plane): make Event Date / timestamp actually reach the API
- CLI `hindsight memory retain` now accepts `-t/--timestamp <ISO>`. The
internal MemoryItem.timestamp was hardcoded to None, so retains from the
CLI lost any caller-supplied event date even though the Python/Node/Go
SDKs accept one. Add a flag and pass it through; regression test asserts
--help advertises the option.
- Control plane "Event Date" inputs in the new-document and per-file flows
used `<input type="datetime-local">`, which only commits a value when the
user enters both date AND time. Typing a date alone silently left the
value empty, so `item.timestamp` was never sent and the resulting
operation payload had no event_date. Switch to `type="date"` and pad
with `T00:00:00` before sending, so date-only entries reach the API as
valid ISO datetimes.
* fix(cli): decode --timestamp into MemoryItemTimestamp enum
MemoryItem.timestamp is generated as Option<MemoryItemTimestamp>
(progenitor's anyOf wrapper), not Option<String>. Round-trip the
flag value through serde_json so the right variant is selected for
both ISO datetimes and the 'unset' sentinel. Fixes CI build break.
The `by` field was set to `omarouldali`, which is not a real GitHub user
(github.com/omarouldali returns 404). As a result the avatar request to
`github.com/omarouldali.png?size=40` failed and the integrations hub card
showed a broken-image placeholder next to the author name. The actual
GitHub handle of the contributor (author of PRs #961 and #1254) is
`ooa-andera`, which resolves cleanly.
lint.sh runs `uv sync` without --frozen at the repo root, which
re-resolves uv.lock. In CI's verify-generated-files job this causes
spurious 1-line diffs on every Dependabot PR, blocking them from
merging.
Use --frozen when $CI is set so the lockfile is never modified by
the lint step. Local development keeps the non-frozen sync to handle
version bumps gracefully.
The DO $$ block that drops vector indexes iterates pg_indexes via a
cursor. When concurrent pytest-xdist workers drop schemas (CASCADE),
the OID references in the cursor become stale, causing
'could not open relation with OID' errors.
Fix the root cause in migrations.py by adding EXCEPTION WHEN
internal_error handling to the PL/pgSQL DO block. Also add
defense-in-depth retry logic to the two test cases that previously
called ensure_embedding_dimension() without the retry wrapper.
* fix(agent-sdk): agent_knowledge_get_page request detail=content (sister of #1543)
* fix(agent-sdk): flatten throw to single line for prettier (printWidth 100)
Adds requestTimeoutSeconds (env: HINDSIGHT_REQUEST_TIMEOUT_SECONDS) to
the claude-code plugin config. When set, overrides the hardcoded per-call
HTTP timeouts (10s recall, 15s retain, 10-15s in knowledge MCP tools).
When unset (default), per-call defaults are preserved — fully backward
compatible.
The health check timeout (5s) is intentionally left alone, since bumping
it would degrade UX when the server is genuinely unreachable.
Fixes#1575
Fixes 4 remaining Dependabot alerts (1 critical, 3 high) for litellm
vulnerabilities including GHSA-pq44-5pcq-4r5g and GHSA-8cjq-wjmh-q42r
that were missed in the #1609 squash merge.
- paperclip: commit trailing whitespace and line-length fixes that the
lint hook produces, fixing verify-generated-files on every PR
- openclaw: update agent_end hook tests to expect the system-role
context message prepended by includeSenderContext (default: true)
* fix(paperclip): align with Paperclip's actual event payloads
The plugin's `agent.run.started` and `agent.run.finished` handlers
destructured fields (`issueTitle`, `issueDescription`, `output`, `result`)
that Paperclip's host does not publish. Paperclip emits a thin lifecycle
payload — `{runId, agentId, status, invocationSource, triggerDetail,
error, errorCode, issueId, startedAt, finishedAt}` — so both handlers
silently early-returned and the plugin never recalled or retained
anything despite registering successfully.
Changes:
- `agent.run.started` now uses `payload.issueId` to look up the issue
via `ctx.issues.get` and builds the recall query from the issue's
title + description.
- New `issue.comment.created` subscription replaces the
`agent.run.finished` retain path. Comments are the durable record of
agent + user output and the existing payload only carries a 120-char
snippet, so we fetch the full body via `ctx.issues.listComments`.
Bank attribution falls back to the issue's assignee when a comment
has no agent author (e.g. user comments).
- `agent.run.finished` is kept as a debug no-op so the subscription
stays visible and can be reused if Paperclip ever embeds output in
the lifecycle payload.
- Manifest gains `issues.read` and `issue.comments.read` capabilities,
required by the new SDK calls.
- Tests updated to seed issues/comments via the harness, exercise the
new comment-created path, and cover the assignee-fallback for
unauthored comments.
Verified end-to-end against a local Paperclip + self-hosted Hindsight:
the patched plugin retains real comment bodies to the correct bank
and Hindsight's recall API returns them on subsequent queries.
Related: vectorize-io/hindsight tracking issue (Paperclip ODIAA-84).
* Log skip retain due to missing agent attribution
Add logging for skipping retain when no agent attribution is available.
* Add test for skipping retain with no agent and assignee
Replaces the Hindsight Cloud preview section with a pill-strip filter
(All / Hindsight Cloud / Deep Dives / Announcements & Releases /
Tutorials & Integrations) that filters the chronological grid by
canonical category tag via a ?cat=<slug> URL param.
Backfills the canonical category tag (release / tutorial / deep-dive)
onto the 49 existing posts that needed one. The hindsight-cloud tag is
already in use and stays unchanged.
Extends BlogTagsPostsPage with friendly titles for the new category
tags so /blog/tags/{release,tutorial,deep-dive} render like the
existing /blog/tags/hindsight-cloud page.
No existing post permalinks or tag-archive URLs change.
The MCP tool exposed `max_results: int = 10` but piped that value
straight into the server's `max_tokens` budget. The server has no
`max_results` concept — recall returns whatever fits in the token
budget — so 10 tokens truncated every recall to an empty result set,
making the tool look like a connection failure even though the bank
contained thousands of nodes.
Rename the parameter to match server semantics and bump the default
to 1024 (same as `client.recall`'s default), so callers can request
deeper recalls by raising the budget honestly.
Two related changes addressing the same class of issue PR #1528 fixed
for list_pages — but on the get_page surface and on the agent prompt.
1. agent_knowledge_get_page now requests detail=content instead of
detail=full. Measured on real banks, reflect_response is 70-95% of
the response bytes; the actual `content` field is 1-2%. At realistic
page sizes (200-280 KB at full) the response overflows the MCP host's
per-tool-result token cap and spills to disk where the agent cannot
consume it inline. Switching to detail=content drops every page to
~5 KB. Sample measurements:
page total content reflect_response
Pre-push gate 276 KB 2.8 KB 201 KB
Local test stack 282 KB 4.0 KB 205 KB
CI failure triage 266 KB 2.8 KB 194 KB
The docstring promises "full synthesized content" — exactly what the
`content` projection returns.
2. The create-agent SKILL template now tells the agent how to recover
when get_page does spill (rare after this fix, but possible on
genuinely large pages): Read the spill file, parse the JSON wrapper,
or fall back to agent_knowledge_recall.
Adds a focused regression test pinning the content projection.
* blog: add "How Hindsight Scales" technical deep dive
Covers performance, quality, and cost scaling across all 4 core
operations: retain, recall, consolidation, and reflect.
* blog: finalize "How Hindsight Scales" post + blog styling
Architecture-focused scaling analysis covering retain, recall,
consolidation, reflect, and mental models. Fact-checked against
codebase. Also switches blog body font to Space Grotesk and adds
colored underline treatment for bold text.
* feat(api): add litellmrouter provider for LLM fallback chains
Closes#1464.
New "litellmrouter" provider wraps LiteLLM Router with ordered fallback
across a configurable chain of deployments. On transient errors
(rate-limit, timeout, 5xx) the Router falls back to the next deployment
in declared order; auth errors (401/403) are not retried so a
misconfigured key cannot silently cascade through the chain.
Configuration is provider-scoped (one-word LITELLMROUTER namespace to
avoid clashing with the existing LITELLM_* settings used by the
embeddings/reranker layers):
HINDSIGHT_API_LLM_PROVIDER=litellmrouter
HINDSIGHT_API_LLM_LITELLMROUTER_CHAIN=<json list of deployments>
Per-operation chains are supported via the same pattern that already
exists for retain/reflect/consolidation:
HINDSIGHT_API_RETAIN_LLM_LITELLMROUTER_CHAIN=...
HINDSIGHT_API_REFLECT_LLM_LITELLMROUTER_CHAIN=...
HINDSIGHT_API_CONSOLIDATION_LLM_LITELLMROUTER_CHAIN=...
Each per-op chain falls back to the default chain when unset, mirroring
the existing per-op provider/model overrides.
Chain entries are tagged as credential fields and are never exposed via
the bank-config API. Batch APIs are intentionally unsupported in router
mode; users that need batch retain should configure a single provider.
* refactor(api): dedup litellmrouter on top of LiteLLMLLM, accept arbitrary chain keys, add CI matrix entry
The retry/parse/metrics loop in LiteLLMRouterLLM was a near-verbatim copy of
LiteLLMLLM. Extract three small hooks on the base class
(_acompletion, _resolve_completion_model, _stage_label) and have the Router
provider inherit + override only what differs.
Drop strict validation of chain entries. The parser now requires only
'provider' and 'model'; everything else passes through to LiteLLM Router
unchanged. Top-level keys (rpm, tpm, weight, model_info, ...) flow to the
deployment record; an optional 'litellm_params' sub-object merges into the
inner params dict. Documented and tested.
Add a litellmrouter row to the LLM acceptance matrix using a single OpenAI
deployment in the chain. The chain JSON is built from secrets in a
dedicated step and masked in logs before being written to GITHUB_ENV.
* refactor(api): pure pass-through to litellm.Router, drop translation layer
Replace the chain-with-Hindsight-shape API with a thin pass-through to
litellm.Router. The HINDSIGHT_API_LLM_LITELLMROUTER_CONFIG env var is now
a JSON object forwarded verbatim to Router(**config). Hindsight's only
imposed rules: model_list is non-empty, each entry has a model_name, and
requests route against the first entry's model_name.
This removes _LITELLM_PROVIDER_PREFIX (provider→prefix translation),
_build_model_list (flat→nested rewrite), and _build_fallbacks (auto-wired
ordered fallback). Users now write LiteLLM-native configs and pick their
own routing strategy — ordered fallback via 'fallbacks', load-balancing
via shared model_name + 'routing_strategy', rate-limit awareness via rpm/
tpm, and so on. The docs link to LiteLLM's reference rather than
recapitulating it.
Renames:
ENV_LLM_LITELLMROUTER_CHAIN -> ENV_LLM_LITELLMROUTER_CONFIG
llm_litellmrouter_chain -> llm_litellmrouter_config
_parse_llm_router_chain -> _parse_llm_router_config
LLMProvider(litellmrouter_chain=) -> LLMProvider(litellmrouter_config=)
The dataclass fields change shape from list[dict] to dict (JSON object).
Net reduction across the touched files: ~165 lines.
* docs: regenerate hindsight-docs skill from updated configuration.md
* refactor(api): drop all shape validation on litellmrouter config, use fixed 'default' entrypoint
The previous version still inspected the user's config in two places:
the parser checked model_list/model_name shape, and __init__ pulled
primary_model_name out of model_list[0]. Both are gone.
The parser now only verifies the env var is parseable JSON. Whatever the
user supplies — dict, list, missing keys, weird shapes — flows through.
LiteLLM Router is authoritative about the shape and raises its own
errors at construction time if something's wrong.
The provider no longer extracts a 'primary' name from the input. Instead
it always issues completions against model_name='default' — the single
Hindsight-imposed convention. Users put one entry with that name in
their model_list as the entrypoint and use any names they want for
fallback/load-balance/weighted-pool members. This avoids both pre-
validation footguns and any dependence on Router's internal API
(model_names, model_list attributes) that could shift between versions.
Docs and tests updated to match. The CI matrix already used 'default'.
* docs: regenerate hindsight-docs skill
* ci(test): cap retain max_completion_tokens for litellmrouter matrix row
gpt-4.1-nano caps OpenAI completion at 32768 tokens, but Hindsight's
default DEFAULT_RETAIN_MAX_COMPLETION_TOKENS is 64000. The 'openai'
matrix row passes because OpenAICompatibleLLM has model-specific token
capping; LiteLLMLLM (and the new LiteLLMRouterLLM by inheritance) don't.
That's a pre-existing limitation orthogonal to this PR — the cap-aware
behaviour lives in OpenAICompatibleLLM and intentionally doesn't apply
to LiteLLM-routed calls.
Lower retain max_completion_tokens via env in the litellmrouter job so
CI exercises the Router path end-to-end instead of dying on a
provider-side BadRequestError that's not the thing we're testing.
* fix(api): cap LiteLLM-routed max_completion_tokens to model registry limit
Hindsight defaults retain_max_completion_tokens to 64000 — fine for
high-capacity models, but breaks against models with smaller caps
(gpt-4.1-nano: 32768; gpt-4o-mini: 16384). OpenAICompatibleLLM already
caps via a hardcoded string-match table; LiteLLMLLM and the new Router
provider didn't, so a default Hindsight install pointed at a small
model would fail with provider BadRequestError.
Cap pre-emptively using LiteLLM's own per-model registry
(litellm.get_max_tokens). For LiteLLMLLM the cap is self.model. For
LiteLLMRouterLLM the cap is the min across all configured deployments,
computed once at __init__ — this way a single max_completion_tokens
value works no matter which deployment Router picks (primary,
fallback, weighted-pool member). Unknown models contribute no cap.
Reverts the temporary CI workaround that lowered HINDSIGHT_API_RETAIN_
MAX_COMPLETION_TOKENS=32000 for the litellmrouter row — Hindsight
should work out of the box.
* docs: shorten litellmrouter config section, add models.mdx pointer
Move the discoverability pointer into models.mdx alongside the existing
LiteLLM tip, where users browsing for model options will find it. Strip
the configuration page entry to its essentials: env-var table, one
ordered-fallback example, and the three short caveats. Defer routing
details to LiteLLM's docs rather than recapitulating them.
The hardcoded `CLIENT_VERSION = "0.5.1"` in src/index.ts has fallen
behind npm releases through 0.5.6 / 0.5.7 / 0.6.0 — every published
release since 0.5.1 ships a stale constant, mis-attributing User-Agent
in server-side telemetry and foreclosing client-side feature gating.
Substitute `__CLIENT_VERSION__` with `pkg.version` via tsup's `define`
at build time. Source has no JSON import, so the fix is uniform across
runtimes (Node CJS/ESM, Deno via npm:, Deno via raw src) — unlike a
direct `import pkg from "../package.json"`, which Deno rejects without
`with { type: "json" }`, and which would in turn cascade into tsconfig
+ ts-jest reconfiguration (see #1535 for that path).
A `typeof` guard with a `0.0.0-dev` sentinel keeps raw-source loads
(jest, `npm run test:deno`) from throwing ReferenceError when the
build-time substitution hasn't run.
Verified locally: build, jest 6/6, Node CJS/ESM, Deno (dist), Deno
(raw src) all report the substituted version (or the dev sentinel
where appropriate). dist no longer inlines the full package.json
(devDependencies, scripts, repository url) — only the version string.
Closes#1535.
The scheduled LoComo job has been failing on most recent runs with
``TimeoutError: Consolidation did not complete within 3000.0s`` from
``benchmark_runner._wait_for_consolidation``. The offender is
``locomo_conv-44``, the largest bank in the dataset (463 unconsolidated
items at ingestion peak), whose per-bank consolidation regularly grazes
or exceeds the hardcoded 50-minute wait budget under CI load. Because
``Publish LoComo to dashboard`` is gated on ``success()``, every such
failure also drops the entire run from the dashboard, so no LoComo
metrics have been published since the dashboard was set up.
Rather than chase the timeout up, narrow what the scheduled run
exercises. Pick three conversations that bracket accuracy on the last
clean full run (May 5):
- ``conv-26`` — best (90.79%)
- ``conv-30`` — middle (86.42%)
- ``conv-43`` — worst (82.02%)
This deliberately omits ``conv-44``: it sits at median accuracy but
carries the largest unconsolidated set in the dataset, and the goal here
is to keep the trend signal (best/median/worst spread, ingest+recall
behavior) without dragging in the bank that has been blowing the
per-bank timeout.
To plumb this through:
- ``--conversation`` becomes ``nargs="+"`` so it accepts a list of IDs
(single-ID form still works). Help text and runner docstring updated.
- ``BenchmarkRunner.run`` widens ``specific_item`` to
``str | Iterable[str]`` and filters via set membership; longmemeval's
single-string usage is unaffected.
- The workflow swaps ``locomo_max_conversations`` for
``locomo_conversations``: a space-separated string of IDs that
defaults to the curated set but can be overridden at
``workflow_dispatch`` time.
Lint clean (``./scripts/hooks/lint.sh``); argparse ``--help`` verified.
* chore: fix formatting in llm_wrapper.py to pass verify-generated-files
* chore: format n8n and openclaw files to pass verify-generated-files
* fix(openclaw): add missing includeSenderContext to plugin configSchema and uiHints
* docs(zai): document z.ai provider and add default model
Follow-up to #1529. Adds z.ai (Zhipu GLM series) to the provider list,
example blocks, default-model table, and `.env.example`. Also wires
`zai` into `PROVIDER_DEFAULT_MODELS` so the new docs entry actually
matches what the engine resolves when only the provider is set.
* docs(zai): use glm-4.5-flash as default (free tier)
glm-4.5-air requires a paid balance on z.ai; flash is on the free
tier and works as a sensible default. Air is still listed in the
example as the paid-tier upgrade.
* fix(cp): improve access-key auth UX and harden middleware
- Move logout button from sidebar to header bar (next to GitHub icon),
shown only when access-key auth is configured
- Remove redundant status bar from dashboard page
- Return 401 JSON for unauthenticated API requests instead of HTML redirect
- Redirect to /login on 401 in the API client (skip if already on /login)
- Allow /logo.png through middleware for the login page
- Replace brain emoji with Hindsight logo on login page
- Fix error message visibility in dark mode
- Add loading spinner for bank selector while banks are fetching
- Expose access_key_auth as a feature flag via version endpoint
- Document HINDSIGHT_CP_ACCESS_KEY in configuration and installation docs
* fix(cp): spread default features to handle unknown fields from API
* fix(cp): wrap login page in Suspense for useSearchParams
When `dynamicBankGranularity` does not include `"user"`, every speaker
in an agent's bank ends up indistinguishable in similarity search --
memories from John look the same as memories from Peter, so recall can
mix them up. Bumping granularity to per-user is one fix, but it forces
fragmented banks and forfeits cross-user shared context (e.g. for an
ops/sprint-driver bot).
Add an opt-out `includeSenderContext` flag (default true) and a new
optional `sessionContext` parameter to `prepareRetentionTranscript`.
When provided, a small `[context] sender / channel / provider [/context]`
block is prepended to the transcript -- as a system-role message in the
JSON formats, or as a literal text block in the legacy text format.
That single header gives vector recall a strong, model-agnostic signal
to attribute and disambiguate memories without changing the bank
scheme. Filtered providers and missing fields collapse cleanly to null,
so the change is invisible when there's nothing useful to say.
Tests cover both formats, opt-out, missing-fields fallback, and the
no-context default.
Add z.ai (https://api.z.ai) as a supported provider in OpenAICompatibleLLM,
following the same pattern as deepseek, minimax, and openrouter.
Changes:
- openai_compatible_llm.py: add zai to valid_providers, base_url, api_key validation
- llm_wrapper.py: add zai to create_llm_provider routing, LLMConfig
Verified: retain (3276 in / 922 out tokens) + recall working with glm-4.5-air
agent_knowledge_list_pages was hitting GET /mental-models with no detail
parameter, so the API returned its default (detail=full) — synthesized
content + reflect_response for every page in the bank. On a bank with
many pages this produces a single JSON-RPC response that exceeds the
Claude Code MCP client's 16 MB without-newline-boundary buffer ceiling
and triggers a deterministic disconnect.
Reproduced locally driving the MCP server end-to-end:
unpatched: 20,054,285 bytes in one JSON-RPC message → disconnect
patched: 44,987 bytes, two messages → clean
The tool's docstring already promises "IDs and names only" — this aligns
the wire call with the documented contract. Agents that need the
synthesized content already use agent_knowledge_get_page, which keeps
detail=full and is unaffected.
Adds a focused regression test pinning the metadata projection.
When a batch_retain parent transitions to 'failed' because at least one
child sub-batch failed, the parent's error_message was hardcoded to the
generic string "One or more sub-batches failed". Any consumer that
classifies failures by error_message (dashboards, alert filters, log
aggregators) loses signal once a batch grows children -- a class of
failures that all share the same root reason at the child level becomes
indistinguishable at the parent level.
Pull error_message in the siblings query and pick the most-common
non-empty failed-child message as the parent's error_message. When all
siblings failed for the same reason (the common case) the parent
inherits that reason verbatim; when reasons vary the most-common one is
still a useful representative. Falls back to the legacy generic string
only when no failed sibling carries an error_message at all, preserving
backward compat for that edge case.
Same change applied to both the worker poller's fallback path and the
memory engine's in-transaction path so the propagation behavior is
consistent regardless of which surface finalises the parent.
6 new unit tests for the helper plus an inheritance assertion added to
the existing integration test.
On macOS, os.fork() without exec() corrupts Apple framework state
(XPC, Metal/MPS, ObjC runtime). The daemon's double-fork pattern
caused SIGBUS crashes when PyTorch auto-selected the MPS backend
for local embeddings/reranker models.
Replace the double-fork in daemonize() with subprocess.Popen
(which uses posix_spawn on macOS), giving the daemon a clean
process where MPS works correctly. The re-exec'd child is
identified by the _HINDSIGHT_DAEMON_CHILD env var.
This also removes the macOS FORCE_CPU workaround from
hindsight-embed, since MPS now works natively in daemon mode.
Fixes#270, #1394, #1497
* docs: surface stable worker_id guidance and zombie-operation recovery
Worker identity defaults to the container hostname, which Docker rotates
on every restart. That stranded several real deployments' consolidation
queues (issue #1470 and the related closed tickets #991 / #696 / #624).
Move the guidance from the configuration reference table — where it
only gets read after the bug bites — into the install path and add a
recovery section next to the decommission commands.
* docs(faq): add zombie-operations entry
Structured-output extraction had three nested retry loops that
multiplied on deterministic failures, burning up to 36 LLM calls
per chunk (inner 4 × middle 3 × outer 3).
- Remove outermost _extract_chunk_with_retry wrapper: its broad
except-Exception added a 3× multiplier on top of already-bounded
inner retries.
- Remove json_validate_failed retry from middle layer: the inner
provider loop already retries 400 errors; re-entering the full
LLM call for the same schema failure is wasted quota.
- Fix claude_code_llm.py: ValidationError was caught by a broad
except-Exception and retried instead of raising immediately.
Same input produces the same schema-violating output.
OpenClaw 2026.2.19+ logs a startup WARN whenever `plugins.allow` is
empty and non-bundled plugins are discovered:
[plugins] plugins.allow is empty; discovered non-bundled plugins
may auto-load: hindsight-openclaw (...). Set plugins.allow
to explicit trusted ids.
Cosmetic — the plugin still loads — but the warning fires on every
gateway start and is the kind of noise users justifiably ask about.
`ensurePluginConfig` now adds `hindsight-openclaw` to `plugins.allow`
so the warning goes away. Conservative wrt user-curated lists:
- Undefined → set to `["hindsight-openclaw"]`.
- Existing array → append our id only when missing (idempotent).
- Existing array already containing our id → no-op.
- Non-array value (deliberate weirdness) → leave alone.
Four regression tests cover all four cases.
* feat(claude-code): resolve git worktrees + explicit directory→bank mapping
Adds two new bank-resolution features so that working in a git worktree
or across multiple project directories doesn't accidentally fragment
memory across separate banks.
- resolveWorktrees (default true): detects git worktrees via
`git rev-parse --git-common-dir` and resolves the project field to the
main repository basename, so all worktrees of the same repo share one
bank. Falls back to cwd basename if git is unavailable.
- directoryBankMap: explicit cwd → bankId mapping that takes priority
over both static and dynamic modes, for users who want full control.
20 new tests cover worktree resolution, directory mapping, prefix
interaction, and graceful fallback paths.
* docs(claude-code): declare resolveWorktrees + directoryBankMap settings
Add the two new bank-resolution fields to the plugin's settings.json so
they show up in the canonical defaults, and document them in the
integration docs (Memory Bank table + a "Worktrees and explicit
mapping" subsection with a config example).
The wizard re-prompted for the API token / API key on every run even
when one was already stored in openclaw.json — confusing for users
(re-typing a long secret) and wasteful when running setup just to
backfill new fields like hooks.allowConversationAccess.
Now: if pluginConfig has an inline string secret (cloud token, api
token, llm api key), the wizard offers to reuse it (showing the last
4 chars masked, e.g. "Reuse the existing token (ends in …***1234)?").
Saying yes keeps the existing secret; saying no falls back to the
masked password prompt as before. SecretRef objects (env-var refs)
aren't pasteable so they keep the previous prompt path.
URL handling tightened up too:
- Cloud: prompt label adapts ("Reuse the configured Cloud URL X?" vs
"Use the default Hindsight Cloud URL?") and reuses the existing URL
on confirm.
- API: text prompt seeded with the existing URL via initialValue so
the user can just press enter.
- API token confirm now defaults to "yes, needs token" when one is
already configured, instead of always defaulting to no.
Adds a pure maskSecret helper in setup-lib.ts (testable without a
TTY) and three regression tests covering long token / very-short
input / surrounding whitespace.
* fix(openclaw): write hooks.allowConversationAccess in setup wizard
OpenClaw 2026.4.24 added a security gate (#71221) that silently drops
"conversation hooks" — including `agent_end`, which the plugin uses
to retain the transcript on every turn — for non-bundled plugins
unless `plugins.entries.<id>.hooks.allowConversationAccess` is
explicitly set to `true` in user config.
Symptom: openclaw logs `typed hook "agent_end" blocked because
non-bundled plugins must set ... allowConversationAccess=true`, the
plugin appears registered, retain count stays at 0, banks stay empty.
Affects every user on openclaw ≥ 2026.4.24 who installed via the
standard `hindsight-openclaw-setup` flow.
Fix: ensurePluginConfig (the helper every wizard mode calls before
saveConfig) now backfills `hooks.allowConversationAccess: true` when
the field is unset. Idempotent — re-running the wizard fixes existing
configs that pre-date the gate. We never override an explicit `false`,
since that's a deliberate user override.
Also extends the PluginEntry shape to include `hooks` and adds four
regression tests covering fresh, backfill, explicit-false, and
foreign-hooks-key cases.
* fix(openclaw): declare contracts.tools in plugin manifest
OpenClaw 2026.5.x added a second gate (loader.js:1448-1455): when a
plugin calls api.registerTool, the loader checks `record.contracts.tools`
(populated from the plugin manifest's `contracts.tools` array). If the
manifest doesn't declare the tool names, openclaw logs:
ERROR [plugins] plugin must declare contracts.tools before registering
agent tools (plugin=hindsight-openclaw, ...)
…and the registerTool call no-ops. Result on 2026.5.x: even with
enableKnowledgeTools=true, none of the agent_knowledge_* tools are
exposed to agents.
Fix: declare the seven agent_knowledge_* names in
openclaw.plugin.json's `contracts.tools` array so openclaw recognises
them at manifest-load time. Pure manifest change — runtime behavior is
still gated by `enableKnowledgeTools` in user config; this just lets
openclaw allow the registration when the runtime flag is on.
Verified locally on openclaw 2026.5.6 with the patched manifest copied
into the installed extension dir + a fresh gateway start: log goes
from "knowledge tools registered" + ERROR plugin-must-declare-contracts
→ "knowledge tools registered" with no error.
This is a pure manifest update — no code changes, no test changes
required.
* fix(n8n): drop hindsight-client runtime dep, inline HTTP calls
n8n's verified-node review (`npx @n8n/scan-community-package
@vectorize-io/[email protected]`) auto-rejects packages with
runtime dependencies via @n8n/community-nodes/no-restricted-imports.
The Hindsight node imported @vectorize-io/hindsight-client, which
triggered the rule.
Replaces the SDK calls with direct HTTP via n8n's built-in
`requestWithAuthentication` helper. The Bearer header is applied
automatically from the existing IAuthenticateGeneric credential — no
credential changes needed.
Endpoints used (verified against the SDK source we removed):
- Retain: POST {apiUrl}/v1/default/banks/{bank_id}/memories
- Recall: POST {apiUrl}/v1/default/banks/{bank_id}/memories/recall
- Reflect: POST {apiUrl}/v1/default/banks/{bank_id}/reflect
Body shapes match HindsightClient.retain/recall/reflect line-for-line
so server-side behavior is unchanged.
Test changes:
- Swapped the vi.mock() of @vectorize-io/hindsight-client for a mock
of helpers.requestWithAuthentication on IExecuteFunctions
- All 22 tests still pass (8 in node-execute, 14 elsewhere)
- Added a new test asserting trailing-slash apiUrl is stripped before
URL concatenation
Package changes:
- Drop @vectorize-io/hindsight-client from dependencies
- Bump 0.1.2 → 0.1.3
After this lands, run ./scripts/release-integration.sh n8n 0.1.3 to
publish 0.1.3 with provenance, then re-run the scan and submit at
creators.n8n.io.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* fix(n8n): use httpRequestWithAuthentication (deprecated rename)
n8n's @n8n/community-nodes ESLint plugin flags requestWithAuthentication
as deprecated in favor of httpRequestWithAuthentication. Caught by
running the full plugin ruleset locally against the dist before publish:
no-deprecated-workflow-functions errors in Hindsight.node.js at
lines 217, 241, 258 (the three operation HTTP calls)
Same signature, same auth behavior — just the modern helper name.
After this rename, all 25 community-nodes lint rules pass clean.
All 22 vitest tests still pass with the helper rename.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(n8n): leave version at 0.1.2 — release pipeline owns the bump
Per Nicolo: the release-integration tooling owns version bumps. This
PR should ship the code change only (drop hindsight-client dep, switch
to httpRequestWithAuthentication, retarget tests). Version 0.1.2 →
0.1.3 will happen automatically when release-integration.sh runs.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(n8n): match main's package-lock.json version field
main's package-lock.json has version "0.1.0" (out of sync with
package.json's "0.1.2", but that's the state on main). The previous
revert overshot to "0.1.2" — restoring to "0.1.0" so the lockfile
diff vs main no longer touches the version field.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
The progress logger (_log_progress_if_due) previously ran two heavy
COUNT/GROUP BY queries against every tenant schema on every stats cycle
(every 30s). With N tenants and W workers that's 2*N*W queries per cycle.
Reuse _scan_active_schemas() — which already calls the optional
schemas_with_pending_work() routine when installed (O(1) marker-table
read) or falls back to per-schema EXISTS checks — to pre-filter schemas
before the expensive breakdown queries. Union with schemas that have
locally-tracked in-flight tasks so processing worker counts stay accurate.
Also wraps per-schema queries in try/except for partially-provisioned
tenants and caps the schema list in log output to 20 entries.
* fix(claude-code): bootstrap Python deps via venv in CLAUDE_PLUGIN_DATA
Install Python deps into ${CLAUDE_PLUGIN_DATA}/venv on demand, and
launch the MCP server through that venv's interpreter — no global
pip install, isolated to the plugin, survives plugin updates.
How it works:
- requirements.txt declares deps (mcp>=1.0.0)
- scripts/run_mcp.sh creates the venv on first run (or when
requirements.txt changes vs the cached copy in plugin data),
pip-installs into it, and execs ${VENV}/bin/python on mcp_server.py
- .mcp.json now points at the wrapper instead of bare 'python3', so
the MCP server always runs with the plugin's pinned interpreter
(avoids version mismatches: e.g. system /usr/bin/python3 was 3.9
but venv was built with 3.11)
Tested locally: cold start ~25s (venv + pip), warm start ~0.4s,
all 9 agent_knowledge_* tools register correctly.
* docs(claude-code): document knowledge tools and subagent skill
The Claude Code integration now ships an MCP server with
agent_knowledge_* tools and a /hindsight-memory:create-agent skill
for scaffolding memory-backed subagents. Document both, plus the
new enableKnowledgeTools config flag and venv bootstrap behavior.
* fix(openclaw): pass enableKnowledgeTools through getPluginConfig
The flag was declared on PluginConfig and read at the
agent_knowledge_* tool registration site, but never copied through
getPluginConfig — so the runtime value was always undefined and the
if-branch never entered, regardless of what users (or the SDA CLI)
wrote into openclaw.json. Live since the feature was added on
Apr 29 2026.
Adds the field to the whitelist (defaulting to false on missing or
non-boolean values, matching the type definition) plus a regression
test in getPluginConfig.
Add a new `type="map"` option to entity_labels that lets users define
structured entity types with named fields. Each field is stored as a
flat `key:field:value` entity string (e.g. `person:name:Alice`,
`person:role:Engineer`), reusing the existing entity storage and
co-occurrence mechanisms with no DB changes.
Fields support all types recursively: text, value, multi-values, and
nested map — enabling schemas like `person:address:city:New York`.
Control plane UI updated with a recursive MapFieldsEditor component
that renders all label types (top-level and nested) using the same
shared component with tree-style visual nesting.
* docs: document AlloyDB ScaNN vector extension
Follow-up to #1459. Adds `scann` to the supported vector-extension
list in installation.md and configuration.md, with installation
hints, the 10k-row deferred-build caveat, AlloyDB Omni compose
pointer, and the relaxed switching rules (switching *to* scann is
allowed with existing data).
* refactor(_vector_index): address review nits from #1459
- Lift `from sqlalchemy import text` (and add `Connection`) to module
top in `_vector_index.py`; both helpers now have proper type hints.
- Make `pg_diskann` a first-class entry in a new `RESOLVED_EXTENSIONS`
tuple via `_normalize_resolved`. The configurable boundary stays
strict (`validate_extension` rejects `pg_diskann`); the resolved
helpers (`index_using_clause`, `index_type_keyword`,
`minimum_rows_for_index`, `uses_per_bank_vector_indexes`) accept it
without per-call special-case branches. Behavior is identical.
- Harden `test_alembic_vector_migrations_freeze_vector_sql_locally`
to resolve the migrations dir from `__file__` so the test no longer
depends on cwd.
- Add a one-liner explaining why `_drop_per_bank_vector_indexes`
inlines identifiers instead of using bound parameters (DDL).
Tests: tests/test_vector_index.py (10), tests/test_migration_shape.py
+ tests/test_migrations_thread_safety.py (64). Lint and ty clean.
* docs(installation): bake custom models into image instead of PVC
Add a runnable example under `docker/docker-compose/custom-models/` that
extends the slim image and pre-downloads non-default embedder/reranker
models at build time. Document this as the recommended pattern for
production over enabling the Helm `modelCache` PVC: image layers cache
per node for free, while a PVC adds storage cost, pins pods to a node,
and needs lifecycle management on uninstall/upgrade. Add pointers from
the api/worker `modelCache` values in the chart to the new section.
Refs vectorize-io/hindsight#1383
* fix(docker/custom-models): install local-ml deps via uv into the venv
The slim image's venv at /app/api/.venv was created by uv sync and does
not ship its own pip, so a bare `pip install` falls through to the
system pip and lands the packages in /home/hindsight/.local — invisible
to the venv python that runs hindsight-api at runtime. Use
`uv pip install --python /app/api/.venv/bin/python` to install into the
venv directly. Verified the resulting image loads both baked-in models
with HF_HUB_OFFLINE=1.
* docs(installation): trim custom-models section to a tip and pointer
The Dockerfile/compose example in docker/docker-compose/custom-models/
already has its own README explaining when to use it and why it beats
the modelCache PVC. The installation page only needs to point readers
there.
* fix(worker): probe pg_proc before calling optional schemas_with_pending_work() (#1408)
The poller called the optional PL/pgSQL routine `schemas_with_pending_work()`
unconditionally on every cycle. When the routine isn't installed (the default
for fresh deployments), Postgres logs a server-side `function does not exist`
error every ~30s even though the Python code silently caught the exception.
This adds a small `OptionalRoutines` registry/cache in
`hindsight_api/engine/db/optional_routines.py` that probes `pg_proc` once on
first lookup and memoises the result for the life of the process. The poller
now calls the routine only when it's actually installed and falls back to the
per-schema EXISTS path otherwise — without any spurious server-side errors.
The registry also carries the canonical install SQL for each routine inline,
so anyone touching the optimisation has a single source of truth (the previous
docstring lived only on `_scan_active_schemas`).
Tradeoffs:
- Probe is permanently cached: installing the routine on a running cluster
requires a worker restart. Acceptable because these routines are expected
to be installed once at deploy time, and a probe-per-poll would defeat the
optimisation.
- Non-PG backends short-circuit to False without touching the DB.
* refactor(worker): drop routine body from registry; document contract instead
Hindsight never installs schemas_with_pending_work() — operators do. Keeping
the SQL body in the API repo would drift from whatever is actually deployed
and falsely imply ownership. Replace the install_sql field on OptionalRoutine
with a contract docstring describing the expected signature, return shape,
and semantic constraints, so any operator-supplied implementation is
interchangeable as long as it matches.
The test installs a minimal contract-satisfying stub locally rather than
relying on a registry-supplied body.
* feat: add AlloyDB ScaNN vector index support
* fix(hindsight_api): resolved SCANN index mismatch by deferring creation
- Added SCANN-aware vector index helpers with a 10k minimum-row threshold.
- Updated bank index generation to skip per-bank clauses and index creation when unsupported.
- Updated vector migrations to validate extension names and skip SCANN-specific index creation or drops.
- Updated migration reconciliation to use row counts and defer SCANN index recreation instead of mismatch errors.
- Added tests for SCANN deferral, per-bank index ineligibility, and migration SQL freeze behavior.
* docs: add AlloyDB Omni compose example
* ci: cosign-sign release images + document verification
Folds the now-proven keyless cosign signing flow into the release
workflow so future releases sign automatically alongside the build,
and adds a "Verifying image signatures" subsection to the Docker
installation docs so downstream consumers know how to verify.
The verification regex accepts signatures from both sign-images.yml
(used to backfill 0.6.0) and release.yml (future releases) so a
single documented command covers all signed tags.
Closes#1484
* docs: tighten cosign verification section
Standalone workflow_dispatch path that resolves a published tag to its
manifest digest, signs it with keyless OIDC via cosign, and verifies the
signature in the same job. Decoupled from release.yml so we can backfill
v0.6.0 (and prior) without coupling supply-chain signing to the release
cut. Once proven, the same sign step will fold into release.yml.
Refs #1484
Allows callers to pick a named retain strategy when bulk-importing files,
overriding the bank's default. The API already accepts a per-file strategy
in FileRetainMetadata; this just wires a CLI flag through to the multipart
metadata.
Closes#1492
The default 0700 on /home/hindsight blocks traversal when running with
--user UID:GID for bind-mount ownership matching. This adds chmod 755
in both api-only and standalone stages so non-owner UIDs can traverse
the home directory.
Closes#1481
* ci: add pre-commit hook to keep skills/hindsight-docs in sync
The CI verify-generated-files job has been failing on ~82% of recent
runs because PRs touch hindsight-docs/src/pages/changelog/ or
hindsight-docs/static/openapi.json without re-running
./scripts/generate-docs-skill.sh, leaving the committed
skills/hindsight-docs/references/ copy stale.
Catch the drift locally instead. The hook regenerates and, if the
working tree diverges from the index after regen, fails the commit
with a clear message pointing the author at `git add skills/hindsight-docs/`.
The pre-commit dispatcher (.githooks/pre-commit) already iterates every
*.sh in scripts/hooks/, so the new file is picked up automatically.
* fix(retain): stop mutating caller-provided content dicts
PR #1398 (memory pressure) added an in-place pop of the "content" key
on contents_dicts after building combined_content, to release per-item
strings the engine no longer needs. Because the engine forwarded the
caller's dict objects all the way through (memory_engine →
_retain_batch_async_internal → orchestrator.retain_batch), the pop
reached back through the same references and stripped the key from
the caller's input. Any code path that holds onto the contents list
after retain_batch_async returns then trips KeyError: 'content'.
This is what was making test_extensions.py::TestOperationHooksParameters::
test_retain_pre_hook_receives_all_parameters fail intermittently on
main (the streaming path triggers the pop; non-streaming paths skip it).
Fix:
- memory_engine.py: take an engine-owned shallow copy of contents
after the validator hook so the orchestrator can mutate freely
without leaking to the caller. Strings are shared by reference,
so the copy adds only ~150 bytes of dict overhead per item —
negligible vs the multi-MB strings.
- orchestrator.py (_streaming_retain_batch): clear combined_content
immediately after handle_document_tracking / upsert_document_metadata
in all three first-batch paths (no-facts skip, mini-batch DB work,
post-loop fallback). Once tracking persists the document, nothing
reads combined_content again, so releasing it shrinks the lifetime
of the per-document text from "until function returns" to "until DB
write completes" — recovering the bulk of #1398's memory savings
without the caller-mutation side effect. nonlocal declarations on
_process_db_batch and _run_mini_batch_db_work are required because
Python infers combined_content as local once any branch assigns to it.
Memory profile vs PR #1398:
- #1398 benchmark shape (caller releases its reference at call time):
identical sustained, brief 2x peak during the combined_content +
per-item-strings overlap window before tracking completes. Other
PR #1398 savings (chunks, batch lists, sanitized_content) untouched.
- HTTP / FastAPI callers (request body holds strings until the handler
returns): no observable change — those strings were going to live
through the request anyway.
* fix(claude-code): bootstrap Python deps via venv in CLAUDE_PLUGIN_DATA
Install Python deps into ${CLAUDE_PLUGIN_DATA}/venv on demand, and
launch the MCP server through that venv's interpreter — no global
pip install, isolated to the plugin, survives plugin updates.
How it works:
- requirements.txt declares deps (mcp>=1.0.0)
- scripts/run_mcp.sh creates the venv on first run (or when
requirements.txt changes vs the cached copy in plugin data),
pip-installs into it, and execs ${VENV}/bin/python on mcp_server.py
- .mcp.json now points at the wrapper instead of bare 'python3', so
the MCP server always runs with the plugin's pinned interpreter
(avoids version mismatches: e.g. system /usr/bin/python3 was 3.9
but venv was built with 3.11)
Tested locally: cold start ~25s (venv + pip), warm start ~0.4s,
all 9 agent_knowledge_* tools register correctly.
* docs(claude-code): document knowledge tools and subagent skill
The Claude Code integration now ships an MCP server with
agent_knowledge_* tools and a /hindsight-memory:create-agent skill
for scaffolding memory-backed subagents. Document both, plus the
new enableKnowledgeTools config flag and venv bootstrap behavior.
The meta packages (hindsight-api, hindsight-all, hindsight-all-slim,
hindsight-dev) are pure entry-point shims — all real code, including
__version__ shown on the startup banner, lives in hindsight-api-slim.
Their dependency on slim was a stale floor (>=0.4.17), so
`pip install -U hindsight-api==0.6.0` left an older slim in place and
the server reported the previous version.
Hard-pin each meta package to the matching slim/api version, and teach
scripts/release.sh to rewrite the pin alongside the existing
`version = "..."` bumps so future releases stay in sync.
* feat(perf): publish perf-test results to external dashboard repo
Adds `--benchmark-output-dir` to perf-test, which emits two JSON files
in github-action-benchmark format: latency.json (smaller-is-better:
durations + recall p50/p95/p99/mean) and throughput.json (bigger-is-
better: items/queries/memories per sec). The Performance Tests workflow
now publishes both to vectorize-io/hindsight-continuous-performance-
monitor's gh-pages branch on each scheduled run.
Iteration mode (TEMP — search "TEMP" to revert before merge):
push trigger on this branch, default scale=small, locomo skipped
unless manually dispatched.
Setup needed (one-time):
- PAT with Contents:write on the dashboard repo, stored as secret
PERF_DASHBOARD_TOKEN.
- After the first run creates gh-pages there, enable Pages on that
repo (Settings → Pages → gh-pages branch).
* fix(perf): wipe benchmark working dir between latency and throughput publishes
github-action-benchmark clones the dashboard repo into a fixed
./benchmark-data-repository directory and doesn't clean up, so the
second invocation in the same job fails with 'destination path already
exists'.
* feat(perf): replace github-action-benchmark with custom dashboard publisher
Drops the two benchmark-action steps (and the dead `--benchmark-output-dir`
flag + `_to_benchmark_entries` helper in system_perf.py) in favour of a
single `scripts/benchmarks/publish-perf-results.sh` step. The script:
1. Reads the perf-test JSON output.
2. Enriches it with commit metadata (subject, author, author_date,
commit URL, PR URL via `gh api commits/<sha>/pulls`).
3. Clones the dashboard repo's gh-pages branch using PERF_DASHBOARD_TOKEN.
4. Writes data/<timestamp>-<short_sha>.json and prepends the run to
data/index.json (newest first).
5. Commits and pushes (with one rebase-retry on push rejection).
The matching custom static site lives on gh-pages of
vectorize-io/hindsight-continuous-performance-monitor (separate commit
in that repo).
* perf(workflow): publish dashboard on workflow_dispatch too
* feat(perf): publish workflow run URL and LoComo results to dashboard
Perf script now embeds workflow_run.{id,url} in each enriched run JSON
and the manifest entry, sourced from default GitHub Actions env vars
(GITHUB_RUN_ID + GITHUB_REPOSITORY).
LoComo gets its own publish script (publish-locomo-results.sh) and a
new step in the locomo job. The script strips per-question
detailed_results (kept in the workflow artifact) before pushing — keeps
each run small enough for git. Output lands at:
data/locomo/<timestamp>-<short_sha>.json
data/locomo-index.json
The matching dashboard page (locomo.html) is in the dashboard repo.
* perf(workflow): revert iteration-mode TEMP markers
Restores the production defaults that were temporarily flipped while
iterating on the dashboard:
- drop the push trigger on feat/perf-dashboard
- default scale: small → large
- default locomo_skip: true → false
- locomo job condition: workflow_dispatch-only → inputs.locomo_skip != true
Scheduled cron now runs the full suite + LoComo daily and publishes
to the dashboard.
Install Python deps into ${CLAUDE_PLUGIN_DATA}/venv on demand, and
launch the MCP server through that venv's interpreter — no global
pip install, isolated to the plugin, survives plugin updates.
How it works:
- requirements.txt declares deps (mcp>=1.0.0)
- scripts/run_mcp.sh creates the venv on first run (or when
requirements.txt changes vs the cached copy in plugin data),
pip-installs into it, and execs ${VENV}/bin/python on mcp_server.py
- .mcp.json now points at the wrapper instead of bare 'python3', so
the MCP server always runs with the plugin's pinned interpreter
(avoids version mismatches: e.g. system /usr/bin/python3 was 3.9
but venv was built with 3.11)
Tested locally: cold start ~25s (venv + pip), warm start ~0.4s,
all 9 agent_knowledge_* tools register correctly.
* feat(engine): optional read-only backend for recall queries
Add a second `DatabaseBackend` (`MemoryEngine._read_backend`) that is
populated when the new `HINDSIGHT_API_READ_DATABASE_URL` env var is set.
The recall search path (`_search_with_retries`, which orchestrates the
parallel semantic + BM25 + graph + temporal retrievers) acquires this
backend via the new `_get_read_backend()` accessor, so all of recall's
heavy SELECT traffic flows through it. Reflect benefits transparently
because it composes recall via its agent-loop tools.
When the env var is unset, `_read_backend` is the same object as
`_backend`. All call sites are unconditional and behaviour is
bit-identical to before this change. Verified by
`test_read_backend_aliases_primary_when_url_unset`.
Intended deployment: front the read URL with a pgbouncer-style pooler
that routes to read-only standbys. Operators can then enable read
offload for individual workloads (e.g. async workers where slight
replication lag is acceptable) by setting the env var on those pods,
while keeping API pods on the primary URL for read-after-write
correctness on synchronous user requests.
Constraints:
- PostgreSQL backend only. The Oracle backend's abstraction layer does
not yet model a second pool, so the engine silently falls back to the
primary backend when the URL is set with `database_backend=oracle`.
- The read backend MUST NOT be used for writes — there is no guarantee
the underlying server is the primary. Only the recall retrieval
pipeline is wired to use it. All other call sites continue to use
`_backend` / `_get_backend()`.
- Cleanup in `MemoryEngine.close()` shuts down the read backend only
when it is a distinct object from `_backend`, so the alias case is
not double-closed.
Tests:
- `test_config_validation.py`: read_database_url defaults to None when
unset, loads when set, treats empty string as unset, and is masked in
startup logs alongside the primary URL.
- `test_read_backend.py`: alias semantics when unset, distinct backend
with separate pool when set, accessor returns the right backend in
both cases, close() terminates the distinct read backend.
`uv run ruff check` clean. `uv run ruff format` clean. `uv run ty check`
clean. New tests pass; existing config tests still pass.
* refactor: add independent read pool knobs and clean up read backend init
- Add HINDSIGHT_API_READ_DB_POOL_MIN_SIZE / READ_DB_POOL_MAX_SIZE env
vars so the read pool can be sized independently from the primary.
- Store read_database_url in __init__ from config instead of re-reading
the global config singleton in initialize().
- Trim redundant comments and docstrings.
* fix: document read-replica env vars and fix test hygiene
- Add READ_DATABASE_URL, READ_DB_POOL_MIN_SIZE, READ_DB_POOL_MAX_SIZE
to configuration.md.
- Remove unused `import os` from test_read_backend.py.
- Use monkeypatch instead of os.environ in test_log_config_masks_read_database_url.
* chore: regenerate docs skill and openapi spec
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(control-plane): enrich bank dropdown with memory stats and activity
Add fact_count and last_document_at to the bank list API response so the
control plane dropdown can show at-a-glance stats for each bank: a
proportional background bar for relative memory volume, compact count
(k/M), and time since last document ingestion. Banks are sorted by most
recently active first. Popover border color softened globally.
* test: assert bank list returns fact_count and last_document_at
* feat(openclaw): drop redundant before_agent_start hook + add debugPerfTiming
Two unrelated-but-tiny openclaw improvements:
- #1354: Stop registering `before_agent_start`. Its body only called
`resolveAndCacheIdentity()` + emitted a debug log. The same identity
resolution already happens in `before_dispatch` (earlier in the
inbound path), `before_prompt_build` (re-resolves before recall, can
infer senderId from prompt content), and `agent_end` (re-resolves
before retain). Subscribing here was duplicate work on the hot path.
- #1406: Add `debugPerfTiming?: boolean` plugin config flag (default
false). When enabled, the plugin emits one info-level perf line per
recall path and per retain path:
perf: before_prompt_build hook_total=4200ms recall_main=3800ms source=fresh results=3
perf: agent_end hook_total=1200ms retain=1100ms outcome=ok bank=main messages=4
Lets users diagnose latency without patching the dist. The
`source=fresh|reused` field reflects in-flight recall dedup; the
`outcome=ok|queued|error` field reflects whether retain succeeded
inline, was queued for retry, or failed outright.
Also fixes a stale comment that referenced before_agent_start where the
actual lifecycle stage is before_prompt_build.
* fix(openclaw): sync manifest with PluginConfig type + add parity test
OpenClaw's plugin loader runs configSchema validation with
`additionalProperties: false`, so any PluginConfig field not declared
in openclaw.plugin.json is silently rejected at config-set time. The
manifest had drifted from the type:
- retainMission, observationsMission (added in #1473) — never declared
- debugPerfTiming (added earlier in this PR) — never declared
- retainDocumentScope — pre-existing gap, declared now
- enableKnowledgeTools — was in configSchema but missing from uiHints
All five are now in both configSchema.properties and uiHints. Also
fixed the bankMission description to match the corrected README from
#1353 (only affects /reflect, not retain).
Added a manifest.test.ts parity test that compares the type's keys to
the manifest's declared keys and fails on either side of drift. This
is the same class of bug as #1443 (whitelist drift) — having a test
prevents the next round.
pg0 0.14.0 bundles libxml2.so.2 + libicu70 inside the binary and
extracts them next to the embedded postgres at first run, so the host
no longer needs libxml2/libicu installed system-wide.
Unblocks embedded mode on:
- Ubuntu 25.10 (Plucky) and the upcoming 26.04 LTS, where libxml2
bumped to .so.16 and the .so.2 SONAME is gone (#1361)
- Modern Arch / EndeavourOS, where libxml2 was split out into the
optional `extra/libxml2-legacy` package (#919)
- Other modern glibc distros where the bundled theseus-rs postgres
failed with "error while loading shared libraries: libxml2.so.2"
The runtime lib bundle ships only on linux-*-gnu builds; macOS,
Windows, and the musl Linux wheel get an empty bundle (their lib
story is unchanged).
Note: this does not fix the second half of #1361 (hindsight-openclaw
strips HINDSIGHT_EMBED_API_DATABASE_URL when regenerating the profile
env file) — that bug lives in hindsight-integrations/openclaw and
needs a separate fix.
Release notes: https://github.com/vectorize-io/pg0/releases/tag/v0.14.0
* feat(claude-code): create-agent skill understands SDA directory layout
When invoked as /hindsight-memory:create-agent <name> from <path>, the skill
now knows the directory was prepared by the SDA installer and contains:
- Content files (.md, .txt, etc.) to ingest
- Optional bank-template.json with exact mental model definitions
The skill ingests files via agent_knowledge_ingest_file, then either:
- Creates the exact mental models from bank-template.json, or
- Creates 3 pages that make sense based on content (no template)
* fix(claude-code): retainToolCalls default false, remove agentName empty override
- Default retainToolCalls to false. Tool calls inflate retained content
significantly and are mostly noise for memory extraction.
- Remove "agentName": "" from settings.json so the Python DEFAULTS value
("claude-code") wins. Empty string in settings.json was overriding
the proper default, producing bank IDs like "::my-project".
* chore: regenerate docs skill
Addresses three triaged issues against the openclaw plugin:
- #1270: Stop substituting a default `bankMission` when none is configured.
Previously every gateway restart re-stamped the default text via
`createBank({reflectMission})`, clobbering per-bank missions written
out-of-band via `PATCH /banks/{id}`. Empty/unset is now a true opt-out.
- #1353: Expose `retainMission` and `observationsMission` plugin config
fields. They each map to the matching bank-config column on first use,
so users can steer retain extraction and observation consolidation
declaratively in `openclaw.json` instead of patching the bank API
out-of-band. README clarified that `bankMission` only affects reflect.
- #1443: Add `retainQueuePath`, `retainQueueMaxAgeMs`, and
`retainQueueFlushIntervalMs` to the `getPluginConfig()` whitelist.
These keys were declared in the plugin schema and read by queue init,
but the strict whitelist silently dropped them — so the queue always
used the hardcoded default path regardless of user config.
Mission stamping is now centralised in `applyConfiguredMissions()` and
gated by `hasConfiguredMissions()`, replacing six ad-hoc `setMission`
call sites with a single helper that no-ops when nothing is configured.
The streaming retain pipeline held multiple redundant copies of document
content in memory for the entire duration of processing.
Changes:
- Clear contents[].content after chunking (chunks are the working set)
- Pop contents_dicts["content"] after building combined_content
- Clear sanitized_content after hash computation
- Clear all_pre_chunks[i] after each chunk is extracted and queued
- Clear batch_contents/extracted/processed/chunk_meta after DB commit
Benchmark (50MB document, 16,666 chunks, mock LLM):
Baseline With Fix
Facts: 148,575 148,600 (identical)
RSS Growth: 1,190MB 61MB (19.5x reduction)
Ratio: 24.9x 1.3x content size
The CLI source, tests, and CI have been moved to
https://github.com/vectorize-io/self-driving-agents and published
as @vectorize-io/[email protected] from that repo.
Removed:
- hindsight-tools/self-driving-agents/ (source + tests)
- CI job test-self-driving-agents from test.yml
- Workspace entry from root package.json
- Tool entry from release-tool.sh
* docs: add 0.6.0 changelog and release blog post
- Generate changelog entry for 0.6.0 (Oracle 23ai, self-driving agents, Dify, n8n, SmolAgents, AgentCore)
- Add "What's new in Hindsight 0.6.0" blog post
- Fix package-lock.json sync for docs workspace
* docs: remove self-driving agents from 0.6.0 changelog and blog post
* docs: remove Claude Code changes from 0.6.0 changelog and blog post
The release script bumped package.json versions but didn't regenerate
the lockfile, causing npm ci to fail in CI for workspaces that depend
on @vectorize-io/hindsight-client.
* fix: resolve CI failures in verify-generated-files, deno tests, and LLM acceptance
- Format n8n integration files with prettier (out of sync on main)
- Format postgresql.py (ruff reformatting)
- Format self-driving-agents tool files with prettier
- Skip jest.spyOn-based abort signal tests when running under Deno
(jest global is not available in the Deno test runner)
- Upgrade bedrock LLM acceptance model from nova-2-lite to nova-2-pro
(lite model too weak for fact extraction quality assertions)
* fix: revert bedrock model back to nova-2-lite for LLM acceptance tests
* docs(claude-code): update README for v0.6.0 — knowledge tools, MCP server, subagents
* fix(claude-code): cross-platform Python fallback in hooks (#1413)
Hook commands now try python3 first, falling back to python if
python3 is not found (e.g. Windows where python3 is a Microsoft
Store stub that returns "Permission denied").
All hook scripts exit 0 on errors (graceful degradation), so the
|| fallback only triggers on "command not found" (exit 127) or
"permission denied" from the Windows python3 stub.
* refactor(claude-code): simplify subagent — no hardcoded bank_id, no Stop hook
The subagent no longer hardcodes bank_id or has its own Stop hook.
Instead:
- inject_bank_id.py PreToolUse hook derives bank_id at runtime from
the plugin config (supports dynamicBankId, per-repo via cwd, etc.)
- The main plugin's Stop hook retains the full conversation (including
user input) to the derived bank
This means:
- Multiple subagents share the same bank (derived from plugin config)
- Per-repo isolation works via dynamicBankGranularity: ["agent", "project"]
- User input from the main thread is retained (not lost in subagent context)
- Subagent template is simpler — just tool instructions, no bank plumbing
* fix(self-driving-agents): don't overwrite plugin config on subsequent installs
If ~/.hindsight/claude-code.json already has a Hindsight connection
configured, use it as-is. Only prompt for Cloud/Self-hosted setup on
first install. This prevents installing a second agent from clobbering
the shared config (agentName, bankId, etc.) that the plugin uses at
runtime.
* feat(self-driving-agents): auto-approve hindsight MCP tools in user settings
* fix(self-driving-agents): use plugin bank derivation for content ingestion
* fix(self-driving-agents): resolve bank with project dimension from cwd
resolveFromClaudeCode now includes all dimensions (agent, project,
session, channel, user) matching the plugin's bank.py logic. The
project dimension uses basename(process.cwd()), so running the
installer from a repo directory ingests content into the correct
per-project bank that the plugin will use at runtime.
* fix(self-driving-agents): use plugin's agentName for bank derivation, not CLI agentId
* fix(self-driving-agents): fail if subagent already exists in claude-code
* feat(claude-code): add /create-agent skill for in-session agent creation
* refactor(claude-code): remove agent-knowledge skill — subagent body is self-contained
* refactor(self-driving-agents): simplify claude-code harness — just save content + print prompt
The CLI no longer writes subagent files, resolves banks, or patches
permissions for --harness claude-code. Instead it:
1. Fetches content from GitHub
2. Saves it to ~/.self-driving-agents/claude-code/<agent-id>/
3. Prints the exact prompt to give Claude Code
Claude handles everything via /hindsight-memory:create-agent skill:
- Creates the subagent
- Ingests the seed docs
- Creates initial knowledge pages based on the content
This eliminates all bank derivation issues (bank resolved at runtime
by the plugin) and keeps one code path for agent creation (the skill).
* feat(claude-code): auto-approve bash for .self-driving-agents dir in create-agent skill
* docs(claude-code): clarify ingest steps in create-agent skill
* feat(claude-code): add ingest_file tool + auto-approve MCP tools in skill
- Add agent_knowledge_ingest_file(file_path) — reads file server-side,
no need to pass content inline. Avoids permission prompts for large
content and keeps tool calls clean.
- Add mcp__hindsight__* to create-agent skill's allowed-tools
- Update skill instructions to prefer ingest_file for disk files
* feat(self-driving-agents): auto-approve MCP tools, skill, and bash for claude-code
* refactor(claude-code): remove bank_id from MCP tool params
bank_id is no longer exposed as a parameter on any MCP tool. The
server resolves it once at startup from plugin config (derive_bank_id).
This prevents Claude from trying to override it or getting confused
about which bank to use.
Removed inject_bank_id.py PreToolUse hook — no longer needed since
bank resolution is server-side only.
* feat(self-driving-agents): copy bank-template.json and instruct Claude to create mental models from it
* feat(claude-code): add get_current_bank tool so Claude can tell user which bank is active
* chore: regenerate docs skill
* chore: trigger CI
The `<&>` operator returns a distance metric where lower values mean
higher relevance, but the code was using DESC ordering, causing the
least relevant results to appear first. Negate the distance to get a
proper score (higher = more relevant), matching pg_textsearch behavior.
* chore: add LLM minimum acceptance test workflow with CI-managed model matrix
Move LLM provider/model selection from Python-level pytest.mark.parametrize
to a GitHub Actions matrix. Each provider/model combo runs as a separate CI
job for clear per-model failure visibility.
- Rewrite test_llm_provider.py to read LLM_TEST_PROVIDER/LLM_TEST_MODEL
from env vars instead of hardcoded MODEL_MATRIX
- Mark with pytest.mark.llm, excluded from test-api via -m "not llm"
- Add test-llm-acceptance.yml workflow (daily cron, manual, or 'llm-tests' label)
with matrix of 14 provider/model combinations
* chore: LLM minimum acceptance tests as CI matrix job in test.yml
Replace the Python-level MODEL_MATRIX in test_llm_provider.py with a
CI-managed matrix job (test-api-llm-acceptance) in test.yml.
- Add hs_llm_mat pytest marker for tests that should run across LLM providers
- Tag 6 tests across 5 files covering all core operations:
- test_llm_provider.py: API methods + memory operations (fact extraction, reflect)
- test_retain.py: test_retain_with_chunks (multi-paragraph retain)
- test_fact_extraction_quality.py: test_comprehensive_multi_dimension
- test_reflections.py: test_reflect_searches_mental_models_when_available
- test_consolidation.py: test_consolidation_merges_only_redundant_facts
- test-api excludes hs_llm_mat tests via -m "not hs_llm_mat"
- New test-api-llm-acceptance job runs only -m "hs_llm_mat" with matrix:
vertexai (gemini-2.5-flash, gemini-2.5-flash-lite), openai (gpt-4.1-mini),
anthropic (claude-sonnet-4, claude-haiku-4), deepseek (deepseek-chat)
* fix: update LLM acceptance matrix to available CI providers
Matrix: vertexai/gemini-2.5-flash-lite, gemini/gemini-2.5-flash-lite,
openai/gpt-4.1-nano, groq/openai-gpt-oss-20b, bedrock/nova-2-lite.
Set HINDSIGHT_API_LLM_API_KEY from matrix-provided secret name.
* fix(dify): rename package from hindsight-dify-plugin to hindsight-dify
Align with the naming convention used by other integrations
(hindsight-crewai, hindsight-litellm, etc.).
* style(dify): apply ruff formatting
* feat(dify): add Dify integration with Hindsight memory tools
Adds a Dify Tool Plugin under hindsight-integrations/dify/ exposing three
tools — Retain, Recall, Reflect — that can drop into any Dify workflow,
chatflow, or agent app alongside other LLM and tool nodes.
- Provider with API URL + optional API key credentials, validated via
Hindsight /health
- 15 unit tests (pytest + pytest-mock)
- test-dify-integration CI job, dify added to release-integration.sh
- Docs page at /sdks/integrations/dify, integrations.json listing,
placeholder icon
- Live-tested end-to-end against local Hindsight: Retain → fact extraction
→ Recall → Reflect synthesis all pass via Dify workflow
Distributed via GitHub for now; Dify Marketplace submission to follow.
* chore(dify): use real Dify logo for integrations listing
Replaces the placeholder blue-D SVG with the actual Dify icon on the
integrations listing page.
* docs(dify): add author + contact info to plugin README
Required by the Dify Marketplace submission checklist.
* fix(dify): address review feedback — add tool tests, error handling, cleanup
- Add 14 tests for RetainTool, RecallTool, ReflectTool _invoke() methods
- Add try/except around client calls with user-friendly error messages
- Simplify urljoin to f-string in provider health check
- Remove deprecated Pydantic v1 dict() fallback in _memory_to_dict
- Remove emoji from build_package.sh output
- Add comment explaining reflect's lower default budget
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(recall): inherit observation entities through source_memory_ids
`include_entities=True` returns `entities: null` for every observation in
the recall response, even when those observations are linked through
`source_memory_ids` to facts whose entities are populated. The
per-memory endpoint (`get_memory_unit`) already handles this case: if an
observation has no rows in `unit_entities`, it inherits the union of
entities from its source memories. The recall path queried
`unit_entities` directly and stopped there, so observation results lost
both their per-result `entities` field and their contribution to the
top-level aggregate map.
The asymmetry made observation-only recall hostile to clients that
needed entity context (URL recovery, entity-aware ranking). The
documented workaround was to add `world` and `experience` to the
`types` filter and rely on those facts to carry the entity payload.
Mirror `get_memory_unit`'s fallback inside the recall entity-fetching
block: for observation result IDs that produced no direct
`unit_entities` rows, look up their `source_memory_ids`, fetch entities
for the union of source IDs in a single batched query, and project the
results back onto the original observation IDs (deduped by entity_id,
preserving source-memory order). The downstream code that derives
per-result `entities` and the top-level aggregate map both consume
`fact_entity_map`, so the inheritance flows through both paths
automatically.
Add a regression test that seeds an observation linked via
`source_memory_ids` to a fact carrying two entities, plus a second
observation with its own direct `unit_entities` link, then asserts
recall projects both per-result entity lists and the top-level map.
* refactor(recall): consolidate observation entity inheritance in one SQL helper
The first commit on this branch fixed the recall projection by mirroring
get_memory_unit's procedural fallback in Python: query unit_entities,
detect observations that came back empty, separately fetch
source_memory_ids, separately fetch entities for the union of source
IDs, then dedupe and merge in Python. That worked but had two issues
worth fixing before the PR lands.
First, the inheritance edge ("observation linked through its source
memories") is dialect-shaped: PG stores it on `memory_units.source_memory_ids`,
Oracle keeps it in the `observation_sources` junction table. The
procedural patch reached for `source_memory_ids` directly, which made
recall observation-entity inheritance silently PG-only.
Second, the same fallback already existed inline in get_memory_unit, so
shipping a second copy in recall left two places that had to stay in
sync forever, by hand.
Introduce `_entity_rows_for_units_sql`, a private engine helper that
returns a single dialect-correct UNION SELECT producing
`(unit_id, entity_id, canonical_name)` rows. Direct rows come from
`unit_entities`; observations that have no direct row inherit through
`source_memory_ids` (PG) or `observation_sources` (Oracle), guarded by
NOT EXISTS so the inheritance only fires when the direct path is empty.
This is the same conceptual shape as `_observations_via_source_match_sql`
on the document view fix branch — both are SQL primitives over the
observation-source edge.
Use the helper in two places that previously hand-rolled the same
inheritance logic:
- The recall entity-fetch block collapses from three queries plus a
Python dedupe loop to one fetch into the same `fact_entity_map`.
- get_memory_unit's two-query "fetch direct, fall back to sources"
pattern collapses to one fetch, with identical observable behavior.
Add a get_memory_unit assertion to the existing regression test so the
shared helper is exercised through both call sites and any future drift
between recall and the per-memory endpoint trips a test, not a
production report.
* fix: repair 4 broken tests on main
1. Merge divergent alembic heads (9f8e7d6c5b4a + b5d4e3f2a1c9) that
were created when deferrable FK and cooccurrence backfill migrations
both targeted the same parent without a merge revision.
2. Fix openrouter null-content mock tests — MagicMock auto-generates
truthy values for .error and .model_dump().get(), triggering the
ProviderResponseError path before reaching null-content handling.
Explicitly set response.error=None and response.model_dump to return
a clean dict. Also update the expected exception from JSONDecodeError
to ProviderResponseError to match current behavior.
3. Fix worker test isolation — clean_operations fixture only cleaned
test-worker-* prefixed operations, but WorkerPoller.claim_batch scans
all pending operations in the schema. Stale consolidation tasks from
other xdist workers caused spurious assertion failures.
4. Add retry to custom embedding dimension schema teardown — pg0
embedded postgres can race with concurrent xdist workers during
DROP SCHEMA CASCADE, causing 'could not open relation with OID'.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* Fix merge migration run_for_dialect and embedding dimension OID race
- Add run_for_dialect pattern to merge migration (required by test_migration_shape)
- Add retry wrapper for ensure_embedding_dimension to handle pg0 OID race
condition when concurrent xdist workers do DROP SCHEMA CASCADE
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
The CI workflow used pull_request_review to re-run secret-requiring jobs
after a maintainer approved a fork PR. But pull_request_review fires on
every review, so approving an internal PR triggered a duplicate CI run on
the same SHA.
Drop the pull_request_review trigger and all the conditional gating it
required. CI now runs once per push on pull_request. Fork PRs run only
the jobs that don't need secrets (gated by has_secrets); to run the full
suite on a fork branch, push it to an internal branch or use
workflow_dispatch.
- Add index.ts entry point (package.json "main" points to dist/index.js)
- Fix credential auth header: use empty string instead of undefined to
avoid sending literal "undefined" header for unauthenticated instances
- Use SVG icon instead of PNG for crisper rendering
- Remove unsafe `as IDataObject` casts on client call options, use
proper Budget type import
- Add node-execute.test.ts with mocked HindsightClient verifying all
three operations (retain, recall, reflect) are called correctly
* feat(n8n): add n8n community-node package for Hindsight memory
Adds @vectorize-io/n8n-nodes-hindsight — an n8n community node package
that exposes Hindsight retain / recall / reflect as workflow operations.
Drop the Hindsight node into any workflow alongside Slack, Sheets,
OpenAI, etc. and you have persistent memory across runs.
Package layout (n8n community-node convention):
- credentials/HindsightApi.credentials.ts: credential class
(apiUrl + optional apiKey, /health test, Bearer auth)
- nodes/Hindsight/Hindsight.node.ts: single node with operation parameter
exposing retain / recall / reflect (matches Slack-style multi-op nodes)
- nodes/Hindsight/hindsight.svg: node icon
- 14 unit tests (vitest) covering credential metadata, node properties,
per-operation field gating, budget enums
Wiring:
- detect-changes filter + test-n8n-integration job in test.yml
(cloned from test-opencode-integration shape)
- Added n8n to VALID_INTEGRATIONS in scripts/release-integration.sh
- New /sdks/integrations/n8n docs page
- Entry in integrations.json so n8n appears on the listing
- n8n.svg icon (placeholder; replace with brand-approved version)
Verified: tsc + vitest both clean (npm run build, npm test).
* feat(n8n): use Hindsight iris logo as node icon
Replaces the placeholder mark with the actual brand logo (PNG).
Updates copy-icons to ship any hindsight.* file with the build, and
ignores npm-pack tarballs.
* fix(entity-resolver): stamp cooccurrences with event_date, not now()
`entity_cooccurrences.last_cooccurred` was always set to `datetime.now(UTC)`
at flush time. For real-time retains that's fine — event time ≈ ingest
time — but any corpus **backfilled in a single session** (for example,
migrating from another memory system) collapses every co-occurrence
onto the import moment. The dashboard's entity graph recency heat then
shows a one-or-two-day range regardless of how far the underlying
knowledge actually spans, and downstream consumers of the column lose
the timeline dimension entirely.
The tuples flowing into `_link_units_to_entities_batch_impl` already
carried the per-unit `fact_date` alongside `(unit_id, entity_id)` — it
was just being discarded at the call site (`_fact_date` underscore).
This change wires the event date through:
- `_CooccurrencePair` grows an `event_date` field.
- `link_units_to_entities_batch` accepts both the legacy
`(unit_id, entity_id)` tuples and the new
`(unit_id, entity_id, event_date)` form, so external callers aren't
forced to migrate in lockstep.
- `_link_units_to_entities_batch_impl` builds a per-unit event-date map
and attaches the unit's date to every co-occurrence pair emitted from
that unit.
- `flush_pending_stats` aggregates per-pair event dates and INSERTs the
observed maximum, falling back to `now()` only when no event date was
carried (preserves the pre-fix semantics for real-time retains).
- Both in-repo callers (`retain/orchestrator.py` and
`retain/link_utils.py`) pass the `fact_date` they were already
holding.
A new Alembic migration repairs historical rows by recomputing
`last_cooccurred` from `MAX(COALESCE(mentioned_at, occurred_start,
created_at))` over `unit_entities × memory_units`, so operators don't
have to run a manual backfill to see the fix in their dashboards.
Regression coverage added in `test_entity_resolver.py` asserts a
historical `event_date` survives the link → flush round-trip.
* chore(docs-skill): pick up HINDSIGHT_API_LLM_DEFAULT_HEADERS row from #1389
Incidental docs-skill regen — `generate-docs-skill.sh` produces a 1-line
diff because #1389 (`feat(anthropic): env-driven max_retries +
default_headers knobs`) added the env var to the source documentation
without re-running the skill exporter at merge time.
Has nothing to do with the entity-cooccurrence fix in the previous
commit, but `verify-generated-files` checks the whole tree, so the row
needs to be in this branch for CI to go green.
- Add --harness hermes to the CLI
- Creates a Hermes profile per agent for isolation
- Installs standalone Python tool plugin (hindsight-sda) that registers
7 agent_knowledge_* tools via ctx.register_tool
- Plugin coexists with bundled hindsight memory provider: bundled handles
auto-retain/recall, our plugin adds knowledge page management
- Both read from the same hindsight/config.json in the profile — single
source of truth, static bank_id with empty bank_id_template
- Prompts for Hindsight credentials (pre-fills from hermes/openclaw config)
- Prompts for agent name (pre-fills from path)
- Adds plugin to plugins.enabled in profile config.yaml
- 43 tests (5 new for hermes)
* feat(self-driving-agents): add Claude Chat/Cowork harness
Add --harness claude support to the self-driving-agents CLI. Generates
a self-contained skill zip that can be uploaded to Claude Chat or Cowork
via Customize → Skills → Upload.
The generated skill:
- Has the agent's Hindsight API URL, bank ID, and token baked in
- Uses curl to call the Hindsight REST API (no external deps)
- Instructs Claude to load knowledge pages at startup
- Includes commands for creating pages, searching memories, ingesting docs
- Tells Claude to self-retain user preferences/feedback (no hooks in Chat/Cowork)
Setup flow prompts for Cloud vs Self-hosted, warns about public
accessibility for self-hosted servers, and includes allowlist
instructions in the next steps.
* test(self-driving-agents): add unit tests for claude harness
Tests cover skill generation (frontmatter, API URL/bank/token baking,
zip structure), config validation (localhost rejection, cloud URL),
harness validation, and all API operations in the generated skill.
* feat(anthropic): env-driven max_retries + default_headers knobs
Add two opt-in env vars to AnthropicLLM.__init__:
- HINDSIGHT_API_LLM_MAX_RETRIES (int): when set, passes through to
AsyncAnthropic to override the SDK's default retry count. Useful when
the deployment has its own outer retry layer (Hindsight already does
2s→300s exponential backoff in call()) and the SDK's auto-retry would
stack unnecessarily, producing request bursts that compound 429s.
- HINDSIGHT_API_LLM_DEFAULT_HEADERS (JSON string): when set, parsed and
passed as default_headers to AsyncAnthropic. Useful when routing
through a proxy that needs custom headers (component attribution,
client-fingerprint markers, etc).
Both no-op when unset; existing deployments unaffected.
Real-world driver: routing Hindsight through Switchboard (a custom
HTTP proxy that handles retries + needs X-Component-Id for attribution
+ X-SB-Impersonate-CC for fingerprint compat). Without these env knobs,
operators have to volume-mount a patched anthropic_llm.py into the
container, which is fragile across image upgrades.
* refactor(anthropic): route default_headers + max_retries through config.py per reviewer feedback
Addresses @nicoloboschi's review on PR #1389: "can we use the usual
path for using config.py? pls check other providers".
Changes:
- config.py: add ENV_LLM_DEFAULT_HEADERS + DEFAULT_LLM_DEFAULT_HEADERS
constants and a static llm_default_headers field on HindsightConfig,
parsed in from_env() the same way llm_extra_body / llm_gemini_safety_settings
already are. Static (not in _CONFIGURABLE_FIELDS) — infrastructure-level.
- anthropic_llm.py: drop the inline os.environ.get() reads and the new
import os. Accept default_headers as a typed __init__ kwarg (sourced from
config). Hardcode max_retries=0 on the SDK client to mirror
OpenAICompatibleLLM (line 179) — wrapper-level retry loop in `call()` already
handles backoff, so SDK retries are double work. Drops our custom
HINDSIGHT_API_LLM_MAX_RETRIES env knob entirely; the existing same-named
variable still controls Hindsight's wrapper retry count via
HindsightConfig.llm_max_retries.
- llm_wrapper.py: thread default_headers through create_llm_provider() and
LLMProvider.__init__/from_env. Falls back to _get_raw_config().llm_default_headers
when not explicitly passed (mirrors the gemini_safety_settings pattern).
- memory_engine.py: pass config.llm_default_headers to all four LLMConfig
constructors (memory / retain / reflect / consolidation), parallel to how
config.llm_extra_body is already passed.
- configuration.md: document HINDSIGHT_API_LLM_DEFAULT_HEADERS in the LLM
variables table.
Behavior:
- Default behavior with HINDSIGHT_API_LLM_DEFAULT_HEADERS unset is unchanged
(None → no headers added).
- SDK-level max_retries change: was Anthropic SDK default (2) when the env
var was unset, now hardcoded 0. Users who relied on SDK retries will get
the same retry semantics from the wrapper retry loop, which the rest of
the providers already use.
Verified: ruff check + ruff format both clean on hindsight-api-slim.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
---------
Co-authored-by: TuftyBruno <[email protected]>
Co-authored-by: cortex <[email protected]>
* fix(hindsight-embed): use sysconfig to find scripts dir in _find_api_command (#1401)
`Path(__file__).parent.parent` resolves to site-packages/ in stock pip
venvs, missing the actual scripts dir (<venv>/bin or <venv>/Scripts).
Use `sysconfig.get_path("scripts")` which works across pip venvs, conda,
and --target installs.
* fix(typescript-client): add jest.spyOn/fn shim to deno_setup.ts
The TestAbortSignal tests use jest.spyOn which doesn't exist under Deno.
Add a mock implementation (matching the pattern in the AI SDK's
vitest-compat.ts) so these tests pass with deno test.
* fix(typescript-client): skip TestAbortSignal under Deno
Deno freezes ES module namespace objects, so jest.spyOn cannot patch
sdk exports. Skip these spy-based unit tests under Deno (they're
already covered by the Jest suite).
* fix(hindsight-embed): restore __file__-relative fallback for --target installs
sysconfig.get_path("scripts") correctly fixes stock venv installs
(#1401) but doesn't cover `pip install --target` layouts where the
binary sits alongside site-packages contents. Keep the original
Path(__file__)-based lookup as a second fallback before uvx (#1240).
#1246 added the `time_field` query parameter to
`/v1/{tenant}/banks/{bank_id}/stats/memories-timeseries` and the
corresponding `MemoriesTimeseriesResponse` field, but the generated
artefacts weren't refreshed at merge time. As a result `verify-generated-files`
fails on every PR opened against `main` until the spec + clients
catch up.
Regenerated by running:
./scripts/generate-openapi.sh
./scripts/generate-bank-template-schema.sh (no diff)
./scripts/generate-clients.sh (rust skipped — built at compile time)
./scripts/generate-docs-skill.sh (no diff)
./scripts/hooks/lint.sh
The diff is purely the `time_field` query parameter and response field
propagated into the openapi spec and the python / typescript / go clients.
Rust client is auto-generated via `build.rs` (progenitor) so it doesn't
appear in the diff.
The MCP recall tool's schema omitted tag_groups, so MCP clients passing
e.g. {"not": {"tags": ["closeout"]}} for negative filtering had it
silently dropped — recall executed without the filter. The REST API
already exposed it; this brings the MCP tool in line.
Validates incoming dicts via TypeAdapter(list[TagGroup]) and enforces
the same tags/tag_groups mutual-exclusivity check as RecallRequest.
asyncio.AbstractEventLoop.add_signal_handler is Unix-only and raises
NotImplementedError on the Windows ProactorEventLoop. The worker would
crash silently ~30s into startup while the API process kept serving reads,
masking the failure (pending operations accumulate, consolidation never
runs).
Wrap the SIGINT/SIGTERM registration in a helper that swallows the
exception and reports back. On Windows we log a warning that the in-loop
two-stage shutdown is disabled; default Python SIGINT behavior still
terminates the process on Ctrl+C.
Fixes#1411
Closes#1384. The previous handler used `{e}` (which collapses to an empty
string for exceptions whose __str__ is blank) and re-raised as bare
`Exception(...)`, dropping the original class and traceback. Operations
rows ended up with an opaque `Failed to search memories: ` and worker
logs carried no traceback.
- Use `{e!r}` so exceptions with empty __str__ still produce a
discriminating class+args string.
- `logger.error(..., exc_info=True)` so worker logs carry the full trace.
- `raise RuntimeError(...) from e` preserves the cause chain.
* fix: clean up async batch retain test and add clarifying comments
Follow-up to #1382. Remove duplicate test fixtures that shadowed
conftest session-scoped embeddings/cross_encoder (causing zero-vector
embeddings in tests). Replace flaky asyncio.sleep(0.1) with a polling
loop. Add comments explaining the legacy checkpoint guard and the
jsonb_set checkpoint SQL.
* fix(daemon): honor --host and HINDSIGHT_API_HOST in daemon mode
Previously, --daemon unconditionally overwrote the host to 127.0.0.1,
ignoring both --host flag and HINDSIGHT_API_HOST env var. Now the
localhost default only applies when the user hasn't explicitly set a
host.
Closes#1402
* fix(retain): defer memory_links → memory_units FKs to break cascade deadlock
Concurrent INSERT into memory_links (from retain link generation —
temporal, semantic, entity, causal — via _bulk_insert_links) and any
DELETE that cascades through memory_units → memory_links (e.g.
delta-retain superseding chunks: chunks → memory_units → memory_links)
can deadlock under sustained single-tenant write load.
The cycle:
Tx A: DELETE FROM chunks WHERE chunk_id = ANY(...)
→ CASCADE acquires row locks on memory_units, then on
memory_links rows where to_unit_id matches the deleted units.
Tx B: INSERT INTO memory_links (...) referencing one of the same
memory_units rows.
→ The immediate FK check takes FOR KEY SHARE on those
memory_units rows.
The two transactions take row locks on the same memory_units rows in
opposite orders depending on which side started first. PostgreSQL
detects the cycle and aborts one of them; the loser is killed mid-batch
and the worker has to retry. Under sustained write load the pattern
repeats.
The _bulk_insert_links sort by (from_unit_id, to_unit_id) prevents
INSERT-vs-INSERT contention but doesn't help INSERT-vs-cascading-DELETE.
Fix: make both memory_links → memory_units FKs DEFERRABLE INITIALLY
DEFERRED. INSERT no longer takes FOR KEY SHARE on the FK target row at
INSERT time — checked at COMMIT instead. Concurrent DELETE cascades
freely; if it has removed the target row by COMMIT, the INSERT
transaction fails with a clean FK violation (sqlstate 23503) instead of
both transactions getting tangled in a deadlock (sqlstate 40P01). The
WHERE EXISTS filter in _bulk_insert_links continues to handle the
typical "stale unit_id" case at INSERT time; the deferred FK is just
the backstop for the narrow race window between EXISTS and COMMIT.
ON DELETE CASCADE semantics are preserved — only the *timing* of the
constraint check moves. The entity_id FK is left immediate (entities
aren't part of the observed deadlock cycle).
PG-only: Oracle's deferrable-FK semantics differ and the deadlock cycle
was only observed on PostgreSQL.
Tests:
* test_memory_links_deferred_fk verifies both FKs end up
condeferrable=true, condeferred=true, confdeltype='c' (CASCADE)
after the migration runs. Schema-shape invariant — locks in the fix
so a future migration can't regress it accidentally.
* test_migration_shape passes — the new migration uses the
run_for_dialect dispatcher correctly.
A behaviour test (concurrent INSERT + cascading DELETE no longer
deadlocks) is hard to write deterministically because PG's deadlock
detector is racy; the schema-shape test is the durable guard.
* review: fix stale migration ID + simplify FK recreation
Address review feedback on the deferred-FK migration:
* tests/test_memory_links_deferred_fk.py: replace stale migration ID
references (a2v3w4x5y6z7) with the actual ID (9f8e7d6c5b4a) in the
module docstring and assertion failure message.
* 9f8e7d6c5b4a_memory_links_deferrable_fk.py: replace _FK_NAMES tuple +
substring-based column derivation with an explicit _FK_COLUMNS dict.
Drop the misleading DO $$ ... EXCEPTION WHEN duplicate_object blocks;
DROP CONSTRAINT IF EXISTS already provides idempotence and the
EXCEPTION clause was unreachable after a successful drop.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Treat model field aliases as known JSON body fields so valid payloads like retain's async flag do not trigger X-Ignored-Params warnings.
Co-authored-by: Tosko4 <[email protected]>
Follow-up to #1382. Remove duplicate test fixtures that shadowed
conftest session-scoped embeddings/cross_encoder (causing zero-vector
embeddings in tests). Replace flaky asyncio.sleep(0.1) with a polling
loop. Add comments explaining the legacy checkpoint guard and the
jsonb_set checkpoint SQL.
* fix(typescript-client): expose missing recall/reflect params (tag_groups, responseSchema, factTypes, excludeMentalModels)
Add client-coverage-check tool that validates Python and TypeScript
wrapper clients expose all OpenAPI request body parameters, similar to
the existing cli-coverage-check for the Rust CLI.
The check caught 6 missing fields in the TypeScript wrapper:
- recall: tag_groups
- reflect: tag_groups, response_schema, fact_types, exclude_mental_models, exclude_mental_model_ids
Closes#1348
* refactor(typescript-client): make retain() delegate to retainBatch()
Mirrors the Python client pattern where retain() is a thin wrapper
around retain_batch(). Also exposes observationScopes and strategy
which were previously only available via retainBatch().
#1246 added the `time_field` query parameter to
GET /banks/{bank_id}/stats/memories-timeseries (and the corresponding
field on `MemoriesTimeseriesResponse`) but didn't run
./scripts/generate-openapi.sh + ./scripts/generate-clients.sh, so the
spec and generated Go/Python/TypeScript clients drifted from the API.
This has been failing the verify-generated-files CI job ever since.
Regenerate the spec and all clients to bring them back in sync. No
behavior change — this is pure codegen output.
Adds a WeakSet<MoltbotPluginAPI> guard at the top of the plugin entry function.
If the same api object is passed again (registry churn), the entry function exits
immediately without re-registering hooks or event listeners.
WeakSet is keyed by object identity, not a module-level boolean. A new api object
(e.g. after a registry migration) will have a different reference and pass through
unconditionally -- this does not reintroduce the bug fixed by #1029 where a
module-level boolean blocked new registries from ever getting hooks.
Old api objects that are no longer referenced are garbage-collected by the WeakSet
(no memory leak).
Closes: #1404
Refs: #1029
* chore(embed): tidy detach-popen helper and close log fds in parent
Follow-up to #1380. With the POSIX inherit-fd path gone, `log_handle` is
always supplied — drop the dead `None` branch in `_detach_popen_kwargs`,
type the parameter, and refresh the docstring. Wrap the daemon and UI
log opens in `with` blocks so the parent's copy of the fd is released
once Popen has dup'd it into the child. Add a regression test that
locks down POSIX stdout/stderr redirection so future refactors don't
silently re-introduce the TUI-corruption regression.
* chore: apply pending lint formatter and uv.lock sync
- Drop trailing commas in api.ts that the project formatter rewrites.
- Refresh uv.lock to resolve opentelemetry-* against the raised floors
introduced in #1373 (`1.41.0` / `0.62b1`).
Both fall out of running `./scripts/hooks/lint.sh` on a clean checkout
and are unrelated to the embed-detach cleanup in this PR — bundling
them so the working tree stays clean after lint.
On POSIX, the daemon subprocess previously inherited the parent process's
stdout/stderr file descriptors. When running inside a TUI (e.g. Hermes
terminal UI) that uses stdio pipes for JSON-RPC communication, any output
from the daemon subprocess (uvx download progress, Python library init
messages, Rich UI frames) would leak into the parent's terminal, corrupting
the Ink UI rendering.
This change makes POSIX behavior consistent with Windows (which already
redirected to daemon_log) and the existing UI-spawn path, by always passing
a log_handle to _detach_popen_kwargs.
Fixes: daemon output leaking into TUI, causing input bar misalignment
and timer display corruption.
Co-authored-by: Li Lao <[email protected]>
Webhook create/list/get/update/delete and list-deliveries endpoints in
the HTTP layer were calling pool.fetchrow/pool.fetch directly with
fq_table("webhooks"), bypassing the async-local schema context that
fq_table reads via get_current_schema(). Under deployments that set a
per-request target schema (multi-tenant routing), this caused webhooks
to be written to and read from the default schema while every other
operation on the same bank correctly resolved to the per-target
schema. Webhooks would land in the wrong schema; the fire path
(which uses the bank's resolved schema) would not see them and never
enqueued webhook_delivery operations -- silent failure, no errors.
Move the SQL into MemoryEngine methods that call _authenticate_tenant
first (matching the pattern used by retain/consolidate/mental-models),
so fq_table sees the same schema as the rest of the bank's data.
Add schema-isolation tests covering create/list/get/update/delete and
deliveries.
The control plane's document detail view ships an Observations tab and
a Memory Composition card alongside World and Experience. Both were
permanently empty for every document.
Root cause: get_graph_data and get_document filter memory_units by
document_id (and chunk_id) directly. Observations are consolidated
rows; their document_id and chunk_id columns are always NULL, with
the link back to a document living on source_memory_ids (PG) or in
the observation_sources junction (Oracle). The equality filter
therefore excluded every observation.
Fix:
- Add MemoryEngine._observations_via_source_match_sql, which returns a
backend-correct predicate matching observations whose source memories
satisfy a column equality, scoped to a bank.
- get_graph_data: extend the document_id and chunk_id filters with an
OR branch using the helper, so observations linked through their
sources are returned. Bank-scope the inner subquery.
- get_document: replace the broken observation_count column with a
COUNT(*) subquery built on the same helper, so nodes_by_fact_type
reflects observations for the document.
- Adjust the existing test_get_document_nodes_by_fact_type assertion:
memory_unit_count covers facts with document_id (world + experience).
Observations are reported separately in nodes_by_fact_type.
- New regression test seeds a document with one source fact, an
observation linked via source_memory_ids, and an unrelated observation,
then verifies the graph endpoint returns only the linked observation
when filtering by document_id.
The Oracle baseline migration had stale CHECK constraint values:
- async_operations.status was missing 'cancelled' (added by i4j5k6l7m8n9)
- mental_models.subtype had old values ('structural','emergent','pinned','learned')
instead of current ('directive','pinned') (changed by o0j1k2l3m4n5)
Both would cause runtime constraint violations on Oracle when cancelling
operations or creating directives.
Co-authored-by: Claude Opus 4.6 <[email protected]>
opentelemetry-exporter-prometheus 0.62b1 calls
MetricReader.__init__(otel_component_type=…), a kwarg that opentelemetry-sdk
introduced only in v1.41.0 (open-telemetry/opentelemetry-python#4970).
The previous `opentelemetry-{api,sdk}>=1.20.0` /
`opentelemetry-{instrumentation,exporter,semantic-conventions}>=0.41b0` /
`opentelemetry-exporter-otlp-proto-http>=1.20.0` floors let pip resolve a
recent exporter-prometheus against an older sdk (e.g. 1.39.x cached in a
lockfile), so on hindsight-api startup metric initialisation explodes with
"MetricReader.__init__() got an unexpected keyword argument
'otel_component_type'. Metrics will be disabled (using no-op collector)."
Functionally hindsight stays up but /metrics is silently empty.
Bumping all six otel pins to the matching 1.41.0 / 0.62b1 floor keeps
pip's resolver consistent across the otel ecosystem and removes the
mismatch that produces the warning.
Closes#1372
Ensure json_object calls include a user-message json hint, and convert
malformed success responses into clear ProviderResponseError failures
instead of crashing on missing choices/content.
This avoids opaque retain extraction TypeErrors and prevents deterministic
provider error payloads from being retried as generic chunk failures.
Co-authored-by: Reese <[email protected]>
* feat(opencode): share memory bank across git worktrees of the same repo
When `dynamicBankId` is enabled, the `project` field was derived from
`basename(directory)`. Linked worktrees (`git worktree add`) of the same
repository therefore ended up using different memory banks just because
their filesystem paths differ — even though they are the same project
and teams want their conventions/knowledge to apply across worktrees.
This change makes the `project` field git-aware:
- Inside a git repository, `git rev-parse --path-format=absolute
--git-common-dir` is used to locate the main worktree's `.git`; its
parent (the main worktree root) provides the project name.
`git-common-dir` always points at the main worktree's `.git`, even
when invoked from a linked worktree, so every worktree of the same
repo now resolves to the same bank id.
- Bare repos (where common-dir is the bare repo itself, e.g.
`myrepo.git`) use that path's basename.
- Outside of git, or when git is unavailable / fails, behavior falls
back to the previous `basename(directory)` — preserving backward
compatibility.
The `project` resolution is moved to lazy evaluation so `git` is not
spawned for granularities that don't include the `project` field.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* review: rename git-aware project to opt-in gitProject field
Per review on #1352: keep `project` semantics unchanged (directory
basename) for backwards compatibility, and expose the new git-aware
behavior as a separate `gitProject` value of `dynamicBankGranularity`.
Users that want worktrees of the same repo to share a single bank now
opt in by setting:
"dynamicBankGranularity": ["agent", "gitProject"]
The previous default `["agent", "project"]` continues to mean exactly
what it did before — basename of the working directory — so existing
banks are not silently rebound.
- bank.ts: VALID_FIELDS gains "gitProject"; `project` resolver reverted
to basename(directory); new `gitProject` resolver wraps the existing
`getProjectRootFromGit` helper.
- bank.test.ts: split into two describe blocks — one asserting that
`project` stays directory-only and never spawns git, one covering the
new `gitProject` behavior across regular clone, linked worktree, bare
repo, and git-unavailable fallback. Also added a combined-fields test.
- README.md: documents both fields and the recommended opt-in.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
* feat(stats): add time_field param to /stats/memories-timeseries
`/stats/memories-timeseries` always bucketed by `created_at` (ingest
time). For a bank built up in real time, ingest time ≈ event time and
that's the right default. But when a corpus is backfilled in a single
session — for example migrating from another memory system — every
record's `created_at` collapses to the import moment, so the chart
shows "all knowledge is new" and hides the underlying timeline.
Adds a `time_field` query parameter that lets the caller choose which
timestamp column drives the bucket assignment:
- `created_at` (default, unchanged) — ingest time
- `mentioned_at` — event time (when the fact was mentioned)
- `occurred_start` — event time (when the underlying event started)
For the event-time columns we `COALESCE(<col>, created_at)` per row so
records lacking an event timestamp still show up somewhere instead of
silently disappearing. The field is whitelisted (never interpolated
from untrusted input), unknown values fall back to `created_at`, and
the chosen column is echoed in the response for UI affordance.
Depends on the tz-aware bucket fix in #1245 (kept as a separate commit).
* feat(control-plane): add Ingested / Mentioned / Occurred toggle
Surfaces the new `time_field` backend option as a three-way toggle next
to the period selector on the "Memories ingested" card:
- **Ingested** — bucketed by `created_at` (default, matches old behavior)
- **Mentioned** — bucketed by `mentioned_at` (event time)
- **Occurred** — bucketed by `occurred_start` (event time)
The card title also updates to reflect which dimension is in view so
the chart reads unambiguously.
Propagates `time_field` through the control-plane proxy
(`/api/stats/[agentId]/memories-timeseries`) and the typed SDK
(`client.getMemoriesTimeseries`). Defaults stay `created_at` everywhere
so behavior is backward-compatible.
* feat(typescript-client): add AbortSignal support to all HindsightClient methods (#1198)
* Add signal?: AbortSignal to every public method's options bag so callers
can cancel in-flight requests without dropping down to the raw SDK.
* Methods with optional options (retain, recall, reflect, listMemories,
createDirective, listDirectives, createMentalModel, listMentalModels,
listDocuments): signal is an optional field inside the existing options.
* Methods with required options (createBank, updateBankConfig,
updateDirective, updateMentalModel, updateDocument): signal added as
an optional field alongside the required fields.
* Methods that previously took no options (getBankProfile, getBankConfig,
resetBankConfig, deleteBank, getDirective, deleteDirective, getMentalModel,
refreshMentalModel, deleteMentalModel, getMentalModelHistory, getDocument,
deleteDocument): accept an optional options?: { signal?: AbortSignal }.
* Add TestAbortSignal suite with 3 unit tests that mock the generated SDK
and verify signal is passed through on retain, recall, and getBankProfile.
* chore(skills): regenerate hindsight-docs skill files
* chore(self-driving-agents): apply prettier formatting
* fix(embed): drop hardcoded gpt-4o-mini fallback when hindsight-api import fails
Closes#1360.
`hindsight-embed/pyproject.toml` only depends on httpx + rich, so
`from hindsight_api.config import PROVIDER_DEFAULT_MODELS` always
fails in standalone venvs (uvx, OpenClaw bundles). The `except
ImportError` branch returned `gpt-4o-mini` for every provider, which
flowed into 4 sites and silently broke retain for every non-OpenAI
provider — `success: true` but zero memories stored because the
provider rejected the OpenAI-shaped model id.
The CLI doesn't need its own copy of the table. The daemon process
runs hindsight-api and already resolves the provider-keyed default
itself (config.py:1349). Leave HINDSIGHT_API_LLM_MODEL unset in the
CLI when the user didn't specify one and let the daemon resolve it:
- get_config() returns llm_model=None when env unset; daemon
forwards env vars only when truthy (daemon_embed_manager.py:333).
- _do_configure_from_env omits the HINDSIGHT_API_LLM_MODEL line in
the profile .env when the user didn't pass one (otherwise it gets
re-injected on every daemon start and suppresses the default).
- _do_configure_interactive drops the model default in the prompt
and labels it "(leave empty for provider default)".
- PROVIDER_DEFAULTS renamed to PROVIDER_API_KEYS (the model field
is gone; only the API-key env var is still needed).
Adds two regression tests covering get_config() and the env-driven
configure path.
* fix(embed): don't reject providers outside the interactive menu
The 5-entry PROVIDER_API_KEYS dict only describes the interactive
menu (openai, groq, gemini, ollama, vertexai). hindsight-api supports
~18 providers via PROVIDER_DEFAULT_MODELS — anthropic, claude-code,
bedrock, openrouter, openai-codex, and more. Gating CI configuration
on the menu set blocked valid setups: a user setting
HINDSIGHT_API_LLM_PROVIDER=anthropic with a key would hit "Unknown
provider".
Drop the rejection. The daemon already validates providers via its
own dispatch table and will surface a clear error if the provider is
truly unsupported. Validation in the CLI's UX-only menu list was
duplicate work and a permanent drift hazard.
Add blog post explaining the SmolAgents integration with Hindsight memory tools.
Covers retain, recall, and reflect tools for agent memory, real-world examples
(code review agent, data analysis, research assistant), setup guide, code examples,
and best practices. ~1,800 words on persistent memory for SmolAgents.
* docs: add Pydantic Logfire as an OTel backend for Hindsight
Hindsight already emits OpenTelemetry spans for retain / recall / reflect
(plus their LLM sub-spans) via the existing OTLP HTTP exporter. Logfire
is an OTel-native receiver, so wiring it up is three env vars — no code
changes, no new dependency.
- New /developer/logfire guide page: env-var config, what the trace tree
looks like, pairing with logfire.instrument_pydantic_ai(), useful
Logfire queries, and troubleshooting
- Cross-link from the existing Distributed Tracing section in monitoring.md
so Logfire sits next to Langfuse / DataDog / Honeycomb in the supported
backends list
* docs: drop dedicated Logfire page per review feedback
Per Nicolò's review on this PR — the dedicated /developer/logfire page
was mostly Logfire setup, not Hindsight. Keeping only the one-line
mention in the existing OTLP-backends list in monitoring.md, with the
link pointing to logfire.pydantic.dev directly.
The setup walkthrough, query examples, and troubleshooting moved into
the companion blog post (hindsight-marketing-content#113).
* feat(self-driving-agents): add nemoclaw harness support
NemoClaw runs OpenClaw inside an OpenShell sandbox. The CLI:
- Checks nemoclaw is installed and sandbox exists
- Runs hindsight-nemoclaw setup for plugin + network policy config
- Installs skill into sandbox via `nemoclaw <sandbox> skill install`
- Uses the same bank resolution from openclaw plugin config
- Adds --sandbox flag (required for nemoclaw harness)
* fix(self-driving-agents): pass skill dir (not parent) to nemoclaw skill install
* test(self-driving-agents): add tests for nemoclaw support, version checks, arg parsing
* feat(self-driving-agents): auto-detect nemoclaw sandbox, prompt if multiple
* fix(self-driving-agents): always run nemoclaw setup + rebuild sandbox for network policy
* fix(config): default openai-codex model to gpt-5.4
gpt-5.2-codex was deprecated by OpenAI and is rejected by the Codex API
on current ChatGPT Pro tiers. Switch the default to gpt-5.4, which is
in the active model list.
Closes#1344
* fix(config): use gpt-5.4-mini as openai-codex default
* feat(oracle): unify migrations under Alembic with dialect dispatcher
Oracle DDL was a 636-line idempotent file (`migrations_oracle.py`) outside
Alembic, which meant no version tracking, no per-tenant version table, and
schema drift every time a PG migration was added without a corresponding
Oracle change. This unifies both backends behind a single Alembic tree.
- New `alembic/_dialect.py::run_for_dialect(pg=, oracle=)` helper. Each
migration declares `_pg_upgrade` / `_oracle_upgrade` and dispatches based
on the live connection's dialect.
- `alembic/env.py` is dialect-aware: PG keeps the existing search_path /
read-write session setup; Oracle uses `ALTER SESSION SET CURRENT_SCHEMA`
and `DDL_LOCK_TIMEOUT`.
- `alembic/script.py.mako` scaffolds the new pattern by default.
- All 59 existing PG migrations refactored mechanically — bodies moved into
`_pg_upgrade` / `_pg_downgrade`, top-level dispatchers added.
- New `o1a2b3c4d5e6_oracle_baseline` migration brings a fresh Oracle 23ai
database to the current schema in one step (PG = no-op). Drops the legacy
partition-conversion / dedup / `observation_sources` backfill since those
only existed for pre-baseline Oracle installs we explicitly are not
supporting.
- `OracleBackend.run_migrations()` now goes through the unified Alembic
pipeline; `migrations.py` skips the PG-specific advisory lock + pgvector
setup when the URL is Oracle.
- `migrations_oracle.py` deleted; tests updated to use `run_migrations()`.
- New `tests/test_migration_shape.py` lint fails CI if any migration omits
`run_for_dialect` — keeps drift from re-emerging.
- CLAUDE.md updated with the new template and dialect-asymmetry guidance.
* ci: run client integration tests against Oracle on oracle-tests label
Adds test-python-client-oracle and test-typescript-client-oracle. These
mirror the existing test-python-client / test-typescript-client jobs but
spin up Oracle 23ai as a service container and point the API server at it
via HINDSIGHT_API_DATABASE_BACKEND=oracle + DATABASE_URL.
Why a new job instead of matrixing the existing one: Oracle Free's image
takes ~2min to start and is network-heavy, so we don't want to pay that
cost on every PR — only when oracle-tests is opted in via the PR label,
matching the existing test-api-oracle gate.
Why client tests, not unit tests: the unit suite already runs against
both backends via the abstraction layer. Only the client tests exercise
full HTTP round-trips with real serialized payloads, so they catch API
changes that work on PG but break on Oracle (or vice versa) in ways the
abstraction can't see.
* refactor(oracle): tighten feature requirements and dedup is_oracle_url
- Move is_oracle_url to db_url.py and import from there in env.py and
migrations.py — was duplicated in both.
- Type-annotate _configure_pg_session / _configure_oracle_session params
(Engine, Connection); ty checks pass.
- Update the Oracle baseline comment around vector + text index creation
to make the hard requirement explicit: VECTOR + CTXSYS must be
available, the migration fails hard if either is missing. The
swallow-only-ORA-00955 behavior was already correct; the previous
comment misleadingly called it "best-effort".
* chore(openclaw): apply pending prettier reformat to keep verify-generated-files green
Three formatting-only changes prettier wants to make. They've been stale
on main; CI's verify-generated-files runs lint with LINT_ALL=1 (vs the
"only changed integrations" local default), which surfaces them on every
unrelated PR. Folding them in here so this PR can land.
* fix(retain): plumb ops through handle_document_tracking
Line 312 of fact_storage.py references ``ops`` without ``handle_document_tracking``
declaring it as a parameter — straight NameError on every retain that walks
the upsert path. Bug landed on main in d8ec2d7f (#1325) when
``delete_stale_observations_for_memories`` started taking a backend-aware
``ops`` to choose between the PG array operator and the Oracle junction
table; the call site was added but the parameter wasn't threaded into the
enclosing function.
Fix: add ``ops=None`` to ``handle_document_tracking`` and pass ``pool.ops``
from each of the three call sites in orchestrator.py.
This is unrelated to the Alembic dialect-dispatcher refactor in this PR but
is what's blocking it — the NameError caused 17 retain tests to fail (and
left a pytest-xdist worker in a state that hung the whole job at 99%).
* test(observation): pass ops to handle_document_tracking in upsert test
The test calls fact_storage.handle_document_tracking directly, which
delegates to delete_stale_observations_for_memories(ops=ops). With ops=None
the helper falls back to the Oracle junction-table query and fails on PG
with "relation public.observation_sources does not exist". Real callers
(orchestrator, _delete_stale_observations_for_memories wrapper) all pass
self._backend.ops; the test just needs to do the same.
* ci: run client-against-oracle on every API change, drop label gate
Reserve the "oracle-tests" label for the heavy test-api-oracle (full unit
suite). The two client integration jobs against Oracle should run on every
API/client change just like their PG counterparts — the whole point is to
catch PG/Oracle drift before merge, which doesn't work if you have to
remember to label every PR. test-api-oracle keeps its label gate because
the full suite is too slow to run on every push.
* fix(oracle): rewrite path-style service to ?service_name= for SQLAlchemy
Oracle Free / Autonomous DB only register a service name with the listener,
but SQLAlchemy's oracle+oracledb dialect interprets the URL path as a SID.
That mismatch crashes alembic migrations on first connect:
DPY-6003: SID "FREEPDB1" is not registered with the listener
Rewrite ``oracle://user:pass@host:port/SERVICE`` to
``oracle+oracledb://user:pass@host:port/?service_name=SERVICE`` so the
dialect uses the correct connect descriptor. ``?sid=`` and ``?service_name=``
already in the URL are passed through untouched.
Also adds scripts/dev/start-oracle.sh / stop-oracle.sh that spin up the same
Oracle 23ai Free image CI uses (``container-registry.oracle.com/database/free``)
and bootstrap the HINDSIGHT_TEST user, so we can repro this kind of issue
locally without round-tripping through GitHub Actions.
* fix(oracle): commit after migrations so alembic_version persists
On Oracle, alembic runs each migration with transactional_ddl=False
("Will assume non-transactional DDL"). Each CREATE TABLE auto-commits, but
the trailing ``UPDATE alembic_version SET version_num = ...`` is plain DML
that needs an explicit COMMIT. Without it the connection close rolls the
update back, leaving the schema fully created but the version row one
revision behind — so ``run_migrations`` reports success while the head row
sits at the previous revision.
Caught locally with the new scripts/dev/start-oracle.sh harness running the
same Oracle 23ai Free image CI uses; alembic_version was stuck at
``k6l7m8n9o0p1`` even though every table from the ``o1a2b3c4d5e6`` baseline
existed. After the fix it correctly advances to ``o1a2b3c4d5e6``, and a
second run is a no-op as expected.
PG already needs the same commit (Supabase RW-mode SET), so just drop the
``if not is_oracle`` guard.
* ci(oracle): run python client tests sequentially to avoid ORA-00060
The python client pyproject.toml defaults to -n auto (pytest-xdist).
Against Oracle that hits row-level deadlocks during retain cleanup —
ORA-00060 is logged repeatedly in the API server output and most tests
fail with "Internal Server Error" at fixture teardown. Same shape as the
existing test-api-oracle issue, which is already pinned to -n0.
Override to -n0 in the Oracle client job (only). The PG client job stays
parallel since pgvector + advisory locks handle concurrent retain fine.
TS client tests are unaffected — they run via vitest, not pytest.
* fix(llm): guard against null content from OpenAI-compatible providers
OpenRouter free-tier models occasionally return message.content=None
alongside a valid finish_reason. Without a guard, _strip_code_fences and
the reasoning-tag regexes crashed with TypeError, and the retry loop
couldn't recover because every attempt hit the same unhandled error.
Now treat null/empty content as a transient failure: log warning, retry
within budget, raise ValueError if exhausted.
Fixes#1334
* refactor: coerce null content to empty string
Simpler than the explicit guard — empty string flows into the existing
JSON parse error handler, which already logs, retries, and raises.
* docs: add Oracle Database as supported enterprise storage option
PostgreSQL remains the primary and recommended backend. Oracle is
mentioned as a drop-in alternative for enterprise environments with
full feature parity.
* docs: remove untested Oracle managed services list
* docs: specify Oracle AI Database 26ai as the supported version
* docs: use "Oracle AI Database" consistently, drop version suffix
* fix(async-ops): atomically commit batch_retain parent and child rows
submit_async_batch_retain inserts a parent row (status='pending',
task_payload=NULL — it's a status aggregator, not directly executable)
and then loops to insert one child row per sub-batch. The parent INSERT
and child INSERTs were not transactionally coupled: the parent's
INSERT ran in its own auto-committing connection, and each child went
through a separate _submit_async_operation call that acquired its own
connection.
Any failure between them (connection drop, asyncpg timeout, schema-
cache invalidation under concurrent load, or any other exception
raised during child setup) leaves a parent row with zero children.
The worker poller skips it forever because of the
"task_payload IS NOT NULL" filter, the status aggregator never fires
because there are no children to complete, and the row sits pending
indefinitely. It also pollutes queue-depth metrics that operators rely
on to size worker pools.
Fix: wrap parent INSERT and all child INSERTs in a single
async transaction so the create-batch operation is atomic — either
all rows become visible to workers or none are. Child INSERT SQL is
inlined for the duration of the transaction; _submit_async_operation
is left untouched so other callers are unaffected. submit_task() is
deferred to after the transaction commits because SyncTaskBackend
(used in tests) executes synchronously and would otherwise read the
not-yet-committed row.
Tests:
- New regression test
test_submit_async_batch_retain_rolls_back_parent_on_child_failure
monkeypatches BatchRetainChildMetadata to raise on the second
sub-batch and asserts zero async_operations rows remain after the
failure (parent must roll back together with children).
- Mirrors the existing
test_submit_async_operation_leaves_claimable_row_when_submit_task_fails
but at the parent-level (the child-level case was already fixed).
* test(async-retain-tags): rewrite for inlined child INSERT
submit_async_batch_retain now inserts children inline inside the
parent's transaction (rather than calling _submit_async_operation per
child) and notifies the task backend after commit. The pre-existing
test mocked _submit_async_operation and asserted on its call args;
that path no longer runs for children.
Replace those assertions with the new equivalent: count the INSERTs on
the connection, inspect the post-commit submit_task payload for
document_tags, and cross-check the JSON serialized into the child's
task_payload column. Same intent (document_tags propagates through to
the worker), aligned with the new code path.
* fix(retain): thread ops through handle_document_tracking
handle_document_tracking calls delete_stale_observations_for_memories
with ops=ops, but ops is not a parameter of handle_document_tracking
itself (introduced in #1325 as part of the backend-aware observation
read split). Every retain that hits the document-tracking path raises
NameError before any actual work happens.
Add ops as a kwarg-only parameter on handle_document_tracking and
forward pool.ops from each of the three call sites in
_streaming_retain_batch. Behaviorally a no-op for the PG path
(uses_observation_sources_table is False, so the existing PG branch
runs) and for the Oracle path (junction table branch already runs
when ops.uses_observation_sources_table is True).
* test(observation-invalidation): pass ops to handle_document_tracking
The test calls handle_document_tracking directly (rather than going
through the retain orchestrator) and didn't pass ops. With the param
defaulting to None, the inner delete_stale_observations_for_memories
call falls through to the Oracle junction-table read path and queries
a non-existent public.observation_sources relation under PG.
The orchestrator's three call sites already pass pool.ops; this test
just needs to mirror that. Pass memory._backend.ops to keep the test
backend-agnostic.
The dev-mode spawn (when hindsight-api-slim sits next to hindsight-embed)
runs 'uv run --project hindsight-api-slim hindsight-api' without --extra,
so only base deps install. On a fresh customer environment with no
pre-synced workspace .venv, the daemon then crashes on startup with
'pg0-embedded is required' (and would also miss sentence-transformers).
The 'all' extra in hindsight-api-slim/pyproject.toml is defined as
local-ml + embedded-db (deliberately excludes local-llm so we don't drag
in llama-cpp-python). Use it explicitly so a fresh spawn lands with the
right runtime extras.
Local dev hides this because the workspace .venv is typically pre-synced
with --all-extras (or the explicit subset).
Both _execute_update_action and _execute_create_action insert into the
observation_sources junction table. Previously, both:
- Built INSERT batches without deduping the source_ids list
- Lacked ON CONFLICT handling
This caused UniqueViolationError on (observation_id, source_id) under
several scenarios:
1. Same source_id repeated within source_ids (a single batch can have
duplicates when several memories collapse to the same effective
source).
2. Concurrent consolidation of the same observation racing on the
DELETE-then-INSERT pattern in _execute_update_action.
3. Residual rows surviving the DELETE (rare but possible at transaction
boundaries).
Fix:
- dict.fromkeys() preserves insertion order while deduping the list.
- ON CONFLICT (observation_id, source_id) DO NOTHING absorbs any
surviving duplicates without aborting the entire batch.
Both layers are needed: dedupe avoids the round-trip on intra-batch
duplicates, ON CONFLICT handles cross-batch / concurrent races.
Add --api-url flag to recall_perf.py benchmark subcommand, enabling
recall benchmarks against a remote Hindsight API (e.g., Docker container).
This allows comparing query behavior across different Hindsight versions
by pointing the benchmark at different API instances.
Usage:
uv run python recall_perf.py benchmark \
--bank-id my-bank --query "database migration" \
--api-url http://localhost:8080
* chore(docs): sync version-0.5 docs from next
* perf: add recall-with-observations suite, split CI steps, fix locomo timeout
- Add new recall-with-observations perf test suite that includes synthetic
observations in the bank to test recall under realistic data mix
- Split CI perf-test job into separate per-suite steps for clearer reporting
- Fix locomo consolidation timeout by starting a WorkerPoller in the
BenchmarkRunner when wait_consolidation is enabled — consolidation tasks
were being queued but never processed
* perf: add consolidation suite with mock LLM
Add a new consolidation perf test suite that measures DB + embedding
overhead of the consolidation pipeline with mock LLM responses.
The mock callback parses fact IDs from the consolidation prompt and
returns create actions, exercising the full DB write + embedding path.
* fix(ci): replace removed gemini-3.1-pro-preview model in locomo
The model was returning 404 NOT_FOUND. Switch answer LLM to
gemini-2.5-flash which is available.
- openclaw now depends on @vectorize-io/hindsight-agent-sdk@^0.1.0 from npm
(file: refs don't resolve when installed from npm registry)
- CLI removes old plugin extension dir before reinstalling (openclaw doesn't
support in-place upgrade)
The enableKnowledgeTools config flag is only recognized by plugin v0.7.0+.
Older versions reject unknown properties, breaking all openclaw commands.
Now the CLI checks the installed plugin version and auto-upgrades if needed
before writing the flag.
* perf(db): eliminate ResultRow wrapping overhead for PostgreSQL
Make ResultRow a Protocol instead of a concrete wrapper class. asyncpg.Record
already satisfies the dict-like access pattern (row["key"], .keys(), .get())
natively in C — wrapping it in a Python class added ~570K __getitem__ calls
per 20-recall benchmark, causing a measurable ~24% regression at 10K bank size.
Changes:
- ResultRow is now a Protocol (interface) in result.py
- DictResultRow is the concrete wrapper, used only by Oracle backend
- PostgresConnection.fetch/fetchrow return raw asyncpg.Record directly
- Oracle backend imports DictResultRow as ResultRow (no behavior change)
- Tests updated to use DictResultRow
Benchmark (medium, 10K items, concurrency=4, same pg0 data):
v0.5.6 baseline: 0.648s mean
With wrapping: 0.805s mean (+24%)
Without wrapping: 0.680s mean (+5%, within noise)
With junction table: 0.680s mean (observation_sources has zero impact)
* perf(db): eliminate ResultRow wrapping and make observation reads backend-aware
Two performance fixes for the Oracle abstraction layer:
1. Make ResultRow a Protocol instead of a concrete wrapper class. asyncpg.Record
satisfies dict-like access natively in C — wrapping added ~570K __getitem__
calls per benchmark, causing a ~24% regression at 10K bank size.
2. Make observation source reads backend-dependent: PG uses native array ops
(source_memory_ids column with &&, unnest), Oracle uses the observation_sources
junction table. PG also skips junction table writes in the consolidator.
At 33K scale, junction table reads doubled retrieval_graph latency (0.093s→0.186s).
Changes:
- ResultRow is now a Protocol; DictResultRow is the concrete wrapper (Oracle only)
- PostgresConnection.fetch/fetchrow return raw asyncpg.Record directly
- DataAccessOps.uses_observation_sources_table property (PG=False, Oracle=True)
- Consolidator guards junction table writes behind uses_observation_sources_table
- memory_engine.py and fact_storage.py branch reads by backend type
Benchmark (large, 33K items, concurrency=4, same pg0 data):
v0.5.6 baseline: 0.853s mean
Junction table reads: 1.027s mean (+20%)
Array ops + no wrap: 1.014s mean (+19%, graph=0.091s matches baseline)
- New release-tool.yml: triggered on tools/** tags, builds workspace deps
then publishes to npm
- Fix release-integration.yml: build workspace deps (hindsight-client,
hindsight-all, hindsight-agent-sdk) before building TS integrations
* feat(claude-code): add wiki script + agent-knowledge skill
wiki.py: CLI for knowledge pages, recall, ingest, documents.
Uses the existing plugin lib/ for bank resolution and API calls.
No separate config — reads from the same settings.json as retain/recall hooks.
agent-knowledge skill: teaches the agent to use wiki.py commands.
Bank resolution is automatic (same as retain hooks).
Pages default to: delta mode, observation-only, exclude mental models.
* feat: hindsight-agent-sdk (Python + TypeScript) + Claude Code wiki integration
* refactor: move skill to SDK, remove harness-specific skill from claude-code
* feat: add trigger params to MCP create_mental_model + MCP-based skill
- MCP create_mental_model now accepts trigger_mode, trigger_exclude_mental_models,
trigger_fact_types params (both multi-bank and single-bank modes)
- Skill uses mcp__hindsight__* tools directly — no CLI, no scripts
- Bank scoped via MCP URL: /mcp/banks/{bank_id}/
* feat(openclaw): register wiki tools via registerTool API
* feat: standalone hindsight-agent-setup (npx-able) for all harnesses
* fix(openclaw): static import for wiki-tools (ESM compat)
* rename: agent_knowledge_* tools + cleaner skill (no hindsight/wiki/mental_model confusion)
* fix(openclaw): set tools optional=false so they're not filtered by allowlist
* refactor: setup reads directory layout (bank-template.json + content/), agent name from dir
* rename: @vectorize-io/self-driving-agents, setup→install
* cleanup: remove setup backwards compat
* fix: list_pages uses detail=metadata to avoid blowing up context
* chore: publish-ready package.json, README, .gitignore for self-driving-agents
* rename: hindsight-agent-setup → self-driving-agents
* cleanup: remove MCP tool changes, Python/TS SDKs, Claude Code wiki — keep only openclaw tools + skill + CLI
* cleanup: remove Rust CLI + Python CLI (superseded by self-driving-agents TS CLI)
* cleanup: rename wiki→knowledge, add release-tool.sh, interactive cloud setup, remove SDKs
* refactor: CLI does zero API calls, plugin bootstraps template+content on first session
* feat: CLI checks plugin install+config, runs wizard if needed
* feat(self-driving-agents): TUI wizard, TS client, GitHub agent sources
- Replace raw HTTP with @vectorize-io/hindsight-client SDK
- Add @clack/prompts for polished terminal UI (spinners, confirms, notes)
- Support GitHub agent sources: bare name defaults to vectorize-io/self-driving-agents,
org/repo/path fetches from any public repo, local paths still work
- Remove bootstrap code from openclaw plugin (CLI handles all API calls)
- Fix ANSI-polluted JSON parsing for openclaw agents list
- Run setup wizard inline when user declines current config
* feat(self-driving-agents): recursive content discovery, drop content/ convention
Content files (.md, .txt, etc.) are now found recursively from the
agent directory root. No special content/ subdirectory needed.
This enables nested agent repos where pointing at any level ingests
all files below it:
- install marketing → all 30 files + root bank-template.json
- install marketing/seo → only SEO files + seo/bank-template.json
* cleanup: remove unrelated files (screenshots, PDF, pretext-poc)
* refactor(self-driving-agents): bundle SKILL.md as file, read at runtime
Move the skill from a hardcoded string to a bundled file at skill/SKILL.md.
Each CLI version ships its own skill — re-running install upgrades it.
* cleanup: remove hindsight-agent-sdk/skill, now bundled in self-driving-agents
* feat: knowledge tools opt-in via enableKnowledgeTools config flag
Plugin: agent_knowledge_* tools only register when enableKnowledgeTools
is true in the plugin config (default: false).
CLI: automatically sets enableKnowledgeTools=true in openclaw.json
during install.
* feat: create hindsight-agent-sdk, move tools under hindsight-tools/
- New @vectorize-io/hindsight-agent-sdk package with harness-agnostic
knowledge tools using @vectorize-io/hindsight-client (no raw HTTP)
- OpenClaw plugin now imports from the SDK instead of inline knowledge-tools.ts
- Move self-driving-agents and hindsight-agent-sdk under hindsight-tools/
- Update release-tool.sh for new paths
* test: add tests for hindsight-agent-sdk and self-driving-agents
Agent SDK (11 tests): tool creation, endpoint routing, request bodies,
auth headers, page defaults (delta mode, observation facts).
Self-driving-agents CLI (23 tests): recursive content discovery,
local/GitHub path detection, ANSI JSON parsing, bank ID resolution
from plugin config.
CI: add test-hindsight-agent-sdk and test-self-driving-agents jobs
with detect-changes filtering.
* refactor: move tests to tests/ dirs, add prettier for hindsight-tools
- Move tests from src/ to tests/ matching repo conventions
- Add hindsight-tools/ prettier block to lint.sh
- Format all files with prettier
* fix(ci): add hindsight-tools to npm workspaces, build agent-sdk before openclaw
- Add hindsight-tools/* to root workspaces so npm resolves the agent-sdk
- Build agent-sdk before openclaw in all 3 openclaw CI jobs
- Use root npm ci + workspace builds for tool CI jobs
- Regenerate lockfiles
* fix(ci): use file: dep for agent-sdk in openclaw, whitelist in lockfile checker
- openclaw depends on @vectorize-io/hindsight-agent-sdk via file: ref
(matching how control-plane depends on hindsight-client)
- Lockfile checker whitelists hindsight-tools/* workspace deps
- Regenerate openclaw lockfile
cryptography 47.0.0 emits CPU instructions that aren't exposed in the
ARM64 Linux VMs used by Docker Desktop and Podman (AppleHV) on Apple
Silicon. Importing `cryptography.hazmat.bindings._rust` crashes with
SIGILL (exit 132), so v0.5.6 containers fail to start on those hosts.
See pyca/cryptography#14733.
The Dockerfile copies only pyproject.toml (not uv.lock) and runs
`uv sync` without --locked, so each build re-resolves to the latest
matching version. Without an upper bound, that picked up 47.0.0 once
it shipped on 2026-04-24.
Closes#1322
Remove two files that were unintentionally included in #1300 (the Pipecat
blog post commit):
- hindsight-integrations/smolagents/examples/interactive_test.py (orphan
local example, unreferenced anywhere)
- sdk-python (orphan submodule pointer with no .gitmodules entry)
Both single-memory convenience wrappers now accept retain_async and
forward it to retain_batch() / aretain_batch() respectively. Default
is False so existing call sites are unaffected.
The REST API's /v1/default/banks/{bank_id}/memories endpoint accepts
async: bool on every retain request, and both batch methods already
expose this via retain_async: bool = False. Since the convenience
wrappers simply delegate to the batch methods, there is no technical
reason to omit the parameter — users who want async on a single memory
today must switch to the batch API, which is an unnecessary friction.
This brings the Python SDK in line with the TypeScript SDK where
retain() exposes async?: boolean. PR #709 fixed aretain_batch() to
actually pass retain_async through to the request model (it was
silently dropped before), but the convenience wrappers were left
without the parameter.
Also adds unit tests verifying the kwarg is forwarded to prevent
silent regressions.
The new mental-models List view in #1296 added a 'source' query parameter
to GET /banks/{bank_id}/tags so the control plane can fetch the mental-model
tag set instead of the memory tag set. The blog post and a guide describe
this, but the API reference (mental-models.mdx + sidecar reference) didn't
mention the parameter. SDK/integration developers who jump straight to the
API docs would not know they can list mental-model tags this way.
Source-of-truth: openapi.json -> GET /v1/default/banks/{bank_id}/tags param
'source' (enum: memories | mental_models, default: memories).
Adds a small 'Listing mental model tags' subsection to the existing
'Tags and Visibility' section, mirrored byte-for-byte across both docs.
When using litellm-sdk with OpenAI-compatible custom models (model name
starts with "openai/"), the "dimensions" parameter is rejected by litellm
unless it is explicitly allow-listed via allowed_openai_params.
This fix adds the allow-listing so that HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_OUTPUT_DIMENSIONS
works correctly with OpenAI-compatible embedding endpoints.
Fixes: custom embedding models with OpenAI-compatible APIs reject the
dimensions parameter unless allowed_openai_params includes "dimensions".
* fix(test): remove stale profile auto-create assertion from bank stats test
GET /banks/{bank_id}/profile no longer auto-creates banks (99a89789),
so the empty-bank timeseries test was failing with 404. The profile
check was unnecessary — the timeseries endpoint handles non-existent
banks by returning zero-filled buckets.
* fix(test): update remaining tests for profile no-auto-create change
Three more tests relied on GET /profile auto-creating banks:
- test_base_path: remove redundant profile GET, retain creates the bank
- test_http_api_integration: same — bank is created by the first retain
- test_bank_templates: export of nonexistent bank now correctly expects 404
* fix(test): replace all GET /profile bank creation with PUT /banks
More tests relied on GET /profile to auto-create banks:
- test_reflections: 6 occurrences used as bank creation step
- test_http_api_integration: 1 occurrence used to ensure bank exists
- test_base_path_deployment: 1 occurrence in integration tests
* fix(test): upgrade gemini-3-pro-preview to gemini-3.1-pro-preview
The older model was timing out in CI.
Revert the two PG query changes introduced by the Oracle abstraction
PR (#1307) back to the exact v0.5.6 SQL:
1. Semantic dedup: restore GROUP BY + MAX(weight) + ORDER BY score DESC
instead of DISTINCT ON. The Oracle PR rewrote this for portability,
but the PG ops layer should emit the identical query shape.
2. Temporal neighbors: restore exact v0.5.6 query shape with
src.unit_id::text AS from_id, ABS(EXTRACT(...)), combined.*,
ROW_NUMBER PARTITION BY src.unit_id.
The only accepted query difference vs 0.5.6 is the observation_sources
junction table reads (new table for Oracle portability).
* feat(smolagents): add SmolAgents integration with Hindsight memory tools
Adds hindsight-integrations/smolagents with retain, recall, and reflect tools
for HuggingFace SmolAgents.
- hindsight_smolagents/: config, errors, and tools (retain/recall/reflect, plus
memory_instructions helper for prompt-time injection)
- 81 unit tests (all passing)
- Docs page at hindsight-docs/docs-integrations/smolagents.md
- Icon at hindsight-docs/static/img/icons/smolagents.png
- Entry in integrations.json so it appears on the listing page
- CI workflow job test-smolagents-integration
- Wired into scripts/release-integration.sh VALID_INTEGRATIONS
Replaces the earlier draft commits (originally opened March 23) with a clean
single commit rebased on latest main, dropping unrelated package-lock.json
changes that had been bundled in by mistake.
* fix(smolagents): add title and description to docs frontmatter
build-docs CI requires every integration page to have both 'title' and
'description' in its frontmatter. Without them, check-integration-seo.mjs
fails the docusaurus build.
* ci: re-trigger CI after flaky test-python-client
* fix(smolagents): wire integration into release + sidebar; lint fixes
- Add smolagents to the INTEGRATIONS table in generate_changelog.py so
the release script can cut a tag (release-integration.sh already had
it after the rebase, but the changelog generator needs its own entry).
- Add a sidebar link in hindsight-docs/sidebars.ts so the docs page is
reachable from navigation, matching the agentcore pattern.
- examples/interactive_test.py: import-order + drop f-prefix on a
no-placeholder f-string (ruff F541, I001).
- ruff format adjustments in tools.py.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
generate_changelog.py kept three parallel lists (VALID_INTEGRATIONS,
package-name map, display-name map). Adding a new integration meant
remembering to update all three; missing one only surfaced mid-release
when the script aborted.
Replace them with a single INTEGRATIONS dict keyed by slug, holding an
IntegrationMeta(package_name, display_name) per row. VALID_INTEGRATIONS
is derived from the dict's keys so the CLI help still works. The
display_name falls back to the slug when omitted, preserving current
behavior for ag2, cloudflare-oauth-proxy, and openai-agents.
generate_changelog.py keeps three integration tables (allowlist, package
name, display name). The previous fix added agentcore to the allowlist;
add it to the package-name and display-name maps too so the release can
finish.
scripts/release-integration.sh was updated to recognize the agentcore
integration in #822, but generate_changelog.py keeps its own copy of
VALID_INTEGRATIONS that wasn't kept in sync. Releasing agentcore failed
at the changelog-generation step. Add agentcore to the generator's list.
The Oracle PR (#1307) introduced subtle behavioral changes to two PG
query patterns during the abstraction refactor:
1. semantic_expanded CTE: the DISTINCT ON rewrite lost the global
ORDER BY score DESC before LIMIT. When results exceeded the budget,
the LIMIT applied in mu.id order instead of keeping the highest-
scored rows. Fix: wrap DISTINCT ON in a subquery that re-sorts by
score before applying LIMIT.
2. temporal neighbors: the ROW_NUMBER() OVER (PARTITION BY ... ORDER BY
time_diff_hours) filter was dropped, doubling the returned rows per
probe (K per direction × 2 instead of K closest overall). Fix:
restore the ROW_NUMBER filter around the UNION ALL of both scan
directions, for both PG and Oracle backends.
3. Migration chain: remove two empty merge migrations that were
artifacts of the Oracle branch being developed in parallel
(e6f7g8h9i0j1, j5k6l7m8n9o0) and linearize the chain:
8c6fa6f7230b → d5y6z7a8b9c0 → i4j5k6l7m8n9 → k6l7m8n9o0p1
* fix(agentcore): switch adapter to async-native client + track retention tasks
Use client.arecall/areflect/aretain directly instead of wrapping the sync
methods in run_in_executor (which spawned a worker thread that itself
created a new event loop per call). Matches the pipecat integration's
pattern.
Track fire-and-forget retention tasks in a set with a done-callback
discard so asyncio cannot GC them mid-flight. Drop the unused
threading.local client cache and the deprecated asyncio.get_event_loop()
calls.
Type _format_memories against RecallResult attributes instead of
getattr fallbacks. Drop the unimplemented 'hybrid' mode from the
RecallPolicy docstring.
* chore(integrations): drop per-package CHANGELOG.md files
The canonical changelog for each integration lives at
hindsight-docs/src/pages/changelog/integrations/<name>.md and is
written by ./scripts/release-integration.sh at release-cut time.
Per-package CHANGELOG.md files duplicate that content and encourage
pre-staging Unreleased entries, which CLAUDE.md disallows.
* feat(agentcore): add hindsight-agentcore Python integration
Adds durable cross-session memory for Amazon Bedrock AgentCore Runtime
agents. Runtime sessions are ephemeral; this adapter persists memory
across session churn keyed to stable user identity.
- HindsightRuntimeAdapter with before_turn() / after_turn() / run_turn()
- TurnContext: maps AgentCore invocation identity to Hindsight banks
- default_bank_resolver: tenant:user:agent format (session ID never used)
- RecallPolicy: recall (default) or reflect mode with configurable budget
- RetentionPolicy: context label, tags, metadata, user message inclusion
- Async-by-default retention — never delays the turn response
- Graceful degradation throughout — memory failures never surface to user
- 41 unit tests covering adapter, bank resolution, and config
* feat(agentcore): add CI job, release entry, and docs page
* Add AgentCore icon to sidebar
* fix(agentcore): add pytest to dependency-groups, fix paperclip.md diff
* feat(agentcore): add LICENSE, CHANGELOG, example, live test, and listing entry
Brings PR #822 to parity with the Pipecat reference (commit f7cc9ad6):
- LICENSE (MIT) for community distribution readiness
- CHANGELOG.md: initial 0.1.0 release notes
- examples/basic_runtime_handler.py: minimal AgentCore Runtime handler
showing TurnContext + adapter.run_turn() with a stub agent_callable
- tests/test_live_integration.py: pytest-skipif live test gated on
HINDSIGHT_API_KEY; verifies retain (turn 1) -> recall (new session, same user)
surfaces the planted fact via memory_context
- integrations.json: agentcore entry so it appears on the listings page
Verified: 41 unit tests pass (live test skips cleanly without the key);
ruff clean.
* feat(oracle): add Oracle 23ai database backend with full abstraction layer
Add Oracle 23ai as a first-class database backend alongside PostgreSQL via
a clean DatabaseBackend / DataAccessOps / SQLDialect abstraction layer.
Key changes:
- DatabaseBackend ABC with PostgreSQL and Oracle implementations
- DataAccessOps for backend-specific multi-statement operations
- SQLDialect for stateless SQL fragment generation
- Oracle SQL rewriter: translates PG syntax at runtime ($N params, ::casts,
ON CONFLICT, LIMIT/OFFSET, JSON operators, date_trunc, intervals, etc.)
- Multi-tenant schema isolation via ALTER SESSION SET CURRENT_SCHEMA
- Oracle Text CONTAINS with graceful BM25 fallback
- FOR UPDATE SKIP LOCKED task claiming (Oracle-native)
- CLOB/JSON handling with automatic LOB-to-string conversion
- Comprehensive Oracle integration + HTTP E2E test suites (60 tests)
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(oracle): resolve rebase conflicts, harden test assertions, add Oracle retry handling
Remove stale causal_weight_threshold parameter from expand_observations
across all backends and link_expansion_retrieval. Add Oracle exception
handling (InterfaceError, OperationalError, IntegrityError) to retry
logic in memory_engine so Oracle connection/integrity errors trigger
proper retry/skip behavior. Strengthen Oracle integration test assertions
to verify non-empty results and handle known ORA-00060 deadlocks.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(oracle): harden Oracle backend for production readiness
- Fix DPY-4008 bind placeholder error in Oracle Text BM25 fallback by
rebuilding semantic-only query with correct param indices when CONTAINS
fails (DRG-10599)
- Add Oracle ORA-00060 deadlock detection to retry_with_backoff so Oracle
deadlocks get the same exponential backoff as PG DeadlockDetectedError
- Use fq_table() for obs_sources_table in both Oracle and PG ops instead
of fragile string replacement on mu_table
- Fix ResultRow.__bool__ to delegate to underlying data instead of always
returning True
- Improve Oracle fuzzy entity resolution fallback logging to include the
actual error message
- Fix OracleDialect.prepare_bm25_text to handle empty token list edge case
with proper fallback to escaped query text
- Add E2E smoke test script for Oracle pipeline validation
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(test): update ResultRow bool test for delegating behavior
The test_bool_always_true test expected ResultRow({}) to be truthy,
but we changed __bool__ to delegate to the underlying data. Update
the test to verify both truthy (non-empty) and falsy (empty) cases.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* chore: regenerate OpenAPI spec, docs skill, and fix lint formatting
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Add 0.5.6 changelog entry documenting the reverted JSON schema
simplification. Add warnings to the 0.5.5 blog post and changelog
entry about the regression that caused 0 facts extracted.
- Add changelog entry generated from commits between v0.5.4..v0.5.5.
- Add blog post highlighting the redesigned Mental Models List view, the
Pipecat integration, full Windows support for the embedded runtime, the
LLM-provider compatibility wave, and the one breaking change in this
release: GET /banks/{bank_id}/profile no longer auto-creates banks.
- Regenerate docs-skill so the skill mirror reflects the new entries.
- Update version to 0.5.5 in all components
- Regenerate OpenAPI spec and client SDKs
- Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-embed
- Python client: hindsight-clients/python
- TypeScript client: hindsight-clients/typescript
- hindsight-all npm wrapper: hindsight-all-npm
- Rust CLI: hindsight-cli
- Control Plane: hindsight-control-plane
- Helm chart
- Sync documentation to version-0.5
scripts/generate-clients.sh: generate the Python client into a tmp dir
then sync into place. The previous direct bind mount of the client dir
worked on Linux CI but failed on macOS Docker Desktop with
NoSuchFileException when openapi-generator wrote api_client.py and
related supporting files; generating into /tmp avoids that.
* feat(api): list mental-model tags via /tags?source=mental_models
Adds a `source` query param to GET /v1/default/banks/{bank_id}/tags so the
same endpoint can list tags from either memory_units (default) or
mental_models. Mental-model tag suggestions previously had no API; the
alternative of a sibling /mental-models/tags route would have shadowed
GET /mental-models/{mental_model_id} for the literal id "tags".
Engine: new list_mental_model_tags method sharing a private
_list_tags_from_table helper with the existing list_tags.
Tests: covers the engine method (basic counts, wildcard) and an HTTP-level
check that source=mental_models reads from mental_models while default
remains memory_units.
* feat(control-plane): mental-models List view with tag filter
Adds a default split-pane "List" view to the Mental Models page (sidebar of
files + content on the right) and a reusable <TagFilterInput> with free-text
entry, debounced suggestions from the server, and chip selection.
Changes:
- Default Mental Models view is "List" (file/folder metaphor); the existing
card "Dashboard" view stays as a secondary toggle. Old "Table" view removed.
- Sidebar entries show name, source query subtitle, and relative refresh time.
- Tag filtering is server-side via the existing tags/tags_match params on
/mental-models; suggestions populate from /tags?source=mental_models.
- Memories (data-view) reuse the same TagFilterInput, gaining suggestions
it didn't have before.
- Adds proxy route for GET /tags (forwards optional source query param).
- TagFilterInput holds the caller's fetchSuggestions in a ref to keep the
debounce effect from refiring on every render when callers pass an inline
closure (which would otherwise loop).
Drives the HindsightMemoryProvider plugin shipped with Hermes Agent against
a locally-spawned Hindsight Embedded daemon, exercising the full
sync_turn -> retain -> recall roundtrip end-to-end through the plugin's
real code path.
Run on demand only (not part of CI) via the installed Hermes venv, which
already has every dep — no new pyproject changes needed:
HINDSIGHT_LLM_API_KEY=... \
~/.hermes/hermes-agent/venv/bin/python -m pytest \
hindsight-integration-tests/tests/test_hermes_embedded_smoke.py \
-v -s -o addopts=""
The test uses a temp HERMES_HOME so it never touches the user's real
~/.hermes profile, and tears down its daemon on exit. Skips automatically
when the LLM key (HINDSIGHT_LLM_API_KEY or OPENAI_API_KEY) isn't set or
when ~/.hermes/hermes-agent isn't installed.
* fix(llm): omit tool_choice="auto" and add deepseek as first-class provider
DeepSeek's reasoner pathway (which deepseek-v4-flash enters by default
with thinking mode) returns HTTP 400 for any tool_choice value, including
"auto". Since omitting tool_choice is semantically equivalent to "auto"
per the OpenAI API spec, we now omit it whenever the caller passes "auto",
which fixes reflect for deepseek-v4-flash without changing behaviour for
compliant providers.
Also promotes DeepSeek to a first-class provider: provider="deepseek"
auto-configures base_url=https://api.deepseek.com and the default model
to deepseek-v4-flash. Documented in configuration.md and .env.example.
* docs(deepseek): add to LLMProvidersGrid, default-models table, and config examples
The LLMProvidersGrid component on the Models page is the canonical visual
list of supported LLM providers; it was missing DeepSeek. Also add it to
the provider default-models table and the per-provider configuration
example block in models.mdx so the page is internally consistent.
* docs: single-source-of-truth for LLM providers (data file + table component)
Adds hindsight-docs/src/data/llmProviders.tsx as the canonical list of
supported providers with id, label, icon, and default model. Both
LLMProvidersGrid (icon grid on the Models page) and the new
LLMProvidersTable component (used in models.mdx for the default-models
table) consume it, so adding a provider now means editing one file
instead of three.
While converting, also added the providers that were missing from the
icon grid: Vertex AI, OpenAI Codex, Claude Code, OpenRouter.
* fix(docs-skill): render LLM provider grid + table in agent skill mirror
The agent-facing skill at skills/hindsight-docs/ is plain markdown — the
MDX-to-MD converter in scripts/generate-docs-skill.sh was leaving
<LLMProvidersTable /> and <LLMProvidersGrid /> as literal JSX, breaking
the verify-generated-files CI check and hiding the supported-providers
data from agents that rely on the skill.
Move the provider data out of llmProviders.tsx into llmProviders.json so
both the React components and the Python skill generator read from the
same source. Teach the converter to render <LLMProvidersTable /> as a
markdown table and <LLMProvidersGrid /> as a bullet list, sourced from
that JSON. Adding a provider is still one-file: edit llmProviders.json.
* chore(pipecat): apply ruff format
Files added in f7cc9ad6 (feat(pipecat)) have unformatted whitespace and
line lengths that the shared ruff config rewrites. Local lint.sh only
re-formats integrations with uncommitted changes, so the drift slipped
in; CI runs with LINT_ALL=1 and surfaces it via verify-generated-files.
The Pydantic CausalRelation/FactCausalRelation models emitted strength as a
float with ge=0.0/le=1.0 constraints, which produced minimum/maximum keys in
the JSON schema. AWS Bedrock Converse API rejects those keys on number types,
causing every retain call against Bedrock Claude to silently produce 0 facts
(see #1289).
In practice the LLM-emitted strength was always 1.0, so the 0.3
causal_weight_threshold filter and weight-based ranking in link expansion
never differentiated anything. Drop the field end-to-end:
- Remove strength from both Pydantic schemas and the dataclass
- Hardcode link weight=1.0 in create_causal_links_batch
- Remove causal_weight_threshold and the AND ml.weight >= $N filters
Causal links still carry weight in the DB (column unchanged) so the signal
can be re-introduced later if a real source of weights appears.
Fixes#1289
* fix(api): make GET /banks/{bank_id}/profile a true read (no auto-create)
The HTTP GET handler for bank profile was calling
get_or_create_bank_profile, so a request for a non-existent bank would
silently create it as a side effect. This is dangerous for any client
that polls or holds a stale bank_id while the surrounding context
(tenant, schema, user session) changes — the GET would create the
bank in whatever tenant the request was authenticated against, not
the tenant the client originally meant.
Reads must not have create-as-side-effect. Changes:
* Add bank_utils.get_bank_profile_if_exists(pool, bank_id) — pure
read; returns None when the row is absent.
* memory_engine.get_bank_profile gets a create_if_missing kwarg
(defaults True for backwards compatibility). When False, uses the
new pure-read path and returns None on miss; the caller is
responsible for translating None to a 404.
* Read-only HTTP endpoints pass create_if_missing=False:
- GET /v1/default/banks/{bank_id}/profile
- GET /v1/default/banks/{bank_id}/template (export)
- GET /v1/default/banks/{bank_id}/audit/logs
- GET /v1/default/banks/{bank_id}/audit/stats
All four now return 404 for a missing bank instead of silently
materializing one.
* Write paths (PUT/PATCH bank, import template, MCP retain/recall)
keep the default create_if_missing=True — they have explicit
expectations about creating banks on first use.
Test: tests/test_agents_api.py adds
test_get_bank_profile_no_auto_create_returns_none asserting that a
missing bank is not created as a side effect of a read, and that
explicit auto-create still works after.
* chore(api): @overload get_bank_profile so existing callers stay non-Optional
The previous commit added a create_if_missing kwarg to get_bank_profile
and changed the return annotation to dict[str, Any] | None. That made
the type checker treat every existing caller as receiving Optional,
producing 12 not-subscriptable errors in mcp_tools.py where callers
assumed non-None.
Add @overload variants so the precise return type is recovered:
- create_if_missing=Literal[True] (the default) -> dict[str, Any]
- create_if_missing=Literal[False] (explicit) -> dict[str, Any] | None
The interface.py abstract declaration mirrors the new signature.
ty check hindsight_api/ is clean after this change.
* fix(llm): simplify JSON schemas for better Ollama and LLM compliance (#1274)
Pydantic v2's model_json_schema() produces schemas with $ref/$defs, anyOf
(for Optional fields), and const — features that Ollama's grammar-based
constrained decoding silently fails on, causing it to fall back to
unconstrained generation. This also confuses weaker models when the schema
is appended as a text hint in the prompt for other providers (Groq, etc.).
Add _simplify_json_schema() that resolves $ref/$defs by inlining,
simplifies anyOf nullable unions, and replaces const with single-element
enum. Applied to both the Ollama native API path and the prompt-text
schema path for all OpenAI-compatible providers.
Controlled by HINDSIGHT_API_LLM_SIMPLIFY_JSON_SCHEMA (default: true).
* docs(configuration): add HINDSIGHT_API_LLM_SIMPLIFY_JSON_SCHEMA env var
Adds pipecat to VALID_INTEGRATIONS, package map, and display name map
so ./scripts/release-integration.sh pipecat can generate the docs
changelog. Mirror of the entry in scripts/release-integration.sh added
in #921.
* feat(pipecat): add Pipecat voice AI pipeline memory integration
* fix(pipecat): make OpenAILLMContextFrame import optional for forward compat
* feat(pipecat): add LICENSE, CHANGELOG, examples, and live integration test
- LICENSE (MIT) + CHANGELOG.md for community distribution readiness
- examples/basic_pipeline.py: full Daily/Deepgram/OpenAI/Cartesia voice pipeline
- examples/interactive_chat.py: text-based REPL for manual memory validation
- tests/test_live_integration.py: pytest-skipped live test, verifies Retain/Recall/Inject/Idempotency against a running Hindsight instance
Verified: 17/17 unit tests pass; live integration test passes all 4 checks against localhost:8888.
* chore(pipecat): add docs page, integrations listing entry, and icon
- hindsight-docs/docs-integrations/pipecat.md: docs page for the integrations site
- hindsight-docs/src/data/integrations.json: entry so Pipecat appears on the listing
- hindsight-docs/static/img/icons/pipecat.png: icon for the listing
* docs(installation): document memory footprint and hardware requirements
Add a Hardware subsection under Prerequisites with per-component RAM
guidance (full vs slim image, control plane, worker, postgres) and
extend the Docker Image Variants table with an Idle RAM column so users
know what to provision before deploying.
* docs(installation): leave Docker Image Variants table alone, soften GPU note
- Revert the Idle RAM column on the Docker Image Variants table; the
Hardware subsection already carries that detail.
- Reword the CPU/GPU line: CPU is fine for dev and basic workloads, but
the local cross-encoder reranker typically benefits from a GPU under
production traffic — or offload reranking to an external provider.
* docs(skill): regenerate hindsight-docs skill mirror
* docs(integrations): add ChatGPT and Perplexity integration guides
- Create chatgpt.md with OAuth setup, custom instructions, and best practices
- Create perplexity.md with OAuth setup, custom instructions, and research workflows
- Update sidebar to include both integrations with icons
- Include troubleshooting, data privacy, and architecture sections
* docs(integrations): add ChatGPT and Perplexity to integrations listing
* docs(icons): add ChatGPT and Perplexity integration icons
FastMCP defaults serverInfo.version to its own library version when the
MCP server constructor isn't given an explicit version. As a result,
clients listing the server saw e.g. "3.0.0" / "3.2.4" (the FastMCP
release in use) instead of Hindsight's actual version. Pass
HINDSIGHT_VERSION explicitly so the reported version reflects this
project.
So formatting violations in hindsight-clients/typescript and
hindsight-all-npm now fail CI via verify-generated-files (same
git-status-after-lint pattern Python uses).
- Add prettier-ts-client and prettier-all-npm tasks to lint.sh
- Delete hindsight-clients/typescript/.prettierrc local override so
openapi-ts auto-discovers the shared root .prettierrc.json (was
printWidth 80 / trailingComma "all", now 100 / "es5")
- Reformat affected files (mostly mechanical)
* fix(consolidation): reduce memory fan-out during consolidation recall (#996)
Three changes to address unbounded RSS growth during consolidation:
1. Default consolidation recall budget to LOW instead of MID, reducing
hnsw_fetch from 1,500 to 500 rows per recall arm. Configurable via
HINDSIGHT_API_CONSOLIDATION_RECALL_BUDGET env var.
2. Default consolidation_source_facts_max_tokens to 4096 instead of -1
(unlimited), bounding the source-fact hydration that was the worst-case
memory amplifier on large banks.
3. Default FlashRank ONNX cpu_mem_arena to False, preventing the ONNX
Runtime memory arena from growing monotonically and pinning RSS after
consolidation batches complete. Configurable via
HINDSIGHT_API_RERANKER_FLASHRANK_CPU_MEM_ARENA env var.
* docs(configuration): document new consolidation and FlashRank env vars
* chore: fix lint formatting and regenerate docs skill mirror
* fix: revert accidental removal of Deno client patch in client.gen.ts
The default dynamicBankGranularity is ["agent","channel","user"] in deriveBankId,
but getIdentitySkipReason defaulted to false when the field was unset, causing
agent:main:main sessions to be silently skipped from retention and recall.
Align both paths: default agentBanking to true (matching the runtime default),
normalise dynamicBankGranularity at config-validation time, and extract a shared
DEFAULT_DYNAMIC_BANK_GRANULARITY constant.
Also adds throttled info-level logging for identity skip events so operators can
discover silent skips without enabling debug mode.
Closes#1215
`subprocess.DETACHED_PROCESS` and `subprocess.CREATE_NEW_PROCESS_GROUP` are
Windows-only constants. The existing code is already guarded by
`if platform.system() == "Windows":`, but `ty`'s static analysis doesn't
track platform-conditional branches, so it flags both attributes as
`unresolved-attribute` on the Linux CI runner — failing
`verify-generated-files`.
Switching to `getattr(subprocess, "DETACHED_PROCESS", 0)` keeps the same
runtime behavior on Windows (constant is present, returned as-is) and
avoids the static-analysis false positive on Linux/macOS where the
attribute access would never execute anyway.
Same fix pattern documented in cpython subprocess docs and used widely
in cross-platform Python codebases.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
* feat(embeddings): add HINDSIGHT_API_EMBEDDINGS_GEMINI_FORCE_IPV4 opt-in
In environments where AAAA records resolve but IPv6 egress is broken
(some Docker/VPC setups), the Gemini embeddings client hangs on connect.
This adds an opt-in flag that configures the google-genai client with an
httpx transport bound to 0.0.0.0 so it uses IPv4 only.
Defaults to false; treated as a static (server-level) config per the
project's hierarchical-config guidelines since it is an infrastructure
concern rather than per-tenant business logic.
* fix(embeddings): move force_ipv4 after batch_size to preserve positional compat
Addresses Copilot review feedback. Inserting force_ipv4 at position 7
shifted batch_size to position 8 — any external caller passing batch_size
positionally would have silently started setting force_ipv4 instead.
All internal call sites use kwargs so nothing in the repo was affected,
but keeping the new param at the end of the signature is the right API
hygiene for downstream users.
* fix(embed): prefer locally-installed hindsight-api over uvx
Falling through to `uvx hindsight-api@...` when hindsight-embed is
installed via `uv pip install --target` (e.g. NixOS, hindsight-all)
downloads a standalone Python whose ABI doesn't match the sibling
site-packages' C extensions, causing `ModuleNotFoundError:
asyncpg.protocol.protocol` at daemon startup (closes#1240).
Check for a sibling `hindsight-api` entry point in `bin/` (or
`Scripts/hindsight-api.exe` on Windows) before falling back to uvx.
* ci(embed): add Windows unit-test job for hindsight-embed
Runs pytest on windows-latest to exercise the Windows code paths in
hindsight-embed (msvcrt file locking, .exe binary detection in
_find_api_command, netstat-based PID lookup).
Skips the test.sh smoke test: the daemon uses POSIX-only
subprocess.Popen(start_new_session=True) and signal.SIGTERM, so making
the full lifecycle Windows-safe is a separate effort.
* ci(embed): add Windows --target install test for issue #1240
Exercises the exact install layout from the issue: `uv pip install
--target` hindsight-embed + hindsight-api-slim, then verify the sibling
`Scripts/hindsight-api.exe` is discovered by `_find_api_command()`
instead of falling back to uvx.
Also runs `hindsight-embed --help` from the installed binary as a
basic smoke check. Daemon startup is still out of scope (needs
secrets + POSIX `start_new_session=True` fix).
* feat(embed): full Windows support for daemon + smoke test
Fixes every platform-specific blocker that previously forced the
Windows CI job to skip the smoke test:
- hindsight-api-slim/daemon.py: skip the double-fork on Windows (no
fork model). The spawning embed process now drives detachment via
CREATE_NEW_PROCESS_GROUP | DETACHED_PROCESS instead.
- hindsight-embed/daemon_embed_manager.py: centralize detach flags in
_detach_popen_kwargs(). Windows requires creationflags plus explicit
stdout/stderr redirection (DETACHED_PROCESS leaves the child with no
console). POSIX keeps start_new_session=True.
- hindsight-embed/cli.py: reconfigure sys.stdout/stderr to UTF-8 on
Windows so Rich's box-drawing / ✓ glyphs don't crash the default
cp1252 codec.
- hindsight-embed/profile_manager.py: seek to byte 0 before msvcrt
lock/unlock. Windows's msvcrt.locking(LK_UNLCK) requires the file
pointer at the start of the locked region, which wasn't true after
json.dump moved the position past the data.
- hindsight-embed/test.sh: detect python vs python3 so Git Bash on
windows-latest (which only ships `python`) can run the smoke test.
- tests: set USERPROFILE alongside HOME because Path.home() on Windows
consults USERPROFILE, not HOME.
- HINDSIGHT_EMBED_DAEMON_STARTUP_TIMEOUT env var: bump on Windows CI
since pg0-embedded's initdb on cold runners is slow.
CI: test-embed-windows now mirrors the Linux test-embed job —
vertexai creds, local-ml/embedded-db extras, HF cache, full smoke
test — on top of the --target install-layout check for issue #1240.
* fix(api-slim): gate mlx/mlx-lm off Windows in local-ml extras
mlx only ships wheels for macOS/Linux, so `uv sync --all-extras` on
win_amd64 errors out with "no source distribution or wheel for the
current platform". Constrain both to `sys_platform != 'win32'` so
Windows resolves local-ml without the Apple Silicon pieces.
* fix(embed): use Path.replace for atomic metadata write on Windows
Path.rename refuses to overwrite an existing destination on Windows
(WinError 183); every profile metadata update after the first one
failed with FileExistsError. Path.replace is the cross-platform
atomic rename added in Python 3.3 precisely for this pattern.
* fix(embed): skip configure prompts when CI env vars are set
do_configure previously gated non-interactive mode on
`sys.stdin.isatty()`: if stdin looked interactive, it went to the
prompt path regardless of env. On Windows GHA pwsh runners stdin
looks like a TTY (it doesn't on Linux headless runners), so the
subprocess-invoked `configure` would block on input and exit with
"Configuration cancelled" — even though HINDSIGHT_API_LLM_* env vars
were set.
Fall through to _do_configure_from_env whenever the required
CI inputs are present (API key set, or provider is ollama/vertexai).
* ci(embed): build and stage hindsight Rust CLI on Windows smoke test
hindsight-embed's retain/recall delegate to the Rust `hindsight` CLI.
On POSIX the embed CLI auto-installs via curl|bash, but on Windows
`bash` routes to WSL (not provisioned) and there's no Windows
installer. Build the CLI from source with cargo and copy the .exe
into ~/.local/bin, which is the first location find_cli_binary()
checks.
Also teach find_cli_binary to look for `hindsight.exe` (and drop the
Unix-only os.access X check on Windows) so the staged binary is
actually picked up.
* fix(cli): update get_graph call to match regenerated client signature
hindsight-clients/rust was regenerated when document_id + chunk_id
query params were added to /banks/{id}/graph; progenitor orders query
params alphabetically, so the call-site now needs three leading
Nones (chunk_id, document_id, limit) and type_filter in the 8th slot.
Building the CLI off the current openapi.json was failing with E0061
"this method takes 9 arguments but 7 arguments were supplied",
blocking the Windows smoke-test cargo build.
* chore(api-slim): bump pg0-embedded to 0.13.0 for Windows support
0.13.0 fixes the "IO error: invalid gzip header" crash that blocked
embedded PostgreSQL startup on Windows, which was the final remaining
blocker for the Windows hindsight-embed smoke test.
* ci(embed): install --target outside repo for sibling-binary verify
_find_api_command's first check looks for a sibling
hindsight-api-slim/ dir via Path(__file__).parent.parent.parent. When
the --target install dir lives inside the monorepo checkout, that
branch matches and the test silently exercises the dev-mode path
instead of the sibling-binary path we're trying to validate.
Move the install into $RUNNER_TEMP so the dev-mode probe misses and
the sibling-binary branch is actually hit.
* fix(tests): repair 9 regressions surfaced on main
Investigation and fixes for test failures on latest main:
1. test_per_operation_llm_config (2 tests): defaults were hardcoded to 10,
but #1121 reduced DEFAULT_LLM_MAX_RETRIES to 3. Drive assertions from
the constant so this tracks future changes automatically.
2. test_sql_schema_safety: #1210 added a docstring on task_backend.py:136
that said "INSERTed into async_operations", which false-positived the
unqualified-table regex (INTO+INSERT+bare table). Rephrased the prose.
3. test_memory_engine_execute_task_passes_through_defer_operation: #1231
made execute_task short-circuit when the async_operations row is
missing (treat as cancelled). The test created a fresh operation_id
without inserting a row, so the handler never ran. Insert a pending
row before execute_task.
4. 4 worker claim_batch / scan tests: assertions were counting total
claims across the whole DB. test_async_batch_retain.py submits
pending async_operations without sharing an xdist group, so parallel
xdist workers polluted each other. Put test_async_batch_retain.py in
the "worker_tests" group and also scope the worker-test assertions
to the banks each test created, as defense-in-depth.
5. test_refresh_content_respects_max_tokens: observed ~1.9x over cap
under Gemini's non-determinism; the 1.5x tolerance was too tight.
Bumped to 2.5x — still well under the ~20x a "cap ignored" regression
would produce.
* fix(tests): extend bank-scoped claim filters to 3 more worker tests
CI on the first fix commit surfaced the same cross-file isolation
problem in three additional worker tests. Apply the same bank-scoped
filter pattern so each assertion only counts claims for the bank the
test actually created:
- test_claim_batch_claims_pending_tasks
- test_concurrent_workers_claim_different_tasks
- test_worker_slot_limits_enforced (in this one the executor itself
ignores leaked tasks so its slot-limit gating stays on our tasks)
These flake under parallel xdist because claim_batch() is global
across bank_id; any pending row from another test file gets scooped
up. The per-test filter is defense-in-depth on top of putting
test_async_batch_retain.py in the same xdist_group.
* fix(tests): isolate more slot/executor worker tests from cross-file claims
test-api CI after the previous fix surfaced four more worker tests
flaking the same way: they assert on counts that include tasks the
poller legitimately claims from other test files running in parallel.
Same bank-scoped filter pattern applied in the executor, plus the
poller-internal counter assertions relaxed to >= (our executor
returns immediately for non-our-bank tasks, but the counter may see
them briefly before the slot frees).
Covers:
- test_worker_fire_and_forget_nonblocking
- test_consolidation_slots_reserved_when_retain_saturates
- test_per_operation_slot_reservations (multi-bank variant)
- test_shared_pool_usable_by_reserved_types (preemptive)
* fix(ui): remove unnecessary \- escape in parseBucketIso regexes
ESLint's no-useless-escape flags \- inside a character class when the
dash is not between two chars. Move the dash to the boundary so it's
always a literal without needing an escape.
Pre-existing on main (introduced by #1245); surfaced when verify-
generated-files started exercising this lint path again after #1248.
* chore: sync generated files with committed sources
verify-generated-files was failing because main's committed copies of
two generated/auto-formatted files have drifted from what the scripts
and ruff now produce:
- hindsight-api-slim/hindsight_api/db_url.py: ruff format now collapses
a 2-line list comprehension to 1 line (long-line threshold).
- skills/hindsight-docs/references/developer/configuration.md: the
doc-skill generator emits the Cohere output_dimensions entry that
#1249 added to configuration.md but didn't regenerate the skill copy.
Not functional changes — just aligning the committed outputs with the
generators/formatters.
* fix(tests): isolate test_recall_time_range hardcoded-UUID fixture
This file inserts memory_units with three hardcoded UUIDs
(00000000-…-000{1,2,3}). memory_units.id is a global primary key, so
parallel xdist workers running these tests simultaneously hit
pk_memory_units uniqueness violations (seen intermittently in
test-api CI as fixture-setup ERRORs).
Two defenses:
- Share an xdist_group so the eight tests serialize on the same
worker — prevents concurrent workers from inserting the same IDs.
- Defensive pre-DELETE at fixture setup so a previous interrupted
run's leftover rows don't poison the next setup.
Flake, not a regression from this branch, but surfaces here so
fixing it unblocks the PR.
* fix(tests): filter claims in test_poller_without_tenant_extension_uses_public
One more worker test that asserted len(claimed) == 3 without scoping
to its own bank; scope the assertion to bank_id. Keeps the schema-None
invariant on every claim since no tenant extension is configured.
* fix(docs): escape curly braces in generated changelog entries
LLM-generated changelog summaries occasionally contain literal
`{...}` (e.g. "{user_id}" template variable), which docusaurus MDX v3
tries to evaluate as a JSX expression, breaking SSG with
`ReferenceError: user_id is not defined`.
Escape `{`/`}` in `entry.summary` at render time in the generator, and
hand-fix the two already-landed claude-code changelog files so main's
Deploy Docs workflow goes green again.
* fix(cli): update get_graph call for new chunks API query params
#1236 added chunk_id/document_id/q/tags/tags_match query params to
/banks/{id}/graph but the CLI wrapper was not updated, so a fresh
cargo build fails with an E0061 arity mismatch against the regenerated
progenitor client. Surfaces here because this PR touches hindsight-docs,
which turns on the test-doc-examples (cli) matrix.
Pass None for the new params and keep the existing type_filter/limit
forwarding; argument order matches the alphabetised generated signature.
Add HINDSIGHT_API_EMBEDDINGS_COHERE_OUTPUT_DIMENSIONS to configure
custom embedding dimensions for Cohere models that support Matryoshka
embeddings (e.g. embed-v4.0). Uses the Cohere v2 API when
output_dimensions is set; falls back to v1 API otherwise.
* fix(db): accept asyncpg-style URLs for external PostgreSQL
Fixes#1216. External PostgreSQL deployments (Cloud SQL, RDS, etc.)
configured with a SQLAlchemy-style URL like
`postgresql+asyncpg://user:pass@host/db?ssl=require` failed in two
places:
1. Five sync `create_engine(database_url)` call sites in migrations.py
— psycopg2 doesn't understand the asyncpg dialect, and it expects
`sslmode=require` rather than `ssl=require`.
2. `asyncpg.create_pool(self.db_url)` in memory_engine.py — asyncpg
doesn't parse the `postgresql+asyncpg://` scheme directly.
Adds a single `to_libpq_url()` helper (urllib.parse-based, idempotent,
safe on passwords containing `+`) and applies it at:
- All five `create_engine()` sites in migrations.py (including the
run_migrations advisory-lock connection)
- `asyncpg.create_pool()` in memory_engine.py
- The ad-hoc scheme rewrite in alembic/env.py (replaced by the helper)
Existing configs (`pg0`, plain `postgresql://`, `sslmode=require`,
`postgresql+psycopg2://`) are returned byte-identical — no behaviour
change for current users.
* test(db): pin current production URL shapes as regression guard
* fix(stats): return tz-aware ISO from memories-timeseries
The `/stats/memories-timeseries` endpoint was serializing bucket
timestamps as naive ISO strings (e.g. `2026-04-18T00:00:00`). Browsers
parse naive date-time strings as local time per ECMA-262, so
`formatBucketLabel` in the control plane was shifting chart buckets by
the browser's timezone offset.
Use `datetime.now(timezone.utc)` so the bucket anchor is tz-aware, and
keep incoming `timestamptz` rows in UTC rather than stripping the
tzinfo. Serialized bucket times now end in `+00:00`, matching the
convention used by every other endpoint (`/memories/list`, etc.).
Adds a regression test that asserts every bucket `time` carries an
explicit UTC offset.
* fix(control-plane): parse bucket ISO as UTC when offset is missing
Defensive parse paired with the backend fix. Older API servers may
still return naive ISO strings for `/stats/memories-timeseries` buckets;
`new Date('2026-04-18T00:00:00')` would then be interpreted as local
time and shift the chart by the browser's timezone.
`parseBucketIso` appends a `Z` when no offset is present so the bucket
always anchors to UTC before `toLocaleString` converts it to the user's
locale.
tool_result blocks can have content as a list of content blocks
(e.g. [{"type": "text", "text": "..."}]) instead of a plain string.
This happens with Agent subagent responses. Previously these were
silently dropped during retention, losing ~1-4% of tool results.
Extract text from list content blocks before applying the existing
string handling and truncation logic.
* fix(litellm): handle streaming responses in _store_conversation (#1221)
Streaming responses (CustomStreamWrapper) lack .choices, causing
AttributeError when _format_conversation_for_storage or
_store_conversation_sync tries to access response.choices. Guard
both the monkeypatch wrappers and the callback handler so they
gracefully skip storage for streaming responses.
Also syncs litellm docs with the current configure()/set_defaults()
API, fixes outdated model names, and corrects the litellm version
requirement in README.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* feat(litellm): add stream wrappers for proper streaming storage
Replace bandaid hasattr guard with proper stream wrappers that collect
chunks during iteration and store the complete conversation when the
stream is exhausted. Adds _LiteLLMStreamWrapper (sync) and
_LiteLLMAsyncStreamWrapper (async) following the same pattern as
the existing _StreamWrapper in wrappers.py.
Also refactors message formatting into _format_messages_for_storage
to share between the stream wrappers and _format_conversation_for_storage.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(litellm): add missing final_messages guard in completion/acompletion
The convenience wrappers completion() and acompletion() were missing
the `if final_messages:` guard before the streaming check, unlike
_wrapped_completion/_wrapped_acompletion which had it. Without this
guard, passing no messages would create a stream wrapper with None
messages, crashing in _format_messages_for_storage.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
- Use correct image: ghcr.io/vectorize-io/hindsight:latest (not vectorize/hindsight)
- Correct ports: 8888 (API) and 9999 (Web UI) instead of 8000
- Add required OPENAI_API_KEY environment variable
- Add volume mount for persistent storage
- Add access URLs for API and UI
* feat(api,ui): document chunks API, reprocess endpoint, and enhanced document detail dialog
- Add GET /banks/{bank_id}/documents/{document_id}/chunks endpoint to list chunks with pagination
- Add POST /banks/{bank_id}/documents/{document_id}/reprocess endpoint to re-run retain pipeline
- Add document_id/chunk_id filters to GET /banks/{bank_id}/graph endpoint
- Add nodes_by_fact_type to get_document response (per-type memory counts, no extra queries)
- Replace document side panel with full-screen dialog (General, Content, Chunks tabs)
- General tab: InfoCard layout with memory composition bar and compact constellation view
- Chunks tab: collapsible rows with side-by-side text/memories split, expandable to full DataView
- Content tab: raw text display with inline edit
- Actions dropdown (reprocess, delete) matching mental model dialog pattern
- DataView compact mode: constellation-only with expand/compact toggle
- Regenerate OpenAPI spec and client SDKs
* fix(ci): add new document endpoints to CLI coverage skip list
* feat(api): add exclude_parents filter to list operations endpoint
Batch retain operations create parent + child rows, cluttering the
operations list. Add an `exclude_parents` query parameter that filters
out parent operations (is_parent=true in result_metadata). The control
plane UI now passes this by default so users only see leaf operations.
* test: add unit test for exclude_parents filter
* fix: update Rust CLI and docs skill for new exclude_parents param
* fix(ops): expose processing/cancelled statuses through API and UI
The API was collapsing 'processing' into 'pending' before returning
operation status to clients. Cancel was deleting the operation row
instead of preserving it with a 'cancelled' status.
- Stop mapping processing→pending in list/get operation responses
- Add 'processing' to OperationStatusResponse Literal type
- Change cancel_operation to set status='cancelled' instead of DELETE
- Guard cancel to only accept pending operations (409 otherwise)
- Extend retry to accept both failed and cancelled operations
- Add _check_op_alive support for cancelled status
- Add DB migration for 'cancelled' in status check constraint
- Add processing/cancelled badges and filters in operations UI
- Add cancel/retry buttons in operation detail dialog
- Align stats card status colors and labels with operations table
- Regenerate OpenAPI spec and all client SDKs
* chore: regenerate docs skill openapi reference
* chore: regenerate clients and openapi spec (full sync)
* fix(cli): handle processing/cancelled status variants in Rust CLI
MemoryEngine.delete_memory_unit never called validate_bank_write, so any
authenticated MCP client could delete memories in any bank regardless of
the configured OperationValidatorExtension policy (issue #1218).
No REST endpoint exposes single-memory deletion, and the CLI already
errors out on it. Drop the matching MCP tool and remove delete_memory_unit
from the public MemoryEngineInterface. The engine method stays so internal
observation-invalidation tests still cover the stale-observation sweep.
Also updates the control plane bank-config UI, MCP docs, and skill mirrors
to drop references to the tool.
* fix(claude-code): preserve raw UTF-8 in dynamically-derived bank_id
derive_bank_id() no longer URL-encodes granularity segments before joining
them with "::". The percent-encoding happened at bank_id construction time
and made the identifier itself percent-encoded server-side, which produced
unreadable bank names for any non-ASCII project folder.
HTTP path encoding still happens in the client transport layer (client.py),
which is the correct place. The API server decodes the path back to raw
UTF-8 before reaching handlers, so the DB stores the readable name.
Existing tests updated; added a UTF-8 case.
Bumps plugin version to 0.4.0 (breaking: dynamic bank names change).
* fix(codex): preserve raw UTF-8 in dynamically-derived bank_id
Same issue as claude-code: derive_bank_id() URL-encoded each granularity
segment before join, storing percent-encoded strings as bank identifiers.
Removed the quote call; HTTP path encoding is still handled by client.py.
Added tests/test_bank.py (no bank tests existed before) covering static
mode, dynamic composition, raw special chars, raw UTF-8, prefix, env-var
fields and missing cwd.
Bumps version to 0.3.0 (breaking: dynamic bank names change).
* fix(opencode): preserve raw UTF-8 in dynamically-derived bank_id
Same issue as the claude-code and codex plugins: deriveBankId() called
encodeURIComponent() on each granularity segment before joining with "::",
so bank identifiers themselves ended up percent-encoded server-side.
HTTP request-path encoding is already handled by the hindsight-client
transport layer, which is correct and untouched.
Existing test updated; added a UTF-8 case.
Bumps version to 0.2.0 (breaking: dynamic bank names change).
* revert: drop version bumps and CHANGELOG entry per reviewer request
Reverts the version bumps in claude-code, codex, and opencode plus the
CHANGELOG 0.4.0 section. The bank.py / bank.ts code fix and tests remain.
After Claude Code compacts the conversation, the transcript shrinks.
In full-session mode the retain hook was using the same document_id
(session_id), so the shorter post-compaction transcript would overwrite
the full pre-compaction document, losing all earlier context.
Track per-session message counts and detect when the transcript shrinks.
On compaction, increment a chunk counter and use a suffixed document_id
(e.g. session-c1, session-c2) so the pre-compaction document is
preserved and new content goes to a separate document.
Runs alongside perf-test in parallel. Uses VertexAI/Gemini Flash Lite
for memory engine, answer generation, and judging. Configurable
max_conversations via workflow dispatch (default: 5, set to 0 to skip).
Adds `recallAdditionalBanks: string[]` to the Claude Code plugin config.
When set, the recall hook queries the listed banks after the primary
bank and concatenates their results into the memory context injected
at UserPromptSubmit.
Rationale: many Hindsight deployments split durable identity/profile
facts (e.g. a "ulysses" bank) from per-agent working memory (a
"claude" bank). Previously the plugin could only read from one bank
per session, forcing users to either duplicate facts across banks or
pick just one.
Changes:
- scripts/lib/config.py: declare `recallAdditionalBanks: []` in DEFAULTS
so the key is recognized during config load.
- scripts/recall.py: after the primary recall returns, iterate through
configured additional banks, recall with the same query/budget/types,
and append results. Failures per bank are logged via debug_log and
skipped (one bank being down does not break recall).
Example user config (~/.hindsight/claude-code.json):
{
"bankId": "claude",
"recallAdditionalBanks": ["ulysses"]
}
Co-authored-by: biostartechnology <[email protected]>
With retainEveryNTurns > 1, short Claude Code sessions (fewer turns
than the interval) never hit a retain boundary and their transcript is
silently dropped on session close. SessionEnd previously only stopped
the daemon and did not flush.
Refactor retain.py by splitting main() into:
- main(): reads stdin, delegates to run_retain(hook_input, force=False)
- run_retain(hook_input, force=False): the retain body; force=True
bypasses the retainEveryNTurns turn-counter skip so a caller can
request a final flush.
session_end.py now imports run_retain and calls it with force=True
before stopping the daemon, guaranteeing that every session lands on
disk regardless of length or retain cadence.
Net effect: `retainEveryNTurns: 10` (the default) stops silently losing
sessions under 10 turns.
Co-authored-by: biostartechnology <[email protected]>
Delta retain already knows, at chunk-level granularity, which content
was new vs unchanged on an upsert to an existing document_id. Surface
that signal to post-retain hooks so extensions can reason about "how
much content actually went through the extraction pipeline" without
re-implementing the dedup logic.
New field `RetainResult.processed_content_tokens: int | None`:
* None — the retain went through the full (non-delta) path or has
no dedup signal. Consumers should treat this as "the full
submitted payload was processed."
* 0 — the submission matched prior content exactly; no chunks
went through extraction (metadata-only update).
* N>0 — only N tokens of content+context were actually re-extracted.
The remainder matched existing chunks by content_hash and
was skipped.
Populated in three places:
* Streaming / full retain path → None
* `_try_delta_retain` no-changes fallthrough (`_delta_metadata_only`)
→ 0
* `_try_delta_retain` partial-delta success → sum of
count_tokens(content) + count_tokens(context) across the chunks
built for extraction (delta_contents)
Sub-batch aggregation propagates None if any sub-batch bypassed dedup,
so callers never accidentally undercount when only part of a large
batch was eligible for delta processing.
Tests exercise the full path, unchanged-resubmit, appended-content,
and no-document-id cases plus a unit check on the aggregation helper.
* feat(api): expose retry_count and next_retry_at on operation responses
The async_operations table tracks retry_count and next_retry_at for every
task, but neither was surfaced through the generic list / status endpoints
or plumbed through to validator extensions. That leaves both consumers
(clients watching task state; validators deciding when to retry) unable
to distinguish a freshly-queued pending task from one parked for a future
retry.
Aligns the generic OperationResponse and OperationStatusResponse with the
pattern already used by WebhookDeliveryResponse (which has exposed these
fields since #1042). Also threads retry_count onto RequestContext so
validator extensions can compute per-attempt backoff without querying
the DB themselves.
Changes:
- Add `retry_count: int = 0` and `next_retry_at: str | None = None` to
OperationResponse and OperationStatusResponse. Completed tasks carry
next_retry_at=null; a pending task with next_retry_at in the future
signals the task is parked rather than awaiting immediate pickup.
- list_operations + get_operation_status: include the columns in their
SELECT, emit as ISO-8601.
- Add `retry_count: int = 0` to RequestContext. Worker task handlers
(_handle_batch_retain, _handle_file_convert, _handle_consolidation,
_handle_refresh_mental_model) populate it from task_dict["_retry_count"]
before dispatching. Defaults to 0 for sync/HTTP requests, so no
caller-side change is required.
Tests: two new regression tests in test_async_batch_retain.py — one
asserts both list/status endpoints expose the fields and that an
ISO-8601 next_retry_at round-trips within 1s; the other injects a
capturing validator and asserts RequestContext.retry_count matches
task_dict["_retry_count"] (both present and missing cases).
* fix(api): make retry_count nullable for client backwards-compat
Per PR review: new clients generated against this spec must be able to
decode responses from older servers that do not yet populate
retry_count. Changing the type from `int = 0` to `int | None = None` in
both OperationResponse and OperationStatusResponse makes the field
nullable in the OpenAPI schema, so generated clients treat it as
Optional/nullable rather than required.
Runtime behavior is unchanged: the SQL selects retry_count from a NOT
NULL DEFAULT 0 column, so the server continues to populate the field
with a real integer on every response.
Regenerates:
- hindsight-docs/static/openapi.json, skills/hindsight-docs/references/openapi.json
- TypeScript, Python, and Go client models
Ran: generate-openapi.sh, generate-bank-template-schema.sh,
generate-clients.sh, generate-docs-skill.sh, hooks/lint.sh
* Fix blog post date: April 21 -> April 22
* Update title to: Hindsight Reaches 10,000 Stars: The Community's Choice for Agent Memory
* Fix blog slug to include date path: 2026/04/22/hindsight-10k-stars
* Fix date format to ISO 8601 with time component: 2026-04-22T12:00
Workers used SyncTaskBackend which executed child tasks inline —
e.g. consolidation triggered by retain would block until consolidation
finished, tying up the worker slot for both operations.
Add WorkerTaskBackend whose submit_task is a no-op: since
_submit_async_operation already INSERTs the child row with task_payload,
the poller picks it up on the next cycle as an independent task.
* feat(db): apply configurable Postgres statement_timeout on pool connections
Adds HINDSIGHT_API_DB_STATEMENT_TIMEOUT (default 600s, set 0 to disable).
Applied via the asyncpg pool init hook, so it only affects runtime
queries — Alembic migrations run on a separate psycopg2 engine and are
untouched.
Also fixes the ANN chunk path in the retain orchestrator to restore the
pool's configured statement_timeout rather than RESET, which would fall
back to the server default and silently drop the safety net on that
pooled connection.
* refactor(ann): drop fixed per-query timeout on compute_semantic_links_ann
Now that the asyncpg pool applies a Postgres statement_timeout to every
connection (HINDSIGHT_API_DB_STATEMENT_TIMEOUT, default 600s), the ANN
path can be treated like any other query — no need for the 300s asyncpg
per-query timeout or the orchestrator's SET/restore dance around the
pool's default.
* chore: regenerate hindsight-docs skill to pick up configuration doc change
Re-runs scripts/generate-docs-skill.sh so the skill reference mirror
matches the HINDSIGHT_API_DB_STATEMENT_TIMEOUT row added in
hindsight-docs/docs/developer/configuration.md.
Also picks up unrelated drift (openapi.json version bump, changelog
index) that had accumulated on main.
* feat(perf): add system performance test runner and CI workflow
Add `uv run perf-test` command that orchestrates retain throughput and
recall latency benchmarks using mock LLM + pg0 for deterministic,
LLM-independent baselines. Wraps existing recall_perf/retain_perf
building blocks without duplicating benchmark logic.
Also fixes _RRFReranker in recall_perf.py to include the cross_encoder
attribute now required by the engine's combined scoring path.
* feat(perf): add run-perf-test.sh script
* feat(perf): use run-perf-test.sh in CI, remove run-retain-perf.sh
Replace ad-hoc retain perf wrapper with the new system perf test
script in CI workflow and docs. The standalone retain_perf.py is still
available for ad-hoc document benchmarking.
* feat(perf): add suite input to workflow dispatch
* feat(worker): per-operation slot reservations for worker task claiming
Add per-operation-type reserved slots so operators can guarantee capacity
for each operation type (retain, consolidation, file_convert_retain,
refresh_mental_model). Remaining slots form a shared pool usable by any
operation type.
New env vars:
- HINDSIGHT_API_WORKER_RETAIN_MAX_SLOTS (default 0)
- HINDSIGHT_API_WORKER_FILE_CONVERT_RETAIN_MAX_SLOTS (default 0)
- HINDSIGHT_API_WORKER_REFRESH_MENTAL_MODEL_MAX_SLOTS (default 0)
- HINDSIGHT_API_WORKER_CONSOLIDATION_MAX_SLOTS (default 2, unchanged)
Sum of reservations must be <= WORKER_MAX_SLOTS. Unreserved slots
(max_slots - sum) form the shared pool, usable by any operation type
on a first-come basis.
* refactor(config): derive slot reservation config from single canonical dict
Replace per-operation-type config fields with a single data-driven dict
(WORKER_SLOT_RESERVATION_TYPES) that maps operation types to their env
var and default. Adding a new operation type now requires only one line
in this dict — from_env(), validation, and the reservations dict are all
derived automatically.
Add test_all_operation_types_have_slot_reservation_config that parses
memory_engine.py and asserts every operation_type is covered, so adding
a new type without the config entry fails CI.
* chore: regenerate docs skill and openapi reference
* release: 0.5.4 changelog
Add changelog entry for v0.5.4 with 6 features and 14 bug fixes.
* release: 0.5.4 blog post
Add release blog post covering delta refresh improvements, embedded
daemon recovery, reflect reliability fixes, and retain/worker fixes.
Delta mode mental model refresh was running a full recall across ALL
memories (identical to full mode), then passing all facts to a second
LLM call for delta ops. This caused content bloat, duplication, and
made delta strictly more expensive than full mode.
Changes:
- Add created_after/created_before time range filter to the recall
pipeline (retrieval.py, link_expansion_retrieval.py, graph_retrieval.py)
threaded through recall_async -> reflect_async -> tool closures
- Delta refresh passes last_refreshed_at as created_after so the
agentic loop only retrieves memories created/updated since the last
refresh (uses updated_at to catch consolidation updates)
- Short-circuit delta when no new facts found (skip LLM call, preserve
existing content)
- Accumulate based_on across delta refreshes (merge previous + new,
deduped by ID)
- Pass context to reflect agent during MM refresh with document name,
stay-on-topic guidance, and example preservation instructions
- Rewrite delta prompt: preserve existing content from prior refreshes,
merge overlapping topics, preserve concrete examples over abstract
rules
- Add recall time-range unit tests (8 tests)
- Add integration test verifying delta fusion quality
Re-ingesting a document via retain with the same document_id deletes and
reinserts the documents row, which reset created_at to NOW(). The
ON CONFLICT DO UPDATE branch preserved it, but was never reached because
the explicit DELETE removed the row first.
- Capture created_at via RETURNING on the DELETE and pass it through to
_upsert_document_row, which now uses COALESCE($7, NOW()) on INSERT.
- updated_at continues to advance on every insert/update.
Control plane:
- File upload defaults document_id to the file name so uploads keep a
meaningful identifier instead of a server-generated UUID.
- Documents table shows an "Updated" column alongside "Created".
- Document detail panel supports editing original_text; Save calls retain
with the same document_id and preserves the original context, event
date, metadata, and tags, triggering the upsert path.
Regression test added for created_at preservation.
_ensure_started() had a sticky short-circuit: once _started=True it
never verified the daemon was still alive. If the daemon crashed, all
subsequent calls failed with connection refused.
Now _ensure_started() calls manager.is_running() (HTTP health check)
each time and transparently restarts the daemon if it's unresponsive.
Also simplifies __getattr__ by removing the redundant wrapper closure.
OpenAIEmbeddings hardcoded batch_size=100 is incompatible with some
OpenAI-compatible providers that enforce smaller per-request limits
(e.g. DashScope / Aliyun Tongyi caps at 10). Without an override,
retain paths that extract > 10 facts fail with 400 errors.
Expose HINDSIGHT_API_EMBEDDINGS_OPENAI_BATCH_SIZE (default 100) and
propagate it to both the 'openai' and 'openrouter' providers, which
share the same OpenAIEmbeddings client. Values <= 0 or non-integer
are rejected at config load time (_parse_positive_int) to fail fast
instead of triggering infinite loops or zero-step range() calls.
The new HindsightConfig field has a dataclass default so existing
direct constructors (tests, external integrations) keep working.
Fixes#1142.
When a bank has directives but no memories, the LLM short-circuits the
reflect agent loop by returning text directly (no tool calls). Because
the system prompt includes directives marked as MANDATORY, the LLM
echoes the directive text verbatim as its answer.
Fix: when directives are present but no evidence has been gathered,
skip accepting the text response and fall through to the final-prompt
path, which uses FINAL_SYSTEM_PROMPT (no directives) and handles
"no data" gracefully.
Users were not seeing auto-retain fire because 10 turns is too high
a bar for typical sessions. Lowering to 3 makes the feature work
out of the box without config changes.
Co-authored-by: Claude Opus 4.6 <[email protected]>
* docs(mcp): document update_bank config_updates and configurable fields
Follow-up to #1168: update_bank now accepts config_updates with all
bank-configurable fields (reflect_mission, retain_*, disposition_*,
entity_labels, recall_*, mcp_enabled_tools, etc.). Existing docs only
showed name + mission; callers had to read mcp_tools.py to discover the
full surface.
Mirrored to skills/hindsight-docs/references/developer/mcp-server.md per
the dual-doc convention (#1137).
* docs(mcp): mirror update_bank config_updates docs to skills reference
* fix(alembic): merge divergent heads for v0.5.3
v0.5.3 shipped with two migration heads that were never unified:
* c4x5y6z7a8b9 — delta-refresh chain
(last_refreshed_source_query -> structured_content ->
backsweep_orphan_observations_v2)
* h3i4j5k6l7m8 — per-bank vector indexes / audit log chain
Both fork from z1u2v3w4x5y6.
This is a structural DAG bug — independent of any specific upgrade path.
Consequences:
* alembic upgrade head (singular) is ambiguous for every v0.5.3
install. Hindsight's startup uses "heads" (plural) so it works
around this, but any dev/ops tooling using the singular form errors
with "Multiple head revisions are present".
* No future migration can chain cleanly — it has to pick one head as
parent, orphaning the other branch.
* Upgrades from v0.5.2 leave alembic_version with two rows stamped
(one per head). The database operates normally, but that split
state trips alembic's walker in some corner cases, e.g. databases
carrying stale multi-head rows from a pre-v0.5.0 era see
"CommandError: Requested revision X overlaps with other requested
revisions Y" at startup.
This change:
* Adds an empty merge revision (8c6fa6f7230b) that unifies the two
heads into a single head. No schema effect.
* Adds a graph-level regression test (tests/test_alembic_dag.py)
that asserts get_heads() returns exactly one head and get_bases()
returns exactly one base. The tests parse revision files on disk,
don't touch a database, run fast in CI, and would have caught
v0.5.3's split DAG before release.
Verified locally: the test fails (AssertionError: Alembic has 2 heads
['c4x5y6z7a8b9', 'h3i4j5k6l7m8']) when the merge file is removed; passes
with it in place. A scratch database restored from a v0.5.2-era backup
walked cleanly to 8c6fa6f7230b (head) (mergepoint) via alembic upgrade
heads, with schema intact.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
* chore(docs): regenerate skill doc to match generate-docs-skill.sh output
CI verify-generated-files check on previous commit was red because
skills/hindsight-docs/references/developer/configuration.md was
1 line out of sync with what `./scripts/generate-docs-skill.sh`
produces. Regenerated; only link-rewrite change (absolute docusaurus
path → relative .md path with .md extension) on the merge-docs
callout.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
Two bugs in the streaming retain pipeline caused duplicate/stale memory units
when documents were upserted multiple times:
1. **Out-of-order chunk index assignment**: The producer-consumer pipeline
extracted facts from chunks concurrently, but assigned chunk_index based on
task completion order rather than the original document position. This caused
chunks to be stored at scrambled indices, making delta retain unable to
detect unchanged chunks on subsequent upserts (always falling back to
expensive full re-processing).
2. **Concurrent upsert race condition**: The streaming path splits document
tracking (cascade-delete) and chunk/unit creation into separate transactions
with LLM extraction in between. Two concurrent retains for the same document
could interleave, producing duplicates or stale data.
Fixes:
- Use the original `global_idx` (position in pre-chunked content) for
chunk_index instead of arrival-order-based offset
- Add a PostgreSQL advisory lock per (bank_id, document_id) to serialize
concurrent retain operations on the same document
- Add stale-request detection: after acquiring the lock, skip if the document
was already updated by a more recent retain (prevents older content from
overwriting newer conversation state)
- Use pg_try_advisory_lock with pool.acquire timeout to avoid deadlocks
when pool is near capacity (graceful degradation)
- Fix content hash mismatch in recovery detection (sanitize before hashing
to match what handle_document_tracking stores)
* fix(reflect): honor reflect_mission identity framing in prompt builder
When a bank's reflect_mission uses first-person identity framing
(e.g. "You are Rei..."), promote it to the primary role declaration
in the system prompt instead of appending it as metadata. This ensures
reflect() and mental model generation produce in-voice output matching
the mission's persona.
Non-identity missions (task-oriented or empty) are unaffected.
Closes#1159
* simplify: use reflect_mission as role whenever set, drop identity detection heuristic
* docs(admin-cli): document decommission-workers and worker-status
PR #1165 added two new admin CLI commands (decommission-workers,
worker-status) but admin-cli.md was not updated. Readers scanning the
Commands section could only find the singular decommission-worker.
Added dedicated sections for each new command following the existing
style (Arguments/Options/Examples/When to Use). Pure docs, mirrors
behavior documented in typer command help strings.
* docs(admin-cli skill): sync decommission-workers and worker-status
Mirror change from hindsight-docs/docs/developer/admin-cli.md so the
docs skill reference stays in sync (matches the pattern set by #1137).
The MCP update_bank tool was writing mission to the legacy DB column
instead of the config system, causing silent data loss. Now uses a generic
config_updates dict that passes through to config_resolver.update_bank_config(),
automatically supporting all current and future configurable fields without
MCP tool changes.
Closes#1156
* fix(worker): scan for active schemas before claiming
claim_batch now calls _scan_active_schemas before iterating schemas
for claims. The scan uses a server-side PL/pgSQL function
(schemas_with_pending_work) that checks all tenant schemas for
pending rows in a single DB round-trip (~200ms). Only schemas the
scan identifies as active are visited with the expensive FOR UPDATE
SKIP LOCKED claim query.
Previously, claim_batch iterated ALL schemas (1400+ in large
deployments) with the claim query on every poll. With the dual-pool
break condition from #1006 (requires both non-consolidation AND
consolidation pools to be zero before breaking), unfilled pool types
caused the loop to walk every schema even when only a few had work.
Measured at 15.8 seconds per poll from a worker pod through
pgbouncer.
After this change: 217ms scan + claims on active schemas only.
Falls back to per-schema Python EXISTS checks if the server-side
function is not installed.
Tests:
- scan correctly identifies schemas with pending rows
- claim_batch only queries schemas the scan found active
- existing fairness/rotation tests pass unchanged
* docs(worker): add server-side function definition to _scan_active_schemas docstring
When json.dumps() serializes non-ASCII text (Korean, Japanese, Chinese, etc.)
with the default ensure_ascii=True, characters are escaped as \uXXXX sequences.
This makes LLM prompts significantly harder to read and degrades comprehension
quality for multilingual content.
Affected paths:
- Consolidation: observation text in prompts
- Reflect: schema, tool output, tool arguments, error messages
- LLM providers: JSON schema instructions (OpenAI, Anthropic, Gemini, Codex,
Claude Code), batch JSONL, error body summaries
- Search: fact formatting for recall prompts
Note: DB storage calls (history_entry, batch_state, etc.) intentionally keep
ensure_ascii=True since PostgreSQL handles UTF-8 natively and the escaped
form is equivalent for storage.
PR #1105 added DeferOperation support in the worker poller
(poller._execute_task_inner catches it and routes to _defer_operation
without bumping retry_count or writing error_message). The outer
dispatcher in MemoryEngine.execute_task, however, still had a
generic `except Exception` that converted every exception — including
DeferOperation — into a RetryTaskAt(60s).
Result: a task deferred hours out (e.g. by a backpressure-aware
validator raising DeferOperation to wait for a quota window) instead
came back in 60 seconds with retry_count bumped, losing the "defer is
not a failure" semantics.
Fix: add `except DeferOperation: raise` alongside the existing
RetryTaskAt passthrough.
Test: new regression test exercises MemoryEngine.execute_task with a
validator that raises DeferOperation from validate_retain, asserting
the exception escapes intact.
When the LLM provider is unavailable at startup (e.g. 429 quota exhaustion),
the server now logs a warning and continues booting instead of crash-looping.
This lets queued operations process once the provider becomes available.
Fixes#1147
* feat(claude-code): add {user_id} template var and drop dangling tags
Resolve {user_id} from HINDSIGHT_USER_ID env var in retainTags and
retainMetadata. After template resolution, tags whose namespace part is
empty (e.g. 'user:' when HINDSIGHT_USER_ID is unset) are dropped from
the outgoing retain request, so a single portable config works whether
or not the user id is set.
Existing behavior preserved: empty/None retainTags -> tags=None; tags
without ':' are never dropped; fully-resolved tags with non-empty
content pass through unchanged.
* test(claude-code): cover {user_id} template var and dangling-tag drop
Four new cases in TestRetainHook:
- {user_id} resolves from HINDSIGHT_USER_ID env var (via _run_hook's
extra_env, since the helper strips real HINDSIGHT_* env vars by design)
- dangling 'user:' is dropped when env is unset; other tags survive
- colon-less tags are preserved regardless of env state
- all-dropped tags produce a request with no 'tags' field
Full suite: 133 passed.
* docs(claude-code): document {user_id} template var and dangling-tag drop
- README: expand retainTags description to enumerate all four template
placeholders ({session_id}, {bank_id}, {timestamp}, {user_id}), add a
Template variables reference table, and add a per-user memory scoping
example showing HINDSIGHT_USER_ID usage and recall filter pattern.
- retainMetadata description updated to note shared template support.
- CHANGELOG: add [Unreleased] section with Added (new template var) and
Changed (dangling-tag drop semantics) entries.
Adds two new admin CLI commands for diagnosing and recovering from
worker crashes (addresses #991):
- `decommission-workers`: resets ALL processing tasks back to pending
regardless of worker_id (unlike existing `decommission-worker` which
requires knowing the dead worker's ID)
- `worker-status`: shows all processing tasks grouped by worker with
operation type, bank, runtime, and last update time
list_operations was hardcoding items_count to 0 instead of reading it
from result_metadata, which is already fetched by the query and correctly
populated during retain/batch_retain submission.
Fixes#1146
ReflectBasedOn.mental_models used {id, name, content?} but the server
emits {id, text, context?}. ReflectBasedOn.directives was missing the
name field. This caused type incompatibility with HindsightClient from
@vectorize-io/hindsight-client, requiring an unsafe cast.
* docs(sdk): add document CRUD methods to TypeScript client reference
PR #1118 added getDocument, listDocuments, deleteDocument, and
updateDocument to HindsightClient (aligning with [email protected])
but the SDK docs page was not updated.
Closes#1131
* sync generated nodejs.md with docs source
* docs: fix HINDSIGHT_API_LLM_MAX_RETRIES default (10 → 3)
PR #1121 reduced the default from 10 to 3 but docs were not updated.
* sync generated configuration.md
* docs(openai-agents): fix SDK version requirement, add memory_instructions docs
- Fix README and docs page to say openai-agents >= 0.7.0 (was 0.1.0)
matching the actual pyproject.toml requirement
- Add memory_instructions() section to both README and docs page
- Add memory_instructions() API reference table to docs
- Add Auto-Inject Memories bullet to Features list
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* polish(openai-agents): add production patterns to README, config tests, fix docs URL
- Add Production Patterns section to README (error handling, bank
lifecycle, multi-agent workflows) matching other mature integrations
- Add dedicated test_config.py with 13 tests (defaults, configure,
env var fallback, reset) matching pydantic-ai pattern
- Fix pyproject.toml Documentation URL to point to integration-specific
docs page instead of generic repo root
Co-Authored-By: Claude Opus 4.6 <[email protected]>
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
* feat: add consolidation_max_memories_per_round config
Prevents a single bank with a large backlog from monopolizing a worker
slot. When the limit is reached, the consolidation job yields its slot
and re-queues itself so other banks get fair scheduling. Mental model
refreshes only run on the final round (when all memories are processed).
Default: 100 memories per round. Set to 0 for unlimited (previous behavior).
Configurable per bank via the config API.
* fix(docs): fix broken anchors in blog post and installation pages
- Blog post linked to non-existent #embeddings--reranker-providers anchor
- Installation pages linked to removed #package-variants heading
* fix: update configurable fields count and add openai-agents frontmatter
- Bump expected configurable field count from 34 to 35 (new consolidation_max_memories_per_round)
- Add missing title/description frontmatter to openai-agents integration doc
* chore: regenerate docs skill references
* chore: fix openai-agents formatting (pre-existing lint drift)
10 retries is excessive and causes long delays on persistent LLM errors.
3 retries is sufficient for transient failures while failing fast on real issues.
Two improvements for self-hosted reranker reliability:
1. Include exception type name in recall error messages so that empty-string
exceptions (e.g. httpcore.ReadTimeout) produce a useful message instead of
'Failed to search memories: ' with no context.
2. Add HINDSIGHT_API_RERANKER_TEI_HTTP_TIMEOUT env var (default: 30.0s) to
configure the HTTP timeout for the TEI reranker. Previously hardcoded,
making it impossible to raise the limit for slower CPU-based rerankers
under consolidation load.
Co-authored-by: octo-patch <[email protected]>
MLX's Metal device is not thread-safe. When consolidation and recall
trigger the jina-mlx reranker concurrently via run_in_executor, two
threads race on Device::end_encoding(), causing a NULL pointer deref
(EXC_BAD_ACCESS / SIGSEGV at 0x0).
Add a threading.Lock to JinaMLXCrossEncoder._predict_sync() so all
MLX inference is serialized. Single-lock, no nesting — zero deadlock
risk. Worst-case added latency ~200-400ms on concurrent rerank calls.
* fix(control-plane): clearer constellation recency legend & node tooltip
- Switch heat ramp to a perceptually monotonic cool-blue → warm-orange so
the gradient reads as a real scale at a glance (the prior 4-stop ramp
through magenta wasn't perceptually ordered).
- Drop the sqrt distortion in the recency mapping so a node's color
reflects its actual fraction of the time range, not a value squished
toward "newer".
- Make the legend explicit about what date drives the color: label now
reads e.g. "RECENCY · MENTIONED" and the gradient endpoints show the
actual oldest/newest dates currently in view.
- Auto-size the gradient bar so longer endpoint labels (ISO dates) don't
overlap, and reorder the size legend to "few • • ● many" to fix the
prior label collision.
- Tooltip now shows Occurred (start → end when ranged) and Mentioned
with date+time, dropping the deprecated `date` and `created_at` rows.
- Data view exposes a "Color by" select (Mentioned / Occurred start /
Occurred end) in the right panel, so the constellation keeps its full
width.
* chore: regenerate docs-skill for DeferOperation section
* fix(migrations): restore broken chain for v0.4.22 → v0.5.x upgrades
v0.4.22 shipped migration d6e7f8a9b0c1 (drop unused documents.metadata
column). In v0.5.0 that file was deleted and its revision ID was
accidentally reused by 2eee35aa3cfc (case-insensitive trigram index).
Any database stamped at d6e7f8a9b0c1 from v0.4.22 would crash on
upgrade to v0.5.x because alembic resolved the ID to a different
migration with an incompatible down_revision tree.
Fix:
- Restore d6e7f8a9b0c1 with the original DROP COLUMN logic
- Give 2eee35aa3cfc its own unique revision ID (was colliding)
- Chain: d6e7f8a9b0c1 → 2eee35aa3cfc → a4b5c6d7e8f9 → h3i4j5k6l7m8
- Remove dead doc_metadata field from Document model (column is dropped)
* chore: fix trailing newline in migration file
Three mismatches between hindsight-ai-sdk and hindsight-client caused
TypeScript errors and a runtime crash when the LLM invoked getDocument:
1. Add getDocument/listDocuments/deleteDocument/updateDocument methods
to the HindsightClient class (wrapping the generated SDK calls).
2. Fix ReflectResponse.based_on type from flat ReflectFact[] to the
actual nested { memories, mental_models, directives } structure.
3. Fix MentalModelResponse: rename mental_model_id → id, make name
required, make timestamps nullable — matching the generated types.
Closes#1114
On Windows, open() defaults to the system locale encoding (cp1252)
instead of UTF-8. Claude Code and Codex transcript JSONL files
contain UTF-8 bytes (e.g. 0x9d) that are invalid in cp1252,
causing UnicodeDecodeError in the auto-retain and auto-recall hooks.
This silently prevented all transcript processing on Windows.
Affected files:
- claude-code/scripts/retain.py (read_transcript)
- claude-code/scripts/recall.py (read_transcript_messages)
- codex/scripts/lib/content.py (_read_transcript_text, _read_transcript_rich)
Co-authored-by: Claude Opus 4.6 <[email protected]>
* feat: add OpenAI Agents SDK integration for Hindsight
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(openai-agents): add memory_instructions, fix bugs, add CI, harden tests
- Add memory_instructions() for auto-injecting memories into agent system
prompt via a callable compatible with Agent(instructions=...)
- Fix or-vs-is-not-None bugs in reflect_max_tokens and reflect_tags_match
that silently ignored falsy values like 0
- Surface entity data in recall output when recall_include_entities=True
- Add user_agent tracking in _client.py for analytics
- Tighten openai-agents dependency to >=0.7.0
- Add CI test job for openai-agents integration in test.yml
- Add 9 new unit tests (31→40 total): entity surfacing, memory_instructions
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix(openai-agents): address review findings from PR #842
- Deduplicate version string into _version.py to prevent drift
- Fix memory_instructions to fall back to config.max_tokens
- Simplify error handling: remove misleading HindsightError re-raise
- Use `is not None` check for reflect response.text (empty != missing)
- Use getattr for entity access instead of fragile hasattr chain
- Add tests for memory_instructions config fallback (max_tokens, tags)
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(control-plane): clearer constellation recency legend & node tooltip
- Switch heat ramp to a perceptually monotonic cool-blue → warm-orange so
the gradient reads as a real scale at a glance (the prior 4-stop ramp
through magenta wasn't perceptually ordered).
- Drop the sqrt distortion in the recency mapping so a node's color
reflects its actual fraction of the time range, not a value squished
toward "newer".
- Make the legend explicit about what date drives the color: label now
reads e.g. "RECENCY · MENTIONED" and the gradient endpoints show the
actual oldest/newest dates currently in view.
- Auto-size the gradient bar so longer endpoint labels (ISO dates) don't
overlap, and reorder the size legend to "few • • ● many" to fix the
prior label collision.
- Tooltip now shows Occurred (start → end when ranged) and Mentioned
with date+time, dropping the deprecated `date` and `created_at` rows.
- Data view exposes a "Color by" select (Mentioned / Occurred start /
Occurred end) in the right panel, so the constellation keeps its full
width.
* chore: regenerate docs-skill for DeferOperation section
* feat(mental-models): structured-ops delta refresh + observation cleanup on upsert
Mental model delta mode (primary feature)
- Store mental models as a structured document (sections + typed blocks) in
a new `structured_content` JSONB column. Markdown shown to users is a
deterministic render of the structured doc, never an LLM output.
- Delta refresh emits typed operations (`append_block`, `replace_block`,
`add_section`, `remove_section`, `replace_section_blocks`, …) against the
structured doc. Sections not mentioned by any op are physically copied
through unchanged, so prose drift is structurally impossible.
- Text-mode JSON for the LLM call (Gemini rejects the discriminated-union
schema Pydantic emits); we parse + validate ourselves.
- Token budget for the delta call is 1.5× the doc cap with a 2048 floor and
the budget is surfaced in the prompt so models can self-trim.
- New `mode: "full" | "delta"` enum on the trigger jsonb. First refresh on
an empty document falls back to full; a source_query change forces full
rebuild via `last_refreshed_source_query` tracking column.
- Worker handler `_handle_refresh_mental_model` now delegates to the public
`refresh_mental_model` (single source of truth — previously had its own
copy of the reflect+update pipeline that bypassed delta entirely).
- Refuse to overwrite existing content with an empty render — small models
occasionally return empty answers from the reflect agent and the previous
behaviour destroyed the working document on transient failures.
Observation cleanup on document upsert (production bug fix)
- `fact_storage.handle_document_tracking` (the retain/upsert path) used to
delete the document row via FK cascade, removing the source memory_units
but leaving observations whose source_memory_ids referenced now-deleted
rows. Only the explicit `MemoryEngine.delete_document` API ran the
cleanup.
- Extracted `delete_stale_observations_for_memories` to a free function in
`fact_storage.py`; both code paths (retain upsert + delete API) now run
the same SQL.
- Migration `c4x5y6z7a8b9` re-runs Pass 2 of `g7h8i9j0k1l2` to sweep the
orphan observations that accumulated since the last cleanup.
UI
- Refresh-mode select in create/update mental model dialogs.
- Per-row actions dropdown (Edit / Refresh / Delete) on dashboard + table,
matching the detail dialog's actions menu.
- History diff view: per-token whitespace-insensitive inline diff so only
the actually-changed substrings light up red/green; runs of unchanged
lines render as plain text.
- Mental-model dialogs widened to `sm:max-w-2xl` and the scroll wrapper
inherits the global themed scrollbar (matches the detail modal layout).
- Auto-refresh badge colour unified to green across all surfaces.
Operational logging fixes
- Surface the actual provider response body on `APIStatusError` retries in
`openai_compatible_llm` instead of only logging on final failure. New
`_summarize_status_error` helper used in `call()` and `call_with_tools()`.
- Consolidator now logs the failing memory IDs in batch-LLM warnings, so
`json_validate_failed` + similar errors can be traced to a specific
memory without waiting for adaptive bisection to narrow it down.
- Worker `[WORKER_STATS]` pool metric was mis-labelled: `waiters` was
reading `pool._queue.qsize()` (free holders), the opposite of what the
name implied. Split into `free_holders` (idle holders in queue) and
`pending_acquires` (`len(_queue._getters)` — actual coroutines blocked
on `pool.acquire`).
Tests
- 39 unit tests in `test_structured_doc.py` covering schema, renderer,
parser, op application, ID stability, byte-identical preservation.
- 6 plumbing tests in `test_mental_model_delta.py::TestDeltaRefreshPlumbing`
covering full/delta branching, source-query change → full rewrite,
per-row LLM-failure fallback, etc.
- 3 real-LLM eval tests in `TestDeltaRefreshGeminiEval` (gated on
`HINDSIGHT_RUN_GEMINI_EVALS=1`, prefers Gemini, falls back to OpenAI).
Migrations
- `a2v3w4x5y6z7` — `last_refreshed_source_query TEXT`
- `b3w4x5y6z7a8` — `structured_content JSONB`
- `c4x5y6z7a8b9` — backsweep orphan observations v2
* chore: regenerate clients + add regression tests + lint fixups
- Regenerate OpenAPI spec and Python/TypeScript/Go client SDKs to surface
the new `mode` field on `MentalModelTrigger`.
- Add regression test for the empty-content guard: when reflect_async
returns "" and the structured-delta call also fails, refresh must NOT
overwrite existing content (was destroying working documents).
- Add regression test for the upsert observation cleanup: directly invoke
`handle_document_tracking` with pre-populated source memories +
observation, assert the observation is gone after the upsert and the
surviving co-source memory is reset for re-consolidation.
- Lint hook reformatted long log strings in consolidator.py /
memory_engine.py / fact_storage.py and ran prettier across the new
control-plane TS code.
* fix(rust-cli): set mode=Full on MentalModelTriggerInput; refresh generated artefacts
- Generated Rust client now requires `mode: Mode` (not Option) on the
MentalModelTriggerInput struct since the Python field has a default. Set
to `Mode::Full` at the call sites in `commands/mental_model.rs`.
- Re-run `generate-openapi.sh` and `generate-docs-skill.sh` after rebasing
on origin/main so the spec includes upstream additions
(`failed_consolidation` from #1100). Without this, the new spec dropped
the field and `check-openapi-compatibility` failed.
- `skills/hindsight-docs/references/openapi.json` is the doc-skill copy of
the spec; was missing from the previous commit.
* chore: regenerate bank-template-schema.json
Auto-generated from BankTemplateConfig; updated by the structured-doc /
mental-model trigger changes earlier in this PR. ``verify-generated-files``
CI step caught it.
* docs(mental-models): document delta refresh mode
Add a "Refresh Mode" section to the mental-models API docs covering the
new ``mode: "full" | "delta"`` trigger field — strategy explanation,
fallback rules (no existing content / source_query change), empty-answer
preservation, and a quick "when to use which" table.
Extensions that need to apply backpressure (rate-limited upstream,
quota window not yet open, dependency warming up) can now raise
DeferOperation(exec_date, reason) from any task-handler hook to
requeue the operation for a future time, without counting as a retry.
Unlike RetryTaskAt this does not increment retry_count or write
error_message. The poller already filters claim_batch by next_retry_at,
so no migration is needed.
Documented as worker-only — raising it from validate_recall /
validate_reflect in synchronous HTTP request paths will surface as
a 500 since there is no queue to defer to.
* feat(recall): make budget mapping configurable per bank
The Budget enum (low/mid/high) used to map to hardcoded thinking_budget
values (100/300/1000) regardless of the request's max_tokens. This adds
a configurable mapping function:
- "fixed" (default, preserves legacy behavior): per-level integer
read from recall_budget_fixed_<level>.
- "adaptive": round(max_tokens * recall_budget_adaptive_<level>),
clamped to [recall_budget_min, recall_budget_max] so retrieval
breadth scales with the requested output size.
All 9 knobs (function selector, 3 fixed values, 3 adaptive ratios,
min/max clamps) are hierarchical config fields — overridable via env
vars and per bank through the existing bank-config API. Validation in
ConfigResolver rejects invalid functions, non-positive values, and
min > max.
* docs(recall-budget): expose new fields in bank template + import API
Adds the 9 recall_budget_* fields to BankTemplateConfig so they can be
set via POST /v1/default/banks/{id}/import (the bank-template manifest
flow), and documents them in the memory-banks API page alongside the
other configurable bank fields.
- Extends BankTemplateConfig in api/http.py with the 9 fields.
- Adds them to the round-trip parametrized test in
test_bank_template_configurable_fields.py.
- Adds a "Recall budget" subsection to memory-banks.mdx covering the
function selector and per-level / clamp fields, with cross-link to
the env-var reference in configuration.md.
- Regenerates openapi.json, bank-template-schema.json, and the
Python/TypeScript/Go client models.
* fix(recall-budget): bump field-count cap and regen docs-skill refs
- test_config_get_bank_config_no_static_or_credential_fields_leak asserts
the resolved-config dict size; cap was 30, now 34 fields fit (added 9).
Bump to 50 to leave headroom for future configurable fields.
- Run scripts/generate-docs-skill.sh so the mirrored docs in
skills/hindsight-docs/references/ pick up the new memory-banks /
configuration entries and openapi schema.
Consolidation reads a source memory, calls an LLM for several seconds, then
writes an observation referencing that source. If the source memory was
hard-deleted during the LLM call, the observation landed referencing a
now-missing uuid — the delete's stale-observation sweep had already run and
could not see the not-yet-inserted row. source_memory_ids is a uuid[] so
Postgres cannot cascade through it, making this manual cleanup necessary.
Two coordinated changes close the race:
- Consolidator filters source_memory_ids against live rows with SELECT ... FOR SHARE
inside the same transaction as the INSERT/UPDATE, dropping any id whose row
has already been deleted and blocking concurrent deletes until the write
commits. Skips the create/update entirely when no live sources remain.
- Delete paths (delete_memory_unit, delete_document, delete_bank by fact_type)
now DELETE the source rows first and run the stale-observation sweep
afterwards, so any observation that was inserted concurrently is also
caught by the sweep under READ COMMITTED.
Adds three regression tests exercising the consolidator helpers directly with
mixed live/dead and all-dead source_memory_ids.
Reasoning models (e.g. qwen3.5) route their entire response to the
thinking field when think is not explicitly set to false, leaving
message.content empty. This breaks structured output (fact extraction,
etc.) for any Ollama reasoning model.
Adding "think": False to the /api/chat payload disables thinking mode.
Non-reasoning models (e.g. gemma3) ignore the unknown field, so this
is a safe no-op for them.
Fixes#1098
Co-authored-by: Claude Opus 4.6 <[email protected]>
Default `retainDocumentScope: 'session'` produces a stable per-session
documentId. Without `update_mode: 'append'` (added to Hindsight in #932,
shipped in 0.5.0), every retain on the same documentId overwrote the
existing document server-side — only the latest retain's slice (the
last user message + assistant replies) survived. Banks ended up with
one document per session containing only the last turn.
Fix: capability-detect at service.start by probing GET /version and
parsing api_version. When the API supports update_mode=append (>=
0.5.0), use the session-scoped documentId AND set updateMode='append'
so each retain concatenates to the existing document. When the API is
older (or /version is unreachable / malformed), fall back to per-turn
documentIds (`<base>:turn:<6-digit-idx>`) so prior turns aren't lost,
and emit a one-time WARN block telling the user to upgrade.
- types.ts: add `updateMode?: 'replace' | 'append'` to RetainRequest
- retain-queue.ts: persist + replay updateMode through the JSONL queue
- index.ts:
- `meetsMinimumVersion(actual, minimum)` semver helper
- `fetchHindsightApiVersion()` probes GET /version (5s timeout,
null on failure -> conservative legacy-mode fallback)
- `detectAppendCapability()` flips `supportsUpdateModeAppend`,
warns on first probe-when-unsupported and on supported→unsupported
transitions; stays silent on repeat probes confirming the same
unsupported state
- Wired into all 4 checkExternalApiHealth call sites
- `buildRetainRequest` takes `appendSupported` option; emits
session-scoped doc + updateMode='append' only when both
documentScope='session' AND appendSupported=true
- Default for omitted `appendSupported` is `false` (conservative —
prevents data loss when the flag isn't threaded through)
Tests:
- meetsMinimumVersion: equal / newer / older / pre-release / partial /
malformed
- buildRetainRequest: session+append when capable, per-turn fallback
when not, per-turn when flag omitted
- 194/194 passing.
No client/peerDependency change — runtime detection handles both
versions.
* feat(control-plane): surface failed-consolidation count and drilldown
Adds a "Failed" cell to the Consolidation card on the bank General page
that shows how many memories are stuck with consolidation_failed_at. When
non-zero, the cell opens a dialog listing the affected memories with a
"Recover all" action that resets the failed flag and queues a
consolidation run so the worker actually retries them.
Backend: additive only — `failed_consolidation` on BankStatsResponse and
an optional `consolidation_state` filter (failed|pending|done) on
/memories/list. Existing fields and callers are unchanged.
* fix(cli): pass consolidation_state arg through list_memories
* chore: regenerate docs-skill openapi reference
* test(file-retain): regression test for timestamp -> event_date mapping
Locks in PR #1092: _handle_file_convert_retain must translate the user-facing
'timestamp' field to the internal 'event_date' key (including the 'unset'
sentinel) before submitting the inner batch_retain task. Without this mapping
the retain orchestrator silently defaulted every file-retained memory to
utcnow().
The test intercepts the inner batch_retain submission from the handler and
covers all three inputs: explicit ISO timestamp, 'unset' (must set event_date
to explicit None), and omitted/None (event_date key must be absent so the
orchestrator falls back to utcnow()).
* test(file-retain): cover document_id, context, metadata, tags, strategy, document_tags
Extends the content-dict flow-through coverage so the same silent-drop bug
class as PR #1092 can't recur on a different key. The new test drives
submit_async_file_retain with non-empty values for every FileRetainMetadata
field plus request-level document_tags, intercepts the inner batch_retain
submission from _handle_file_convert_retain, and asserts each field arrives
at the retain pipeline with the right key and value.
Existing file retain tests only asserted HTTP 200 or inspected the outer
file_convert_retain task_payload; nothing verified what reached the retain
pipeline.
Follow-up to #1091. That PR made _submit_async_operation insert
task_payload atomically in the same row that the async_operations
row is created, closing a crash-window that left orphaned
NULL-payload rows. The follow-up call to _task_backend.submit_task is
still needed so SyncTaskBackend can execute the task inline in tests
and embedded mode, but for BrokerTaskBackend the call redundantly
UPDATEd task_payload and bumped updated_at on a row that was already
claimable — and could even touch a row that a worker had already
claimed and transitioned to processing/completed.
Make the UPDATE a no-op when task_payload is already set by adding
`AND task_payload IS NULL` to the WHERE clause. Existing callers
that still rely on a two-step INSERT-then-submit pattern (legacy/
fallback) continue to work, but the common path stops writing to a
row it has nothing new to say about.
Also add two regression tests:
- test_worker.py::test_submit_task_preserves_existing_payload
locks in the idempotent semantics at the backend level.
- test_async_batch_retain.py::
test_submit_async_operation_leaves_claimable_row_when_submit_task_fails
simulates a crash between the INSERT transaction commit and
submit_task by mocking submit_task to raise, and asserts the
row is still born claimable (status=pending, task_payload
populated). This is the invariant the original bug violated.
Include task_payload in the async_operations INSERT atomically instead
of the previous two-step INSERT-then-UPDATE approach. When a crash or
timeout occurred between the two statements, rows were left with
task_payload IS NULL. The worker claim query filters on
task_payload IS NOT NULL, so those orphaned rows became permanently
stuck as unclaimed pending tasks.
Co-authored-by: Christian Cabauatan <[email protected]>
Map the timestamp field to event_date when building retain contents in
_handle_file_convert_retain_task. The previous code passed timestamp
as-is, but the retain pipeline expects event_date. Also handles the
special "unset" sentinel to explicitly clear the date.
Co-authored-by: Christian Cabauatan <[email protected]>
* feat(mental-models): staleness signal + history reflect snapshot + UI revamp
Backend
- Add MemoryEngine.compute_mental_model_is_stale(): scope-aware check
using MM tags + trigger.tags_match (+ fact_types filter). Replaces the
bank-wide `pending_consolidation > 0` shortcut that falsely flagged
unrelated MMs and missed the "consolidation done, MM not refreshed"
case.
- MentalModelResponse.is_stale (detail=full) exposes the flag on the API.
- Consolidation refresh trigger and tool_search_mental_models now use the
shared helper, so refreshes only fire for MMs whose scope actually has
new memories.
- history entries now snapshot previous_reflect_response (based_on +
answer) alongside previous_content, so the UI can show per-version
grounding.
UI (control plane)
- Replace the right-side MentalModelDetailPanel with a near-fullscreen
Dialog (Content / Configuration / History tabs).
- Content tab: stored-content card with In sync / Stale badge, relative
"last refreshed" timestamp, Based On list.
- Configuration tab: 4 cards surfacing id, source query, tags, trigger
(fact_types, exclude rules, recall params, tag_groups).
- History tab: content diff + per-version based_on diff (+added, -removed,
kept).
- Shared CompactMarkdown + relative-time helpers; card previews use the
same renderer as the detail modal.
- Dialog border removed, shared delete-item styling for dark mode.
Tests
- 8 new unit tests for compute_mental_model_is_stale covering untagged
scope, tagged scope, any_strict / all_strict, fact_types filter, plus a
tool_search_mental_models regression test.
- test_history_snapshots_previous_reflect_response verifies history rows
capture the prior reflect_response.
Regenerated OpenAPI spec and Python/Go/TypeScript clients.
* chore: regen hindsight-docs skill openapi snapshot
claim_batch iterated tenant schemas in a fixed order from
tenant_extension.list_tenants() and claimed until slots filled.
With a multi-tenant workload where one tenant has a much larger
backlog, tenants at the front of the iteration could monopolize
every claim and leave others queued indefinitely.
Fix is round-robin rotation at the schema level:
- WorkerPoller tracks _next_schema_idx, which advances past the
last schema we serviced (not just +1 from the previous offset,
which would still let a heavy tenant at the same position win
iteration after iteration).
- Pass 1 caps at 1 claim per pool per schema so every tenant with
pending work is considered before we return to a tenant we
already claimed from.
- Pass 2 backfills remaining slots from any schema when capacity
is spare, so single-tenant throughput is not sacrificed for
fairness.
Starvation bound: (time until any worker frees up) + one poll
interval. Under steady load a small tenant's single task is
claimed within one rotation cycle.
Tests cover:
- rotation advances past serviced schema
- empty sweep advances by 1 to avoid re-hitting the head
- small tenant not starved by heavy tenant
- MAX_SLOTS>1 spreads claims across tenants in pass 1
- MAX_SLOTS>1 backfills from a single tenant in pass 2
Adds a second Docusaurus blog instance at /guides, separate from /blog.
Articles are sitemap-indexed and footer-linked for discoverability but
have no navbar entry.
Includes three Hermes how-to guides:
- Migrate hindsight-hermes to native Hermes memory
- Hermes memory modes (hybrid, context, tools)
- Debug Hermes memory not recalling context
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
* feat(paperclip): replace library with Paperclip plugin (v0.2.0)
Replaces the @vectorize-io/hindsight-paperclip npm library with a proper
Paperclip plugin. Works with all adapter types (Claude, Codex, Cursor, HTTP,
Process) via the event system — no code changes required by operators.
- Auto-recalls on agent.run.started, auto-retains on agent.run.finished
- hindsight_recall and hindsight_retain agent tools for mid-run access
- onValidateConfig with live connectivity check
- 15 tests passing
* chore(paperclip): apply prettier formatting and update skills changelog
JsonFormatter now emits the current tenant schema as a `tenant` field
when set. Adds HINDSIGHT_API_LOG_JSON_FIELDS env var to filter which
keys are included in JSON log output (defaults to all).
* feat(cli): add named connection profiles (-p/--profile)
Adds named profiles stored at ~/.hindsight/cli-profiles/<name>.toml
so a single hindsight binary can target multiple deployments without
stomping on the shared ~/.hindsight/config file. Profiles are plain
TOML (api_url, api_key) with 0600 permissions on Unix.
- New global flag `-p/--profile <NAME>` (also reads $HINDSIGHT_PROFILE)
- New `hindsight profile {create,list,show,delete}` subcommands
- Config precedence: env > profile > ~/.hindsight/config > default
- Missing profile produces an actionable error pointing to
`hindsight profile create <name> --api-url <url>`
- Unit tests cover round-trip save/load, name validation, list order,
missing-file error, and 0600 permission bit
* test(cli): end-to-end tests for profile CRUD + docs
- Add tests/cli_profile.rs covering create/list/show/delete against a
temporary HOME (no API server required), plus `-p` precedence over
~/.hindsight/config and the HINDSIGHT_PROFILE env var.
- Fix silent error swallowing in main(): surface anyhow errors via
ui::print_error before exiting so users see why a command failed
(previously `profile show missing` just exited 1 with no message).
- Document named profiles in hindsight-docs/docs/sdks/cli.md with the
new precedence rules.
* fix(cli): regen docs skill + gate profile integration tests to unix
- Run generate-docs-skill.sh so skills/hindsight-docs/references/sdks/cli.md
picks up the new Named Profiles section (fixes verify-generated-files).
- Gate tests/cli_profile.rs with #![cfg(unix)]: these tests set \$HOME to
redirect dirs::home_dir() at a tempdir, which only works on Unix.
On Windows dirs::home_dir() resolves via the shell API (FOLDERID_Profile)
and ignores env vars, so letting them run there would pollute the real
user profile. The Windows runtime path is still exercised through the
config::tests::* unit tests that drive save_profile_to_dir /
load_profile_from_dir with explicit tempdirs.
* fix(reflect): forward mental model max_tokens to refresh
refresh_mental_model loaded the mental model (which carries a
max_tokens column populated via create/update APIs) but never forwarded
that value to reflect_async. The call therefore used reflect_async's
default of 4096, so the per-model limit was silently ignored and
refreshed content could exceed the configured cap whenever there were
enough facts to synthesize.
* fix(reflect): enforce max_tokens through gemini and agent loop
The mental_models max_tokens cap was leaking past the wire even after
refresh_mental_model started forwarding it, because:
1. The Gemini provider's call/call_with_tools silently dropped
max_completion_tokens — it never set Gemini's max_output_tokens, so
responses were uncapped on Gemini-backed deployments.
2. The reflect agent only passed max_completion_tokens on the
forced-final paths. The agent can also short-circuit and return text
directly from a tool-call iteration (the "no tool calls" branch),
and that path used the uncapped call_with_tools.
Map max_completion_tokens to max_output_tokens in the Gemini provider
and forward it to call_with_tools in the agent loop so the mental
model's configured cap is honored end-to-end. Adds an integration test
that retains a batch of facts, refreshes a mental model with a small
max_tokens, and asserts the resulting content is within the cap.
* revert(reflect): keep tool-call iterations uncapped
Drop the max_completion_tokens forwarding into call_with_tools — only
the final-answer paths should carry the user-facing token cap. Tool-
call iterations need the full budget for tool-call JSON and intermediate
reasoning, and the forced-final synthesis path already enforces the cap
on the user-visible answer.
* test(mental-models): drop integration cap test — unit test is sufficient
The end-to-end content-length assertion was flaky: the reflect agent
can legitimately short-circuit and return text directly from a tool-
call iteration (uncapped by design, per the tool-call-budget rule),
so content length depends on which path the agent takes. The unit
test already proves the real regression (refresh_mental_model forwards
the stored max_tokens to reflect_async), and the Gemini/forced-final
provider changes are exercised by the existing reflect test suite.
* Revert "test(mental-models): drop integration cap test — unit test is sufficient"
This reverts commit 96a8644583.
* fix(reflect): cap the short-circuit answer path
When the reflect agent short-circuits and returns text directly from a
tool-call iteration (instead of the forced-final synthesis path), that
text becomes the user-visible answer and must respect max_tokens — the
same as any other final-answer path. Previously it returned uncapped
because call_with_tools is intentionally not given the cap (tool-call
iterations need full budget for tool-call JSON + intermediate reasoning).
Fix: after receiving short-circuit text, if it exceeds max_tokens, run
one extra capped rewrite call to fit it within the budget. This keeps
tool-call iterations uncapped while guaranteeing the final answer
respects the user's limit.
* test(reflect): unit-test the short-circuit rewrite with a mock LLM
Two pure-unit tests for the agent's short-circuit path:
- oversized short-circuit answer triggers a capped rewrite call and
the final text is the rewritten version
- short-circuit answer that already fits skips the extra call
These lock in the cap behavior without needing a real LLM or DB.
Bank ids can contain URL-unsafe characters (e.g. openclaw composite ids
like `agent::channel::user`), which broke navigation and proxy requests
when interpolated raw into template strings. Some routes encoded, most
did not, leading to inconsistent routing and display.
Introduce `bankRoute`, `bankApi`, `bankStatsApi`, `memoryApi`,
`documentApi`, and `dataplaneBankUrl` helpers and migrate every bank-id
URL interpolation (client navigation, control-plane API client, and
server-side proxy routes) through them.
Refs #1069
* release: 0.5.2 notes and blog post
Adds the 0.5.2 changelog entry and blog post, and teaches the
main changelog generator to exclude integration-only commits
(integrations now have their own release cadence and per-integration
changelogs).
* feat(changelog): add contributors grid to generated entries
Fetches GitHub authors for each commit via `gh api` and renders a
grid of avatars linking to their profiles at the bottom of the
entry. Applies to both the main and per-integration changelogs.
Also backfills the 0.5.2 entry with the new section.
* refactor(changelog): put author avatar next to each entry
* style(changelog): mute author/commit metadata with smaller font
* style(changelog): switch meta to emphasis color for contrast, italic handle
* style(changelog): align entry metadata in right-hand column
* style(changelog): inline GitHub-release layout (title · @author · hash)
* style(changelog): apply ruff format
* chore: regenerate docs skill mirror for 0.5.2
- Add `retainDocumentScope` config (default `session`) so all retains within
an OpenClaw session accumulate under one Hindsight document
(`openclaw:{sessionKey}`) instead of minting a new per-turn document id.
Set `retainDocumentScope: 'turn'` to keep the legacy `:turn:NNNNNN` /
`:window:NNNNNN` suffix behavior.
- Lift OpenClaw's per-message `timestamp` into a structured `timestamp`
ISO-8601 field on each message in the retained JSON, and strip the inline
`[Www YYYY-MM-DD HH:MM GMT±N]` prefix OpenClaw injects into user text.
Facts are no longer polluted by weekday/date prefixes that vary per turn.
* feat(entities): add co-occurrence graph view in control plane
Adds a Relations (constellation) view to the bank Entities page, backed by
a new GET /v1/default/banks/{bank_id}/entities/graph endpoint that returns
entity nodes and co-occurrence edges from the materialized
entity_cooccurrences table.
The shared Constellation component gains optional nodeSizeFn, nodeHeatFn,
compactLabels, and legend captions so each caller can map size/color to a
meaningful dimension without touching the component internals:
- entities: size = total co-occurrence weight, color = recency of last
co-occurrence
- observations: size = source fact count (proof_count), color = recency
- world/experience memories: default sizing, color = recency
Also swaps the heat gradient from an all-blue ramp to a more contrasty
indigo -> magenta -> orange -> gold ramp so older/newer reads at a glance.
* chore(cli): skip get_entity_graph in CLI OpenAPI coverage manifest
* chore: sync generated hindsight-docs skill openapi reference
* chore(entities-graph): drop dead var, type entity-graph response
- Remove unused max_mentions accumulator in get_entity_graph.
- Replace the raw-dict node accumulator with a small dataclass.
- Tighten entities-view: store and consume the typed getEntityGraph
response instead of casting to any.
* fix(consolidation): tighten retry budget config handling and repair tests
Followup to #1064:
- Replace `getattr(config, "...", None) or 3` with explicit `is not None`
check. Prior form silently coerced `max_attempts=0` to 3; both fields
are now required attributes on HindsightConfig so getattr is unnecessary.
- Fix test fixtures: memories require an `id` key — without it the suite
failed with KeyError before reaching the assertions, so the new tests
weren't actually exercising the retry logic on main.
- Drop dead `or call_kwargs[1].get(...)` and `if ... else {}` branches
from the assertions; `call_args.kwargs` is always a dict.
* refactor(consolidation): require config in _consolidate_batch_with_llm
The config=None default was dead defensive code — every production call
site threads config through. The None fallbacks (max_attempts=3,
observations_mission=None, etc.) silently masked bugs where config
failed to propagate.
Make config a required parameter and raise ValueError if None, so
programmer errors surface immediately instead of running with defaults.
Drops the None branches from the three config reads in the function
body and updates the test that asserted the defaulting behavior to
instead assert it raises.
* chore(lint): share ruff/prettier config across integrations
Adds root ruff.toml and .prettierrc.json so every integration package is
formatted with the same rules. lint.sh now also lints integration
packages — only those with modified files locally, all of them in CI
(when $CI is set, or via LINT_ALL_INTEGRATIONS=1).
* style(integrations): apply shared ruff/prettier formatting
Mechanical reformat — output of ruff format / prettier --write under the
new shared configs. No behavior changes.
* chore: regenerate docs skill
HINDSIGHT_API_CONSOLIDATION_LLM_MAX_RETRIES existed in config and docs
but was never threaded to the actual llm_config.call() in
consolidator.py — operators had no knob to limit inner retries during
upstream outages.
Also adds HINDSIGHT_API_CONSOLIDATION_MAX_ATTEMPTS (default 3) to make
the outer retry loop configurable, capping worst-case API calls per
batch from unbounded 33 to MAX_ATTEMPTS × (MAX_RETRIES + 1).
Signed-off-by: r266-tech <[email protected]>
Co-authored-by: r266-tech <[email protected]>
hindsight-docs/src/data/templates.json holds both presentation metadata
and inline BankTemplateManifest bodies. A contributor who only tweaks
retain_mission has to touch a 130-line file full of metadata they did
not mean to edit.
Move each manifest into its own file under src/data/templates/. The
catalog entry keeps the presentation fields and replaces inline
manifest with a manifest_file path. The renderer uses webpack's
require.context to bundle every manifest file at build time, so
adding a template only needs a new file plus a catalog entry.
scripts/check-templates.mjs follows manifest_file off disk.
Add a "Submit a template" CTA button to the gallery banner, like the
integrations page already has.
Existing templates render unchanged in the Template Hub.
hindsight-docs/static/bank-template-schema.json is hand-edited.
Nothing regenerates it and nothing checks it. Three PRs have
changed BankTemplateManifest since it was last touched:
#902 flipped entity_labels from list[str] to list[dict[str, Any]],
#1044 added ten BankTemplateConfig fields, #1048 added three
MentalModelTrigger fields.
None of the bundled templates use the new fields, so Ajv in
check-templates.mjs still passes. A template that uses the
dict-shaped label format fails with 'should be string' on
every label.
Regenerate from BankTemplateManifest.model_json_schema() and
hook the generator into verify-generated-files alongside
generate-openapi and generate-clients.
BankTemplate types were added in #819 and registered in the Python
client's hindsight_client_api.models top-level export. The TypeScript
client's hand-maintained src/index.ts re-export block was never
updated to match, so downstream TypeScript consumers cannot reach
BankTemplateManifest or its five related types from the package
root. The generated types already exist in generated/types.gen.ts,
but the package's exports field only surfaces the "." entry, which
means tsc rejects the deep subpath import.
Python and TypeScript have had an asymmetric public type surface
since #819 merged. This closes the gap by adding the five types to
the existing re-export block, matching what Python already does.
- Add BankTemplateManifest, BankTemplateConfig, BankTemplateMentalModel,
BankTemplateDirective, BankTemplateImportResponse to the import type
pull-in and the export type re-export block in
hindsight-clients/typescript/src/index.ts
Non-breaking. Existing exports unchanged. No client regeneration
needed. Per CONTRIBUTING.md, src/index.ts is hand-maintained and
clients are only regenerated at release time. This commit only
widens the package's public surface.
* docs(opencode): drop misleading npm install step, document Hindsight Cloud
OpenCode auto-installs plugins listed in the "plugin" array at startup via
Bun; the prior instructions to `npm install` the package were misleading.
Also add a dedicated Hindsight Cloud section with api.hindsight.vectorize.io
and token guidance.
* fix(opencode): default-export the Plugin function directly
OpenCode's plugin loader iterates Object.entries(mod) and invokes every
export as a Plugin factory `(input) => Promise<Hooks>`, deduping by
identity. Our prior default export was a PluginModule object
(`{ id, server }`), which opencode tried to call as a function and
crashed with `fn3 is not a function. (In 'fn3(input)', 'fn3' is an
instance of Object)` at load time.
Default-export the HindsightPlugin function itself so both default and
named `HindsightPlugin` exports point to the same reference (dedupe
suppresses a second call). Update the default-export smoke test to
assert this invariant.
Verified end-to-end against opencode 1.1.49 with the built dist — the
plugin now initializes, registers tools/hooks, and processes session
events without error.
PR #993 added hardcoded console.error calls throughout hooks.ts for
debugging the message parsing fix. These are not gated behind the debug
config flag, so they spam every user's TUI with red error text on every
event, message parse, and retain cycle.
Replace all console.error calls with debugLog(config, ...) so they only
appear when debug: true is set in plugin options.
Co-authored-by: Claude Opus 4.6 <[email protected]>
* fix(openclaw): make identity skip filters config-aware for per-agent banking
When dynamicBankGranularity includes 'agent', each agent should get its own
bank — including 'main' and CLI sessions. The existing filters in
getIdentitySkipReason() unconditionally rejected agent:*:main sessions,
provider 'main', and anonymous senderIds, which prevented per-agent banks
from ever being created for the main agent or any CLI-accessed agent.
Thread pluginConfig through resolveAndCacheIdentity to getIdentitySkipReason,
and when per-agent banking is enabled:
- allow agent:*:main sessions through
- allow provider 'main' (still skip cron/heartbeat/subagent)
- synthesize agent-user:<agentId> for anonymous CLI sessions
Default behavior is unchanged when dynamicBankGranularity does not include
'agent'.
Fixes#1046
* fix(openclaw): also bypass CLI session filters for static bankId mode
Broaden the carve-out so the same skip-bypass behavior fires when the user
has explicitly opted into a single named bank via dynamicBankId=false +
bankId. In that mode every session — including agent:*:main, provider 'main',
and anonymous senders — should retain into the configured bank.
The carve-out still requires a non-empty bankId; dynamicBankId=false alone
doesn't trigger it (the bank would be unresolvable).
* fix(openclaw): strip inline retain tags in structured block path
extractStructuredBlocks was calling stripMemoryTags + stripMetadataEnvelopes
but not stripInlineRetainTags, so <retain_tags>...</retain_tags> directives
survived into the retained JSON transcript on the default
retainFormat=json + retainToolCalls=true path.
* test(openclaw): update hook integration tests to default json retain format
The two transcript-format assertions still expected the legacy text markers
(`[role: user] ... [user:end]`), but the default retainFormat is now 'json'
with Anthropic-shaped typed blocks. Parse the JSON and assert against the
structured shape instead.
* feat(control-plane): revamp bank stats view and modernize shared UI primitives
Rework the bank stats tab to be dashboard-grade. Adds a new memories-ingested
time-series endpoint (1h/12h/1d/7d/30d/90d, zero-filled UTC buckets, per
fact-type breakdown), per-fact-type toggleable area chart, consolidated card
layout, modern palette, period switcher, and a memory-type staleness card for
mental models.
Also modernizes shared UI primitives so the new look propagates everywhere:
- ui/card.tsx: drop the harsh white border, use a soft ring + dark-mode-aware
shadow, rounded-xl.
- ui/table.tsx: self-contained rounded card with subtle ring, modern uppercase
header tint, softer row borders, last-row border collapse. Callers no longer
need border/rounded wrapping divs.
- fact-type-filter.tsx: align memory-type switch colors (World=violet,
Experience=pink, Observation=indigo) with the stats chart palette.
Backend:
- BankStatsResponse gains operations_by_status (all statuses grouped).
- GET /v1/default/banks/{bank_id}/stats/memories-timeseries returns padded
bucket sets anchored on UTC for a stable, timezone-independent response.
- Both fields/endpoints covered by tests in tests/test_bank_stats.py.
Clients: OpenAPI + Python/TypeScript/Go SDKs regenerated.
* fix(bank-stats-ui): appease CI — type errors, docs-skill regen, cli coverage
- bank-stats-view.tsx: use recharts TooltipContentProps (not TooltipProps) with
Partial<> so <Tooltip content={<ChartTooltip />}> type-checks in recharts v3;
introduce OpsStatusEntry to widen the tuple-inferred literal union.
- Regenerate skills/hindsight-docs/references/openapi.json via
scripts/generate-docs-skill.sh so verify-generated-files passes.
- Add get_memories_timeseries to hindsight-cli/.openapi-coverage.toml skip
list; this endpoint only makes sense for the UI chart.
- test_retain.py: pin fact_type_override="world" on retains that later
filter recall by fact_type=["world"]; the LLM was classifying facts as
"experience" non-deterministically, returning 0 recall results.
- test_load_large_batch.py: add disable_observations fixture so inline
consolidation (SyncTaskBackend) doesn't run during load tests — the
pool-under-load mock wasn't handling scope="consolidation" and was
timing out under 10 concurrent retains.
- test_load_large_batch.py: mark the file with xdist_group so the heavy
load tests don't contend for CPU/memory with other parallel workers.
The retain_chunk_batch_size hierarchical config field and its
ENV_RETAIN_CHUNK_BATCH_SIZE loader have existed in HindsightConfig
since the retain streaming batch landed, but the Retain section of
the configuration reference never got a row for them — users who
want to cap chunk-batch size on large document ingestion had to
discover the env var by grepping the source.
Add a row to the Retain table next to the other chunk/batch knobs,
with the same format as surrounding entries and an explicit note
that the field is configurable per bank via the bank config API.
Cloudflare (and other proxies with UA-based bot filtering) block the
default "Python-urllib/X.Y" and "reqwest/..." UA strings with error 1010,
causing all retain/recall traffic to silently fail against self-hosted
deployments.
Generated-client wrappers now send "hindsight-client-<lang>/<version>"
by default and expose a user_agent/userAgent override so integrations
can identify themselves. Each integration passes its own UA
("hindsight-<integration>/<version>") at client construction.
Integrations using raw urllib/fetch (claude-code, codex, openclaw,
paperclip) set the header directly in their HTTP layer — this fixes
the reported Cloudflare 1010 issue for the claude-code plugin.
* feat(api): add recall controls to mental model trigger
Internal recall during mental model refresh used to hardcode
include_chunks=True with fixed token budgets, wasting prompt budget on
chunks that some refreshes don't need.
Adds three knobs exposed both as hierarchical config (env -> tenant ->
bank) and as per-mental-model overrides on the trigger JSONB field:
- recall_include_chunks / trigger.include_chunks
- recall_max_tokens / trigger.recall_max_tokens
- recall_chunks_max_tokens / trigger.recall_chunks_max_tokens
Trigger value (when set) wins over bank/global config. Both refresh
paths (task handler and synchronous refresh_mental_model) forward the
overrides into reflect_async.
* feat(control-plane): expose recall trigger fields in mental model dialogs
Adds form fields under the Options tab for the three new trigger
overrides (include_chunks, recall_max_tokens, recall_chunks_max_tokens)
in both the create and update mental model dialogs. Empty/Default means
inherit the bank/global config.
* fix(control-plane): cap mental model dialog height and add scroll
* style(control-plane): theme scrollbars to match app surface
* refactor(control-plane): group mental model options into Refresh/Tags/Recall sections
* refactor(control-plane): move Fact Types into Recall, add Other Mental Models section
* fix(cli): pass new recall trigger fields in MentalModelTriggerInput
* chore: regenerate hindsight-docs skill openapi/configuration
* test(hierarchical-config): bump configurable field count for new recall fields
* docs: reframe observations as evidence-grounded consolidated knowledge
The previous framing leaned on "synthesis" and "patterns", which reads as
LLM summarization and undersells what observations actually are: deduplicated
beliefs grounded in specific source memories (with quotes), refined — not
overwritten — when new evidence arrives, and carrying a computed freshness
trend (stable / strengthening / weakening / stale).
* docs: regenerate hindsight-docs skill references
* feat(operations): expose task_payload and document_ids on async ops
Add a "Load raw" affordance to the operations dialog so users can
inspect which document(s) an async operation was processing. Motivated
by pending/failed retain ops where there was previously no way to tell
which content was in flight.
- API: `GET /v1/default/banks/{bank_id}/operations/{operation_id}` now
accepts `?include_payload=true` and returns `task_payload` (the raw
submission params). Off by default since payloads can be large.
- Retain: replaces the singular `generated_document_id` in
`result_metadata` with a `document_ids: list[str]` that captures
every effective doc id (user-provided or generated), via an atomic,
idempotent JSONB set-append. Multi-doc retains and user-supplied ids
are now visible from the operation row.
- Control plane: dialog shows `result_metadata` as JSON (always) and
a "Load raw" button that fetches the payload on demand; handles
parent ops (payload lives on children) with a clear message.
- Regenerate OpenAPI spec and Python/TS/Rust/Go clients.
- Add tests covering user-supplied/generated/shared document_ids and
the include_payload query param.
* chore: regenerate hindsight-docs skill openapi.json
* fix(cli): pass new include_payload arg to get_operation_status
BankTemplateConfig declared 12 hierarchical config fields, but
HindsightConfig._CONFIGURABLE_FIELDS — the allowlist the engine uses
to decide what can be overridden per-bank — contains 22. Ten fields
existed in HindsightConfig and config_resolver.update_bank_config()
accepted them, but the template import path at
POST /v1/default/banks/{id}/import couldn't deliver them: the
manifest handler resolves overrides via BankTemplateConfig.get_config_updates(),
which is a model_dump() filter, so any field not declared on the model
is silently dropped before reaching update_bank_config().
Expose the ten missing fields on BankTemplateConfig so they flow
through get_config_updates() and reach update_bank_config() unchanged:
retain_default_strategy, retain_strategies, retain_chunk_batch_size,
mcp_enabled_tools, consolidation_llm_batch_size,
consolidation_source_facts_max_tokens,
consolidation_source_facts_max_tokens_per_observation,
max_observations_per_scope, reflect_source_facts_max_tokens,
llm_gemini_safety_settings.
No engine changes. No new validation. config_resolver.update_bank_config()
already validates these fields correctly through _CONFIGURABLE_FIELDS;
the template manifest schema was the only thing blocking the path.
Adds a parametrized integration test that POSTs each new field through
/v1/default/banks/{id}/import and asserts the applied value round-trips
via GET /v1/default/banks/{id}/config under the "overrides" slot, matching
the shape test_import_applies_config already uses at
tests/test_bank_templates.py.
Production incident: a 'pending' retain sat in the queue for hours while
workers had free slots. WORKER_STATS only reports the global pending count,
so there was no way to tell whether the rows were claimable-but-not-claimed
(real bug) vs filtered out by the claim WHERE clause (data state — orphaned
batch_retain parents with task_payload IS NULL, retry backoff, or worker_id
already stamped).
Add one extra periodic line, only when global_pending > 0, that buckets
pending rows per operation_type by the predicates the claim query filters
on. ``claimable`` is the residual that should be picked up next poll; if
``claimable > 0`` while workers report free slots, the bug is somewhere
else (lock contention, tenant discovery) and that line narrows the search.
[PENDING_BREAKDOWN] batch_retain: total=1 claimable=0 payload_null=1 ...
| retain: total=3 claimable=1 payload_null=0 retry_blocked=1 assigned=1
| consolidation: total=26 claimable=26 payload_null=0 ...
Implementation reuses the existing per-schema loop in _log_progress_if_due,
adding one GROUP BY query per schema. Buckets are aggregated across schemas
before rendering.
`generate_embeddings_batch` now raises if the backend returns a different
number of vectors than input texts, instead of letting `zip()` silently
drop facts and surface later as `IndexError` in `_map_results_to_contents`.
`_map_results_to_contents` is also reworked to iterate `processed_facts`
(which is 1:1 with `unit_ids` by construction) and validates the lengths
match, providing defense-in-depth against any future drift.
Three bugs fixed:
1. msg.role → msg.info.role: OpenCode SDK wraps role inside info, so all
messages were silently filtered out, breaking retain and recall (#941)
2. Move PluginState to module level so it persists across sessions instead
of being recreated per plugin instantiation
3. Reset lastRetainedTurn after compaction so idle-retain resumes when the
message list shrinks
Co-authored-by: Claude Opus 4.6 <[email protected]>
* feat(openclaw): retain conversation as JSON by default
Default retention payload now mirrors the Claude Code integration: a
JSON-stringified array of {role, content} message objects, instead of the
legacy `[role: x] ... [x:end]` text markers. Structured JSON makes
downstream consumers (recall reranking, control-plane document viewer,
external pipelines) much easier to parse and stops fact extraction from
chasing the marker syntax as if it were content.
Add `retainFormat: "json" | "text"` plugin config (default `"json"`) so
operators can roll back to the legacy text shape if a custom downstream
pipeline depends on it.
* feat(openclaw): retain tool_use and tool_result blocks by default
Extends the JSON retain format so each message's content is an
Anthropic-shaped block array — text, tool_use, tool_result — instead of
a flat string. The agent's tool calls (with full inputs) and tool
results are now preserved in memory, matching what the Claude Code
integration stores and giving downstream fact extraction / recall
rerank a much richer signal.
- New `retainToolCalls` config (default true). Set false to keep
flat-string content per message.
- Operational Hindsight MCP tools (recall/retain/search/CRUD) are
filtered out to prevent feedback loops.
- Tool result content truncated at 2000 chars.
- OpenClaw's native shape (toolCall blocks inside assistant messages,
separate role=toolResult messages) is normalized to Anthropic's shape
on the way out: tool_use stays on assistant, tool_result becomes a
synthesized user message containing just the tool_result block.
- `thinking` blocks are dropped.
- Generated 0.5.1 section in changelog via scripts/dev/generate-changelog.sh
- Added "What's new in Hindsight 0.5.1" blog post covering CLI coverage,
Cloudflare OAuth proxy, default bank template, SiliconFlow reranker,
hindsight-all daemon lifecycle package, and reliability fixes
* fix(embedded): add timeout to _cleanup lock acquisition (#1022)
_cleanup() acquires self._lock with a bare 'with' statement. When another
thread holds the lock (e.g. _ensure_started mid-operation), Ctrl+C causes
the shutdown path to hang indefinitely.
Replace with self._lock.acquire(timeout=5.0) so cleanup completes within
5 seconds even when the lock is contended. If timeout expires, proceed
with best-effort cleanup and log a warning.
Also wrap self._client.close() in try/except since the client may be in
an inconsistent state during interrupted shutdown.
Closes#1022
* test(embedded): add unit test for _cleanup lock timeout behavior
* fix(embedded): rework — skip shared-state teardown on lock timeout
Address Codex review findings:
- On timeout, only set _closed flag (prevents new ops) and return.
Do NOT mutate shared state without the lock — the daemon's idle
timeout handles cleanup on its own.
- Log client.close() exceptions at DEBUG level instead of swallowing.
OpenClaw calls the plugin entry multiple times per process (CLI, gateway,
lazy reloads), each with a fresh api bound to its own plugin registry. A
module-level `hooksRegistered` flag let the first call win and left later
registries with zero hindsight hooks — so auto-recall/auto-retain silently
stopped firing on live agent turns in 0.6.0/0.6.1.
Also document in CLAUDE.md that changelogs never carry "Unreleased"
sections; the release script writes entries at cut time.
* feat(reranker): add SiliconFlow provider and share Cohere-compatible HTTP client
Closes#859.
Adds a `siliconflow` reranker provider for SiliconFlow's Cohere-compatible
`/rerank` endpoint, and refactors ZeroEntropy plus the Cohere custom-base_url
code path onto a shared `_CohereCompatibleRerankClient`. Setting
`HINDSIGHT_API_RERANKER_COHERE_BASE_URL` now routes the `cohere` provider
through the same HTTP client, making it a generic entry point for any
Cohere-compatible rerank host (Azure AI Foundry, Jina, Voyage, self-hosted
BGE, ...).
* fixup: update cohere tests for shared HTTP client + regen docs skill + ruff format
User feedback from the 0.6.0 wizard: the prompt "Environment variable
holding your Hindsight Cloud API token" is confusing. Users paste the
raw token (or worse, the whole `NAME=value` pair), get an
UPPER_SNAKE_CASE validation error, and have no idea the wizard expected
a name instead of the value.
Rework: the interactive wizard now asks for the token / API key VALUE
via `p.password()` (masked input) and stores it inline as a plaintext
string in openclaw.json. The outro note tells users where the secret
was stored and shows the one-liner to switch to a SecretRef later.
For CI / production where a SecretRef is preferred, the existing
`--token-env` and `--api-key-env` non-interactive flags continue to
work. Also added their direct-value counterparts:
--token <value> stores inline in openclaw.json
--token-env <VAR> stores as SecretRef
--api-key <value> stores inline in openclaw.json
--api-key-env <VAR> stores as SecretRef
`--token` / `--token-env` and `--api-key` / `--api-key-env` are
mutually exclusive within a mode. For api mode, any combination with
`--no-token` is also rejected.
The plugin manifest marks `llmApiKey` and `hindsightApiToken` as
sensitive, so `openclaw config get` continues to redact their values
regardless of storage shape.
Tests: 142 unit tests (up from 127 pre-change) cover both direct-value
and SecretRef paths across all three modes, plus the new mutual-
exclusivity errors. Smoke test exercises 7 setup variants (was 4) and
5 negative tests (was 3); all pass end-to-end against a real openclaw
install.
* feat(worker): diagnostic logging for stuck/slow async tasks
Surface what each in-flight worker task is doing so users can diagnose
stalls (issue #1001) and runaway LLM retry loops (#996) from logs alone,
without killing tasks and losing the forensic trail.
Adds four new periodic log lines (every 30s):
* [WORKER_STATS] now includes asyncpg pool stats (idle/in_use/waiters)
and process RSS — pool exhaustion and unbounded memory growth are
invisible without these.
* [WORKER_TASK] one line per in-flight task with op_id, type, bank,
age, current stage, and stage age. Sorted oldest-first; tasks past
5 min get a [STUCK?] prefix.
* [STUCK_STACK] async stack trace dumped once per doubling threshold
(5/10/20/40 min...) so stuck tasks self-document without flooding.
* [DB_WAITS] pg_stat_activity snapshot of any non-idle Hindsight
session waiting on a lock — catches the retain-pipeline deadlock
case where the coroutine looks fine but is blocked on a Postgres lock.
Stage breadcrumbs are wired via a contextvar (worker/stage.py) at:
* memory_engine.execute_task — task.{type}
* retain/orchestrator phases — retain.phase1/2/3, retain.extract_and_embed
* llm_wrapper.call/call_with_tools — llm.{provider}.{scope}[+structured|+tools]
* per-attempt updates in openai_compatible (incl. _call_ollama_native),
litellm, and gemini retry loops — llm.{provider}.{scope}.attempt=N/M
The attempt counter makes JSON-schema retry loops on small models
visible by stage name + stage age, instead of needing to bump log
level and grep for WARN lines.
set_stage is a no-op outside a worker context, so engine code is safe
to call from sync HTTP requests, tests, and the CLI without setup.
* fix(test-api): repair regressions from main merges
Three independent regressions surfaced in test-api after recent merges to
main; fix all of them so this PR's CI can pass.
1. apply_combined_scoring overwrote single-result scores
#957 added passthrough-reranker detection via `len(ce_scores) <= 1`,
which also triggers for n=1 candidate cases — corrupting any
single-result rerank by replacing the real CE score with a rank-based
value. It also misfired when multiple legitimate results happened to
tie on score (common in tests with synthetic data).
Replace the heuristic with an explicit `is_passthrough_reranker`
parameter, set by the caller based on `cross_encoder.provider_name`.
Fixes 13 tests across test_combined_scoring and test_reranking_proof_count.
2. tool_search_observations breaks when request_context is a MagicMock
#972 added `replace(request_context, internal=True)` inside
tool_search_observations to avoid double-billing internal recall calls.
The existing test suite passes a MagicMock as request_context, which
`dataclasses.replace` rejects.
Update the test fixture to pass a real RequestContext dataclass.
Fixes 4 tests in test_reflect_source_facts_config.
3. recall_id collisions cause "Operation already exists"
recall_id was `f"{bank_id[:8]}-{int(time.time() * 1000) % 100000}"` —
two recalls on the same bank within the same millisecond collide,
raising ValueError from budgeted_operation. This presented as flaky
"Operation recall-... already exists" failures in test_consolidation
and test_consolidation_failure_recovery.
Append a uuid suffix so recall_id is guaranteed unique.
* fix: repair main-branch CI regressions blocking this PR
* test-embed: 3 tests in test_profile_daemon_config.py patched
manager.is_running to True, but #1016 added pre-Popen is_running
checks in _start_daemon and _start_daemon_locked that short-circuit
on True, so Popen was never called and the env was never captured.
Make is_running return False before Popen and True after via a
popen_called flag, so both pre-Popen guards proceed and the
post-Popen readiness loop breaks immediately. Patch time.sleep too
to skip the 2s stability wait.
* test-openclaw-integration: package.json required hindsight-all@^0.1.0
but the workspace ships 0.5.0, so npm ci refused. Bump the constraint
to ^0.5.0 and regenerate package-lock.json.
* verify-generated-files: regenerate skills/hindsight-docs/references
for mental-models.md and cli.md (drift on main, untouched by this PR).
The openclaw 0.6.0 release workflow failed at `npm run build` because
`hindsight-integrations/openclaw/package-lock.json` had
`@vectorize-io/hindsight-client` resolved as a workspace symlink
(`link: true`) instead of a registry URL. npm had silently preferred the
workspace over the declared registry version when `npm install` was
originally run from the monorepo root, even though openclaw isn't in
the root `workspaces` array. The release runner has no pre-built
workspace `dist/`, so tsc couldn't find the types and the publish never
happened. (The test CI job masked this because it explicitly pre-builds
workspace deps before `npm ci`.)
Add two guards so it can't recur:
1. `scripts/check-integration-lockfiles.sh` — scans every
`hindsight-integrations/*/package-lock.json` and fails if any dep's
`resolved` URL is empty, a `file:` URL, a relative path, or the entry
is a `link: true` workspace symlink. Prints the exact fix (regenerate
the lockfile from inside the integration directory, not the monorepo
root).
2. `check-integration-lockfiles` job in `.github/workflows/test.yml` —
runs the script on every PR that touches an integration lockfile or
package.json. Gated on the new `integrations-lockfiles` detect-changes
output. Added to `report-pr-status` needs list.
3. Inline `Check integration lockfile` step in `release-integration.yml`
for the TypeScript branch — belt + suspenders in case a bad lockfile
ever slips past PR gating.
Verified: regression-tested the script against the broken pre-release
lockfile from commit da21e072 and it correctly identifies
`node_modules/@vectorize-io/hindsight-client: (link=true — workspace
symlink)` and exits non-zero. On the current tree (post-fix) all 7
integration lockfiles pass.
The release-integration.yml workflow failed at `tsc` with
Cannot find module '@vectorize-io/hindsight-client' or its corresponding
type declarations.
Root cause: the openclaw integration's package-lock.json had
@vectorize-io/hindsight-client resolved to ../../hindsight-clients/typescript
— the monorepo workspace path. That happened because an earlier
`npm install` was run from the monorepo root, where npm preferred the
workspace over the registry even though openclaw isn't itself listed in
the root workspaces array. Locally the build worked because the
workspace directory exists; in CI the workspace's `dist/` is gitignored
and not built before the release workflow's `npm ci`, so tsc couldn't
resolve the types.
Regenerated the lockfile from within the openclaw directory so npm
resolves @vectorize-io/hindsight-client (^0.5.0) and
@vectorize-io/hindsight-all (^0.1.0) directly from the npm registry. The
lockfile's `resolved` URLs now point at registry.npmjs.org.
Some OpenClaw hook contexts populate `ctx.channelId` with the provider
name (e.g. "discord") instead of the actual channel ID, which short-
circuited the sessionKey fallback in `deriveBankId` and collapsed all
Discord channel memories into a single `main::discord` bank.
Add a `sanitizeChannelId` helper that treats `ctx.channelId` as missing
when it equals the provider or matches a known provider token, so the
parsed sessionKey channel is used instead. Apply it to both
`deriveBankId` and `buildRetainRequest` so `channel_id` metadata and
thread extraction also benefit.
* feat(openclaw): interactive setup wizard with Cloud / API / Embedded modes
Ship a new `hindsight-openclaw-setup` bin that walks users through picking a
mode and writes the corresponding plugin config into openclaw.json:
- Cloud — managed Hindsight (default URL + token SecretRef)
- External API — user's own running Hindsight (URL + optional token SecretRef)
- Embedded daemon — local hindsight-all daemon (LLM provider + key SecretRef)
Pure config manipulation (mode application, SecretRef construction, atomic
save/load) lives in src/setup-lib.ts and is covered by 21 unit tests. The
src/setup.ts CLI entry is a thin @clack/prompts wrapper on top.
Mode switches correctly clear stale fields from the opposite modes so a
user flipping between e.g. Cloud and Embedded doesn't end up with a mixed
configuration. All credentials are always written as env-backed SecretRef
objects, never plaintext.
Scanner-safe: neither setup.ts nor setup-lib.ts imports subprocess APIs or
reads environment variables, so the new files don't reintroduce the
dangerous-exec / env-harvesting findings that #974 just cleared.
* feat(openclaw): non-interactive setup flags + smoke test + CI
- setup.ts now accepts --mode cloud|api|embedded plus mode-specific flags
(--api-url, --token-env, --no-token, --provider, --api-key-env, --model,
--config-path) to skip the interactive TUI. Interactive remains the
default when no --mode is given. main() is guarded by an isDirectRun()
check so importing from tests does not trigger the wizard.
- src/setup.test.ts adds 23 unit tests covering every flag, invalid input
(unknown flags, missing values, conflicting --token-env + --no-token,
mode requirements) and the full non-interactive write path for each
mode including cross-mode state cleanup.
- scripts/smoke-test.sh is a new end-to-end install smoke test:
* packs a fresh tarball (or uses an existing one passed in argv[1])
* installs via `openclaw plugins install <tarball>` WITHOUT
--dangerously-force-unsafe-install — fails loudly if the scanner
reports any findings
* asserts workspace deps (@vectorize-io/hindsight-all, hindsight-client)
resolved from the npm registry into the extension's node_modules
* runs `hindsight-openclaw-setup` non-interactively for all 4 mode
variants (cloud default URL, external API no-auth, embedded openai
with model override, embedded claude-code no-key) and asserts
`openclaw config validate` + `openclaw plugins doctor` pass after each
* runs 3 negative tests to assert bad flag combinations fail fast
* backs up and restores ~/.openclaw/openclaw.json around the run
- .github/workflows/test.yml adds a smoke-openclaw-install job on
ubuntu-latest that installs the published `openclaw` CLI, rebuilds the
workspace deps, and runs scripts/smoke-test.sh. Gated by the same
detect-changes outputs as build-openclaw-integration and added to the
report-pr-status needs list.
* chore(openclaw): point cloud mode at api.hindsight.vectorize.io, drop stale install.sh
- Replace the placeholder Hindsight Cloud URL with the real one,
https://api.hindsight.vectorize.io, in setup-lib.ts and the three
suites that hard-coded it (setup-lib.test.ts, setup.test.ts,
scripts/smoke-test.sh).
- Delete hindsight-integrations/openclaw/install.sh. It predated
`openclaw plugins install` and documented the pre-0.6.0 env-var flow
('export OPENAI_API_KEY', 'openclaw plugins enable'), which is
superseded by the interactive/non-interactive hindsight-openclaw-setup
wizard plus README quick start.
* fix(openclaw): smoke test — tolerate unrelated bundled-plugin diagnostics
In clean CI environments, `openclaw plugins doctor` can emit diagnostics
for bundled plugins (seen: "ollama: memory embedding provider already
registered") that have nothing to do with hindsight-openclaw. The
previous smoke-test check required the literal string "No plugin issues
detected" in doctor output, which treated those unrelated warnings as
failures.
Replace that check with two narrower ones: (a) `plugins doctor` must
exit zero, and (b) its output must not contain any line that mentions
hindsight together with fail/error/not-loaded. Unrelated bundled-plugin
warnings no longer fail the smoke test.
* docs(openclaw): document hindsight-openclaw-setup wizard
The plugin's own README was updated to lead with the setup wizard when
the feature landed, but the docs site page (docs-integrations/openclaw.md)
was still showing a Quick Start driven entirely by raw `openclaw config
set` commands. Update the Quick Start to mirror the README flow: install
the plugin, run `hindsight-openclaw-setup`, start the gateway. Include
the three modes (Cloud / External API / Embedded) and the non-interactive
--mode flag variants for CI.
Also add pointer notes at the top of the "LLM Configuration" and
"External API (Advanced)" sections so readers who arrived there directly
know the wizard already covers those paths.
Extend the 0.6.0 (Unreleased) changelog entry with the wizard under
**Features** and regenerate the skill mirror.
* fix(openclaw): resolve bin invocation when launched via npm symlink + doc the correct invocation
Two related problems found during end-to-end install testing:
1. `isDirectRun()` in setup.ts compared `process.argv[1]` against
`fileURLToPath(import.meta.url)`. When the bin is invoked through
`node_modules/.bin/hindsight-openclaw-setup` (an npm-created symlink
into `dist/setup.js`), these two paths differ: argv[1] is the symlink
and import.meta.url is the resolved target. The equality check failed,
`main()` never ran, and the command silently exited with status 0 and
no output. Canonicalize both via `realpathSync` before comparing —
same approach the backfill bin already uses (`isDirectExecution` in
src/backfill.ts).
2. `openclaw plugins install @vectorize-io/hindsight-openclaw` unpacks
the plugin into ~/.openclaw/extensions/ but does not put its bins on
$PATH, so the README/docs instruction `hindsight-openclaw-setup` was
misleading — users would get "command not found". Update the Quick
Start in both README.md and hindsight-docs/docs-integrations/openclaw.md
to invoke the wizard via `npx --package @vectorize-io/hindsight-openclaw
hindsight-openclaw-setup`, matching the existing invocation shown for
the hindsight-openclaw-backfill bin.
* fix(embed): serialize daemon start and stop killing healthy daemons
Two concurrent `hindsight-embed daemon start` calls used to kill each
other's freshly-started daemons: `_clear_port` unconditionally stopped
any hindsight daemon on the target port before spawning a new one, so
each caller detected the other's healthy daemon and SIGTERM'd it.
Two changes fix this at the source instead of requiring every
integration to serialize externally:
1. `_clear_port` no longer kills a *healthy* hindsight daemon. If
/health returns 200, return True and reuse the existing daemon.
Only reclaim the port when the listener is unhealthy (stale from a
version upgrade or a crash), matching the original stated intent.
2. `_start_daemon` now holds an exclusive flock on the profile's lock
file for the whole startup sequence, and re-checks `is_running()`
inside the lock. Concurrent callers serialize on the flock; the
waiter returns immediately once the winner's daemon is up. The
post-_clear_port `is_running()` check also prevents spawning a
second daemon if a foreign-started daemon showed up mid-flight.
Tests updated: two existing tests codified the old kill-on-healthy
behavior; they now assert the new reuse behavior. Added new tests for
unhealthy-daemon reclamation and for the serialization/double-check
paths.
* style(retain): reformat ann seeds sql calls onto single lines
Addresses #945 and the related confusion in #1004. The mental model
`tags` field acts as a hard `all_strict` filter on source memories
during refresh, but this wasn't obvious from the parameter tables
or the UI form — users hit empty refresh content while direct reflect
on the same query worked.
- Expand the `tags` parameter description in the mental-models API
doc and mirror it in the skills reference.
- Add a warning callout in the "Tags and Visibility" section pointing
users at backfill / trigger.tags_match / tag_groups workarounds.
- Add helper text under the Tags input (both Create and Edit forms)
in the control plane mental-models view.
* fix(reranker): surface real import errors and fix transformers 5.x race in jina-mlx
Two fixes for jina-mlx reranker startup on Apple Silicon (#994):
1. Pre-warm transformers.AutoTokenizer before importing mlx_lm. transformers 5.x
uses _LazyModule and has an unguarded window where concurrent imports from
another thread (e.g. local embeddings init in an executor) can cause
`from transformers import AutoTokenizer` inside mlx_lm's tokenizer_utils to
raise ImportError.
2. Narrow the `except ImportError` so unrelated transitive failures inside
mlx_lm propagate verbatim with chained traceback. The previous bare except
masked the real error with a misleading "install mlx" message even when
mlx and mlx_lm were correctly installed.
* fix(tests): stub mlx modules for jina-mlx import test + sync link_utils lint format
- Stub mlx and mlx.core in sys.modules so test_initialize_surfaces_transitive_import_error
works in CI environments where mlx is not installed (CI's import mlx.core was failing
before the patched __import__ ever saw mlx_lm, hitting the install-hint branch).
- Apply the lint reformat to link_utils.py that lint.sh produces; verify-generated-files
was failing because the committed file didn't match lint output.
Consolidation tasks were sharing the same slot pool as retain and could only
claim leftover slots. With a continuous retain queue, retains saturated
max_slots and consolidation was permanently starved.
Make consolidation_max_slots a true reservation: non-consolidation tasks may
use at most (max_slots - consolidation_max_slots) slots, leaving the remainder
always available for consolidation. Also inject operation_type on claimed
consolidation rows so in-flight tracking works (the JSON payload didn't carry
the field, so _in_flight_by_type["consolidation"] was never incremented).
Adds a regression test that submits 10 retains + 1 consolidation with
max_slots=5, consolidation_max_slots=2 and verifies retain caps at 3 while
consolidation still claims its slot. Existing retain-only saturation tests
updated to set consolidation_max_slots=0.
Docs clarify the reservation semantics in configuration.md.
* docs: clarify audit logging is off by default (#944)
Explains that /audit-logs returns empty until HINDSIGHT_API_AUDIT_LOG_ENABLED=true, which was the confusion reported in the issue.
* docs: regenerate skill mirror for audit logging section
Previously `hindsight memory retain/recall/reflect` errors rendered as
"Unexpected Response: Response { ... }" with no body, hiding the actual
validation detail (e.g. FastAPI's `{"detail": "..."}` payload). Users had
to fall back to `curl` to see why a request failed.
Adds a helper that unpacks progenitor's `ErrorResponse`,
`UnexpectedResponse`, and `InvalidResponsePayload` variants and includes
the response body in the error message.
Refs #1007.
* fix(embed): restore macOS FORCE_CPU default for local embeddings/reranker
PR #933 (0.5.0) removed the unconditional macOS CPU-force block from
DaemonEmbedManager._start_daemon. The block was the actual mechanism
that reached the daemon subprocess env — the profile .env value written
by `hindsight-embed configure` does not propagate, because _start_daemon
only copies a whitelist of keys (llm_*, log_level, idle_timeout) into
the subprocess env.
Net effect on 0.5.0 + macOS Apple Silicon: sentence-transformers
auto-selects MPS, daemon init hangs, startup times out.
Restore the block so FORCE_CPU is set by default on Darwin, while still
honoring an explicit user override (e.g. FORCE_CPU=0 to opt into MPS).
Fixes#962
* fix(embed): propagate all HINDSIGHT_* keys from profile config to daemon env
The daemon env builder only copied a whitelist of keys (llm_*, log_level,
idle_timeout) from the merged profile config. Any other HINDSIGHT_* key
written to the profile's .env — e.g. HINDSIGHT_API_EMBEDDINGS_PROVIDER,
HINDSIGHT_API_EMBEDDINGS_TEI_URL, or the FORCE_CPU flags on non-macOS —
was silently dropped when spawning the daemon subprocess.
Pass the full set of HINDSIGHT_* keys through after the whitelist loop,
so profile-level settings actually reach the daemon.
The recall hot path in _search_with_retries calls
embedding_utils.generate_embedding() synchronously, which runs
sentence-transformers GPU inference on the asyncio event loop thread.
This blocks /health and all concurrent requests for the duration of
each embedding call. Under consolidation load (WorkerPoller runs
in-process with 2 concurrent slots), stacked sync embedding calls
cause /health to exceed watchdog timeouts and trigger destructive
service restarts.
Replace the single sync generate_embedding() call with the async
generate_embeddings_batch() wrapper that already exists in the same
codebase and is used correctly at 3 other call sites in this file
(lines 5469, 6655, 6877). The batch wrapper offloads GPU inference
to a thread pool via run_in_executor, keeping the event loop free.
This was the only remaining sync embedding call in memory_engine.py.
Previously, PATCH /v1/default/banks/{id}/config accepted malformed
entity_labels (e.g. plain strings instead of LabelGroup dicts) with
HTTP 200, then failed with a 500 on the next retain call. The fix in
PR #902 added validation to config_resolver.update_bank_config, but
no regression test was added to prevent a future regression.
This commit adds a focused test that:
- Asserts that a string list (["person", "client"]) raises ValueError
with "Invalid entity_labels format" rather than being silently stored
- Asserts that a correctly shaped LabelGroup list succeeds
Co-authored-by: octo-patch <[email protected]>
* fix(cli): read fact_type key in memory list/get pretty output
The API response uses the key 'fact_type' but the CLI formatter reads
'type', causing every memory to display as [UNKNOWN]. Also fixes the
serde rename on MemoryUnitDetail and adds 'observation' match arm.
* fix(cli): add observation and experience match arms to print_fact gradient
PR #972 fixed double-billing by marking reflect's internal recall calls
as internal=True. Add 4 focused tests to prevent regression:
- search_observations passes internal=True to recall_async
- tool_recall passes internal=True to recall_async
- Neither function mutates the original request context
Fixes#988
PR #968 added full OpenAPI endpoint coverage (46/62 → 62/62) but
cli.md was not updated. Add sections for:
- Webhook management (list/create/update/delete/deliveries)
- Audit logs (list with action/transport/date filters)
- Operation management (list/get/cancel/retry)
- Memory history and clear-observations
- Document update
- Bank set-disposition and consolidation-recover
- New flags on recall (--tags, --query-timestamp) and reflect (--fact-types)
Fixes#982
Add ContextForge as a community integration. ContextForge (IBM) is an
open-source MCP gateway that aggregates multiple MCP servers behind a
single authenticated endpoint.
This integration registers Hindsight's built-in /mcp endpoint as a
gateway backend in ContextForge, giving every connected AI tool (Dust,
Claude Desktop, custom agents) access to retain, recall, and reflect
tools through a unified MCP hub.
- Add integration entry to integrations.json (community, mcp category)
- Add docs page with setup guide (UI, API, Helm auto-registration)
- Add sidebar link
Tested end-to-end locally: ContextForge discovers all 30 Hindsight MCP
tools and can execute them through the gateway.
The slim deployment default (`reranker_provider=rrf`,
`RRFPassthroughCrossEncoder`) returns a constant 0.5 score for every
candidate. After sigmoid normalisation that becomes a constant
`cross_encoder_score_normalized` across all candidates, so the
multiplicative recency / temporal / proof_count boosts inside
`apply_combined_scoring` become the *only* ranking signal.
For non-temporal queries on `world` facts the temporal and proof_count
boosts collapse to 1.0, leaving `recency_boost` alone. The final
ordering is then a pure newest-first sort, regardless of how relevant a
candidate is to the query — and `rrf_normalized` is explicitly set to
0.0 a few lines above, so the upstream RRF rank is discarded entirely.
In practice this means any biographical / historical / long-tail world
fact (anything with an old `occurred_start`) is guaranteed to lose to a
recent fact in the candidate set, even when RRF, BM25, semantic search
*and* graph traversal all agree it should be the top result.
## Repro
A `world` fact with `occurred_start` ~30 years in the past, indexed
alongside a few thousand recent observations and world facts in the
same bank, is correctly identified as the top match by every retrieval
arm:
```
semantic (world): 1000 items | target rank 1
bm25 (world): 1000 items | target rank 1
graph (world): 346 items | target visited
RRF merged : 1673 items | target rank 1
```
After reranking with the passthrough cross-encoder it lands at rank 80,
and the token-budget filter then drops it from the response entirely.
The same pattern reproduces for every query phrasing tested (short,
long, with and without entity names).
## Fix
Detect the degenerate-CE case in `apply_combined_scoring` and seed
`cross_encoder_score_normalized` from the RRF rank before the boosts
are applied. The boosts then modulate a meaningful base instead of
replacing it.
- No-op for real cross-encoders (`flashrank`, `local`, `cohere`,
`litellm`, …) — those produce diverse scores so the `len(set(...)) <= 1`
guard never triggers.
- No schema, embedding, or API changes.
- Recency / temporal / proof_count boosts are still applied on top, so
ranking ties between adjacent RRF candidates can still be broken by
the secondary signals.
## After fix
Same database, same queries, target fact moves from "dropped from
response" to a stable top-10 position across every query variation
tested.
Co-authored-by: akhater <[email protected]>
Two related fixes for retain re-submission failures:
1. store_chunks_batch now upserts via ON CONFLICT (chunk_id) DO UPDATE.
Re-submitting a retain under the same document_id (the pattern in #977)
previously failed with UniqueViolationError on pk_chunks when any
upstream path — cascade-delete on is_first_batch, delta-retain chunk
diff, concurrent worker tasks — didn't clean up before the insert.
Overwriting is the correct semantics for document_id as a grouping key.
2. MemoryEngine.execute_task now classifies asyncpg
IntegrityConstraintViolationError subclasses as non-retryable (#980).
Previously the poller retried them ~3 times over ~3 minutes, burning
worker capacity on a deterministic error that will never succeed.
Fixesvectorize-io/hindsight#977, vectorize-io/hindsight#980
Follow-up to #922. The initial PR was merged without the tests, CI
job, or release-script entry that CLAUDE.md mandates for new
integrations, and the source had a handful of code-quality issues
flagged in review.
Testing & CI
- Split src/index.ts into env/html/cors/proxy/auth/router modules so
each unit can be exercised in plain Node without the Workers runtime
- Add 50 vitest tests covering html escaping, CORS application /
stripping, the /authorize GET+POST flow with a mocked OAuth provider,
the MCP proxy's header sanitisation, and the outer router's
preflight + metadata hardening
- Add tsconfig.json, vitest.config.ts, typecheck+test scripts, and a
test-cloudflare-oauth-proxy-integration job wired into detect-changes
and report-pr-status
- Add cloudflare-oauth-proxy to VALID_INTEGRATIONS
Hardening
- Remove `any` types; introduce an explicit OAuthHelpers interface
- Replace the plain `!==` password check with a constant-time
SHA-256-based comparison
- Drop the PII (email) log line from the MCP proxy
- CORS: list explicit methods instead of `*`, include `Mcp-Session-Id`
in Allow-Headers, emit `Vary: Origin`
- Proxy: strip client Authorization + X-Proxy-Secret + hop-by-hop
headers, filter upstream response headers through an allowlist
(drops Set-Cookie and upstream CORS), buffer request body to avoid
needing `duplex: "half"`
- Override OAuth metadata to advertise S256 only
- README: align PKCE wording with reality and document the single-user
threat model; wrangler.toml defaults to workers_dev=false
PR #858 made the openai provider fall back to max_tokens whenever a custom
base_url was set, to support Mistral/Together-style endpoints. This regressed
two important setups:
1. Reasoning models (GPT-5, o1, o3) reject max_tokens outright with a 400
("Unsupported parameter: 'max_tokens' is not supported with this model.
Use 'max_completion_tokens' instead.").
2. Azure OpenAI is fully OpenAI-API-compatible — it was only classified as
"third-party compatible" because it requires a custom base_url.
The combination of the two — Azure OpenAI + GPT-5 — is the exact setup the
reporter hit in issue #978 and fails connection verification on startup.
Fix _max_tokens_param_name() so it:
- Always returns max_completion_tokens for reasoning models, regardless of
base_url (they only support the new parameter name).
- Detects Azure OpenAI endpoints by the *.openai.azure.com hostname and
treats them as native OpenAI.
The Mistral/Together behavior from #858 is preserved for non-reasoning
models on non-Azure custom base URLs.
Fixes#978
* fix: add PEP 561 py.typed marker to all Python packages
Add empty py.typed marker files to all 13 Python packages that were
missing them. Only hindsight-integrations/autogen already had one.
Per PEP 561, packages that wish to support type checking must include
a py.typed marker file. Without it, type checkers (mypy, pyright) treat
the package as untyped and skip all inline type annotations.
Fixes#965
* fix: ensure py.typed markers survive client regeneration
Add touch commands in generate-clients.sh to recreate PEP 561 py.typed
marker files after the OpenAPI generator runs, since the script deletes
and regenerates the hindsight_client_api directory.
---------
Co-authored-by: r266-tech <[email protected]>
Reflect's tool functions (tool_search_observations, tool_recall) call
recall_async with the user's original request_context, which has
internal=False. The usage metering extension sees these as user-facing
recall operations and bills them separately — double-charging the
customer for recalls that are already included in the reflect operation
cost.
Fix: wrap request_context with dataclasses.replace(internal=True) before
passing to recall_async. This matches the pattern used by consolidation,
which already creates an internal RequestContext for its sub-operations.
The internal flag causes the metering extension to:
- Record the usage as "internal_recall" (tracked but not billed)
- Skip credit deduction entirely
Observed impact: a single reflect call was generating 2 extra billed
recall entries (one from tool_search_observations, one from tool_recall),
inflating the customer's recall token count by ~26 tokens per reflect.
Adds an OAuth 2.1 proxy Worker that connects cloud MCP clients
(claude.ai, Claude Code, Codex) to a self-hosted Hindsight instance
via Cloudflare Workers and Tunnel.
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
compute_semantic_links_ann created a TEMP TABLE outside any transaction,
then ran a TRUNCATE / COPY / SELECT / DROP sequence as separate statements
on the same asyncpg connection. This is fine against a direct Postgres
connection but fails intermittently when the caller is routed through
PgBouncer in transaction pool mode:
CREATE TEMP TABLE IF NOT EXISTS _ann_seeds (...) -- backend A
TRUNCATE _ann_seeds -- backend B -> FAILS
Temp tables are session-scoped to the backend that created them. In
PgBouncer transaction mode the backend is only pinned to the client for
the duration of an actual transaction, so between standalone statements
the pooler can (and under concurrency, will) rebind the client to a
different backend. When that happens the _ann_seeds table disappears
and the follow-up statement fails with:
relation "_ann_seeds" does not exist
Symptom: ~3% of sync retain calls (2 of 61) failed the Hindsight Cloud
smoke test on a recent hindsight-dev deploy. Async retains are masked
by the 3-attempt retry loop so they usually eventually succeed.
Fix: wrap the CREATE TEMP TABLE -> COPY -> SELECT sequence in a single
`async with conn.transaction():` block, and use ON COMMIT DROP so the
temp table is transaction-scoped and auto-cleaned at commit. Also
switch `SET hnsw.ef_search = 60` to `SET LOCAL` so the tuning is
transaction-scoped and no longer leaks onto the pooled backend for
subsequent recall queries. Drop the now-unnecessary manual TRUNCATE,
explicit DROP TABLE, and RESET hnsw.ef_search.
The function docstring still correctly describes this as running on a
separate connection outside the surrounding write transaction — this
change only adds an inner transaction around the ANN work itself to
keep the temp table visible to PgBouncer.
Tests:
- Add TestComputeSemanticLinksAnnPgBouncerSafety with 5 regression
tests using a mocked connection. These are structural asserts — they
check that the function enters conn.transaction(), uses ON COMMIT DROP,
uses SET LOCAL, and does not reintroduce manual TRUNCATE / DROP /
RESET calls. They would have caught the original bug if they had
existed, and will catch any future reversion.
* refactor(openclaw)!: read config from plugin config instead of process.env
The plugin loaded credentials and runtime settings from environment
variables (HINDSIGHT_API_LLM_*, HINDSIGHT_EMBED_API_*, HINDSIGHT_BANK_ID)
plus auto-detection of OPENAI_API_KEY / ANTHROPIC_API_KEY / GEMINI_API_KEY
/ GROQ_API_KEY. That tripped OpenClaw's install-scanner env-harvesting
rule and bypassed the framework's first-class SecretRef resolution.
Switch to reading from the plugin config exclusively, with secrets
configured via 'openclaw config set ... --ref-source env|file|exec'.
Combined with the daemon lifecycle extraction in #949, this closes the
remaining install-scanner findings the 0.5.x plugin was hitting. The
plugin source now contains neither process.env nor child_process; the
former moved to plugin config (resolved by OpenClaw before the plugin
loads), and the latter lives in @vectorize-io/hindsight-all under
node_modules where the scanner's directory walker skips it. The plugin
can be installed without --dangerously-force-unsafe-install.
BREAKING CHANGE: drops the llmApiKeyEnv plugin config field along with
the HINDSIGHT_API_LLM_*, HINDSIGHT_EMBED_API_*, and HINDSIGHT_BANK_ID
environment variables. Users must now configure llmProvider and
llmApiKey explicitly via 'openclaw config set'. Migration guide is in
hindsight-docs/docs-integrations/openclaw.md and the integration
changelog.
* chore(openclaw): pin published versions of hindsight-all and hindsight-client
Phase 2 (#949) introduced @vectorize-io/hindsight-all and
@vectorize-io/hindsight-client as plugin dependencies using 'file:'
workspace paths. Those paths resolve inside the monorepo but break when
the published tarball is installed outside it — 'openclaw plugins
install @vectorize-io/hindsight-openclaw' failed with 'Cannot find
module @vectorize-io/hindsight-all' because npm could not resolve the
file: path from the extracted extension directory.
Replace both with semver ranges targeting the published versions:
@vectorize-io/hindsight-all ^0.1.0
@vectorize-io/hindsight-client ^0.5.0
Verified end-to-end: 'openclaw plugins install <local-tarball>' now
succeeds without --dangerously-force-unsafe-install and without the
workspace-symlink hack. npm pulls both dependencies from the registry
into the extracted extension's node_modules, the plugin loads cleanly,
and 'openclaw plugins doctor' reports no issues.
Wires the Rust CLI up to every endpoint exposed by the Hindsight OpenAPI
spec and adds CI enforcement so new endpoints or new request-body fields
cannot slip in without matching CLI coverage.
Endpoints
- New `hindsight webhook {list,create,update,delete,deliveries}` and
`hindsight audit {list,stats}` subcommands.
- `hindsight bank` gains `set-disposition`, `consolidation-recover`,
`export-template`, `import-template`, `template-schema`.
- `hindsight memory` gains `history` and per-memory `clear-observations`.
- `hindsight document update`, `hindsight operation retry` added.
- Brings CLI coverage from 46/62 to 62/62 operations.
Request-body parameters
- Expose missing flags that the CLI was silently hardcoding: directive
`--priority`; mental-model `--tags` / `--max-tokens` /
`--trigger-refresh-after-consolidation`; recall `--query-timestamp`;
reflect `--fact-types` / `--exclude-mental-models` /
`--exclude-mental-model-ids`; retain `--document-tags`.
CI enforcement
- New `cli-coverage-check` entry point in `hindsight-dev` parses
openapi.json and verifies that (a) every operationId is called from
hindsight-cli/src/ (the progenitor client method names match the
operationId), and (b) every request-body property is present in
main.rs as a clap field or `long = "..."` attribute.
- Intentional non-exposures live in `hindsight-cli/.openapi-coverage.toml`
under `[skip]` / `[fields.<op>]` with a reason each (38 documented
field skips for flattened structs, nested structs, or fields surfaced
via a different subcommand).
- New `check-cli-coverage` job in .github/workflows/test.yml, triggered
on cli/core/dev/ci path changes, runs the script on every PR.
- smoke-test.sh exercises the new webhook / audit / bank-template /
set-disposition / consolidation-recover commands.
* feat: add HINDSIGHT_API_DEFAULT_BANK_TEMPLATE env var
Server-level default bank template applied automatically to every
newly-created bank. Holds an inline JSON BankTemplateManifest with the
same shape as the /import endpoint body. Fields set by the template
become per-bank overrides so they take precedence over equivalent
HINDSIGHT_API_* env defaults. The template is applied once on first
creation and never reapplied, so user overrides via PATCH /config are
never clobbered. Malformed manifests are logged and ignored so a broken
server-level setting cannot wedge bank creation.
* chore: regenerate docs skill
* test: update async_retain test mock for renamed bank_profile helper
* feat: add @vectorize-io/hindsight-embed daemon lifecycle package
Create a new top-level `hindsight-embed-npm/` package that owns the daemon
lifecycle for the Python `hindsight-embed` CLI: spawning via `uvx`, writing
the profile, waiting for `/health`, and shutting down. Nothing more.
Deliberately does not ship an HTTP client — `@vectorize-io/hindsight-client`
already covers retain / recall / reflect / createBank against the Hindsight
API, and the two packages compose: once `manager.start()` returns, consumers
talk to the daemon via `new HindsightClient({ baseUrl: manager.getBaseUrl() })`.
`HindsightEmbedManagerOptions.env` forwards an arbitrary `Record<string,
string>` to both the daemon process and the profile config via `--env K=V`,
and `extraProfileCreateArgs` / `extraDaemonStartArgs` escape hatches cover
any new CLI flag without waiting for a wrapper release.
Refactor `hindsight-integrations/openclaw` to consume both packages:
`HindsightEmbedManager` for daemon lifecycle in local mode, `HindsightClient`
for all HTTP memory operations. Drop the bespoke subprocess/HTTP client that
used to live in openclaw. The retain queue stays local to openclaw (it's a
client-side reliability workaround with a single consumer today — will move
to the client package or server-side when a second consumer needs it).
Wire the new package into the main release pipeline (versioned alongside
the other core packages, published from `v*` tags) and add a CI build job.
* docs: add Embedded Node.js SDK page for @vectorize-io/hindsight-embed
* refactor: rename hindsight-embed-npm to hindsight-all, restructure docs sidebar
The Node package previously named @vectorize-io/hindsight-embed was
semantically misnamed: hindsight-embed (Python) is a CLI tool, while what
this Node package actually provides is the Node equivalent of hindsight-all
— a programmatic lifecycle manager for a local Hindsight daemon. Rename to
match.
Package rename
- hindsight-embed-npm/ → hindsight-all-npm/ (git mv, history preserved)
- @vectorize-io/hindsight-embed → @vectorize-io/hindsight-all
- class HindsightEmbedManager → HindsightServer (matches Python hindsight-all)
- HindsightEmbedManagerOptions → HindsightServerOptions
- src/manager.ts → src/server.ts, src/manager.test.ts → src/server.test.ts
- openclaw (index.ts, backfill.ts, tests) and the claude-code Python port
updated to reference the new names
Docs restructure
- Split sdks/python.md: now client-only content. New sdks/hindsight-all.md
covers the programmatic hindsight-all Python package (HindsightServer and
HindsightEmbedded).
- Rename sdks/embed-npm.md → sdks/hindsight-all-npm.md with HindsightServer
examples.
- New "Installation" sidebar section, placed after Hosting, containing
Docker / Kubernetes / Bare Metal (anchor links into developer/installation)
plus Programmatic API (Python), Programmatic API (Node.js), and Daemon CLI.
- Add si-docker, si-kubernetes, si-nodedotjs, lu-hard-drive to the sidebar
ICON_MAP.
Docs dev-server fix
- docusaurus.config.ts: drop the flaky NODE_ENV sniff for including the
"Next" version. Use INCLUDE_CURRENT_VERSION exclusively. NODE_ENV was
unreliable across hot-reload paths and caused the Next version to
disappear intermittently when editing files.
- scripts/dev/start-docs.sh: export INCLUDE_CURRENT_VERSION=true so local
dev always shows Next; production builds leave it unset.
Lockfile cleanup
- package-lock.json and hindsight-integrations/openclaw/package-lock.json
had extraneous hindsight-embed-npm blocks left over from the rename.
Removed manually and verified with npm install.
* ci: fix openclaw jobs by pre-building workspace deps; regenerate docs-skill
The build-openclaw-integration and test-openclaw-integration jobs failed
with "Failed to resolve entry for package @vectorize-io/hindsight-all"
because openclaw depends on two monorepo workspaces via `file:` deps
(@vectorize-io/hindsight-client and @vectorize-io/hindsight-all) whose
`dist/` directories are gitignored and never built before openclaw's npm ci.
Both jobs now install the root workspace and build the two deps first,
mirroring the release-control-plane pattern.
Also regenerate skills/hindsight-docs/references/* via
./scripts/generate-docs-skill.sh:
- new skill pages for sdks/hindsight-all{.md,-npm.md}
- updated skill pages for sdks/embed.md and sdks/python.md to match
the new H1s and split content
- incidental refreshes to changelog/index.md, developer/models.md,
openapi.json, and uv.lock that verify-generated-files picked up
* ci: build openclaw before running tests so symlink test can realpath dist
PR #932 added update_mode (replace/append) to retain items but
did not update the docs. Add a section explaining the parameter,
when to use append mode, and a JSON example.
Closes#957
* feat(openclaw): add session pattern filtering for ignore and stateless sessions
Adds three new config options to the OpenClaw plugin that allow filtering
sessions by key pattern before recall and retain operations fire:
- `ignoreSessionPatterns`: glob patterns for sessions to skip entirely
(no recall, no retain). Useful for cron/scheduled agent sessions.
- `statelessSessionPatterns`: glob patterns for read-only sessions —
retain is always skipped; recall is also skipped when
`skipStatelessSessions` is true (default).
- `skipStatelessSessions`: boolean (default: true). When false, sessions
matching statelessSessionPatterns can still recall but never retain.
Pattern syntax mirrors lossless-claw: `*` matches non-colon characters,
`**` matches anything including colons. Session keys follow the OpenClaw
format `agent:<agentId>:<type>:<uuid>`.
Example config:
ignoreSessionPatterns: ["agent:*:cron:**"]
statelessSessionPatterns: ["agent:*:subagent:**", "agent:*💓**"]
skipStatelessSessions: true
Implementation:
- New `session-patterns.ts` module with compile/match utilities
- Session filter applied in `before_prompt_build` and `agent_end` hooks
immediately after the existing `excludeProviders` check
- New fields wired through `getPluginConfig`
- Schema added to `openclaw.plugin.json` (additionalProperties: false
was already set, causing config validation errors without this)
- 11 unit tests in `session-patterns.test.ts`
- 5 integration tests added to `hooks.integration.test.ts`
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* test(openclaw): support HINDSIGHT_API_TOKEN in integration tests
Pass HINDSIGHT_API_TOKEN env var through to HindsightClient and plugin
config in integration tests so tests work against authenticated APIs.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
* docs(openclaw): document session pattern filtering options
Add ignoreSessionPatterns, statelessSessionPatterns, and skipStatelessSessions
to the README config table with glob syntax reference and usage examples.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
---------
Co-authored-by: Marco Rutsch <[email protected]>
Co-authored-by: Claude Sonnet 4.6 <[email protected]>
* docs: add 0.5.0 release notes and changelog
* docs: include all commits since v0.4.22 and add recall perf to blog
* docs: include all commits since v0.4.22 and add recall perf to blog
* docs: add openrouter default model to provider table
* docs: reorder blog sections, fix code snippets, remove paperclip
* docs: add hermes integration docs link
* docs: fix broken anchor in blog post TOC
greenlet 3.4.0 lacks manylinux_2_41_aarch64 wheels. Use a UV_CONSTRAINT
file instead of the workspace lock file (which doesn't work in the
single-package Docker context).
Without the lock file, uv sync resolves fresh and picks up greenlet
3.4.0 which lacks arm64 wheels for manylinux_2_41, breaking the
multi-arch Docker build.
* fix: exclude local-llm from [all] extra to avoid heavy llama-cpp-python dep
local-llm (llama-cpp-python) requires C++ compilation and is only needed
for the built-in llamacpp provider. Keep it as a separate opt-in:
pip install 'hindsight-api-slim[local-llm]'
* feat: add local-llm optional extra to hindsight-all
Allows: pip install 'hindsight-all[local-llm]' to get built-in llamacpp support.
* chore: regenerate uv.lock from workspace root
* feat: add built-in llama.cpp LLM provider for fully local inference
Add `llamacpp` as a new LLM provider that manages a llama-cpp-python server
subprocess. Auto-downloads Gemma 4 E2B Q4_K_M (~3.5 GB) on first use and
runs inference locally via Metal/CUDA with no external services needed.
- New provider: `HINDSIGHT_API_LLM_PROVIDER=llamacpp`
- Singleton server shared across retain/reflect/consolidation
- Configurable: model path, GPU layers, context size, grammar enforcement
- User-extensible via `HINDSIGHT_API_LLAMACPP_EXTRA_ARGS`
- Flash attention + prompt caching enabled by default
- LLM provider cleanup on shutdown (stops subprocess)
- hindsight-embed: `--ui` flag on `daemon start`, removed FORCE_CPU on macOS
- Docs: configuration.md, models.mdx, providers grid updated
* chore: regenerate docs skill and update lockfile for local-llm dep
* feat: add update_mode='append' for retain to concatenate content to existing documents
When retaining with update_mode='append' and a document_id that already exists,
the new content is appended to the existing document text and the full document
is reprocessed. Delta retain automatically skips unchanged chunks, so only the
new content triggers LLM extraction.
- Add update_mode field to MemoryItem (API), RetainContentDict (internal), MCP tools
- Validate that update_mode='append' requires a document_id
- Fetch existing document content and prepend before processing in orchestrator
- Update Python, TypeScript, Go generated clients and top-level client wrappers
- Add tests for append, multiple appends, no-existing-doc, validation, and default replace
* fix: add update_mode field to Rust CLI and client MemoryItem initializers
* chore: regenerate docs skill references for update_mode
* docs: add best practice for filtering recall by memory shape (#856)
Add guidance on using entity labels with `tag: true` to deterministically
filter recall results when a bank contains different memory shapes
(e.g., concise rules vs. detailed procedures).
* feat: add OpenRouter support for LLM, embeddings, and reranking
OpenRouter is OpenAI-compatible for chat/embeddings and Cohere-compatible
for reranking, so no new provider classes are needed.
- LLM: added as OpenAICompatibleLLM provider (default model: qwen/qwen3.5-9b)
- Embeddings: reuses OpenAIEmbeddings with OpenRouter base URL (default: perplexity/pplx-embed-v1-0.6b)
- Reranker: reuses CohereCrossEncoder with OpenRouter rerank endpoint (default: cohere/rerank-v3.5)
- API key fallback chain: dedicated key → shared OPENROUTER_API_KEY → LLM_API_KEY
* chore: regenerate docs skill references and fix formatting
Extend format_facts_for_prompt() to include occurred_end and mentioned_at
temporal fields (when non-null), matching the MemoryFact model. Also add
RecallResponse.to_prompt_string() to Python and TypeScript client SDKs so
users can serialize recall results (with chunks and entity summaries) into
LLM-ready prompt strings.
Closes#924
* fix: make LiteLLM SDK embeddings encoding_format configurable (#925)
The hardcoded encoding_format='float' breaks providers like Voyage AI
(only accepts 'base64') and Gemini (doesn't support the parameter at all).
Add HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_ENCODING_FORMAT config option
that defaults to 'float' for backwards compatibility. Set to empty string
to omit the parameter for incompatible providers.
* chore: regenerate docs skill after configuration change
* security: bump lodash, lodash-es, and defu in root lockfile
Fixes Dependabot alerts in the root npm workspace lockfile:
- GHSA-r5fr-rjxr-66jc (high) lodash <4.18.1 (alert #338)
- GHSA-r5fr-rjxr-66jc (high) lodash-es <4.18.1 (alert #335)
- GHSA-737v-mqg7-c878 (high) defu <6.1.7 (alert #343)
defu (6.1.4 -> 6.1.7) and lodash (4.17.23 -> 4.18.1) were bumped via
targeted `npm update`. lodash-es was pinned exactly to 4.17.23 by
@chevrotain packages (transitive dep of mermaid in hindsight-docs),
so a `lodash-es` override (>=4.18.1) is added to the root package.json
to force resolution to the patched 4.18.1.
Verified: `npm ci` succeeds with 0 vulnerabilities. Mermaid/chevrotain
consumers all dedupe to lodash-es 4.18.1. lodash-es 4.x is semver-
compatible.
* chore: regenerate hindsight-docs skill
Picks up FAQ and best-practice sections added in #905 that were not
regenerated at merge time, so that `verify-generated-files` passes
for this branch.
* security: bump vite across integrations to patched versions
Fixes Dependabot alerts for vite transitive dev dependency:
- GHSA-v2wj-q39q-566r (high): server.fs.deny bypass with queries
- GHSA-p9ff-h696-f583 (high): related vite server vulnerability
Adds a `vite` entry to the npm `overrides` in each integration's
package.json to force the patched version (>=8.0.5). To make this
possible in ai-sdk, chat, and openclaw — which pinned vitest ^4.0.18
whose vite peer is `^6.0.0 || ^7.0.0` — the minor-compatible bump
vitest ^4.0.18 -> ^4.1.2 is also included. vitest 4.1.x supports
vite 8.x (peer: ^6 || ^7 || ^8), so all six integrations converge on
vite 8.x consistently.
paperclip had no overrides block; one was added.
Verified locally: `npm ci && npx vitest run` passes in all six
integrations (ai-sdk 23, chat 28, openclaw 66, opencode 89, paperclip 27,
nemoclaw 36 tests).
* chore: regenerate hindsight-docs skill
Picks up FAQ and best-practice sections added in #905 that were not
regenerated at merge time, so that `verify-generated-files` passes
for this branch.
Some LLM providers (e.g. Anthropic Haiku) return 1-indexed
content_index values. When only one content item is provided,
this causes KeyError: 1 since the dict only has key 0.
Clamp content_index to the valid range instead of crashing.
Fixes#873
Co-authored-by: easonysliu <[email protected]>
* fix(recall): cap entity fanout in graph expansion to prevent slow queries
On large banks, the entity co-occurrence self-join in _expand_combined()
produces massive intermediate row counts when seeds reference high-fanout
entities (e.g. an entity with 25K+ mentions). This causes recall latency
to degrade significantly.
Changes:
- Replace unbounded entity self-join with LATERAL per-entity cap
(graph_per_entity_limit, default 200), reducing intermediate rows
from potentially millions to at most num_entities * 200
- Add ORDER BY unit_id DESC in LATERAL subquery for deterministic
recency-biased sampling (rides the PK index, no extra sort)
- Add timeout fallback (graph_expansion_timeout, default 10s) that
drops entity expansion and falls back to semantic+causal only
- Add composite index (entity_id, unit_id) on unit_entities for
index-only scans in the LATERAL subquery
- Merge 3 unmerged migration heads into one
- Fix recall_perf.py dotenv override issue
Unlike the approach in #895, this does NOT filter out hub entities
entirely — all entities are kept but capped equally, preserving
retrieval quality for queries about frequently-mentioned entities.
Benchmarked on a 67K-unit bank (top entity = 25K mentions):
- retrieval_graph: 0.337s → 0.055s (84% faster)
- end-to-end recall: 0.912s → 0.519s (43% faster)
* fix(tests): fix broken test_combined_scoring and test_reranking_proof_count
- test_combined_scoring: replace MagicMock(spec=RetrievalResult) with real
dataclass instances — MagicMock attributes returned nested mocks that
failed on >= comparisons with int
- test_reranking_proof_count: remove deleted `embedding` param from
RetrievalResult constructor, use None for occurred_start/end to get
neutral recency (datetime.now gave recency=1.0 which boosted scores)
* refactor: rename config to link_expansion_ prefix, fix observation fanout
- Rename GRAPH_PER_ENTITY_LIMIT → LINK_EXPANSION_PER_ENTITY_LIMIT and
GRAPH_EXPANSION_TIMEOUT → LINK_EXPANSION_TIMEOUT to follow the
convention that these are specific to the link_expansion graph retriever
- Apply the same LATERAL per-entity cap to _expand_observations(), which
had the same unbounded self-join through unit_entities
* style: fix formatting in config.py
* feat(openclaw): support exact static bank ids
* test(openclaw): use generic static bank id example
* feat(openclaw): support bankId static bank configuration
---------
Co-authored-by: Aldous the Orchestrator <[email protected]>
Fixes Dependabot alerts:
- GHSA-jjhc-v7c2-5hh6 (critical): Authentication bypass via OIDC userinfo
cache key collision (CVE-2026-35030)
- GHSA-53mr-6c8q-9789 (high): related litellm vulnerability
Updates both hindsight-api-slim and hindsight-integrations/litellm to
require litellm >=1.83.0. The previous upper cap (<=1.82.6) was set due
to the 1.82.7/1.82.8 supply chain compromise, which has since been yanked
from PyPI; 1.83.0 was published from the new secure CI/CD v2 pipeline
and is safe.
The uv.lock diffs are large because the current uv version (0.9.11)
upgrades the lockfile format (adds revision=3 and upload-time fields);
only litellm itself changes version (1.81.10/1.80.10 -> 1.83.0).
All 68 tests in hindsight-integrations/litellm pass against 1.83.0.
* fix(mcp): validate UUID inputs at engine level and add sync_retain tool (#888)
- Add UUID validation in memory_engine for get_memory_unit, delete_memory_unit,
get_mental_model, delete_mental_model, get_mental_model_history (raises ValueError)
- Catch ValueError → 400 in HTTP route handlers
- Add sync_retain MCP tool that calls retain_batch_async directly for immediate
availability (no polling needed)
- Register sync_retain in _ALL_TOOLS, _SINGLE_BANK_TOOLS, UI MCP_TOOL_GROUPS
- Add code-review check for MCP tool registration completeness
* fix: remove UUID validation for mental model IDs (column is TEXT, not UUID)
Mental model IDs are TEXT columns that accept arbitrary string IDs
(e.g., 'team-communication-preferences'). UUID validation was incorrectly
added to get_mental_model, delete_mental_model, and get_mental_model_history.
* test: add regression tests for #874 and #894
Add tests for None event_date in fact extraction (AttributeError fix)
and for _register_profile skipping .env overwrite with short config keys.
* fix(config): validate entity_labels structure on PATCH (#891)
Config PATCH accepted bare strings in entity_labels values without
validation, causing silent failures at retain time. Now validates
via parse_entity_labels() before writing to DB, and fixes the
BankTemplateConfig type from list[str] to list[dict[str, Any]].
* fix(scripts): handle Python client generator README crash gracefully
The openapi-generator sometimes crashes writing README_onlypackage.mustache.
Allow the failure with || true since all API/model files are generated
before that step, and add a verification check for api_client.py.
* chore: regenerate docs skill openapi.json
Add guidance on using entity labels with `tag: true` to deterministically
filter recall results when a bank contains different memory shapes
(e.g., concise rules vs. detailed procedures).
* feat: add OpenCode persistent memory plugin
Add hindsight-opencode integration with:
- Three custom tools: hindsight_retain, hindsight_recall, hindsight_reflect
- Auto-retain on session.idle with document_id deduplication
- Memory injection on session start via system transform hook
- Memory preservation during context window compaction
- Sliding window retain with retainOverlapTurns support
- 4-level config hierarchy (defaults, user file, plugin options, env vars)
- Dynamic bank ID derivation (agent, project, channel, user dimensions)
- CI job, release script entry, docs page
79 tests across 6 test files.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix: address review findings for opencode integration
1. Pre-compaction retain now uses shared retainSession() helper,
respecting retainMode, documentId, and session_id metadata
consistently with idle-retain (was bypassing retention policy).
2. System transform recall is only consumed after successful injection.
If Hindsight is briefly unavailable, the plugin retries on the next
LLM call instead of permanently skipping recall for the session.
3. Config validation for retainMode and recallBudget — typos like
"full_session" or "maximum" now log a warning and fall back to
the default instead of silently changing retention semantics.
85 tests (6 new covering compaction documentId, recall retry, and
config validation).
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix: docs/tools findings from second review round
1. Remove "session" from supported dynamic bank fields in docs —
the implementation can't vary bank ID per session since it's
derived once at plugin startup.
2. Explicit tools (retain, reflect) now call ensureBankMission()
before API calls, so bankMission/retainMission are applied even
when the agent uses tools exclusively without triggering hooks.
3. Added tests for mission setup via tools path.
88 tests pass.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix: recall retry semantics and README bank scoping clarity
1. recallForContext now returns { context, ok } to distinguish
"no results" (ok=true) from "API error" (ok=false). System
transform consumes the session on ok=true even with 0 results,
so empty banks don't cause repeated queries. Only transient API
failures preserve retry.
2. README clarifies that channel/user bank dimensions are process-
scoped (set via env vars before launch), not per-session dynamic
within a running OpenCode process.
89 tests pass.
Co-Authored-By: Claude Opus 4.6 <[email protected]>
* fix: review fixes for opencode integration
- Rename CI job from build-opencode-integration to test-opencode-integration
to match naming convention for integrations that run tests
- Fix tsconfig module resolution to Node16 (consistent with other integrations)
- Extract shared makeConfig test helper to avoid duplication across 3 test files
* fix: remove unused PluginState import from tools.ts
---------
Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
2026-04-07 10:11:57 +02:00
1487 changed files with 172394 additions and 32152 deletions
@@ -157,7 +157,16 @@ If any files in `hindsight-integrations/` were added or changed, verify:
- **Release process** — check that the integration name is in the `VALID_INTEGRATIONS` array in `scripts/release-integration.sh`. If missing, flag it.
- **Code standards** — the integration code must follow all Python style rules (type hints, no raw dicts, no tuple returns, etc.).
### 10. Review against other coding standards
### 10. Check MCP tool registration completeness
If any new MCP tools were added or existing tools renamed in `hindsight-api-slim/hindsight_api/mcp_tools.py`:
- **`_ALL_TOOLS` set** in `mcp_tools.py` — must include the new tool name
- **`tools_to_register` default set** in `register_mcp_tools()` in `mcp_tools.py` — must include the new tool name
- **`_SINGLE_BANK_TOOLS` set** in `hindsight-api-slim/hindsight_api/api/mcp.py` — must include the new tool if it is bank-scoped (not a bank-management tool like `list_banks`/`create_bank`)
- **`MCP_TOOL_GROUPS`** in `hindsight-control-plane/src/components/bank-config-view.tsx` — must include the new tool in the appropriate group for the UI tool selector
- **Tool count assertions** in tests (e.g., `test_mcp_tools.py`) — must be updated to reflect the new count
### 11. Review against other coding standards
Check the diff for violations of the standards listed above:
- Python files at project root (not allowed)
@@ -169,7 +178,7 @@ Check the diff for violations of the standards listed above:
# 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)
@@ -54,12 +65,25 @@ HINDSIGHT_API_LOG_LEVEL=info
# HINDSIGHT_API_VECTOR_EXTENSION=pgvectorscale # Auto-detects pg_diskann on Azure
# Embeddings Configuration (Optional - uses local by default)
# Provider: "local" (default) or "tei" (HuggingFace Text Embeddings Inference)
Make the asymmetry deliberate. Don't leave an Oracle slot empty just because
you didn't think about it — copy-pasting a PG migration without the Oracle
half is exactly how schemas drift.
3. **Run migrations locally**:
```bash
# Set database URL and run migrations for the base schema plus all tenants
@@ -222,6 +261,10 @@ Every new integration in `hindsight-integrations/` must satisfy all of the follo
If any of these are missing, the integration is incomplete and must not be pushed or merged.
### Changelogs
Never add "Unreleased" entries to changelogs (e.g. `hindsight-docs/src/pages/changelog/**`). Changelog entries are written by the release script (`./scripts/release-integration.sh`) when a version is actually cut. If a bug fix or feature needs documenting before release, describe it in the PR/commit — the release tooling will surface it in the published changelog section.
### Adding New API Configuration Flags
Configuration follows a hierarchical system: **Global (env vars) → Tenant (via extension) → Bank (database)**.
@@ -30,7 +30,7 @@ It eliminates the shortcomings of alternative techniques such as RAG and knowled
Hindsight is the most accurate agent memory system ever tested according to benchmark performance. It has achieved state-of-the-art performance on the LongMemEval benchmark, widely used to assess memory system performance across a variety of conversational AI scenarios. The current reported performance of Hindsight and other agent memory solutions as of January 2026 is shown here:
The benchmark performance data for Hindsight has been independently reproduced by research collaborators at the Virginia Tech [Sanghani Center for Artificial Intelligence and Data Analytics](https://sanghani.cs.vt.edu/) and The Washington Post. Other scores are self-reported by software vendors.
@@ -84,6 +84,8 @@ cd docker/docker-compose
docker compose up
```
> Oracle AI Database is also supported for enterprise deployments with full feature parity. See the [storage documentation](https://hindsight.vectorize.io/developer/storage) for details.
Node.js equivalent of the Python [`hindsight-all`](https://pypi.org/project/hindsight-all/) package — programmatic lifecycle manager for a local Hindsight daemon. Use this when you want to embed Hindsight in a Node application without hand-rolling subprocess management.
This package deliberately does **not** ship an HTTP client. Once the daemon is running, talk to it with [`@vectorize-io/hindsight-client`](https://www.npmjs.com/package/@vectorize-io/hindsight-client) against `server.getBaseUrl()`. The two packages compose — one owns the daemon process, the other owns the HTTP API surface.
## Requirements
- **Node.js >= 22** — uses global `fetch` and `AbortSignal.timeout`.
- **`uv` / `uvx`** on `PATH` — used to download and run the underlying `hindsight-embed` daemon on first use. Install via <https://docs.astral.sh/uv/>.
awaitclient.retain("user-123","User prefers dark mode and concise answers.",{
documentId:"pref-2026-04-01",
});
constrecall=awaitclient.recall("user-123","what are the user preferences?");
console.log(recall.results);
awaitserver.stop();
```
For a remote Hindsight API, skip `HindsightServer` entirely and just point `HindsightClient` at the remote URL.
## Open config — forward-compatible with new daemon flags
`HindsightServerOptions` is designed so every new environment variable or CLI flag in the underlying Hindsight daemon can be used without waiting for a wrapper release:
- **`env`** accepts an arbitrary `Record<string, string>`. Every entry is exported into the daemon process and written into the profile config via `--env KEY=VALUE`.
- **`extraProfileCreateArgs`** / **`extraDaemonStartArgs`** append raw args to the respective commands.
## Development against a local checkout
If you're hacking on the Python `hindsight-embed` package in the same monorepo, point the server at the local path — it'll use `uv run --directory <path>` instead of `uvx`:
-`Logger` interface plus `silentLogger` (default) and `consoleLogger` helpers.
-`getEmbedCommand(opts)` — low-level helper that returns the `[cmd, ...args]` tuple used to invoke the underlying Python CLI.
For memory operations (retain, recall, reflect, bank management, stats) use [`@vectorize-io/hindsight-client`](https://www.npmjs.com/package/@vectorize-io/hindsight-client).
"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.",
"""Add 'mental_model' to the fact_type check constraint."""
schema=_get_schema_prefix()
@@ -38,7 +40,7 @@ def upgrade() -> None:
""")
defdowngrade()->None:
def_pg_downgrade()->None:
"""Remove 'mental_model' from the fact_type check constraint."""
schema=_get_schema_prefix()
@@ -48,3 +50,11 @@ def downgrade() -> None:
ADD CONSTRAINT memory_units_fact_type_check
CHECK (fact_type IN ('world', 'experience', 'opinion', 'observation'))
""")
defupgrade()->None:
run_for_dialect(pg=_pg_upgrade)
defdowngrade()->None:
run_for_dialect(pg=_pg_downgrade)
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.
Ben