* 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.
* 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
* 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 <boschi1997@gmail.com>
* 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
- 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(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 <noreply@anthropic.com>
---------
Co-authored-by: TuftyBruno <noreply@anthropic.com>
Co-authored-by: cortex <cortex@cortexone.local>
* 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).
* 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
* 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
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.
* 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.
* 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
* 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
* 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
* 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.
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.
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.
* 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.
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.
* 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
* 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).
* 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
* 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)
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 <octo-patch@github.com>
* 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.
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).
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 <r2668940489@gmail.com>
Co-authored-by: r266-tech <r266-tech@users.noreply.github.com>
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.
* 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(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
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.
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
* 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
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
* 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
* 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
* 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
* 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
* fix: make bank_id metric label opt-in to prevent OTel memory leak
bank_id as an OTel metric attribute creates unbounded histogram growth
since each unique bank_id produces never-evicted time series. Default
to excluding it; opt in with HINDSIGHT_API_METRICS_INCLUDE_BANK_ID=true
for deployments with few banks.
Closes#850
* refactor: use config.py for metrics_include_bank_id setting
Move HINDSIGHT_API_METRICS_INCLUDE_BANK_ID from direct os.getenv in
metrics.py to the standard HindsightConfig path. Add configuration
documentation.
Nicolò Boschi