* feat(coding-agents): retry a rate-limited write-back instead of dropping it
A 429 on POST /memories was indistinguishable from a 500: `req` threw a plain
Error, the write-back was abandoned for that turn, and nothing backed off. The
content survived — the cursor stays dirty, so the next Stop replaces the whole
document — but the turn's write simply did not happen, and on a session's LAST
Stop there is no next one.
429 now raises a typed RateLimitedError carrying the parsed Retry-After, and the
session write-back retries on it. Retrying is safe rather than duplicative
because the payload carries a deterministic operation_id: an identical
resubmission is collapsed into the original operation server-side, so a retry
after a response we never saw cannot write twice.
Two conditions bound it, and the first is the point:
- ONLY while our write is still the newest. If another write-back has claimed the
cursor since — a newer turn, another process — ours is superseded: the newer
one carries what we were sending, or replaces the document outright because our
failure left the cursor dirty. Retrying then would spend a hook's remaining
time re-sending content already on its way.
- ONLY within a hook's clock. Claude Code allows 60s for a Stop hook and a cold
daemon can already have eaten most of it, so a Retry-After that does not fit a
6s budget is not honoured at all — waiting less than the server asked would
just earn another 429, and waiting the full amount trades a deferred retain for
a killed hook.
Anything that is not a rate limit still fails immediately, as before.
* feat(coding-agents): add maxParallelRetains config and 429-aware drain
* fix(coding-agents): cap the 429 backoff so a long Retry-After cannot park a drain
Review follow-up on the retry path.
`Retry-After` was honoured without a ceiling, so an hour-long value — an
incident, a misconfigured limiter, a proxy inventing one — would park the drain
for that hour, up to the whole `maxMs`, with the background seed frozen behind
it. The header is a server's hint, not a budget we owe it.
Capped at 60s. That keeps the signal (the floor and the header still lengthen the
wait) without handing over the schedule: if the limit still applies, the next
poll gets another 429 and backs off again.
Also re-syncs the docs page and skill mirror from the README, which the rebase
onto main left stale by a column width.
---------
Co-authored-by: David Eriksson <[email protected]>
* fix(embed): define daemon stop() success by port occupancy, not the health probe
stop() used is_running() -- a 2s /health probe -- both as its already-stopped
guard and as its final success condition. A daemon that is alive but busy
(slow provider call, model load) fails that probe, so 'daemon stop' returned
True without sending any signal, and a failed termination or missing PID
also fell through to a reported success.
Resolve the port from the profile and use occupancy for every decision:
already stopped only when nothing is bound; bound port with no findable PID
is a failure; a False from _kill_process() is a failure; after the kill,
success means the listener is gone. This mirrors the occupancy/health
separation _clear_port() already uses.
Closes#3169
* fix(embed): gate daemon stop on health identity, not just occupancy
koriyoshi2041 review: occupancy alone is not authorization to kill. An
unrelated service on the profile port would be SIGTERM'd by the previous
fix. Restore an identity check before signaling: _port_health_ok confirms
the listener answers like Hindsight (status/database in /health payload),
which is stricter than the old is_running() 200-only check.
A busy Hindsight daemon (the #3169 scenario) fails this probe, so stop()
now returns False rather than killing blind - a failed stop is recoverable,
an unknown kill is not. Port occupancy remains the success condition after
termination (koriyoshi endorsed this).
Adds test_foreign_listener_is_not_signaled (the regression koriyoshi asked
for) and updates the busy-daemon test to assert the new refuse-to-kill
behavior.
* fix(embed): drop the health-identity gate from daemon stop()
The gate refused to signal a listener that failed /health, but a busy
Hindsight daemon is exactly what fails that probe - the case #3169 is
about. It turned "claims success, kills nothing" into "reports failure,
kills nothing", leaving a wedged daemon unstoppable, and contradicted
_clear_port(), which reclaims the same port state on the start path.
stop() now decides on occupancy alone: port free means already stopped,
a bound port with no PID or a failed kill is a failure, and success is
the listener disappearing.
The two identity tests now assert the listener is signalled; one of them
also pins stop() and _clear_port() to the same policy for an occupied,
unhealthy port.
I committed this in #3380 and it has been on main since, in the v0.2.0 and
v0.2.1 tags: a symlink at hindsight-integrations/coding-agents/node_modules
pointing at an absolute path on my own machine. Anyone cloning gets a dangling
link where the package's node_modules belongs.
The published npm tarballs are unaffected — npm excludes node_modules from packs
— so this is repository hygiene, not a shipped defect.
.gitignore had `node_modules/`, which matches directories only. A symlink is a
file, so it slipped straight past — which is exactly how it got committed, since
pointing a scratch worktree at an already-installed node_modules is the fast way
to run this package's tests. Adding the slashless pattern closes that.
* feat(coding-agents): apply retain attribution to all ingestion paths
* refactor(coding-agents): one retain call per survey marker, not two
Review follow-up. Both survey-baseline writes branched into two complete
client.retain(...) calls that differed only in whether `{ metadata }` was passed
— six duplicated argument lists between them, which is where a later edit updates
one and misses the other.
`retain` only assigns metadata when it is truthy, so `{ metadata: undefined }`
already omits it and one call covers both cases. That is what knowledge-tools.ts
does with `Object.keys(metadata).length ? { metadata } : {}`.
The marker assertion in session-start.test.ts gains the opts argument, since the
call now always passes one. Behaviour is unchanged: with no retainMetadata
configured the stamp is empty and nothing reaches the API.
---------
Co-authored-by: Reese <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
A DB failure inside one tag group's recall propagates out of
run_consolidation_job to the worker, which marks the operation failed and
re-queues it with a 5s base backoff. Plain asyncio.gather re-raises the
first exception but does NOT cancel its siblings, so the other tag groups
kept running detached: still calling the LLM, still stamping
mark_consolidated, still committing write-groups — after the operation had
already failed, and while the retry was starting.
The per-scope scope_locks are local to a single dispatch, so nothing
serialised an orphan against the retried run, and the "batches within a
group share a scope and MUST run serially" invariant that keeps two
consolidators out of the same observation scope was broken exactly when it
mattered.
Replace both consolidation gathers with _gather_or_cancel, which cancels
the outstanding tasks and awaits them before propagating the original
exception. Not asyncio.TaskGroup: it wraps failures in an ExceptionGroup,
and the worker's _is_non_retryable_task_error does isinstance checks — a
wrapped IntegrityConstraintViolationError would be retried forever.
Cancelling a batch mid-flight leaves its minted write-group undecided, so
also abort it explicitly on the failure path instead of leaving it pending
for the recovery sweep. The abort sits outside decide(commit=True): once
the witness has committed the batch's fate is settled.
The per-fact recall gather keeps failing its batch rather than degrading to
an empty candidate set — hiding an existing twin from the LLM would turn an
UPDATE into a duplicate CREATE. Those memories stay unconsolidated and are
picked up on retry.
Found while investigating #3301.
The write-back cadence is removed. The persistent-plugin harnesses (opencode,
Kilo, Cline CLI) now write back every turn, which is what the default of 1
already did; the hook harnesses never consulted it at all.
Two reasons, and the second is what makes it a removal rather than a
documentation fix.
A client-side cadence holds turns in a process the host can close at any moment,
and there is no reliable signal on the way out: #2869 measured ZERO SessionEnd
retains across 36 hours because Claude Code cancels that hook at shutdown. The
flush a cadence needs cannot be built on the only event that would carry it, so
extending the setting to the seven hook harnesses was never available — and the
asymmetry that left (honoured by three of eleven) was itself the complaint.
The batching it approximated now happens server-side, where nothing can be
stranded: queued retains for one document fold into a single execution
(`engine.retain.fold`, #3395), on top of a claim predicate that serialises
same-document work. Submitting every turn therefore costs one extraction over
the concatenated turns rather than one per turn — the burst control #2143 asked
for, in the place that can do it without risking a turn.
`retainSessions` stays: opting out of write-back entirely is a different
question from how often it fires.
Removed from the config type, the resolver, HINDSIGHT_RETAIN_EVERY_TURNS, the
runtime check and its now-unread retainedUsers bookkeeping, the settings table,
and the tests. The other integrations' `retainEveryNTurns` is a separate setting
in separate packages and is untouched.
Consolidation recalls with stored fact text as the query, so a phrase
like "十万年前" (100,000 years ago) hit unguarded offset arithmetic in
extract_period — which runs BEFORE analyze()'s dateparser guard — and
escaped as ValueError('year -97974 is out of range'), deterministically
failing every recall and consolidation touching the bank. The three
years observed in #3217 (-534, -974, -97974) are exactly
now.year - {2560, 3000, 100000}: query-time arithmetic, not stored rows
(Python datetimes can't represent them, so no bad date can reach the DB
through asyncpg in the first place).
Three layers, mirroring the #2636 add_years fix:
- extract_temporal_constraint (the recall choke point) degrades any
analyzer failure to 'no temporal signal' with a warning; analyze()
itself stays strict so parser bugs still surface in tests.
- chinese_temporal_periods: add_months/subtract_months are now
bounds-checked like add_years (returning None, plumbed through every
call site), and day/week offsets go through the overflow-guarded
add_days instead of raw timedelta addition.
- temporal_periods: an explicit month + year 0000 match returns
NO_TEMPORAL_CONSTRAINT instead of crashing datetime().
* fix(knowledge): sync backing mental_model name on page rename (#3307)
rename_knowledge_node updated knowledge_pages.name only, leaving the
backing mental_models.name stale. A page's searchable document is its
mental model's name + content, so after a rename search kept indexing the
old name (and the two names were not updated atomically).
Update mental_models.name in the same transaction as the node rename
(re-tokenizing search_vector for vchord; native regenerates, other
backends index base columns), so a knowledge_pages name-uniqueness
violation rolls both names back together. Folders (mental_model_id NULL)
are untouched.
Scopes #3307 down to this last remaining gap; roots 1-3, 5, 6 were
already fixed by #3318 and #3335.
* docs(skill): add generated agent-plugin integration page
Pre-existing drift from #3240: the agent-plugin docs source and
integrations.json entry were committed, but the generated docs-skill
mirror was never regenerated, so verify-generated-files was red on main.
Regenerated; only this one file is produced.
Found porting #3136 (unlocked state read-modify-write on Windows). The race it
describes is far less severe here — state is one file per session rather than a
dict keyed by session, so a lost update cannot drop other sessions — but looking
for it surfaced a worse, unconditional bug underneath.
The retain cursor was a FIELD of the session cache, and the prompt hook writes a
fresh `{turns, reflectAnswer, pages}` object rather than merging. So every user
prompt dropped the cursor the previous Stop had written; the next Stop found
none and rewrote the whole document. The incremental write-back added in #3336
therefore never engaged past a session's first turn on ANY hook harness — seven
of eleven. Not a race: deterministic, every session, every turn.
after Stop : {"retain":{"turns":5,...}}
after prompt : {"turns":2,"pages":{...}} <- cursor gone
cursor now : undefined
No test caught it because the unit tests inject a memoryCursorStore directly and
never exercise the file store against a real prompt-hook write. The regression
test added here does exactly that interleaving.
The cursor now lives in its own file. That makes the invariant structural rather
than a convention every future writer has to remember: the two writers have
different lifecycles, no longer share a record, and neither can clobber the
other — which also leaves the concurrent read-modify-write #3136 measured with
nothing to lose here.
State writes are also atomic now (temp file + rename). A plain writeFileSync can
be observed half-written and leaves a fragment behind if the process is killed
mid-write; rename is atomic on POSIX and replaces on Windows. The per-agent
plugin's Python writes already had os.replace() — this had no equivalent.
Cannot be verified on Windows from here; the atomicity is platform-independent
and the clobber fix is verified on macOS.
Explain how tags, tags_match, tag_groups, and directive isolation
interact across REST, MCP, versioned docs, and agent skills.
Clarify the different defaults used by reflect and directive listing,
then regenerate OpenAPI and supported client artifacts.
`prune_stale_cooccurrences` (PG) checked staleness with a correlated
`NOT EXISTS (… INTERSECT …)` evaluated once per cooccurrence row. Each
evaluation re-scanned a hub entity's full membership set, so cost scaled
as (cooccurrence rows) × (hub degree) — 88-140s on a real bank with a
~22K-degree hub (215s in a 12K-degree repro). #2473 had swapped an
earlier hub-rescanning self-join to that INTERSECT, but only made each
per-row check cheaper; it kept the per-row structure, so the product
resurfaced at scale.
Decide staleness against a SET of currently-live pairs built ONCE per
sweep: a `WITH live AS MATERIALIZED` unit-grouped self-join emits every
co-occurring (e1<e2) pair, its cost driven by unit degree (small) not
entity degree, and the victims anti-join hashes against it. `live` is
scoped to the bank's entities so a per-bank sweep stays O(bank), not
O(schema), across a multi-bank maintenance cycle. The #2529 ordered-lock
(`ORDER BY … FOR UPDATE OF c`) is preserved. Oracle already used a
set-based form and is unchanged.
Repro (12K-degree hub, 14K cooccurrence rows): 215,329ms -> ~250ms,
identical delete set. Added a regression test covering partial pruning
around a hub and bank-scoping isolation.
The deadlock #2570 targeted still fired a few times a day because the
insert-side lock ordering was only partial:
1. _bulk_insert_links sorted on (from, to) — two of the four columns in
the unique index (from, to, link_type, COALESCE(entity_id, nil)). A
temporal and a semantic edge on the same pair compared equal, so a
stable sort left them in input order and concurrent inserts could take
the two index entries in opposite orders.
2. That order also disagreed with chunk_storage.delete_chunks_by_ids,
which normalises direction via LEAST/GREATEST. Two different total
orders can still cycle.
Sort both paths on one canonical key — the full, direction-normalised
unique key — by extracting _lock_order_key and pointing the insert sort
at it. The delete side already uses exactly this order and is unchanged.
* fix(coding-agents): resolve the project when the working directory is gone
Supersedes #3110, filed against the per-agent Claude Code plugin.
A hook runs after the fact, so the directory it reports can already be deleted —
an ephemeral worktree removed once the task finished, a checkout moved or deleted
mid-session. git can only answer about a path that exists, so the probe failed
and `basename` of the vanished path became the project identity: a throwaway name
like `agent-a33c4d63` that scatters memory into orphan banks.
Resolution now walks up to the nearest ancestor that still exists and probes
that. This is harness-agnostic on purpose: no harness has to export anything, so
it covers all eleven rather than the one that happens to publish a project-root
variable. For a live directory the walk returns it unchanged, so the common path
is untouched and no existing bank moves.
CLAUDE_PROJECT_DIR is kept as a last rescue for the one case the walk cannot
reach: a LINKED worktree is a sibling of the repository, not a child, so walking
up from it leaves the repository entirely. It is deliberately a list of one
rather than a guess at nine names — only Claude Code is known to export such a
variable, and inventing the others would register behaviour nothing implements.
Also stops project names from being empty. `basename("/")` is "", which produced
bank ids like `coding-agent::` naming nothing; both `{gitProject}` and
`{project}` now fall back to "unknown". That case was flagged reviewing #3286 and
never fixed.
Tests use real git against real directories rather than the mocked
child_process of bank.test.ts, since what is under test is behaviour against
paths that do and do not exist.
* chore(docs): restore the agent-plugin skill mirror
Generated artifact missing on main: #3394 added
hindsight-docs/docs-integrations/agent-plugin.md without regenerating the docs
skill, so skills/.../integrations/agent-plugin.md was never committed.
verify-generated-files only runs on PRs, so the drift is invisible on main and
surfaces as a failure on the next unrelated PR — this one. Separate commit
because it is not part of the project-resolution fix.
* fix(compose): use HINDSIGHT_API_LLM_API_KEY env var
* docs(compose): point run examples at HINDSIGHT_API_LLM_API_KEY
The compose files no longer read OPENAI_API_KEY, so every doc telling
users to export it was left describing a variable nothing reads.
- custom-models/README.md + compose header: export the correct var
- timescale/README.md quick start, prereq and env-var table
- timescale/.env.example: compose's project directory is the compose
file's own directory, so this file IS auto-loaded - naming the wrong
var here silently dropped the key on the documented happy path
---------
Co-authored-by: Ish Fuseini <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(coding-agents): add Prime Agent as a supported harness
Adds Prime Agent (PrimeIntellect) as a plugin harness in
@vectorize-io/hindsight-coding-agents, giving it the shared reflect-and-inject
core (auto-seed, knowledge pages, attribution, per-repo bank naming) like
opencode/cline. A Prime Agent extension entry (src/prime-agent.ts) wires
before_agent_start -> recall + system-prompt injection and agent_end ->
transcript write-back onto RuntimeCore, and registers the hindsight_* knowledge
tools natively via pi.registerTool (Zod raw shape -> JSON Schema; Prime Agent
forwards it to the model provider). Installer registers the built extension in
~/.prime/agent/settings.json; registry lists it for backfill. Includes a
transcript normalizer, unit tests for the hooks/tool adapter/converter/installer,
a README entry, and the synced docs page.
Supersedes the standalone @vectorize-io/hindsight-prime-agent package.
* fix(coding-agents): register Prime Agent in the control plane, wire its E2E, pass the workspace
Follow-ups from review, on top of a rebase onto main (the branch was 66 commits
behind and predates the append write-back, bounded transcript reads, the retain
stamp and both 0.2.x releases).
Control-plane registry. CLAUDE.md requires a new harness to land its logo entry
in the same change, and this one didn't: documents retained by Prime Agent carry
metadata.harness = "prime-agent" and a harness:prime-agent tag, which the
documents list resolves a logo from, so every one of them rendered as bare
metadata. Verified against a real local run before fixing. Neither guardrail
catches this — the parity test's EMITTED_HARNESSES is a hand-maintained list, and
it lives in the control plane, so `detect-changes` never runs it for a
coding-agents-only PR. Added to the registry, the icon copied into
public/img/harness, and the id added to that list so it is covered from now on.
The mark is dark line art, so invertOnDark like the other monochrome ones.
E2E. Every other harness has a Docker E2E entry; this one had none. Added
Dockerfile.prime-agent and a setup entry, so it joins the roster that installs
the CLI, seeds a bank with a decision the prompt never mentions, and requires the
agent to carry it back out. It skips cleanly without credentials, like the rest.
Prime Agent ships no npm package — the upstream repo is a private monorepo — so
the image uses the vendor installer and puts ~/.local/bin on PATH.
createRuntime passed four arguments to RuntimeCore, dropping the workspace
directory added in #3346. Harmless today because repoPath is process.cwd(), but
{gitProject} and {project} in retainTags/retainMetadata would silently resolve
against the wrong directory the moment those diverge; plugin-entry and cline both
pass it explicitly.
Regenerated the docs skill mirror, which verify-generated-files was failing on.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
When reflect is forced to answer without tools (context guard, last
iteration, LLM error, clean stop) and the accumulated tool results exceed
the prompt budget, build_final_prompt dropped any over-budget block whole —
plus every older one. The synthesis model then saw an empty Retrieved Data
section and answered a confident 'I don't have information' while the
response attached every retrieved citation (#3122). Whether anything
survived depended on whether a small-enough block happened to be newest.
Now the history is split, not truncated: budget-sized chunks (block-boundary
greedy packing; an over-budget block splits on result-entry boundaries) are
each compressed by a parallel LLM call into dated, cited claims, and one
reduce call synthesizes the answer from every chunk's claims. Claims carry
mentioned_at + memory ids so the reduce call can apply the
latest-statement-wins supersession rule across chunks — conflicting facts
may land in different chunks. Only an indivisible entry larger than the
whole budget (e.g. one giant document expand) is token-cut.
When everything fits — the overwhelming majority of reflects — the path is
byte-identical to before: one final call, same prompt. The four duplicated
forced-synthesis bodies in the agent loop collapse into one helper.
Closes#3122.
* blog: Best Open-Source Agent Memory Systems (Self-Hosted, 2026)
A fair, benchmark-grounded comparison of the self-hostable open-source agent
memory systems (Hindsight, Mem0, Graphiti/Zep, Letta, Cognee): comparison
table, per-system profiles, "what self-hosted really costs", FAQ, and a
"when to pick each" guide. Every stat/claim verified against live sources
(GitHub stars, licenses, Zep CE deprecation, benchmarks). Swiss-type cover.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* blog(oss-memory): refresh GitHub star counts to current
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
`pending_consolidation` counted every fact with `consolidated_at IS NULL`,
including the ones stamped `consolidation_failed_at` that the consolidator's
own candidate query (`reads.find_unconsolidated`) excludes on purpose. The
gauge therefore had a floor no amount of work could clear: it sat above
`?consolidation_state=pending` by exactly `failed_consolidation`, and an
operator could not tell a real backlog from an abandoned residue.
`pending` now carries the consolidator's predicate, so the two buckets are
disjoint and a bank with no live backlog reaches zero. The same predicate was
missing in five more places:
- `get_bank_stats` keeps a second copy of the freshness SQL for the
`writes_memory_rows_in_sql` path — fixing only `counts.py` would have left
the default Postgres path wrong.
- `hindsight.consolidation.backlog` had the same floor, which made
"backlog > 0 for N minutes" unalertable on any bank holding a residue.
- reflect's `tool_search_observations` derives `is_stale` / `freshness` from
this count, so a residue told the model the observations were stale on every
call, for ever (fixed transitively via `get_bank_freshness`).
- the control plane's consolidation card computed `done = total - pending`,
which would have counted the failed rows as done once pending got strict.
- the benchmark runner waits for this count to reach 0, so one permanently
failed fact burned the full 3000s timeout.
Everything else that answers "what is left to consolidate" already excluded
them: the memories list filter, `count_unconsolidated`, and the
`banks_needing_consolidation()` maintenance routine — so scheduling was never
spinning on the residue.
## The bug
`update_mode="append"` is a read-modify-write over the whole document: the retain reads `documents.original_text`, concatenates the new content onto it, and reprocesses the result — with LLM extraction sitting between the read and the write. Nothing made that atomic, so concurrent appends to one document raced, and the losers were dropped **silently**, with every caller getting a success.
Reproduced on `main` — three parallel appends after a seeded turn:
```
outcomes: ['t2:ok', 't3:ok', 't4:ok'] ← all three "succeeded"
document: TURN_ONE ... TURN_FOUR ← TWO and THREE gone
memory_units: TURN_ONE, TURN_FOUR ← their units cascade-deleted too
```
This is now the standard integration shape: a session gets one stable `document_id` and each turn is appended from an independent process (see `openclaw`'s session-scoped document, `index.ts`), plus queue flushes replaying buffered turns.
Every existing guard was written for *replace* semantics, where "someone newer won, drop mine" is correct. For append it is data loss — the dropped turn is content nobody else has.
## The fix
Three layers, each carrying a different guarantee.
**1. Append compare-and-swap** — correctness. The append records the `content_hash` it built on and verifies it under the document row lock, before the write that establishes ownership. A moved base raises `ConcurrentAppendConflict`; the append is redone on the newer text (3 attempts, jittered) rather than committing over the winner. The paths that used to discard content — the stale-request skip and the streaming takeover — now raise for appends and are untouched for replace.
**2. Per-document claim serialization** — avoids the conflict rather than paying for it. New `async_operations.serialization_key` plus `document_serialization_sql`, the same predicate shape `graph_maintenance_bank_serialization_sql` already uses per bank. One in-flight retain per document; a waiting operation holds **no worker slot** (it simply isn't claimed), and different documents stay fully parallel — so a 12-worker fleet keeps saturating.
**3. Claim-time coalescing** — performance. A backlog for one document is claimed and run as a single execution, so a client flushing 50 buffered turns costs one pass instead of 50 sequential ones.
The coalescing is deliberately shaped to be low-risk:
- It folds **at claim time, over immutable rows** the claim transaction already holds `FOR UPDATE` — it never rewrites a pending operation's `task_payload`. The submit-time alternative races the worker reading that row and would reintroduce the very lost-update bug being fixed.
- **Operation identity survives.** Each submission keeps its own `operation_id`, status and post-retain hook, so nothing downstream of the queue — polling, webhooks, cancellation, metering — has to learn about folding.
- It is a **pure optimization**: delete it and the system is still correct, only slower. Layers 1 and 2 carry correctness independently, so a folding bug can cost latency or LLM spend but cannot lose a turn.
Fold width halves per `retry_count`, so a poisonous turn converges on running — and failing — alone instead of holding good turns hostage.
## Fold eligibility
Folding is sound only for **appends**, because only appends are cumulative: running two as one execution over the concatenated turns gives the same document as running them in sequence. Replace means "this body supersedes what is stored", so a fold must never take one — two folded replaces would store `body1 + body2` where the answer is `body2`, and an append folded behind a replace would turn a document-wiping submission into a concatenation. Anything that is not append-only runs alone, as primary and as peer (including items with no `update_mode`, since the default is replace).
A peer also has to match the primary on everything the execution applies **once** from the primary's payload — tenant, API key, `document_tags` (compared order-insensitively), `strategy` — or folding would apply the primary's value to the peer's content and silently drop the peer's. File-backed retains are excluded on both sides: a converted upload attaches its storage key afterwards, and that step only fires for a single-item retain.
A rejected peer defers everything behind it. Taking a later peer past a rejected one would commit turns out of order.
## Post-retain hooks
A folded execution fires the hook **once per member**, in submission order, each with its own content slice and a `folded_with` list. The execution's usage lands on the first member and zero on the rest, so `sum(llm_total_tokens)` across a fold is exactly what the execution spent — the same total the callers would have seen retaining one at a time. Asserted directly in `test_folded_execution_reports_one_hook_per_operation`.
## Also fixed
`_run_delta_db_work` signalled its concurrency abort with a bare `return None` from a function declared `-> None`, and the caller discarded the value. The delta concurrency guard has therefore been logging *"aborting delta, falling back to full retain"* while actually committing on top of the concurrent writer. Distinct latent bug, found while tracing this one.
## Relationship to #3363 / #3386#3363 said of the queued path: *"Keep the guard there, or serialise children per document first."* Layer 2 is that serialization. #3386 (now on main) made the sync path fold shared `document_id` items; a claim-time fold hands `retain_batch_async` exactly that shape, so this rides #3386's grouping rather than duplicating it. The queued-path submit guard is left as-is — out of scope here.
## Tests
- `test_concurrent_appends_keep_every_turn` — the regression test; fails on `main`, passes here.
- Claim predicate and fold, deterministic at the queue layer (no LLM): one retain per document, no cross-document serialization, waits for a processing peer, folds in submission order, every member claimed.
- Fold planner as pure functions: submission order, token budget, never skipping a turn to reach a later one, `max_peers`, retry narrowing.
- Hook totals, folded and unfolded.
303 passed across the retain / delta / worker / batch / extensions / file-retain / backup-restore suites on a clean database. `lint.sh` and `ty` clean.
## Notes for review
- The CAS is scoped to the first sub-batch (where the append read happens). A multi-sub-batch append that loses later still raises rather than dropping — it just fails the operation and relies on the worker's retry instead of the in-process redo.
- The fold is capped by `retain_batch_tokens` so a folded execution stays within a single orchestrator pass; splitting one document across differently-bodied sub-batches trips the streaming ownership check (#3282).
- A peer wedged in `processing` holds its document until claim recovery releases it — the same caveat the graph-maintenance predicate already carries, not new here.
Add a vendor-neutral Hindsight plugin conforming to Vercel's Agent Plugins
1.0.0 standard (plugin.json + mcp.json + skills/SKILL.md), so one artifact
gives long-term memory to any compatible client (Codex, Cursor, GitHub
Copilot, Kiro, VS Code) instead of a per-IDE integration. The plugin is a
thin transport wrapper over Hindsight's existing MCP server (retain / recall
/ reflect); a bundled skill teaches the agent when to use it.
Wiring:
- CI: test-agent-plugin-integration job runs the manifest validator, gated on
hindsight-integrations/agent-plugin/** changes.
- Docs: integrations.json gallery entry + docs-integrations/agent-plugin.md.
- Release: agent-plugin added to release-integration.sh and the changelog
generator; both learn to read a root-level plugin.json and link the
changelog to the source tree (git-distributed bundle, no registry package).
* fix(retain): match chunk-delete link endpoints through indexable joins (#3387)
The ordered memory_links pre-delete in delete_chunks_by_ids matched link
endpoints with `tu.id = ml.from_unit_id OR tu.id = ml.to_unit_id`. An OR
spanning two columns of ml cannot be driven from either endpoint index, so
PostgreSQL made memory_links the outer relation of a nested-loop semi join
and sequentially scanned the whole table on every delete — O(links x units),
with no bank_id predicate, so every bank scanned every other bank's rows.
Past a few million links that exceeded the asyncpg command timeout and delta
retain failed with a bare TimeoutError (str(TimeoutError()) is empty, so it
logged as "Task execution failed: batch_retain, error:" with nothing after).
Splitting the OR into a UNION of two single-column joins makes each half an
index scan. Measured on PG18 with the current index set, 300k units /
1.5M links, deleting the links of 3 chunks (150 units):
before 20,420 ms Seq Scan, 224.9M rows removed by join filter
after 31 ms two index scans, same 1,464 rows
10 chunks took 49.8s before — already over the 60s default at a table size
well below production. The row set is identical (EXCEPT in both directions
returns nothing), and the deterministic ORDER BY + FOR UPDATE that #2570
added stay in ordered_links, which still locks the rows in that order.
* test(memories): update store doubles for the per-bank capability API
#3388 moved the store capability to writes_memory_rows_in_sql_for(bank_id) and
added drop_bank_storage, but two duck-typed test doubles still carried the old
surface, so test-api shard 2 has been red on main since it merged:
test_integrity_violation_not_retried — SimpleNamespace(writes_memory_rows_in_sql=True)
-> AttributeError: no attribute 'writes_memory_rows_in_sql_for'
test_list_banks_non_sql_store._NonSqlStore — teardown's delete_bank routes the
drop through the store for a non-SQL bank
-> AttributeError: no attribute 'drop_bank_storage'
Both doubles are hand-rolled rather than subclasses of the store base, which is
why the refactor could not update them mechanically.
On thinking models the provider's output budget covers reasoning tokens plus
visible output, so passing the reflect/mental-model `max_tokens` straight through
as `max_completion_tokens` let reasoning consume the whole budget and truncated
the page mid-word — silently, since the call still returned success.
Treat `max_tokens` as what it means to a user: a *visible* page-length target.
It is now communicated to the model as a prompt directive and enforced by the
existing post-hoc rewrite, never as a hard cap on the synthesis call. The
transport-level cost cap is a separate, uncapped-by-default config
(`HINDSIGHT_API_REFLECT_MAX_COMPLETION_TOKENS`) so reasoning never starves the
answer. This fixes the truncation for every provider without model-specific
detection.
Also surface `finishReason == MAX_TOKENS` on Gemini as a warning instead of
returning half-written text as a silent success.
- config: add `reflect_max_completion_tokens` (None = uncapped)
- reflect: synthesis + rewrite use the config cap, not the page budget;
`build_final_prompt` carries the length directive
- gemini: log a truncation warning on a non-empty MAX_TOKENS response
- docs: models.mdx reasoning/`max_tokens` note + configuration.md entry
- tests: prompt directive, config default/override, uncapped-by-default
synthesis, config-cap override, Gemini truncation warning
The sync retain batch endpoint rejected any batch whose items shared a
document_id, contradicting the RetainRequest schema/example, the
MemoryItem.document_id docs, and the SDK's batch-level documentId (which
inlines one id into every item). The guard existed to avoid a race, but
that race is only real on the queued path, where children fan out to
parallel workers. The synchronous path processes sub-batches sequentially.
retain_batch_async now folds items sharing an explicit document_id into
one document, in request order, running each document in a single
orchestrator pass. A single pass is required: splitting one document
across sub-batches that carry different bodies trips the streaming
pipeline's content-hash ownership check and silently drops later
sub-batches. Batches with no shared document_id are unchanged.
The queued path (submit_async_retain) keeps the guard, with a message
that points clients at async=false for folding.
Re-applies the per-bank store-capability seam onto current main. The pluggable
memories backend (#2917) is on main, but the per-bank capabilities landed later
on feat/pluggable-memories-provider (#3350, plus fix#3381) while main advanced
~179 commits.
A pluggable memories store may keep memory rows outside SQL and/or own the
document store. The process-level flags writes_memory_rows_in_sql /
owns_document_store gain per-bank forms — writes_memory_rows_in_sql_for(bank_id)
and owns_document_store_for(bank_id), defaulting to the class attrs — and every
bank-scoped call site in memory_engine, consolidation/consolidator, retain/* and
reflect/tools consults the per-bank form. Process-level maintenance gates keep
reading the class attr.
Also two NameError fixes of the same class (a bare bank_id where the in-scope
variable differs): list_banks (row["bank_id"], originally #3381) and get_chunk
(chunk["bank_id"], newly surfaced by pyflakes while rebasing).
Conflict resolution: only consolidation/consolidator.py conflicted — main added
consolidation sites since the branch; all are bank_id-scoped, so all convert to
the per-bank form.
Validation: pyflakes on all changed engine files reports 0 undefined names;
py_compile clean; per-bank + list_banks unit tests included.
* feat(llm): opt-in forced-tool structured output for LiteLLM providers (#3300)
Bedrock Claude rejects the structured-output route Hindsight uses. LiteLLM sends
a well-formed Converse `outputConfig`; Bedrock's Anthropic layer rewrites it to
snake_case internally and its own validator then refuses the key:
BedrockException - {"message": "The model returned the following errors:
output_config.format: Extra inputs are not permitted"}
Every `LiteLLMLLM.call()` with a `response_format` fails on that provider, so
retain returns 500 and consolidation degrades to "skipping batch" with no API
error at all. Reflect is unaffected because it goes through `call_with_tools()`,
which emits `toolConfig` — and Bedrock accepts that. The reporter's boto3 repro
isolates it to the transport, not the schema: the same trivial schema fails via
`outputConfig` and succeeds via `toolConfig`.
This is a different failure from the two earlier Bedrock schema fixes (#1289
`minimum`/`maximum`, #2500 `maxItems`). Those leaked one unsupported keyword into
an otherwise-accepted request and were fixed by not emitting it; here the whole
`response_format` route is refused, so no amount of schema sanitizing helps.
HINDSIGHT_API_LLM_STRUCTURED_OUTPUT_FORCED_TOOL (default false) makes the
LiteLLM-backed providers — litellm, litellmrouter, bedrock — ask for structured
output the way `anthropic_llm.py` already does natively: one tool whose
parameters are the response schema, forced via tool_choice. The tool call's
arguments are substituted for the message content before the existing parse
block, so markdown-stripping, `parse_llm_json` repair, retries, usage accounting
and tracing are untouched. If the model answers without calling the tool — a
gateway that drops tool_choice — the text is parsed as before.
Default false because every other LiteLLM backend handles `response_format`
natively; this only pays off where the backend refuses it.
* docs(llm): record the verified Bedrock behaviour behind the forced-tool flag
Reproduced on a real AWS account. In ap-southeast-2 with the au.* inference
profile, raw boto3 converse (no litellm at all) refuses the outputConfig
structured-output route while accepting the identical schema via toolConfig; the
same model in us-east-1 with us.* accepts both. So this is region/inference-profile
dependent, not "Bedrock Claude is broken" — which is why the flag stays opt-in
rather than being keyed off the provider.
Also: the rejected key comes back as `model: Extra inputs are not permitted`, not
the `output_config.format:` the issue quotes. Same validator and signature, but
operators grepping for that exact string would not find it, so the docs now name
the behaviour instead of the key.
Reported in #3377 and verified against a live Azure OpenAI resource.
The OpenAI-compatible tip told users to point HINDSIGHT_API_LLM_BASE_URL at
"your provider's endpoint", which for Azure reads as the resource root -- and
Azure does not serve the API there, so it returns 404 Resource not found.
Measured against a real resource (gpt-5-mini deployment):
https://<res>.openai.azure.com 404
https://<res>.openai.azure.com/openai/deployments/<dep> 404 (no api-version)
https://<res>.openai.azure.com/openai/v1 works
.../openai/deployments/<dep>?api-version=2025-01-01-preview works
Adds an Azure OpenAI Setup section with both working shapes and the three
things that actually bite: the model is the *deployment* name, the key is the
resource key (an APIM subscription key is a different setup), and gateways
must preserve the path shape.
Also records that Azure accepts the prompt_cache_key field sent under
cache_affinity=auto (#3271) on every api-version from 2024-02-01 onward, so
that default needs no Azure carve-out -- an explicitly untested risk when
#3271 merged, now closed.
Delta retain drops a document's outgoing facts by deleting their chunks and
letting the FK cascade take the memory_units with them. Nothing swept the
observations derived from those facts: the sweep lives in
handle_document_tracking, which only the full-replace path calls. Every
re-ingest that took the delta path — a small edit to an existing document,
exactly what delta retain is for — therefore left the observations of the
changed chunks behind, still valid and still recallable, pointing at
source_memory_ids that no longer resolved.
Those rows were unreachable afterwards: consolidation batches are built from
facts, so an observation whose sources are all gone is never selected into a
batch again, and no runtime path deletes it.
Sweep in delete_chunks_by_ids, before the cascade, so the invariant holds at
the choke point rather than at one call site. It returns the number it
invalidated and the delta log line now carries that count unconditionally —
"the sweep matched nothing" and "the sweep never ran" were indistinguishable
from the outside, which is what made this hard to diagnose.
The sweep is keyed on the deleted chunks, not the document, so an edit to one
chunk leaves the other chunks' observations alone instead of requeueing the
whole document for consolidation.
Supersedes #3302. Reported and diagnosed by @fhiltscher.
Fixes#3294.
* fix deletion of failed document uploads
* fix(control-plane): swallow delete errors on failed upload rows
deleteFailedUpload only had try/finally, but fetchApi both toasts and
rethrows, and the handler is invoked from onClick without being awaited —
a failed delete left an unhandled promise rejection. Match the sibling
handlers in bank-operations-view, which catch and rely on the API client
interceptor for the user-facing error.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Found investigating #3379, which asked for a PreCompact hook to avoid losing
context at compaction. The premise does not hold — compaction APPENDS a summary
record and leaves every earlier record in the transcript (verified on a real
11,144-record session compacted twice: 3,312 records precede the first marker and
are still there), and Stop fires after every assistant response, so the content
was already retained before compaction ran.
The investigation turned up the opposite problem. That summary record is a plain
type:"user" line with no isMeta flag, so nothing filtered it and Claude Code's
machine-written recap was retained as something the user said: 29 records /
474,016 chars across local transcripts, averaging 16KB each. Worse than
misattribution, it summarises turns ALREADY retained, so the same decisions get
extracted a second time from the recap.
Dropped alongside isMeta and isSidechain. Verified against the session that
surfaced it: 2886 -> 2884 turns, exactly the two summaries gone, every other turn
byte-identical.
Also corrects retain-cursor.ts, which cited Claude Code compaction as an example
of a transcript being rewritten rather than extended. It is not: the prefix stays
intact, so the append path keeps working through a compaction. The guard is
unchanged — only the example it named was wrong.
Exporting a bank and importing it back into a new id on the same instance
failed with a ForeignKeyViolationError on mental_models.bank_id.
The banks row carries a globally-unique internal_id (banks_internal_id_unique,
used only for per-bank index naming). Import remapped only bank_id, so the copy
inherited the source bank's internal_id. On a same-instance re-import the source
row is still present, so the banks INSERT hit the unique constraint and
ON CONFLICT DO NOTHING silently skipped the parent row - then every child
(mental_models, directives, webhooks) tripped its bank_id foreign key.
Drop internal_id from the banks row before restore so the column DEFAULT
(gen_random_uuid) mints a fresh one. It is a local identifier that nothing in
the archive references, and create_bank_vector_indexes already reads it back
from the DB after insert. Cross-instance migration was unaffected (random UUIDs
don't collide); only the same-instance copy flow broke.
Adds a regression test that imports a bank (with a mental model) into a new id
without deleting the source and asserts the copy lands with a fresh internal_id.
It has exactly one consumer, RuntimeCore — the persistent-plugin harnesses
(opencode, Kilo, Cline CLI), which stay loaded and therefore choose when to write
back. The hook harnesses ignore it, and not by oversight: the host decides when
they run, and each Stop is a fresh process with no memory of how many turns have
passed.
Neither the config comment nor the settings table said so. Its neighbour
retainSessions does spell out the same split ("hook harnesses always write on
Stop"), so the silence read as "applies everywhere" — a Claude Code user setting
retainEveryTurns: 5 gets no effect and no warning. That is the workaround #2143's
reporter reached for, so the gap was load-bearing.
The README also said "opencode", which undersold it: Kilo and Cline CLI share
that runtime.
Closes#3023.
Claude Code delivers <task-notification> as an ordinary type:"user" message —
string body, no isMeta flag — so nothing filtered it and fact extraction saw the
harness's background-task plumbing (task id, tool-use id, status, summary) as
something the user said. Measured across 400 local transcripts: 39 such messages,
16,289 chars, every one of them the entire message.
Reproduced with the real reader on a real transcript (243 retained turns, 1 of
them a task-notification carrying 519 chars of transport), and verified after:
242 turns, 0 noise, every genuine turn preserved.
The tag joins MEMORY_TAG_RE, which already covered codex's <hook_prompt> for
exactly this reason. <system-reminder> joins it too: today those only ride inside
tool_result blocks, which this reader drops entirely, so it is insurance against
the harness moving them — the rule is tag-structural, not content-guessing.
Note what the issue asked for and this does NOT do. Its two named cases are
already handled here: skill bodies arrive with isMeta:true (8/8 in the sample)
and are dropped with every other meta line, and <system-reminder> is inside a
dropped tool_result. Only the third case was live.
Stripping removes the BLOCK and keeps surrounding text, so a message that is
nothing but a wrapper renders empty and is dropped as a no-content turn, while a
real message mentioning one keeps the user's words — the mistake the old plugin's
unanchored strip_channel_envelope made (#3124).
hindsight-obsidian-sync keyed its sync index only on the vault name
(~/.hindsight/obsidian/<vault>.json) with a {syncIndex, lastSyncAt}
envelope carrying no destination identity. Pointing the CLI at a
different --bank or --api-url while reusing the default index made it
treat files synced to the old target as "unchanged", silently leaving
the new bank incomplete and potentially issuing prune DELETEs against a
bank it never wrote to.
Bind the index to its destination identity (canonical API origin, bank,
resolved vault path, vault name, prefix-doc-id):
- defaultIndexPath is now target-scoped: <vault>-<bank>-<fingerprint>.json,
so different targets never share a default file.
- The envelope records the identity; loadIndex fails closed with an
actionable IndexIdentityError (naming the changed field) when the
persisted destination differs, and refuses legacy indexes with no
identity metadata rather than silently trusting them.
Include/exclude scope is deliberately not bound: on the same destination
narrowing scope legitimately reuses the index and prunes newly-excluded
notes it owns there. Every harm in the issue requires a destination
change, which is what this refuses.
Adds regression tests for cross-bank/cross-API refusal end-to-end,
per-field mismatch, legacy-index refusal, target-scoped default paths,
and canonicalApiOrigin credential/path stripping.
* feat(transfer): async document export (issue #3321)
The synchronous GET /banks/{id}/document-transfer loaded the whole bank
into memory, held a DB connection for the full request, and blocked the
event loop building the ZIP — enough to take down the shared API on a
large bank.
Make export asynchronous, mirroring the already-async import path:
- new document_export operation: submit_export_documents_async enqueues
it; the worker builds the archive, stores it in file storage, and
records download_url/storage_key/byte_size in result_metadata
- POST /banks/{id}/document-transfer/export (202 + operation_id)
- the sync GET is removed -> 410, pointing at the async endpoint
- GET /v1/default/files/download/{key} streams the archive; retrieval +
bank authorization live in MemoryEngine.retrieve_bank_file (IDOR guard)
Harden export_documents: batch the entity/causal attach ANY() queries
instead of passing hundreds of thousands of UUIDs at once, and move ZIP
assembly off the event loop with anyio.to_thread.
Regenerate all SDKs; add blocking export_documents convenience helpers to
the Python + TS wrappers (submit -> poll -> download), fetching the
server-provided download_url to avoid %2F path-encoding. Update the
control-plane proxy to orchestrate the async flow and the docs.
* refactor(transfer): name the export op export_documents; surface it in the CP
- rename the async operation/task type document_export -> export_documents
(and _handle_document_export -> _handle_export_documents) so it mirrors the
import_documents operation
- control plane: add export_documents + import_documents to the operations
type filter and localize both (operationType.exportDocuments/importDocuments
across all 10 locales) — previously neither appeared in the filter and both
rendered as the raw task_type string
* feat(transfer): clean up export archives with their operation + add download button
Export archives were stored in file storage but never deleted, so they
outlived their operation: the retention sweep prunes the async_operations
row but left the blob orphaned, and a user delete didn't remove it either.
Tie the archive to its operation record:
- delete_operation now deletes the export archive along with the row
- the retention sweep purges export archives (matching prune's terminal +
updated_at < cutoff predicate) before pruning the rows
So an export is retained exactly as long as its operation — indefinitely by
default, or until HINDSIGHT_API_OPERATION_RETENTION_DAYS prunes it.
Control plane:
- add a Download button to the export operation's detail dialog (streams the
archive through a new /api/files/download proxy, SSRF-guarded to the
file-download path) + localize the label across all 10 locales
* chore(docs-skill): regenerate references for export retention note
* chore(cli): skip new export/download ops in CLI OpenAPI coverage
export_documents_sync_removed (the 410 stub) and download_file are
served via the API/control plane, not the end-user Rust CLI.
* fix(transfer): register export_documents slot config + fix cleanup-sweep tests
- add export_documents to WORKER_SLOT_TYPE_DEFAULTS (every operation_type
used in memory_engine must be listed there — enforced by test_worker)
- stub engine.purge_expired_export_archives in the operation-cleanup test
mocks (the sweep now calls it before pruning each schema)
* test(transfer): make export-archive purge test xdist-safe
purge_expired_export_archives is schema-wide, and CI shares the schema
across xdist workers, so a future cutoff purged other concurrent tests'
fresh archives (flaky count + cross-test interference). Backdate this op
and use a past cutoff so it targets only itself; assert purged >= 1.
The build-docs CI job had crept from ~95s (January) to ~290s, essentially
all of it webpack: the Server bundle took 1.82m and the Client 2.72m on a
4-vCPU runner, with Babel transpiling ~385 routes and no cache surviving
between runs.
Enable Docusaurus Faster, opting in one flag at a time. The blanket
`experimental_faster: true` preset does not work on this site — both the
SWC JS minifier and the SSG worker threads crash rendering /api-reference
with "ReferenceError: Prism is not defined", because Redoc expects a
`Prism` global neither provides. Leaving those two off and taking the
Rspack bundler, SWC loader, LightningCSS and the MDX cross-compiler cache
keeps the build green.
Measured cold builds (14-core machine, cache cleared each time):
webpack + Babel + Terser (before) 171s
SWC loader + LightningCSS only 132s
Rspack + SWC loader + Terser 56s
Output is unchanged: both bundlers emit the same 871 HTML pages, the same
330M build directory and a byte-identical search index.
No CI cache step accompanies this — Rspack's persistent cache only buys
another ~13s (43s vs 56s) and is not worth a 672MB entry against the
repository's cache budget.
The sub-batch splitter invented its own boundaries — it sliced an oversized
item at `tokens_per_batch * 3` chars, a chars-per-token fudge unrelated to the
chunk boundaries the rest of the retain path works in. Everything downstream
reuses stored work by chunk content hash: delta retain, the streaming recovery
pass, and chunk_index bookkeeping. A slice that happened to line up with native
chunks reused them; one that cut mid-chunk matched nothing, so a replacement
with a small edit plus a tail re-extracted the whole unchanged history — which
is why the bug only appears when `3 * retain_batch_tokens < retain_chunk_size`.
Slice on the bank's own `chunk_text(chunk_size, structured_chunk_size)`
boundaries instead, packing whole chunks up to the token budget, and verify
each slice re-chunks back to exactly the chunks it holds (merged JSON array,
then "\n\n", then "\n"; falling back to one sub-batch per chunk, which
chunk_text's idempotency guarantees — #2301). That makes one invariant hold by
construction rather than by luck:
the chunks stored for a document depend only on its body,
never on how transport split it.
Deliberate consequence: a slice honours `retain_batch_tokens` only down to one
native chunk — below that, `retain_chunk_size` is the real bound. Cutting finer
is the defect, not the budget.
Two follow-ons fall out of the same invariant:
* The split reports `chunk_counts`, so the caller stops re-deriving them just
before handing each sub-batch over — a workaround that existed only because
the orchestrator pops `content` while streaming (#1888).
* `document_body_override` is Memory Defense screened once, by the engine that
produces it, instead of by every slice that carries it. A 42 KB body split
into 26 sub-batches was rescanned 26 times.
Tests: regression coverage for the oversized replacement and for single
screening, unit tests pinning the alignment invariant across prose, JSON
conversation and JSONL payloads, and one covering the unjoinable-run fallback.
Server-side prompt caches are per backend server, so a load balancer scatters
the calls of one multi-call operation (reflect, mental-model refresh,
consolidation) across replicas and the shared prefix almost never hits. This
adds each vendor's documented affinity mechanism to the OpenAI-compatible
provider family: xAI's `x-grok-conv-id` header and OpenAI's
`prompt_cache_key` field, keyed on the operation's trace id.
Measured independently against a live xAI backend with an ~11.9k-token shared
prefix: 29% of it cached without the header vs 99% with it, with a
rotating-id control ruling out header presence as the cause.
Defaults to `auto`, which is an allowlist rather than a best-effort probe:
only x.ai / grok.com (header) and native OpenAI / openai.com / Azure OpenAI
(field) receive anything, and every other backend -- vLLM, ollama, groq,
deepseek, openrouter, lmstudio, custom proxies -- gets byte-identical requests
to before. Set `HINDSIGHT_API_LLM_CACHE_AFFINITY=none` to disable.
Also wires the existing `default_headers` setting into the OpenAI-compatible,
Fireworks and Nous providers, where it was previously accepted and silently
dropped, and folds the duplicate affinity derivation added by #3272 into the
shared module so the two lanes cannot drift.
Full CI via workflow_dispatch on the rebased head (fork PRs get no secrets and
skip test-api): 103 jobs green, all three test-api shards included. The final
rebase changed documentation context only -- no Python differs from the tested
tree (verified with git range-diff).
The MCP server resolved its harness (HINDSIGHT_MCP_HARNESS, defaulting to
claude-code) for bank resolution but never passed it to buildKnowledgeTools, so
the tools it builds had no idea which agent they were serving.
Two things follow from passing it:
- hindsight_diagnose reports the actual harness instead of 'unknown'.
- hindsight_ingest_document now stamps the harness:<id> tag and metadata.harness.
Documents ingested through the MCP tool were previously unattributed, and the
documents list resolves a document's agent logo and filter from exactly those
fields.
cfg.harness is the right source: loadConfig back-fills the asking harness onto an
unset field (#3247), so it is the launching harness rather than resolveConfig's
'opencode' default.
Co-authored-by: TheAngryPit
Closes#2492.
configureBank POSTed the full CODING_BANK_TEMPLATE — reflect/retain/observations
missions included — to /banks/{id}/import on every run, and the server's import
calls update_bank_config unconditionally for whatever the manifest carries. The
seed engine runs on every session start, so a user who rewrote a mission in the
control plane had the plugin's default stamped back over it on the next session.
Same regression #1270 fixed for OpenClaw, arriving here by the same route: the
template was carried over without the guard.
A bank is now seeded once. Before importing, the client reads the bank-scoped
OVERRIDES (not the resolved config, so inherited global defaults don't read as
"already set"); if any mission is set there — ours from an earlier pass or the
user's own edit — it imports CODING_BANK_STRUCTURE instead, which omits the
missions. Omitted fields are untouched server-side: get_config_updates keeps only
non-None values.
The retain strategies and entity labels are still re-applied every time. They are
not preferences: this plugin writes documents under git / gitlog / conversation /
document, a bank missing one would reject the write, and a newer plugin adding a
strategy needs it to reach existing banks.
Two cases deliberately still seed: `configureBank({reset: true})`, because the
bank was just deleted, and a deployment with the bank-config API switched off —
without that API a user cannot set per-bank missions at all, so there is no edit
to protect.
* feat(coding-agents): retainTags / retainMetadata with template placeholders
Closes#3269.
Every conversation retain carries `source:chat` and `harness:<id>` — what wrote
the memory, but nothing about where it came from. That is fine while each repo
has its own bank, since the bank is the answer. It stops being fine on a
deliberately shared bank, the setup in the issue: one bank holding cross-project
knowledge so facts recall everywhere, where a retained fact then carries no
record of the repository it came out of.
Both settings take `{placeholder}` templates resolved per retain, against the
vocabulary the dynamic bank id already uses plus what only a retain knows:
{gitProject} {project} {harness} {bankId} {sessionId} {timestamp}
{channel} {user}
{ "retainTags": ["project:{gitProject}"], "retainMetadata": {"repo": "{gitProject}"} }
{gitProject} is worktree-aware here too, so linked worktrees of one repo stamp a
single name rather than project:app and project:app-wt2.
The substitution itself moves to core/template.ts, shared with bank.ts rather
than duplicated — each call site keeps its own resolver map, because the valid
placeholders genuinely differ (a bank id cannot reference {bankId}).
Two things are deliberately not user-controllable. Built-in metadata is written
last and wins, and retainTags entries in the `source:`/`harness:` namespaces are
dropped with a warning: the documents list filters on those and resolves each
document's agent logo from them, so a template that could forge them would break
attribution for everyone reading the list.
Unconfigured, this adds nothing to a retain.
* docs(coding-agents): document retainTags/retainMetadata in the README, not the generated page
The docs page is generated from the integration's README by
hindsight-docs/scripts/sync-coding-agents-doc.mjs, and build-docs runs it with
--check. The first pass edited the generated page, so the build failed with
"docs page is out of date with the README".
Same content, moved to the source and re-synced (README, generated page and the
docs skill mirror). The row's cross-reference is plain text rather than an anchor
link because the generator flattens links.
* feat(coding-agents): HINDSIGHT_RETAIN_TAGS env override
Closes#2896.
The old Claude Code plugin had HINDSIGHT_RECALL_TAGS but no retain counterpart,
so per-project retain tagging could only be configured globally in the file. Now
that retainTags exists here, it joins the env surface on the same convention:
HINDSIGHT_ + the field in SCREAMING_SNAKE, still a FALLBACK the file wins over.
It is a list rather than a scalar, so a new ENV_LISTS branch splits on commas and
trims — blank entries dropped, so a trailing comma or "a,,b" is a typo rather
than an empty tag reaching the API.
HINDSIGHT_RETAIN_TAGS="project:{gitProject},env:work"
retainMetadata deliberately gets no env form: it is map-valued, and per-key
branching doesn't survive flattening into one variable — the same rule already
applied to mapPathToBank, harnesses and banks.
Also corrects this file's header, which still claimed the plugin reads no
environment variables at all — untrue since ENV_KEYS was added.
* fix(ci): compare OpenAPI against the merge-base; build benchmark role configs whole
Two unrelated CI failures, both of which fail without anything being wrong
with the code under test.
OpenAPI compatibility diffed the branch's spec against the LIVE tip of the
base branch, so every endpoint main gained after a branch was cut is
reported as "Endpoint removed (breaks old clients)" by that branch. Three
open PRs failed this way today on /health/live and /health/ready (added by
#3329), none of which touch the spec at all; the only cure was an unrelated
rebase. Compare against `git merge-base origin/$BASE_BRANCH HEAD` instead,
which asks the question the check means to ask: did *this branch* remove
something. Genuine removals still fail — verified both directions against
the real specs.
The scheduled LoComo benchmark has failed every night since at least Aug 8,
before its first question: `LoComoAnswerGenerator()` raised
"HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID is required". The workflow does export
that variable — but each benchmark role built its LLMConfig from exactly four
env vars (provider, api_key, base_url, model), and LLMConfig deliberately does
not read the environment for provider-specific settings (from_env is where the
API resolves them). Every Vertex AI value was therefore dropped. The same
four-var construction was copy-pasted at three sites — locomo, longmemeval and
the shared judge — so fixing only the crashing one would have moved the failure
down a line. Replace all three with a shared builder that carries the Vertex AI
project/region/service-account through.
hindsight-dev/tests had no CI job, which is why a plain construction bug was
left for a nightly benchmark to find hours later. Add one, so those tests
(and the new regression test) actually run on PRs.
* fix(ci): make the benchmark role-config tests hermetic
They passed locally off the developer's HINDSIGHT_API_LLM_API_KEY and failed
in the new test-dev job, where no key exists, with "API key is required for
openai" — the tests were reading ambient environment instead of declaring
what they need. Clear every HINDSIGHT_API_*LLM* var before each test and set
the ones under test explicitly.
A bank-deterministic 400 INVALID_ARGUMENT on consolidation+structured was
being retried through the full LLM retry budget (4 attempts) and the batch
retry ladder above it — 12+ identical rejected calls per consolidation cycle,
recurring every cycle. HTTP 400 is deterministic; retrying cannot recover it.
- Retry classification: 400 now fails fast in both call() and call_with_tools().
The recoverable cache-400 one-shot is reordered above the fail-fast so it is
not mistaken for a hard rejection; only 429/5xx still consume the retry budget.
- Diagnosability: dump_request_on_4xx() gains a force flag. A deterministic 400
now always logs its content-free structural profile (request config + per-part
sizes) on first occurrence, even with HINDSIGHT_API_LLM_DEBUG_DUMP_4XX off.
Message previews stay gated behind the opt-in flag, so the forced dump never
spills user content.
Tests: test_gemini_400_fail_fast.py + force cases in test_llm_4xx_dump.py.
Extraction can hand back entity names carrying embedded newlines/tabs, which
are then stored verbatim as entities.canonical_name and shear every
line-oriented consumer (psql -A output, log lines, exports).
Collapse whitespace runs to a single space and strip the ends at
_prepare_entities_for_resolution -- the single choke point both entity
resolution entry paths funnel through, and before the flat list /
entity_to_unit mapping is derived, so the resolver's positional invariant is
untouched. Case is left alone: the registry already matches on
LOWER(canonical_name).
Two consequences handled at the same spot:
- a candidate that is empty after normalization is dropped instead of being
created as an entity with a blank canonical_name (the resolver has no guard
of its own);
- candidates that normalization makes identical are deduplicated per fact, so
the same entity is not resolved twice and its mention_count bumped twice
(the upstream dedup in entity_processing runs on the raw text).
Existing rows are not migrated: renormalizing a stored name can collide with
the (bank_id, LOWER(canonical_name)) uniqueness, so cleaning them up is a
merge, not an UPDATE.
* fix(search): use PGroonga for Knowledge Pages
Route Knowledge Page lexical search through the PGroonga expression index instead of applying native tsvector functions to PGroonga deployments. Reconcile the renamed mental_models table and preserve its generated tsvector plus GIN index as a rollback projection while adding the canonical PGroonga index.\n\nThe populated-table exception is deliberately narrow: memory_units backend switches and unknown mental-model index shapes remain fail-closed. Empty native reconciliation restores the generated mental-model projection.\n\nContext:\n- #3318 fixed backend dispatch but intentionally treated PGroonga as native because reconciliation still targeted reflections.\n- Existing PGroonga installs therefore retained a tsvector mental_models column.\n- Keeping that projection avoids a rolling-deploy window where old instances or a rollback build would fail after the new index is installed.\n- Query text is escaped with pgroonga_query_escape and the indexed expression is repeated exactly for planner matching.
* fix(search): convert mental_models to pgroonga instead of a hybrid shape
Reconciling to pgroonga now does the same clean conversion for
mental_models as for every other table (drop the derived tsvector, add
the dummy TEXT search_vector, build the expression index) instead of
keeping the native projection alongside it under a renamed GIN index.
The transition is safe on a populated table because pgroonga indexes
name + content directly, so the replacement column has nothing to
backfill; transitions that do need a per-row value (vchord's
bm25vector, native's tsvector, anything touching memory_units) stay
fail-closed.
Trade-off: rolling back to a build without this change leaves pgroonga
knowledge search broken, since the old read arm queries
mm.search_vector as a tsvector.
Also in this pass:
- Make every reconciliation statement re-executable (IF [NOT] EXISTS).
Replicas boot concurrently during a rolling restart and each runs this
reconciliation; on a populated database the loser of the race would
otherwise crash on DDL the winner had already committed.
- Share the mental_models document expression between the index DDL and
knowledge_bm25_arm — an expression index is only selectable when the
query repeats its expression verbatim, so the two must not drift.
- Match the learnings/pinned_reflections migration's generated-column
expression exactly.
- Tiebreak the pgroonga ordering: pgroonga_score() silently reads 0 on
any plan that did not use the pgroonga index.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
The HINDSIGHT_API_LLM_STRICT_SCHEMA description listed the OpenAI-compatible
backends it applies to but omitted LM Studio, Ollama, and Volcano — which are
exactly the providers whose soft path skips json_object grammar, so their small
models emit unconstrained output. Enabling the flag is the documented fix for a
JSONDecodeError during retain on those backends (see #3262).
Regenerated the skills/hindsight-docs mirror to match.
* blog: guest post — writenode, continuity over retrieval (by Josh Groves)
Community guest post by Josh Groves (@Xp3rtMag1c1an), maker of writenode, on
building an AI note-taking Chrome extension on Hindsight: per-user memory
banks, a mode classifier, Node Gravity, and the SOURCE NODE chat. Adds the
post, four product screenshots, a co-brand cover, and an authors.yml entry.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* blog(writenode): add benfrank241 as co-author
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* blog(writenode): update date to 2026-08-10
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Selecting a zip in Documents > Actions > Import from zip and pressing the
button dimmed it briefly and then did nothing (#3327). The zip was a zip of
the reporter's own documents, which is rejected — correctly and quickly, so
the button only dimmed for a moment — but the rejection never reached the
screen. #3333 fixed that half: the control plane now toasts the failures of
the direct-fetch helpers that bypass the shared error interceptor.
Two things it did not cover remain.
A file that isn't a readable zip escaped parse_archive as
zipfile.BadZipFile and surfaced as an opaque 500. That is a wrong upload,
not a server fault, so it now raises ValueError like every other archive
problem and the API maps it to a 400 with the reason. The check moves into
a shared _open_archive helper so parse_bank_archive gets it too.
And the rejection now names the fix rather than only the missing file:
"Import from zip" reads like a bulk upload of ordinary files, so the
message says the endpoint only accepts an archive produced by export and
points at file upload / retain for PDFs and text. The import dialog gained
the same hint under the file picker, pointing at Add Document > Upload
Files.
Add the current UTC date and time to the reflect retrieval and final-synthesis
prompts so the agent has a reference point for time-relative questions
(recently elapsed plans were staying classified as upcoming).
Time is at minute precision and placed after the static instruction block —
right before the bank-specific/custom data — so the large static prompt stays
a cacheable prefix and only the volatile timestamp falls outside the cache.
Closes#3279.
Adds the `xai-oauth` provider: serves Hindsight's LLM lanes from a flat-rate
SuperGrok subscription via an RFC 8628 device-code grant against auth.x.ai, with
proactive/reactive refresh over a shared 0600 on-disk store. No API key. For
API-key access to the same endpoint, `provider: openai` with an api.x.ai base
URL still applies.
Reviewed and tested live against a real xAI subscription (grok-4.5): device-code
login, plain/structured/tool-calling completions, and a real token refresh.
Six follow-up fixes landed on top of the contribution, each with a RED-proven
regression test — see 5e04ab0be for the detail.
Full CI (workflow_dispatch on the rebased ref, since fork PRs get no secrets and
skip test-api): 103 jobs green, all three test-api shards included.
The native structured-output path hardcoded think=False, so gpt-oss models
failed fact extraction (they require a thinking level). Rather than a
model-name heuristic, merge the configured extra_body into the native
/api/chat payload: top-level native fields (think, keep_alive, ...) pass
through, and an "options" sub-dict merges into Ollama's generation options.
Set HINDSIGHT_API_LLM_EXTRA_BODY='{"think": "low"}' for gpt-oss.
Fixes#3246
Closes#3292.
Every live-transcript reader did `readFileSync(path, "utf8").split("\n")`. Past
V8's maximum string length (~537M chars) that throws ERR_STRING_TOO_LONG before a
single record is parsed; the readers catch it as "unreadable file" and return no
turns, so the Stop hook exits successfully having retained nothing. An agent that
had been running for weeks just stops updating memory, with no error anywhere.
Reproduced on a 575MB Codex rollout: readFileSync throws ERR_STRING_TOO_LONG,
readCodexTranscript returns []. With this change the same file yields 8,162 turns
ending in the most recent exchange, in 51MB of heap.
core/jsonl.ts streams the file a chunk at a time through a StringDecoder (so a
multi-byte character split across chunks is reassembled) and reads only the last
MAX_TRANSCRIPT_BYTES. Truncating the HEAD is what makes a cap safe here: the
recent exchange is the part worth retaining, and the incremental write-back only
sends turns after its cursor anyway. Landing mid-record drops that fragment
rather than emitting half a line; starting one byte early keeps a record whose
boundary the cut happened to land on. A truncated read is logged, never silent —
which was the actual complaint.
Applied to all six readers that shared the pattern (claude-code, codex,
antigravity-cli, copilot-cli, cursor-cli, grok-build), not just the one filed:
same bug, same line, and a large Claude Code transcript fails identically.
Two things, both about cost.
The periodic full re-sync (a replace every 20 appends) defeated the point of
appending: on a long session it re-uploads the entire document on a fixed cadence,
which is the expense this whole path exists to avoid. Removed.
What it was insuring against still stands, and is now accepted: retains are async,
so a write can be acknowledged and then fail server-side, and a resubmitted
operation_id replays the original operation whatever its status — those turns are
not re-sent. The other replace triggers (no cursor, fingerprint drift, dirty, bank
change) are unaffected, so a write we can SEE fail still self-heals; only a
silent server-side failure after acknowledgement is uncovered.
Second: test-doc-examples gated on a `docs` filter that matched
'hindsight-integrations/**' — added so an integration rename would reach the docs
build's integrations check, except build-docs has no `if:` and runs on every PR
regardless. So the only consumer of that breadth was the doc-examples matrix,
which runs every sample against a live LLM-backed server: four provider-credentialed
jobs on every integration PR (and every prose-only docs PR), none of which those
files can affect.
It now gates on a `doc-examples` filter covering the runnable samples themselves
(hindsight-docs/examples/**) and their runner. `docs` had no other consumer, so it
is removed rather than left as config nothing reads.
Adds /health/live (no DB access) and /health/ready alongside the existing /health, on the API server and the worker. Helm liveness probes now use /health/live; readiness stays on /health. Worker liveness reports seconds_since_last_poll for alerting without gating on it.
Fixes#3329
Show errors from document export, transfer import, and file uploads
that bypass the shared API error interceptor.
Format API errors safely so structured validation details remain
readable.
get_entity and get_observation_history passed entity_id / memory_id straight
to uuid.UUID() without a try/except. A malformed id (typo, copy-paste error)
raised a bare ValueError that the HTTP handler mapped to 500 instead of 400.
get_memory_unit and update_memory_unit already validate their id this way
(#906, #3062); these two endpoints were missed.
Wraps both in the same try/except and adds a ValueError -> 400 branch to the
two HTTP handlers (api_get_entity, api_get_observation_history). Adds stub-
engine regression tests mirroring test_delete_memory_units_validation.py.
Whole-bank export/import previously dropped the Knowledge Pages tree
(knowledge_pages was in _SKIP_TABLES because its self-referential parent_id
FK needs a topological restore) and restored mental models without an
embedding or lexical search state — leaving imported knowledge pages
disconnected and unsearchable, on every text-search backend.
Export:
- Add a typed TransferKnowledgePage model (no raw dicts across phases) and
carry the folder/page tree in knowledge_pages.json, parent-first, preserving
id, parent_id, mental_model_id, managed, sort_order, name and timestamps.
- Remove knowledge_pages from _SKIP_TABLES; classify it under a new
KNOWLEDGE_TABLES bucket (coverage guard updated).
Import:
- Regenerate each restored mental model's embedding with the TARGET model
(same "{name} {content}" text create_mental_model embeds), off-connection so
no DB conn is held across the embedding call.
- Rebuild backend-specific lexical state via the shared pg_search_vector_expr
(vchord's bm25vector column; native's is GENERATED and repopulates on insert;
pg_search/pg_textsearch/pgroonga index base columns).
- Restore the tree after its backing mental models exist and parents-first
(topological order tolerant of cycles/dangling parents), ON CONFLICT DO NOTHING.
Tests: whole-bank roundtrip asserts the nested tree restores exactly (ids,
parents, mm refs, managed) and pages are searchable after import with no NULL
mental-model embeddings; plus non-DB unit tests for the topological ordering.
* feat(coding-agents): write back only the new turns (append + idempotent retain)
The live write-back re-uploaded the WHOLE conversation on every Stop, and every
N turns under the persistent-plugin runtime. A long session therefore re-sent its
entire transcript each time, which is what turns a large session into an
unretainable one rather than merely a slow one.
Retains now carry a per-session cursor. A session that has already been written
appends only the turns added since the last successful write, using the server's
`update_mode: "append"` (supported since #932); the server concatenates them onto
the stored document with "\n", which is exactly why the transcript is JSONL.
Append is only correct while our view of the document matches the server's, so
every uncertain case falls back to the full REPLACE this always did - no cursor,
a transcript that was rewritten rather than extended (compaction, a truncated
rollout), or a previous write whose outcome is unknown. Replace is idempotent by
construction and so is always the safe recovery.
Two supporting changes:
- Conversation retains carry a deterministic v5 `operation_id`, so a resubmitted
write is collapsed into the original operation instead of being applied twice.
That is what makes append safe: the client aborts at 15s, and a server that
committed the write anyway would otherwise get the same turns again. The field
landed in v0.8.6 (#2937/#2947) and is silently IGNORED by anything older, so
the append path is gated on a cached GET /version probe and older servers keep
replacing.
- `RetainOpts.async` is gone. Nothing ever passed `false`; retains are always
async, and nothing in this plugin can afford to block a hook on extraction.
Backfill, git, knowledge and survey retains are untouched: they keep replacing,
and deliberately do not take a deterministic operation id, so re-retaining
identical content after a document is deleted still restores it.
* fix(coding-agents): serialise a session's write-backs so appends cannot overlap
Found reviewing the append cursor: the runtime fires retains without awaiting
them, and reading the cursor was not atomic with claiming it — the capability
probe awaits in between. Two overlapping write-backs therefore both planned an
append from the SAME position and submitted overlapping slices, duplicating turns
inside the document:
replace(REF-ID + turns 0-4), append(turns 5-7), append(turns 5-8)
Serialising only the claim would not have fixed it either: that leaves an append
racing a replace on the wire, where the order they land in decides the outcome.
The whole read-plan-send-confirm cycle is now chained per session, so each
write-back plans against the previous one's CONFIRMED cursor.
The runtime's idle test now waits a tick before asserting on the fire-and-forget
retain, as its sibling assertions already did — one extra microtask hop.
* fix(coding-agents): key the write-back cursor to the bank it wrote to
The cursor is keyed by (harness, session id), but the bank is re-derived from
each hook event's cwd — so a session that moves between repos (#3133) keeps its
id and changes bank. The new bank holds no document for that session, and the
cursor still claimed a position in it:
bank repo-a: replace(REF-ID + turns 0-4)
bank repo-b: append(turns 5-7) <- turns 0-4 never existed here
The cursor now records the bank it wrote to, and a mismatch replaces. Same
reasoning as the fingerprint and dirty checks: anything that makes our view of
the document unreliable falls back to the full write.
Also covers a config change (mapPathToBank, an explicit bankId) that re-points a
live session at a different bank.
* fix(coding-agents): re-sync the whole document every 20 appends
Review follow-up. Retains are async: the server acknowledges the submission and
extracts later, so a write can be confirmed to us and still fail afterwards — and
_resolve_retain_replay returns a prior operation whatever its status, so
resubmitting the same payload will not redo it. Replacing everything used to be
self-healing precisely because each write re-sent the whole document; appending
gives that up, and a single lost write would otherwise cost the rest of the
session.
A full write every MAX_APPENDS_BEFORE_RESYNC appends bounds that to the turns
since the last re-sync. A replace of any kind resets the count.
Also from the review:
- drop a session's chain entry once it settles, so a host that outlives many
sessions (opencode runs for days) does not keep one resolved promise per
session id forever
- pin the version test to MIN_IDEMPOTENT_RETAIN_VERSION rather than repeating
the literal, which also gives the exported constant a consumer
Knowledge-base routes reached the engine without invoking
OperationValidatorExtension, so any authenticated tenant could read or
write another bank's knowledge tree — including the mental-model content
that pages render — by knowing its bank_id.
- Add knowledge-base members to BankReadOperation (tree/get-page/search/
export) and BankWriteOperation (create-folder/create-page/update-page/
rename/move/delete).
- Gate all nine KB engine methods through _validate_operation before any
read or write, mirroring the mental-model paths. This also makes the
KB routes' pre-existing (previously dead) OperationValidationError
handlers reachable.
- Add a _nested_operation_authorized contextvar so composite methods
(create_knowledge_page, update_knowledge_page) and the new
export_knowledge_base engine method fire exactly one validator hook and
never auto-create a bank on an unauthorized path.
- Move export bundle data-gathering into export_knowledge_base (typed
KnowledgeBaseExport/KnowledgeBaseExportPage); http.py only renders.
Tests: deny bank_read -> 403 leaking no content on tree/get-page/search/
export; deny bank_write -> 403 leaving the tree unchanged and no bank row;
success paths assert exact hook counts.
Follow-up to #3036 / #2488.
recall_async only populates each result's entities field when
include_entities=True, and it defaults to False — so reflect's recall and
search_observations tools never surfaced them. Canonical entity names are
semantic signal the surface text may lack ("Bob" in the text vs canonical
"Robert Smith"): they give the agent resolved names to cite and to pivot
follow-up queries on, for the cost of one extra lookup query per recall.
The top-level EntityState dict recall also builds is not serialized into
tool results; only the per-fact names reach the agent.
* fix(structured-doc): add TableBlock to fix markdown table rendering
StructuredDocument only supported 4 block types (paragraph, bullet_list,
ordered_list, code). When the LLM generated markdown tables, _parse_block
treated the multi-line table as a ParagraphBlock and joined all lines with
" ".join(), collapsing the table into a single line and breaking formatting.
Add a TableBlock type with headers/rows fields, plus parse and render
support. The parser detects table chunks by checking that all lines match
the markdown table row pattern and at least one line is a separator
(|---|---|). The renderer emits standard markdown table syntax with
one row per line.
Also update the delta ops prompt to include the table block shape so
delta refreshes can emit table operations correctly.
* fix(structured-doc): escape pipes in table cells and cover TableBlock with tests
The new TableBlock joined cells with a bare " | ", so a cell whose text
contained a pipe emitted extra columns and re-parsed into a different block
— the render/parse round-trip the structured-delta architecture depends on
was not stable for tables. Escape \\ and | on render, scan escapes on parse.
Also: a table with no headers dropped every row (rendered ""), rows wider
than the header lost cells to GFM, and the no-separator branch of
_parse_table_block was unreachable. Adds the missing unit tests.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Seven per-bank configurable fields were not declared on BankTemplateConfig, so
export/import silently dropped them: consolidation_llm_parallelism,
consolidation_max_memories_per_round, enable_auto_consolidation, memory_defense,
recall_chunks_max_tokens, recall_include_chunks, recall_max_tokens. Cloning a
bank produced a clone that looked correctly configured while quietly running on
the server defaults for those seven — and memory_defense being one of them means
a bank's defense policy did not travel with it.
All seven are now part of the template engine, so an exported bank reproduces its
full configuration on import.
The rest of the change is about not needing to notice this again. Adding a
per-bank config field is a multi-step flow, and each step now fails until the
previous one is done:
1. add it to _CONFIGURABLE_FIELDS -> test_every_configurable_field_is_exportable
fails until it is declared on BankTemplateConfig (both directions: a template
field that is not configurable fails too, since the engine would reject it);
2. declare it there -> test_sample_values_cover_every_exportable_field fails
until it has a value in _SAMPLE_VALUES;
3. give it a value -> the existing round-trip test exercises it end to end;
4. touching BankTemplateConfig moves the OpenAPI spec, the generated clients and
bank-template-schema.json, so verify-generated-files fails until those are
regenerated.
An intentional exclusion is now a decision to record in the guard with a reason,
not an omission that no one sees.
The docs listed 15 of the 45 fields in a hand-maintained table that was already
stale and would contradict "every field is supported" the moment it drifted
again. It now states the guarantee and points at the generated schema as the
authoritative list, keeping the common fields as examples.
Verified by mutation: adding a configurable field without a template field,
adding a template field that is not configurable, and adding a template field
with no sample value each fail the suite.
* perf(reflect): drop retrieval plumbing from reflect tool results
Reflect tool results are handed to the model verbatim, so every field in them
is spent context. `search_observations` and `recall` currently serialize the
whole result model, which includes retrieval internals the agent never reads:
per-stage `scores`, ingest `metadata`, extracted `entities`, and the
`chunk_id` / `document_id` plumbing. On real banks that envelope measures
several times the observation text it accompanies.
These are internals rather than evidence, and the loop does not depend on any
of them: the agent cites by `id`, `based_on` persists only
id/text/type/context, and the expand tool takes `memory_ids` and resolves
chunks server-side. Identity, text, dates, tags and `source_fact_ids` are all
kept.
`chunks` in `recall` is deliberately left alone: `ChunkInfo` carries only
chunk_text / chunk_index / truncated, so it holds none of these fields and
trimming it would be a no-op. A test pins that, so if a future field lands
there the decision is revisited rather than quietly going stale.
Scope, stated plainly: this reduces the envelope, it does NOT implement the
accounting change #3122 asks for. The token budget still counts observation
text only, and forced synthesis still drops oversized blocks whole, so the
user-visible failure in that issue -- a confident "no information" answer
carrying hundreds of citations -- can still occur on a large enough result
set. This is a smaller, independent improvement; #3122 should stay open.
Tests pin both directions, since the risk in removing fields is that
something downstream quietly needed one: every trimmed field is gone, and
every field the loop depends on survives.
* keep entities in reflect tool results: canonical names, not plumbing
The entities field carries canonical entity *names* (not ids), which are
semantic signal the surface text may lack ("Bob" in the text vs canonical
"Robert Smith"). Reflect's recalls don't populate it today
(include_entities defaults to False, so _prune_nulls already drops the
None), but trimming it would bake in eating the names if that ever flips
on. Only true plumbing stays trimmed: scores, metadata, chunk_id,
document_id.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Existing coverage left a gap in the middle. test_bank_template_configurable_fields
sets fields one at a time and never exports, so it proves import writes a field,
not that export reads it back. TestExport::test_export_reimport_roundtrip does
export then import, but with a single config field, and asserts only the response
flags (config_applied is True) — never that a value survived.
A field that import accepts but export drops, or that export reshapes into
something import rejects, passes both today.
This sets every field BankTemplateConfig declares on one bank, exports it,
imports the exported manifest into a fresh bank, and asserts the clone's
overrides match the source's. Overrides, not resolved config: the resolved view
would hide a dropped field behind the server default and read as a pass. The
comparison is source-vs-clone rather than against the literal input because some
fields normalize on the way in (entity_labels migrates legacy shapes) — the
property under test is that a clone ends up configured like its source.
BankTemplateConfig.model_fields is the exportable surface (the export endpoint
filters overrides through exactly that set), so a guard test asserts the sample
table matches it. Adding a template field fails that guard until it gets a
value, which stops the round-trip from silently narrowing.
Verified by mutation: dropping a field from the export filter, dropping one from
BankTemplateConfig.get_config_updates(), and adding an unsampled template field
each fail the suite.
The bank-config API took `dict[str, Any]` updates and never checked the values
against the declared `HindsightConfig` field types, so a client could store a
JSON object in a string-typed field such as `observations_mission`. The write
succeeded; the bank then failed *every* consolidation with "expected string or
bytes-like object, got 'dict'" — `re.sub` inside `escape_for_prompt`, reached
from prompt assembly. Deterministic, so the bank never recovered. A sweep of one
deployment found 7 banks across 7 tenants in this state, spread by a third-party
tool that writes structured JSON into the mission/instruction fields.
- Write side: `validate_bank_config_updates` now type-checks every value against
the field's dataclass annotation and rejects with a 400 naming the field and
the expected type. Applies to nested `retain_strategies` overrides too, since
`apply_strategy` splices those onto the resolved config and they reach the same
fields. `entity_labels` keeps its wider contract (list or {"attributes": [...]}).
- Read side: banks configured before this landed are tolerated rather than
wedged. A non-string in a string field is JSON-encoded — the same remediation
applied in the field, and it preserves intent since the structure still reaches
the prompt as text. Anything not coercible is dropped with a WARNING so the
bank falls back to the tenant/global value.
- Observability: task-failure paths log `exc_info` instead of a bare
`traceback.print_exc()` (the stderr copy carries no task id and rotates away
first), and messages/stored `error_message` go through `format_task_error`, so
an exception with an empty `str()` no longer logs
"Task execution failed: graph_maintenance, error: ".
Hermes installs `hindsight-all` into its OWN venv via `hermes memory setup` to
run memory in local_embedded mode, and exact-pins every direct dependency
(`==X.Y.Z`) as a deliberate supply-chain policy. Any version range Hindsight
declares that excludes one of their pins therefore makes the two impossible to
co-install for every Hermes user on embedded memory — that is what #3251 hit
with our cryptography/pillow floors.
Hermes main has since bumped to cryptography==48.0.1 / Pillow==12.3.0, which
already matches our floors, so no dependency change is needed and none is made
here. What was missing is the check that keeps it that way: both sides bump on
their own schedule, so the collision recurs silently until something looks for
it. Tracking their main branch surfaces it while it is still cheap to fix on
either side rather than in a released Hermes.
scripts/test-hermes-compat.sh runs five checks of increasing depth: resolution
(both into ONE resolution, so an unsatisfiable pin is a hard error instead of a
silent downgrade), `pip check` plus a dump of the contested versions, `hermes
memory status`, the runtime imports Hermes makes for embedded memory, and a real
embedded daemon boot with bank operations.
Implementation notes:
- Hindsight installs from BUILT WHEELS, not `file://` directories. uv installs a
workspace member given as a directory such that hindsight_embed.__file__ still
points into the source tree, and the daemon manager keys dev-mode detection on
that path — so a directory install launches the API via
`uv run --project <repo>/hindsight-api-slim`, out of the monorepo's venv and
.env, bypassing the Hermes venv this script exists to test. Step 5 asserts the
daemon binary resolves inside the test venv so this cannot regress.
- Hermes is cloned and installed editable: their build backend refuses
wheel/sdist builds by design, so `git+https://` fails outright.
- Python is pinned to 3.12 rather than .python-version because Hermes caps
itself at <3.14; the venv must sit inside both projects' windows.
- Hindsight state is isolated by a dedicated `hermes-ci` profile rather than by
redirecting HOME, which would also hide the uv/HuggingFace caches from the
runner and re-download the local-ml stack every run.
- Step 5 runs from the work dir, not the repo, so a developer's .env cannot hand
the daemon credentials a runner does not have.
- MemoryEngine refuses to construct without an LLM key, so the daemon boots on a
placeholder one; nothing calls the LLM during startup or bank operations.
The job needs no secrets and so runs on fork PRs too. Only the retain/recall
round-trip requires a real LLM key and is skipped without one.
Verified end-to-end locally against hermes-agent main (0.20.0): all five steps
pass, 225 packages consistent, daemon boots from the test venv and stops cleanly.
* fix(api): dispatch knowledge-base search on the text-search backend (#3268)
search_knowledge_pages hard-coded the native tsvector SQL
(ts_rank_cd / @@ over mm.search_vector) in both its RRF BM25 arm and its
embedding-unavailable fallback. But mental_models.search_vector is only a
tsvector under the `native` backend; under pg_search / pg_textsearch /
vchord it is a dummy TEXT (or bm25vector) column, so knowledge-base search
500'd with `function ts_rank_cd(text, tsquery) does not exist` on every
non-native deployment while recall (which already dispatches) kept working.
Add knowledge_bm25_arm() in the PG dialect — the same per-backend dispatch
PostgreSQLDialect.build_bm25_arm already does for memory_units — and route
search_knowledge_pages through it:
- native / pgroonga: generated tsvector (ts_rank_cd / @@). pgroonga's
mental_models is never reconciled to pgroonga structures, so it keeps the
migration-time tsvector and the native operators are correct for it.
- pg_search: paradedb.score / @@@ over the (id, name, content) BM25 index.
- pg_textsearch: BM25 distance over the content column.
- vchord: its bm25vector column is never populated on mental-model writes,
so the BM25 index is empty — degrade to a vector-only search rather than
emitting SQL that returns nothing (or 500s).
Fix the stale docstring that claimed a tsvector for all backends, and add a
backend-dispatch regression test that pins the SQL each backend emits
(no live extension required, matching test_multilingual_bm25).
* fix(api): make knowledge-base search reuse the recall BM25/vector logic for all backends (#3268)
Follow-up to the first cut, which degraded vchord to a vector-only search
because mental_models.search_vector was never populated. Instead, reuse the
exact per-backend logic the memory-recall path already uses so knowledge
search works identically across native / pgroonga / pg_search / pg_textsearch /
vchord — read AND write.
Write side: mental_models.search_vector is now tokenized on write for vchord
via the shared pg_search_vector_expr helper (the same single source of truth
insert_facts_batch / consolidator use for memory_units), threaded through the
create-pinned INSERT, the update-mental-model UPDATE (re-tokenized only when
name/content change), and clear-mental-model. The helper gains signals_col=None
(two-column tables) and native_inline=False (mental_models' native search_vector
is a GENERATED column that populates itself, so only vchord's plain bm25vector
column needs an explicit value). memory_units keeps its three-column,
native-inline behaviour unchanged.
Read side: knowledge_bm25_arm now emits a real vchord BM25 arm (negated <&>
distance over search_vector, gated > 0) mirroring build_bm25_arm, and no longer
returns None — search_knowledge_pages drops the vector-only/empty-result
branches.
Tests: pin the vchord read arm and the per-backend write tokenization (only
vchord writes; memory_units default expr unchanged).
Every graph_maintenance run is the same bank-wide sweep: the payload carries
only bank_id, run_graph_maintenance_job discards the request context, and the
relink pass drains the whole queue. A second concurrent run for one bank adds
no work — and claim_graph_maintenance_batch locks queue rows FOR UPDATE with no
SKIP LOCKED precisely because it assumes a single runner per bank, so the runs
convoy on each other while each holds a worker slot.
Same guarantee consolidation already gets from its busy-bank exclusion, applied
as a predicate on the existing claim queries rather than a claim phase of its
own. graph_maintenance has no reserved-slot floor and the poller's fairness pass
claims with shared_limit=1, so a trailing phase would drop it below every other
operation type and let a single pending retain starve it; as a predicate it
keeps competing by created_at.
The predicate also takes at most one same-bank row per batch. Excluding busy
banks alone does not cover that: with several pending rows and nothing yet
processing, one batch claims them all. Several pending rows per bank are
reachable through the recovery paths — recover_own_tasks resets all of a
worker's processing rows at once, plus _schedule_retry / _defer_operation /
admin recover.
Fixes#3230
DROP INDEX CONCURRENTLY on the shared memory_units table deadlocks with
other sessions' index DDL by design; CI's end-of-run teardown storm
outlasted the drop path's ~2.4s retry budget. Serialize per-table index
DDL in-process on PostgreSQLOps and give the drop path a ~30s jittered
retry budget for the cross-process residue.
The PGroonga example referenced groonga/pgroonga:latest-debian-pg17, which has no registry manifest, so the documented Compose stack could not build.\n\nPin the current PGroonga 4.0.8 PostgreSQL 17 image and install pgvector 0.8.6 from the PGDG repository already configured by that base image. This removes the source clone and build toolchain while keeping the example on PostgreSQL 17 for parity with neighboring recipes.\n\nContext:\n- Fixes #3311.\n- Verified on arm64 with a disposable PostgreSQL instance.\n- CREATE EXTENSION vector and pgroonga both succeed.\n- Mixed Korean/English PGroonga search and pgvector distance queries pass.\n- PostgreSQL 18 deployment work remains a separate operational concern.
The background seed engine (deepen.js) resolves {harness} from cfg.harness,
which falls back to a hardcoded "opencode". buildSessionStartContext fired the
seed via startSeed(cwd, { limit }) without the harness — so every non-opencode
session's codebase survey and git history were misfiled into an
`opencode::<project>` bank that no session ever reads, while the session hooks
correctly wrote to `<harness>::<project>`.
- session-start.ts: forward the asking harness to startSeed, mirroring the
survey spawn right beside it.
- config.ts: resolve cfg.harness to the harness that called loadConfig when the
config file sets none, instead of the silent "opencode" default — this also
fixes the same latent misfiling for kilo and opencode-fork harnesses.
Also (#3248): add a supersession clause to OBSERVATIONS_MISSION so a revised
convention updates its existing observation instead of accumulating a
contradictory sibling, matching the language already used in the conversation
and reflect missions.
Verified end-to-end with the built artifacts: the real claude-sessionstart-hook
now spawns `deepen.js ... --harness claude-code`, which resolves
`bank=claude-code::<project>`.
* docs: draft blog posts for v0.9.0 (release + coding-agents)
* docs: 0.9.0 changelog + consolidate coding-agents launch post
* docs: update launch post to the shipped coding-agents harness list
* docs(blog): add per-agent wall time to the 0.9.0 benchmark table
The table reported corrections and cost but not how long a task took, which is
the number a reader feels. Computed from the same runs as the other columns —
outputs/sdebench/{hindsight,vanilla}-{claude,codex,opencode}-{1,2,3} on the
benchmark repo's main, meta.wall_s averaged per task across the three runs of
each arm:
Claude Code 84.7s -> 75.1s (-11%)
opencode 174.2s -> 163.3s (-6%)
Codex CLI 53.6s -> 48.6s (-9%)
Verified against the published columns before trusting the source: the same
files reproduce corrections 0.85/0.36, 1.20/0.80, 1.34/0.47 and costs -24%,
-13%, -52% exactly.
The prose claim is deliberately the weaker one — every memory run beat its
agent's vanilla AVERAGE, which holds for all nine. 'Faster than every vanilla
run' does not: opencode's slowest memory run (171s) is slower than its fastest
vanilla run (163s), and Codex ties at 51s.
* docs: regen 0.9.0 changelog and expand release blog for new features
* docs: refresh 0.9.0 changelog (99 commits)
* docs: date the 0.9.0 posts (launch 08-06, release 08-07) and unset draft
* docs(blog): embed 0.9.0 launch video, add coding-agent logos cover, cross-link posts
* docs(blog): drop cover image from the 0.9.0 release post (keep it on the launch post)
* docs(blog): fix coding-agents install to npx, link the Coding Agents docs page
* docs: regenerate 0.9.0 changelog against the release tag; sync docs-skill mirror
* docs: launch the Coding Agents page and mark the per-agent plugins superseded
Hold until the Coding Agents plugin is announced — merging this makes the page
public and tells existing users their plugin is legacy, so it should land with
the announcement rather than before it.
Two halves:
- Launch. Undoes the deliberate hide: the page drops `unlisted`, its entry
returns to integrations.json (which drives both the gallery and the sidebar),
and coding-agents leaves the EXCLUDED set in check-integrations.mjs, so the
released-tag check guards it like every other integration.
- Supersede. The six overlapping integrations — claude-code, codex, opencode,
cursor-cli, cline, copilot-cli — get an admonition in the style already used
on the Hermes page: what replaces them, the install command for their harness,
and a link to the migration section. Pages and packages keep working; nothing
is deleted and no registry deprecation is published, so existing links and
installs are unaffected.
Each notice states plainly that memory does not move — the old plugins scope a
bank per agent per project where this one uses a bank per repo — and points at
`--import-conversations` for Claude Code and Codex, the two whose transcripts
record enough to attribute a session to a repo. The other four say so instead of
implying an import exists.
* docs: group the integrations sidebars into coding agents / frameworks / apps
Both sidebars driven by integrations.json rendered one flat run of 59 entries.
Split them into three groups so a coding agent is distinguishable from an SDK.
The existing `category` field couldn't drive this on its own: its `tool` bucket
mixed CLI agents and editors with chat apps, note-taking and voice platforms.
The 19 coding agents move to a new `coding-agent` category; `framework` is
unchanged, and `tool`/`mcp` become the catch-all group.
Grouping lives in src/lib/integration-groups.ts, kept free of the @site alias and
of any JSON import so both consumers can use it — the theme swizzle (webpack) and
sidebars-integrations.ts (evaluated at config load). An unrecognised category
falls into the last group rather than disappearing from the sidebar.
* docs: regenerate the docs-skill mirror for the supersede admonitions
scripts/generate-docs-skill.sh mirrors docs-integrations/ into skills/; the
launch commit edited seven pages without re-running it, so the mirror still
described the per-agent plugins as current.
* docs: spell out the migration path for Claude Code and Codex
Both pages said memory "does not move automatically", which is now only half
true: the server endpoint IS carried over (~/.hindsight/claude-code.json and
~/.hindsight/codex.json, same keys), so nobody is silently switched to Cloud.
Each page now states what moves — the endpoint automatically, conversations via
--import-conversations — and what does not: the recall/retain settings, missions
and bank-naming options. It also says why conversations come from local
transcripts rather than the old bank: that bank defaulted to a single static
bank shared by every project, whose documents record only a session id, so
attributing them to a repo requires the local transcripts regardless.
These are the only two superseded plugins with an endpoint to carry; the other
four pages already say their history can't be imported and are unchanged.
* feat(claude-code,codex): deprecation notice in the old plugins' sessions
Folded in from #3205 so the launch lands as one change: the docs that announce
the Coding Agents plugin and the in-session notice that points existing users at
them ship together, rather than one arriving without the other.
Both plugins keep working, but they are deprecated — development has moved to
@vectorize-io/hindsight-coding-agents. A changelog entry reaches nobody who
installed a year ago, so the SessionStart hook says it, via systemMessage (the
channel Claude Code shows the USER; additionalContext would only reach the
model). Codex accepts the same hook output shape, so one design serves both.
Emitted before the existing early returns: neither the memory settings nor
whether the server is reachable changes the fact that the plugin is deprecated.
Shown every session, with `"upgradeNotice": false` as the permanent opt-out —
stated in the message itself, which is what makes that frequency acceptable.
With no rate limit there is no state file and none of its failure modes; what
remains is a config check that returns None rather than raising, because a
promotional message must never be why a session breaks.
* docs: per-harness install sections, featured hub cards, browsable sidebar
Page
- One subsection per harness with its logo and a copyable install command,
replacing the table: the command is what a reader came for, and a table cell
is not copyable.
- Title is just "Coding Agents"; the old keyword-stuffed title read as spam in
the sidebar and breadcrumbs.
- "Ingestion internals (no CLI)" is dropped from the docs page via the existing
DROP_SECTIONS mechanism, staying in the README where the contributor-facing
audience is.
Integrations Hub
- A Featured grid pins Coding Agents, Vercel AI SDK and OpenClaw above the
rest, and only on the unfiltered view — pinned cards above non-matching
search results would read as noise.
- The Coding Agents card draws all ten supported harness logos. "One install,
every agent" is the whole pitch and a single icon cannot carry it.
- Logos come from the control plane's harness set, which is already keyed by the
exact harness ids the plugin uses, so the two stay consistent by construction.
Sidebar
- Groups are open but show six entries each, with the tail behind a nested
"Show all N". Fully expanded, 59 entries were a wall; fully collapsed hid that
the list was worth opening.
- The umbrella Coding Agents entry leads its group instead of sorting under "C",
since it is the entry point to every other agent in that list.
* fix(docs): point the page's harness logos at this build, not production
The README must use absolute URLs so the logos render on npm and GitHub, but the
docs page inherited them verbatim — pinning every image to hindsight.vectorize.io,
where /img/harness/* does not exist yet. Logos were broken locally and in
previews, and would only start working after a deploy.
The sync script now rewrites our own absolute asset URLs to site-relative, next
to the repo-relative-link rewrite it already does for the same reason: two
audiences needing different URLs from one source.
* docs: curate the sidebar previews, harness logos for coding agents
The coding-agent group now previews HARNESSES, not pages: ten logos that all
link to the Coding Agents page. Listing ten integration pages there presented
one plugin as ten separate integrations, which is the opposite of its pitch —
and the logos make the group recognisable at a glance. Every individual page
moves behind "Show all", which is also what keeps it associated with the
sidebar.
The other groups get hand-picked previews instead of the first six
alphabetically — the first names in a sorted list are an accident of spelling,
not a description of the group:
Frameworks & SDKs — LangGraph/LangChain, Vercel AI SDK, Vercel Chat, Eve, CrewAI
Apps & tools — ChatGPT, Hermes, OpenClaw, Obsidian
Hermes, NemoClaw, OpenClaw and Paperclip move from framework to tool.
The overflow label counts what opening it actually reveals: "Show 21 more" where
some entries are already previewed above, "Show all 19" for coding agents, whose
overflow really is every page.
* docs: inline sidebar preview, full list on the integration pages
The two sidebars do different jobs, so they now show different things.
Main docs sidebar — a preview: three groups rendered INLINE and
non-collapsible, nothing behind a disclosure. Ten harness logos for coding
agents, five frameworks, four apps, then an "All integrations" link to the
gallery, which offers search and filters a sidebar cannot.
Integration pages — the full list again: flat, alphabetical, every entry. Once
you are on one of these pages you are comparing and hopping between them, so
hiding two thirds behind "Show N more" worked against the reader. Listing each
page directly is also what associates it with this sidebar.
* docs: promote the sidebar groups, separate Featured, brand the umbrella card
Sidebar: the "Integrations" placeholder is replaced BY its contents instead of
filled, so the three groups sit at the same level as the rest of the navigation.
The wrapper was two levels of nesting to say one thing, and it indented every
entry beneath it.
Hub: a divider and an "All integrations" heading separate the pinned Featured
cards from the full list, which otherwise read as one uninterrupted run.
The Coding Agents card carries the Hindsight mark rather than the GitHub logo —
it is our own package, and the GitHub icon said nothing about it.
* docs: install with npx, no global install
Every example across the README, the seven integration pages, the companion
skill and the generated docs now runs the installer with npx. Nothing here asks
anyone to keep a package installed whose only job is to wire other tools up.
The paragraph telling people to install globally — and warning that npx was
refused — is replaced by what actually happens: install copies what it needs
into ~/.hindsight/coding-agents and points each agent's wiring there, so it does
not matter where it ran from, and updating is the same command again.
Depends on #3241, which makes that staging real; until it ships in 0.0.6 the
published installer still refuses to run from an npx cache.
* docs: move the superseded pages into a Legacy section, out of the gallery
The six per-agent pages the Coding Agents plugin replaces — Claude Code, Codex,
Cursor CLI, Copilot CLI, opencode, Cline — move to a `legacy` category.
They keep their pages and their migration banners: people still run these
plugins and still arrive from old links, so removing the pages would break both.
What changes is where they are offered. The gallery is where someone comes to
CHOOSE an integration, and offering one we are actively migrating them off
points them at a dead end — so legacy entries are filtered out of it, including
the hero banner, whose hardcoded list still advertised Claude Code and now
advertises the plugin that replaced it.
In the sidebar they sit in a collapsed "Legacy" section at the end instead of
mixed in alphabetically, so the main list is only what we would recommend today.
Docusaurus expands that section automatically when you are on one of the pages.
Grouping keys off an explicit `harnessPreview` flag now: "no previewIds" used to
imply the coding-agent group, which the Legacy group would also have matched.
Four bank templates (hermes-gateway-bot, hermes-orchestrator, customer-support,
research-assistant) listed only `hermes`, making them look Hermes-exclusive even
though their memory pattern fits other harnesses. Add a small, curated set of the
most relevant integrations to each (keeping `hermes`):
- hermes-gateway-bot: langgraph, crewai, agno
- hermes-orchestrator: langgraph, crewai, autogen
- customer-support: langgraph, crewai, dify
- research-assistant: obsidian, llamaindex, langgraph
Also fixes two stale icon IDs on the conversation template
(ai-sdk -> vercel-ai-sdk, chat -> vercel-chat) so its icons resolve.
`hermes` is kept on all seven templates, so the Hermes setup picker is unaffected.
- clack/Vercel-style rail renderer (src/install-ui.ts, zero-dep): per-harness
step groups keyed on the '<name>: ' log prefix, severity from message
phrasing plus run()'s own emoji markers, $HOME shortened to ~, version
header, honest outros (partial failures say so instead of 'nothing changed')
- arrow-key server picker (❯ pointer, ↑/↓/j/k + Enter, digit shortcuts,
Esc/q/Ctrl+C cancels) with the numbered prompt kept as fallback when a raw
TTY is unavailable; rows truncate to the terminal width and autowrap is
disabled during repaint so narrow terminals don't duplicate lines
- fix: the interactive picker never actually waited (v0.0.4/v0.0.5) —
process.stdin.isTTY flips fd 0 non-blocking, readSync EAGAINs, and every
answer silently became its default. Probe with tty.isatty instead and treat
EAGAIN as wait-for-input
- fix: configureServer now honors HINDSIGHT_CONFIG like the runtime, so the
wizard writes the file sessions actually read
- Hindsight Cloud API token is now REQUIRED: interactive re-asks (3 attempts),
--server cloud without --api-token refuses up front instead of writing a
config that 401s on the first session
- installSkill logs with the harness prefix so skill lines group correctly
Adds three hierarchical config fields — enable_temporal_retrieval, enable_graph_retrieval, enable_reranking — all defaulting to true, so recall behaviour is unchanged unless a bank opts out. enable_reranking reuses the existing RecallReranking strategy by downgrading "cross_encoder" to "rrf"; "interleave" (consolidation dedup) and "rrf" are never overridden.
Paired with retain_extraction_mode=chunks and enable_observations=false, a bank behaves like a conventional vector store. Ships as a `plain-retrieval` bank template.
Surfaced through the bank config API, both hand-written SDK wrappers, and a Recall Pipeline section in the control plane translated across all ten locales.
* feat(coding-agents): stage the runtime so npx installs work
Installing from an npx cache was refused outright. Everything this writes into a
host's config is an absolute path into the package, so from a cache those paths
die on the first eviction and every hook stops SILENTLY — the agent keeps
working, memory just stops. Refusing was the honest response to that, but it
made a global install mandatory for a tool whose only job is to set other tools
up.
`install` now copies the runtime to ~/.hindsight/coding-agents and wires THAT.
The problem disappears rather than moving to the user: no cache path is ever
written, and no global install is needed.
Both dist and pkgRoot are repointed in one place, so none of the twenty call
sites that bake a path into a host config needed to change, and opencode/Kilo
still get a directory with package.json and the plugin entry.
The staged directory is named `coding-agents` deliberately: MARKER matching is
what lets a re-install replace our entries and `uninstall` remove them, and it
looks for that substring in the command path.
Staging is skipped when there is nothing to copy — a checkout whose dist was
never built, and the tests — so wiring falls back to the source path instead of
pointing at a directory that does not exist.
* fix(coding-agents): make upgrades safe, including from a global install
Three upgrade paths, now verified end to end and pinned by tests:
- version to version: dist is replaced wholesale, so a file dropped in the new
release cannot linger and stay reachable from a host config that names it. The
wiring path never changes, so hook entries stay at exactly one.
- from a 0.0.5 global install: the old entry points into node_modules, which
contains the marker, so it is REPLACED rather than duplicated — verified
against the actually-published 0.0.5, not a rebuild of it.
- re-running the staged installer: previously this compared paths as strings, so
a symlinked or differently-spelled route to the same directory would fall
through to the copy and delete the dist it was executing from. Compared
through realpath now.
The endpoint carry-over only read ~/.hindsight/claude-code.json, so someone
migrating off the Codex plugin silently landed on Cloud despite having a server
configured. Codex uses the same key names in ~/.hindsight/codex.json, so one
reader serves both.
The agent being installed is checked first: wiring Codex must take Codex's
server even when a stale claude-code.json is still present. It then falls back
to any known legacy config, since one server shared by both is the common case.
These two are the only superseded plugins that shipped a user config —
Cursor CLI, Copilot CLI, opencode and Cline have no endpoint to carry.
Webhook destination URLs are caller-supplied. Restrict where the delivery
worker will connect and what it returns to callers:
- Block private, loopback, and link-local destinations (incl. the cloud
metadata address) by default. Operators re-permit specific hosts/CIDRs via
HINDSIGHT_API_WEBHOOK_ALLOWED_HOSTS (e.g. 127.0.0.1 for local testing).
- Route all delivery traffic through a guarded httpx transport that resolves
the host, rejects disallowed addresses, and pins the connection to a
validated IP (preserving Host + TLS SNI) so a DNS name cannot be rebound to
an internal address between validation and connect.
- Validate destinations at registration time for immediate 4xx feedback.
- Stop returning the raw upstream response body from the delivery-history API
by default; the status code is still returned. Operators can opt in with
HINDSIGHT_API_WEBHOOK_EXPOSE_RESPONSE_BODY. Both flags are server-level only
(not per-bank configurable).
Adds unit + transport tests for the URL guard and API-layer body gating, plus
HTTP integration tests for registration rejection and delivery-history gating.
`import_bank_async` resolved the target bank's config before the archive's bank
row was restored. The bank cannot exist at that point — import refuses to write
into an existing bank — so the resolve saw only global + tenant config and never
the bank's own `entity_labels`, which arrives with the archive. Retain Phase 1
then classified every label entity as regular for the whole import.
That silently disabled #3208/#3214 on imported banks: the partial trigram index
`WHERE entity_kind != 'label'` excluded nothing, so every fuzzy probe kept paying
the recheck-discard cost the index removes. It also let the import fuzzy-merge
distinct label values, which the exact-match-only path (#3187) exists to prevent.
The migration backfill does not cover it — it runs once, and a bank imported
afterwards has nothing to correct it.
Measured on an 862-document production export whose bank has a free-text label
group: 5,374 label-shaped entities, of which the import marked 0 as labels.
Correcting the classification takes entity-resolution p50 from 263 ms to 37 ms
and a single fuzzy probe from 8.28 ms to 0.38 ms.
import_bank now takes a `resolve_config` callback and re-resolves once the bank
row is in place, replaying the documents with the bank's own config.
An in-flight task that stops running without reaching its terminal-marking
code leaves its async_operations row 'processing' under a *live* worker,
forever: _cleanup_task has already dropped it from _active_tasks, the
recover_own_tasks sweep only runs at startup, and no dead-worker handling
applies because the worker is alive. Clients polling that operation wait
indefinitely. Two paths get there — shutdown cancelling in-flight work past
the drain timeout (CancelledError derives from BaseException, so it escapes
every `except Exception` in _execute_task_inner), and _mark_failed, itself a
DB write, failing.
Extract the reconciliation recover_own_tasks already performs into
_reclaim_own_processing_tasks and reuse it from both new sites, so the guards
that make it safe stay in one place: scoped to this worker's own rows, batch
API operations excluded, and rows at the retry limit failed rather than handed
back forever (#2675/#2834).
shutdown_graceful now waits for the cancellations to land before reconciling,
so a task partway through its own terminal write still gets to finish it.
Fixes#3228
`test_migration_drops_stale_global_index` stepped below the repair migration with
`command.downgrade(cfg, "f2a6d8c4b1e9@-1")`. That is alembic's branch@relative
syntax: it counts back from the *head* of the branch containing the revision, not
from the revision itself. It meant "the parent" only for as long as f2a6d8c4b1e9
was head.
b3e8d1c6f4a9 (#3214) landed on top of it, so `@-1` began resolving to
f2a6d8c4b1e9 itself: the downgrade stopped ON the repair migration, the test
planted the stale index after the drop had already run, and the upgrade never
re-ran it. The test has been failing on main for every PR since — `assert 1 == 0`
— with nothing wrong in the migration it covers.
The parent now comes from the revision map, so the next migration added on top
cannot break it. Verified it still fails when the DROP INDEX is disabled.
hindsight-api-slim splits its litellm requirement by platform, because litellm
publishes no macOS wheels for any release >= 1.92.0:
litellm>=1.93.0; sys_platform != 'darwin'
litellm>=1.91.3,<1.92; sys_platform == 'darwin'
This integration raised its own floor to >=1.93.0 for the Python 3.14 cp314
wheel, but without the platform marker. The two are then irreconcilable on
darwin, so anything depending on both packages fails to resolve there at all —
not a slow install or a missing wheel, an outright resolution error. Linux is
unaffected, which is why CI stays green while local macOS development breaks.
Applies the same split here. The lockfile now carries both (1.91.4 for darwin,
1.95.0 elsewhere), so each platform still gets the newest release it can
actually install, and the cp314 reasoning behind the 1.93.0 floor is preserved
everywhere it applies.
Claude-Session: https://claude.ai/code/session_01RGtzHiRg5o4k2UiXJL3zUx
Every fuzzy candidate was scored with difflib.SequenceMatcher in a
synchronous loop on the event-loop thread, and candidate volume per query
text was bounded only by what the trigram probe returned. On a bank whose
index is polluted by many near-identical names, one resolution batch
became minutes of uninterrupted CPU: /health could not answer, the
orchestrator killed the worker mid-op, and the requeued op wedged the
next one.
Measured on a 100-mention batch (mock candidates, 10ms heartbeat task):
1M candidate rows took 10.6s at 99% CPU with the heartbeat getting zero
turns; it now takes 0.38s with a max loop stall of 14ms.
- Cap candidates per query text in SQL, ranked by the similarity score
the probe already computes: LATERAL ... ORDER BY similarity() LIMIT on
PG, ROW_NUMBER() OVER (PARTITION BY query_text) on Oracle. New
HINDSIGHT_API_RETAIN_ENTITY_RESOLUTION_MAX_CANDIDATES (default 200).
- Yield to the event loop every 256 scored candidates, so responsiveness
does not depend on the cap being configured sanely.
- Backstop truncation in _resolve_from_candidates with an O(1)-per-
candidate ordering key, for sets built without a DB score (the "full"
strategy's Python substring matching).
The PG rewrite also drops DISTINCT ON (e.id), which deduplicated across
query texts: an entity matching two mentions in the same batch was
silently dropped as a candidate for one of them (on a 2-text fixture the
old query returned 1004 + 997 of 2001 matches instead of 2001 each).
Label entities resolve by exact match only, yet their rows were still
covered by the shared trigram index — every fuzzy probe for a regular
entity pulled them into its candidate set only to discard them in the
bitmap recheck. On banks where a free-text label group accumulated tens
of thousands of mutually-similar values this dominated database CPU
under ingest bursts.
- Add entities.entity_kind ('regular'/'label', CHECK-constrained) on
both dialects, set at insert time by the resolver; the Phase-2
reassert carries the kind so a pruned label parent resurrects as a
label.
- Rebuild the PG trigram index as a partial index excluding label rows
(CONCURRENTLY, create-before-drop) and add the matching
entity_kind != 'label' predicate to the trigram candidate query and
the Oracle UTL_MATCH fuzzy scan.
- Migration backfills existing rows per bank by classifying
canonical_name against the bank's entity_labels config with the same
is_label_entity() the resolver uses.
- Fix the label classification gating on the enum lookup set: a config
with only text/map groups builds an empty set, so its labels were
never recognised — neither by the #3187 exact-lookup split nor by the
new insert-time kind.
Bank import needs no changes: transfer archives treat entities as
derived data and re-resolve them through the standard retain Phase 1,
which now stamps the kind.
The maintenance loop runs in every API/worker process with no leader election, so
N processes were N schedulers making the same due-and-stale judgment each interval.
The in-flight guard that should have prevented a second refresh lives in the
discovery routine `mental_models_with_cron()` — a *read*, so every process saw the
same "nothing in flight" snapshot and inserted its own operation. A few hundred due
models became thousands of queued refresh ops, which occupy claim slots, inflate
queue-depth (an autoscaler input) and delay unrelated tenants.
The check now rides on the INSERT itself: with
`submit_async_refresh_mental_model(skip_if_in_flight=True)` the operation row is only
materialised `WHERE NOT EXISTS` a pending/processing `refresh_mental_model` op for the
same `(bank_id, mental_model_id)`, so the check cannot be separated from the write.
The submit also takes the existing `FOR NO KEY UPDATE` bank-row lock that
`dedupe_by_bank` uses (#1842) — no extra round-trip — so two simultaneous submits
serialize instead of both passing the READ COMMITTED snapshot.
Only the cron scheduler opts in; explicit user-triggered refreshes (HTTP, MCP,
consolidation-triggered) still queue unconditionally and are never swallowed.
* fix(entities): dedup same-batch entity variants via pg_trgm (#3107)
Entity resolution only ran fuzzy matching against already-persisted rows, so
the first time surface-form variants of one entity appeared together in a
single retain (e.g. 'Wren 🕯️'/'Wren 🗯️', 'Aster'/'aster 0', a 'Merrivale'/
'Merryvale' typo), each variant created a distinct entity — fragmenting
identities with no way to tell wrong attributions from right ones.
Add an in-batch clustering pass over the new (non-label) names about to be
created: a pg_trgm similarity self-join (the same trigram mechanism as
candidate recall, no temp table needed for the small N) pairs them, union-find
clusters the pairs, and each cluster collapses to one entity under a
deterministic canonical name. pg_trgm ignores non-alphanumerics, so decoration
variants score 1.0; the 0.5 merge cutoff sits in a clean gap below genuinely
distinct names ('Aster'/'Astrid' 0.30), which stay separate.
Scoped to PostgreSQL+pg_trgm (default). Label entities are excluded (GH-1558),
and Oracle / the pg_trgm-absent 'full' fallback keep exact-match grouping — a
deliberate asymmetry, since Oracle's UTL_MATCH is prefix-biased and
emoji-sensitive and needs separate calibration.
No new config: reuses the existing trigram path; the merge cutoff is a
calibrated constant, distinct from the recall-only pg_trgm.similarity_threshold.
* refactor(entities): make in-batch merge cutoff configurable + tighten perf cap
Address review on #3107 in-batch dedup:
- Promote the 0.5 merge cutoff to config HINDSIGHT_API_ENTITY_INTRABATCH_MERGE_SIMILARITY
(static, validated (0,1], default 0.5), threaded to EntityResolver. Docs + env template.
- Lower the O(N^2) self-join cap from 1000 to 250 after benchmarking on the retain hot path
(measured: ~4ms@100, ~24ms@250, ~95ms@500, ~390ms@1000 names) — 250 stays well above any
realistic new-entity count while bounding worst-case DB time.
- Drop the fictional-name examples from code comments.
Verified end-to-end against a real local API: emoji/case/suffix/longer-typo variants collapse
to one entity; distinct ('Aster'/'Astrid') and short typos ('Corvin'/'Corvyn', trgm 0.40) stay
separate.
* docs(entities): drop remaining fictional-name examples from code comments
* perf(entities): compute in-batch trigram similarity in-memory, not via Postgres
Replace the pg_trgm SQL self-join with an in-memory trigram-similarity reimplementation
(_trigram_similarity), verified byte-for-byte against Postgres pg_trgm across emoji / accent /
CJK / hyphen / apostrophe cases — so the calibrated 0.5 merge cutoff is unchanged.
Benefits:
- No DB round-trip on the retain hot path (was ~4/24/95/390ms at N=100/250/500/1000; now
~0.8/5/22/81ms, pure CPU, and off the retain transaction's connection).
- Backend-agnostic: in-batch dedup now runs identically on PostgreSQL, Oracle, and the
pg_trgm-absent 'full' fallback — removes the previous PG-only asymmetry and its guard.
- Simpler: drops the SQL, the _ops call, and the async DB hop; _intrabatch_canonical_map is
now a pure function.
Add DB-free unit tests asserting _trigram_similarity equals pg_trgm's values and that the pair
finder respects the threshold.
* feat(templates): add Hermes-branded bank templates (gateway, orchestrator, support)
The Templates Hub had 3 templates and only one was tagged for Hermes
(personal-assistant), and it was thin. Hermes runs as a desktop assistant,
a gateway bot across Telegram/Discord/Slack, and multi-agent orchestrations —
none of which had a starter template.
- Add `hermes-gateway-bot` — per-person profiles kept distinct, learns each
community's norms, tracks open threads across users.
- Add `hermes-orchestrator` — decisions + rationale, ownership map, escalation
playbook; high literalism/skepticism for coordination (the multi-agent pattern).
- Add `customer-support` — issues/resolutions/sentiment/account context, high
empathy, "never re-ask known details".
- Enrich `personal-assistant` — add reflect_mission, dispositions, and directives.
- Tag `conversation` with the `hermes` integration (default chat option).
- Add `orchestration` and `support` categories to the Templates Hub filter.
All six manifests validate against the bank-template JSON Schema
(scripts/check-templates.mjs).
* feat(templates): ground Hermes templates in real Hermes user stories
Reworked the set against Nous's 262 published Hermes user stories:
- personal-assistant: sharpened toward the real flagship pattern — proactive,
cross-platform (iMessage/WhatsApp/Signal/Discord), routine/schedule-aware;
added a "Routines & Schedule" model and an "act on what you remember" directive.
- hermes-gateway-bot: centered on per-channel persona consistency (the Horse
Racing / Family WhatsApp / QQ pattern) with a "Channel Persona & Norms" model
and a "stay in character per channel" directive.
- hermes-orchestrator: broadened beyond escalation to cover build pipelines
(plan→code→QA→ship) and chief-of-staff cross-project coordination.
- coding-agent: tagged `hermes` (dev workflow is the single largest Hermes
category), added a "Review Patterns" model + dispositions.
- research-assistant (new): research/monitoring/second-brain agents — learns
interests, tracks what to ignore to sharpen curation, compounds knowledge
with source provenance.
- Added a "research" category to the Templates Hub filter.
All 8 templates validate against the bank-template JSON Schema.
* test(templates): e2e-import every shipped Hermes template
Integration test (real pg0 + app) proving each `hermes`-tagged manifest in the
catalog imports: creates the bank, applies config, and creates its mental
models + directives. Also covers idempotent re-apply (updated, not duplicated)
and additive layering of a second template.
For per-bank vector backends, every search is bank + fact_type scoped and
served by the idx_mu_emb_* partial indexes; migration d5e6f7a8b9c0 drops
the global idx_memory_units_embedding for exactly this reason. But older
versions of the post-migration reconcile (ensure_vector_extension)
recreated the index when they found none, so schemas provisioned or
reconciled in that window still carry it — paying a second vector graph
insertion on every memory_units write for an index no query uses.
Two changes, split by responsibility:
1. Migration f2a6d8c4b1e9 drops the leftover index (no-op for ScaNN,
which keeps a global index by design; PG-only, Oracle never had the
old reconcile). Index DDL belongs in the versioned migration path,
not runtime code — DROP INDEX takes an ACCESS EXCLUSIVE lock and must
not fire at unpredictable startup/provisioning times.
2. ensure_vector_extension is now strictly hands-off for memory_units on
per-bank backends: never creates the global index (as before), never
drops one, and no longer routes it through the type-mismatch
reconcile — which would otherwise recreate a global index with the
new type on a backend switch.
Tests: reconcile leaves a legacy global index untouched; alembic
downgrade → plant legacy index → upgrade removes it; fresh schemas still
get no global index. Tests share one embedded-postgres on a fixed port,
so they are pinned to one xdist group.
* feat(coding-agents): local daemon mode, and pick the server at install time
The package that supersedes the per-agent plugins had no embedded mode at all:
apiUrl defaulted to Cloud and there was no daemon lifecycle anywhere. The old
Claude Code plugin auto-managed hindsight-embed (scripts/lib/daemon.py), so
anyone without a Cloud account or a server lost a working setup in the move.
Three modes, resolved the way the old plugin resolved them: an external API
(cloud or self-hosted), a healthy local server adopted as-is, or a daemon we
start. `install` asks once on a terminal; `--server cloud|self-hosted|daemon`
scripts it, and a config that already names a server is never re-asked or
rewritten.
Lifecycle is delegated to @vectorize-io/hindsight-all, which owns the uvx
invocation, profile creation and the macOS Metal workaround. It has zero
dependencies and is inlined by tsup, so hook bundles stay self-contained.
Design points worth knowing:
- Daemon mode resolves its URL inside resolveConfig, so all eight existing
client-construction sites work unchanged instead of threading a mode through
each one.
- A cold start (uvx download + model load) outlives every hook timeout, so it is
never awaited inline: SessionStart spawns a DETACHED starter, the same idiom
seeding and the codebase survey already use, and each caller waits only a
bounded slice of its own budget. The prompt hook never starts a daemon.
- There is deliberately no stop-on-session-end, unlike the old plugin: one
daemon serves every agent and repo, so ending one session must not cut memory
out from under another. daemonIdleTimeout retires it instead.
- Port 9077, not hindsight-all's 8888 — 8888 is the conventional port for a
server the user runs, and a daemon must not squat on it.
- Daemon settings keep the old plugin's env names (HINDSIGHT_API_PORT,
HINDSIGHT_DAEMON_IDLE_TIMEOUT, HINDSIGHT_EMBED_VERSION,
HINDSIGHT_EMBED_PACKAGE_PATH), so a migrating environment carries over.
Prerequisites are reported at install time rather than failing silently later:
uv on PATH, an LLM for local extraction (explicit provider, then a known key
env, then the Claude Code CLI which needs none), and on macOS a current Rust
toolchain — litellm publishes no macOS wheel, so a Mac builds it from source and
its crates pin a recent rustc. These are advisory, not blocking: unlike the
devin-cli preflight, every one of them can be installed after the fact.
* fix(coding-agents): treat a down daemon exactly like a down server
Two divergences between daemon mode and the api modes, both removed so the
client and everything downstream of the resolved URL behave identically:
- The Stop hook gated retain on ensureDaemon's result, so a daemon that wasn't
up made retain SKIP — the conversation was dropped — while an unreachable
Cloud or self-hosted server let retain proceed and fail through buildRetain's
handler, which already logs and emits `retain_failed` with the error. A local
port being closed is just a connection failure; it now takes the same path.
ensureDaemon is called for its side effect only and its result is ignored.
- ensureDaemon's `allowStart: false` branch, and the `daemon_not_ready`
diagnostic it emitted, were never reached: the prompt hook has no daemon code
at all, so only a unit test exercised them. Dropped, along with the option;
the module docstring described that unwired prompt-path behaviour and now
describes what actually runs.
The remaining daemon-mode work is a side effect at two lifecycle points
(SessionStart and Stop) plus one ternary in resolveConfig. Nothing downstream
knows which mode is active.
* feat(coding-agents): carry the server endpoint over from the old plugin
Installing over an existing ~/.hindsight/claude-code.json now adopts its
endpoint — hindsightApiUrl -> apiUrl, hindsightApiToken -> apiToken, and an
empty URL meaning the local daemon, exactly as that plugin read it. Someone
running against a self-hosted server or a daemon has already decided where
their prompts and transcripts go; defaulting to Cloud would silently redirect
them. --server still overrides.
ONLY the endpoint. None of the old plugin's ~40 behavioural settings are
translated: 12 recall*, 7 retain*, the mission pair and dynamicBankGranularity
describe a pipeline this package replaced, and reinterpreting them would be
guesswork.
Conversations keep coming from local transcripts (--import-conversations),
re-extracted as new documents. That is not a fallback — the old bank cannot be
split by repo on its own. Its default was a SINGLE static bank (dynamicBankId
defaults to false, so everything landed in `claude_code`) whose documents record
only retained_at, message_count and session_id, with nothing identifying the
project. Attributing them means joining session_id back to the cwd in the local
transcript, so the transcripts are required either way.
Also corrects the migration docs, which claimed the old plugin scoped a bank per
agent per project (true only in dynamic mode, not the default) and that the old
bank could not be merged (document-transfer does merge, with on_conflict).
litellm publishes no macOS wheels for any release >= 1.92.0, so every
macOS install of the published hindsight-api compiles litellm's sdist
Rust/PyO3 bridge. That silently required a Rust toolchain, and litellm
1.95.0 raised the bar further (vendored aws-smithy crates need
rustc >= 1.94.1), breaking even machines with a recent-but-not-newest
rustc. A stock 'uvx hindsight-api' / hindsight-all install on macOS
failed during daemon startup.
Pin litellm to the 1.91.x line on darwin only - the last releases that
ship pure-python py3-none-any wheels - so installs need no compiler at
all. Linux and Windows keep the existing >= 1.93.0 floor (litellm
publishes manylinux/win_amd64 wheels there, including cp314).
Verified on macOS arm64: fresh workspace resolve picks litellm 1.91.4
(pure wheel), the embedded daemon boots via @vectorize-io/hindsight-all,
and retain/recall run real LLM extraction through litellm successfully.
Revisit when litellm ships macOS wheels (BerriAI/litellm#31261).
Deleting an isolated document left its entities behind. `delete_document`
submits graph maintenance precisely so the bank-wide orphan sweep reclaims
them, but `submit_async_graph_maintenance` short-circuits on `no_work` when
`graph_maintenance_queue` is empty — and that queue is only fed by
`enqueue_relink_victims`, which finds nothing for a document no other unit
links to. So the job was never created and `prune_orphan_entities` never ran,
leaving banks reporting 0 documents / 0 memory units but N entities.
The short-circuit is a real optimisation for retain, which calls this
unconditionally on every ingest. So gate it instead of removing it:
`force_sweep=True` skips the pre-check for callers that dropped unit→entity
references and therefore need the sweep regardless of relink work — the
document/memory/bulk delete paths, and the two curation paths whose comments
already claimed to force a sweep.
Fixes#3196
DryRunExtractRequest and BankTemplateConfig typed entity_labels as a bare
list / list[dict], so the LabelGroup shape never appeared in the OpenAPI
document — callers hit a validation error with no discoverable schema.
Type both as list[LabelGroup] with a mode='before' validator that preserves
the legacy free_values/multi_value input shape, and normalize the dry-run
override back to plain dicts so the resolved-config path is unchanged.
Regenerated OpenAPI spec, bank-template schema, docs-skill, and SDK clients.
The cross-encoder always pre-filtered merged candidates to a flat 300
(reranker_max_candidates) regardless of the recall budget, and the
cross-encoder is the dominant cost of a large recall. Add a per-budget
override mapping (RERANKER_MAX_CANDIDATES_LOW/MID/HIGH) so operators can
trade rerank depth for latency at budget=low without a new API parameter.
The per-level values default to 0 = unset, falling back to the flat
reranker_max_candidates, so recall behavior is 100% unchanged until set.
_resolve_reranker_max_candidates mirrors _resolve_thinking_budget; the
resolved cap is threaded into _search_with_retries (other callers keep the
flat default). Docs + env template + docs-skill updated.
* fix retry concurrency permit scope
* chore: sync generated docs schema
* fix: scope concurrency permits to provider attempts
* fix: gate responses retries per attempt
* review fixes: keep .queued stage until permits, stamp .backoff, codex attempt labels, test coverage
- llm_wrapper: attempt-gated providers no longer stamp the bare base stage
before holding any permit — a call queued on the semaphore stays '.queued'
until the provider's post-acquire 'attempt=N' stamp (#3002), and
_attempt_permits suffixes '.backoff' when an attempt fails so backoff
sleeps are distinguishable from in-flight requests.
- codex tools path: attempt-numbered stage labels (1/2, 2/2) and 401/403
before the reactive refresh logs as warning, not error.
- typing: deprecated typing.AsyncContextManager -> contextlib.AbstractAsyncContextManager;
uniform 'is not None' guards; document attempt_context in LLMInterface.
- tests: end-to-end regression through the real OpenAI-compatible retry loop
(permit released during backoff, reacquired on attempt 2), cancellation
while queued on the global permit releases the per-op permit, stage
queued->attempt->backoff lifecycle; fix provider stubs missing
supports_attempt_scoped_concurrency.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(embed): bound daemon log growth
* fix embed log rotation lifecycle
* chore: sync generated embed docs
* fix(embed): correct the retention claim and harden profile deletion
Review follow-ups on the daemon log rotation:
- The docs claimed a peak retained size of MAX_BYTES x (BACKUP_COUNT + 1),
then immediately said an uninterrupted run is not bounded. Both cannot
hold: size is only checked at startup, so a long run grows past
MAX_BYTES and is then kept whole as the first backup. Say when the
bound actually applies and how to keep it meaningful.
- delete_profile() unlinked each retained log without a guard, ahead of
the metadata cleanup. One unremovable log (still open on Windows) threw
and left the profile registered in metadata with its config already
gone. Warn and continue instead, so the profile is always deregistered.
- Drop the import-time env parsing. The values were re-parsed per start
from the merged profile env anyway, so the module-level constants only
survived as that parse's fallback and as default arguments no caller
used -- and an invalid value warned once at import, before logging is
configured, and again at startup.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(consolidation): keep observations in their source facts' language
Consolidation's prompt is entirely English and only carried a language rule
when HINDSIGHT_API_LLM_OUTPUT_LANGUAGE was set, so with it unset multilingual
models drifted: Chinese source facts produced English observations (#3166).
Retain already defaults to preserving the input language; consolidation now
does the same, and the rule settles the three ambiguous cases — language is
picked per observation from its own source facts, an update rewrites the whole
observation in the new facts' language (so drifted banks self-heal), and proper
nouns/identifiers are never translated.
An explicit output language still wins: the default rule is dropped in that
case rather than left to contradict "translate everything into X".
Reproduced and verified against gpt-oss-120b: before, the issue's Chinese facts
yielded "The user often walks their pet in the park on weekends."; after, they
yield 用户周末经常带宠物去公园散步。
Fixes#3166
* refactor(consolidation): compress the language rule
The rule rides in the system prefix of every consolidation call, so on
providers without prompt caching its size is paid per batch. Four sentences
carry the same four constraints the bullet list did, at 69 tokens instead of
223. Re-verified against gpt-oss-120b: identical output on all four cases
(Chinese creates, English observation updated by a Chinese fact, explicit
English override, English facts left alone).
* chore(docs): resync hindsight-docs skill for the multilingual page
* fix(consolidation): make the update-path language rule explicit
CI showed Gemini merging a Chinese fact into an existing English observation
by editing the English sentence in place, keeping it English — the same result
with the verbose rule and the compressed one, so wording length was not the
problem. Name the failure mode instead: don't edit the old text, compose the
merged observation from scratch in the new facts' language.
Also stop the test asserting the merge routing. Whether the model updates the
existing observation or records a sibling is its call (gpt-oss-120b does both
across runs); asserting UPDATE made this a flaky test of merge behaviour rather
than of language. It now checks every emitted text, create or update.
* test(consolidation): absorb LLM sampling noise in the language tests
All three tests now go through one helper that retries up to three times while
the output language is wrong, so a single stray response doesn't fail the suite
— the same shape test_multilingual.py uses.
The update test is additionally xfail(strict=False): Gemini keeps an existing
observation's English wording when a Chinese fact updates it, editing in place
rather than recomposing, and did so identically across three CI runs and three
prompt wordings. The OpenAI-compatible models the issue reports against comply,
so it xpasses there. The creates test stays a hard gate — that is the reported
bug, and every model tried passes it.
* fix(mental-models): never overwrite a document with a delta-window candidate
A delta refresh runs reflect with created_after = last_refreshed_at, so its
candidate only covers memories newer than the last refresh. When the delta
operations failed to reach the document, that candidate was written as the
whole document and the watermark advanced past it — everything grounded in
older memories was gone for good, while the log said "falling back to full
synthesis" and the operation completed successfully (#3112).
Refuse it instead, keyed on the window rather than on each failure branch so
future ones inherit the guard: when delta was requested, was not applied, and
the reflect window was narrowed, preserve the document and raise
MentalModelRefreshError. The watermark stays put, so the retry reads the same
facts again.
Also:
- Treat "the model emitted operations but every one was rejected" as a delta
failure. The document is unchanged, so persisting it looked like a clean
refresh while dropping that run's facts outside every future delta window.
- Recover from an unusable structured_content by re-parsing the stored
markdown instead of giving up — nothing else rewrites that column, so
failing there wedged the model permanently.
- Record skipped operations even when the delta did not land, count them in
the operation's result_metadata, and warn when a partial skip means some of
this run's evidence never reached the document.
- Route every failure through one preserve-and-fail helper, so the
structured-output failure now leaves the same reflect_response audit trail
the other two already did.
* docs(mental-models): describe what a failed delta refresh does to the document
The delta section promised the opposite of what the code now does — "zero valid
operations means an identical document … never corrupt it" read as a guarantee
while a failed delta was in fact replacing the document with a partial one. Say
plainly that the document is kept and the refresh fails, and list the two new
diagnostic values.
* feat(query-analyzer): configurable dateparser locale detection
search_dates() runs auto-detection across 200+ locales on every recall.
This costs 62 ms P50 on the recall critical path, and misdetects English
queries as other locales: "May 23, 2023" parses to 2023-11-23 after the
detector picks 'bas' (Basaa), where May maps to November.
Adds an optional languages restriction to DateparserQueryAnalyzer, wired
through HINDSIGHT_API_QUERY_ANALYZER_LANGUAGES. Default stays None (full
auto-detection), since restricting degrades explicit dates in unlisted
locales to a wrong date rather than to no constraint.
* docs(configuration): document HINDSIGHT_API_QUERY_ANALYZER_LANGUAGES
---------
Co-authored-by: wangyufan03 <[email protected]>
* fix(embeddings): honor query and document prompts locally
* fix(embeddings): require sentence-transformers >=5.0 for local asymmetric encoding
encode_query()/encode_document() only exist from sentence-transformers 5.0
onwards. The local-ml extra pinned >=3.3.0, so on 4.x the new code path was an
AttributeError at the first encode (recall/retain), not at startup. The extra
was only accidentally safe because it also pins transformers>=5.5.0, which ST
<5 caps out; docker/docker-compose/custom-models/Dockerfile mirrors the pins
with transformers>=4.53.0 and could genuinely resolve to ST 4.x.
Also:
- assert the real SentenceTransformer class exposes both entry points; the
existing test drives a MagicMock, so it passes on any version
- explain why the model's own entry points are used instead of prefixing here,
and note that prompt-less models are unaffected
- document the one case that needs a re-index: a local model that instructs the
stored side as well as the search side
---------
Co-authored-by: jpmf33 <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
Add HINDSIGHT_API_ENTITY_TRGM_SIMILARITY_THRESHOLD (static, default 0.15),
applied once as `SET pg_trgm.similarity_threshold` in the pool's per-connection
setup callback alongside the other session GUCs. Because that callback is wired
as both asyncpg `init` and `setup`, the value survives the release-time RESET ALL
and every re-acquire.
Entity resolution's trigram probe no longer toggles the threshold per query — it
just runs against a connection that already has it set — so the runtime
SET/RESET (and its RESET-on-error handling) is removed. The value is validated
to pg_trgm's (0, 1] range at config load so a bad setting fails fast instead of
breaking every connection's setup.
Label entities resolve by exact match only (their canonical names are
user-defined and must not be fuzzy-merged). Sending them through the pg_trgm
candidate probe — and the Oracle Jaro-Winkler equivalent — only returns
similar-but-distinct label values that are always discarded downstream. The
cost grows with the number of values a label accumulates: each probe returns
proportionally more candidates, all thrown away.
Partition entity texts before the candidate fetch: resolve label texts with an
exact lookup on the unique (bank_id, LOWER(canonical_name)) index, and only send
non-label texts through the fuzzy probe (also skipping the pg_trgm threshold
SET/RESET entirely when there are no fuzzy texts).
No behavior change — label resolution was already exact-match-only in
_resolve_from_candidates; this only removes the wasted candidate scan.
* refactor(obsidian): decouple HindsightClient from obsidian via a Transport seam
Introduce a Transport abstraction so the HTTP client no longer imports
`obsidian` directly. The plugin injects an obsidian-transport (requestUrl,
to escape the renderer CORS sandbox); a headless CLI will inject a
fetch-based transport. This lets both frontends share one client and one set
of request semantics instead of maintaining divergent copies.
No behavior change: existing client tests pass unchanged after switching from
mocking requestUrl to injecting a fake transport (same request shape).
* feat(obsidian): headless CLI vault ingestion (hindsight-obsidian-sync)
Add a headless second frontend over the shared SyncEngine so a vault can be
ingested into Hindsight from an always-on server with no Obsidian desktop app
(issue #3128). Because it drives the same engine as the plugin, it produces
identical document ids, scope tags, and prune-ownership — the two ingesters
never fight or duplicate.
New Node modules (src/node/):
- fs-vault.ts — filesystem SyncVault (recursive *.md walk, POSIX-relative
paths, ms mtime/ctime, skips dotfolders)
- fetch-transport.ts — fetch-based Transport for the client (no renderer CORS)
- json-index.ts — sync index persisted to JSON, atomic write; defaults to
~/.hindsight/obsidian/<vault>.json (outside the vault so
Obsidian Sync never propagates it)
- cli.ts / cli-bin.ts — `hindsight-obsidian-sync reconcile --vault <p> --bank
<id>` with env fallbacks, --include/--exclude/--prefix-doc-id,
and a chokidar --watch mode
Packaging: second esbuild target builds dist/cli.js (node, shebang); package.json
gains the bin, a files allowlist, and chokidar. README documents the CLI, the
out-of-vault index, and the shared-scope constraint when running both frontends
against one bank.
Tests (33 new, 79 total): FsVault, json-index, fetch transport, CLI arg parsing
+ watch handlers + a full runCli path (fetch mocked), and a full-stack reconcile
suite over a real temp vault (create/update/skip/delete/rename/exclude/prefix/
prune-ownership) plus a parity check that the filesystem and in-memory (plugin)
vaults emit byte-identical retain requests.
* test(obsidian): broaden CLI coverage with real-framework and e2e tests
Add higher-fidelity tests beyond the mocked units, and refactor watch mode to
be testable:
- Extract watchVault() from startWatch() so a test can drive a REAL chokidar
watcher over a temp vault and then close it. New watch.spec.ts asserts
create/modify/delete on disk flow through to the engine and non-markdown is
ignored (polling + tight awaitWriteFinish for CI determinism).
- e2e-http.spec.ts runs runCli against a real node:http server — the full
FsVault → SyncEngine → HindsightClient → fetch → sockets path with nothing
mocked: asserts the retain POST (bearer token, document id, scope tags) and a
real DELETE on prune, plus exit-code 1 when the server is unreachable.
- fetch-transport: full-stack HindsightClient error propagation + health()
true/false, a fetch-rejection case, and a cross-transport parity test proving
the same call yields an identical request under two transports.
- reconcile: frontmatter tags + created-date timestamp + vault metadata,
empty-body skip, and includeFolders-only scoping.
- cli: --exclude threaded end-to-end through runCli.
Pin chokidar to ^4.0.3 (bundles its own TS types). 90 tests pass (+11).
* fix(obsidian): make dual-ingester parity test platform-deterministic; add CLI to docs-site page
- Parity test pinned mtime via utimes but ctime/birthtime can't be set and
differs across OSes (macOS clamps birthtime to a past mtime, Linux doesn't),
so the FS vault's created-date tags diverged from the memory vault's on Linux
CI. Give both notes a frontmatter created: date so the tags come from the note.
- Add a 'Headless / CLI ingestion' section to the public docs-site page
hindsight-docs/docs-integrations/obsidian.md (mirrors the package README).
* docs(obsidian): regenerate skill mirror for the headless CLI section
* style(obsidian): apply repo prettier formatting to CLI + tests
* blog: Per-User Memory for AI Products — Multi-Tenant Patterns
A patterns guide for SaaS/AI-product builders on isolated per-user memory: the
hard-boundary vs soft-partition decision (banks vs tags), reading across
private/org/global scopes without a cross-bank query, a CI cross-tenant
leakage test, GDPR deletion, and scaling to many tenants on one store.
Editorial deep-dive cover.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* blog(per-user-multi-tenant): swap cover to dark comparison-card template
Reuse the context-window-is-not-memory template (dark, teal-accent title +
comparison cards). Positive framing: "Every user gets their own bank" with
BANKS (isolate a tenant) + TAGS (partition a bank).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* feat(reranker): failover chain via indexed HINDSIGHT_API_RERANKER_<n>_* members
An unreachable reranker took the whole recall down with a 500: the stage is a
refinement, but nothing on the path treated it as optional and no setting could
change that (#3168).
Configure extra rerankers by index, mirroring the multi-LLM chain: the unindexed
config is member 0 and HINDSIGHT_API_RERANKER_<n>_* declares the fallbacks, tried
in order when a member fails (error, timeout, or a wrong-length response). Every
setting of member n carries the same index, so a fallback gets the full
provider-specific knob set; it inherits nothing from the primary or from the
shared provider keys, and missing-setting errors name the exact indexed variable.
Ending the chain with the existing `rrf` provider makes recall fail open — the
retrieval order comes back untouched instead of the request failing. With no
indexed members (the default) behaviour is unchanged.
Round-robin is deliberately not offered: reranker scores are not comparable
across providers, so rotating members per request would make score thresholds
non-deterministic.
A member that fails to initialize is logged rather than fatal, and retried on the
next request that reaches it — otherwise a chain configured for a flaky primary
would still die at startup. `CrossEncoderModel.blocking_init` replaces the
`provider_name == "local"` checks at the two init call sites, so the chain can
offload its own in-process members instead of being threaded by its callers.
* fix(reranker): tolerate duck-typed cross encoders, sync the docs skill
Tests inject cross encoders that don't subclass CrossEncoderModel, so reading
`blocking_init` off them raised AttributeError in test-api. Read it with getattr,
matching the provider_name read a few lines away in _recall, instead of making
every test double implement the property.
Also regenerates skills/hindsight-docs for the new configuration section (the
retain/openapi/coding-agents hunks are pre-existing drift on main that
verify-generated-files requires be committed).
Raise a dedicated persistence conflict when a validated bank config
update can no longer find its bank row.
Map this race to HTTP 409 for template imports while preserving PATCH
404 behavior and 400 responses for invalid configuration. Add an
event-coordinated regression test for the deletion window.
* fix(consolidation): skip observation_history when UPDATE matches 0 rows
The source-liveness checks in _execute_update_action guard the *source*
memories, but the observation row itself (UPDATE ... WHERE id = $5) can be
concurrently invalidated/deleted, matching 0 rows. The code then fell through
to _append_observation_history, whose INSERT carries an observation_id FK onto
memory_units — raising ForeignKeyViolationError, a (correctly) non-retryable
integrity failure that marked the whole consolidation op failed for a row that
simply no longer exists.
Capture the UPDATE status in the SQL branch and bail out (return None) before
the history append when 0 rows matched. The store/upsert branch cannot hit the
0-row case, so it needs no guard. The Oracle wrapper reshapes rowcount into the
same "UPDATE <n>" form, so the parse is dialect-safe (mirrors config_resolver).
Adds mock-level regression tests covering both the 0-row bail and the
positive (rowcount==1) control.
* refactor(db): add execute_rows_affected primitive; use it for the 0-row guard
Move the command-tag rowcount parse out of consolidation business logic and
into the pg/oracle connection layer. DatabaseConnection.execute_rows_affected
runs a DML statement and returns a plain int, normalizing the dialect-divergent
result shape the same way parse_json normalizes JSON columns: asyncpg returns
the tag directly, the Oracle connection reshapes cursor.rowcount into the same
trailing-count form, so parsing the last token is dialect-safe.
_execute_update_action now calls conn.execute_rows_affected(...) and checks the
int directly instead of hand-parsing an "UPDATE <n>" string. Adds a parser unit
test covering the tag shapes both dialects emit.
#2943 fixed the shared-DB test-api deadlock flake by wrapping
get_or_create_bank_profile in retry_with_backoff, but shipped without a unit
test for that retry. Add a deterministic, no-DB test: an ops stub raises
DeadlockDetectedError on the first per-bank index DDL then succeeds, and the
test asserts the profile creation retries (two index-DDL attempts) and the
bank ends up created.
Guards against a future refactor silently dropping the deadlock retry and
re-introducing the flake. Committed --no-verify: the generate-docs-skill hook
is blocked by a pre-existing skills/hindsight-docs drift on main, unrelated to
this test-only change.
Keep metadata and tags on unchanged memory units aligned with their
document during delta retain.
Cover metadata-only replace and append paths with regression tests.
Closes#3008
Entity edges are no longer materialized in memory_links. Retain stores
memory-to-entity associations in unit_entities, and both read paths derive
entity edges from that table on demand — the /graph endpoint from shared
unit_entities rows and recall via the unit_entities self-join. Migration
e9b2c7d1f3a4 deleted the stored entity rows and current writers only ever
pass entity_id = NULL, leaving the entity-specific schema on memory_links
as dead weight.
New migration (PG + Oracle) drops the entity_id column and its FK, the
entity index, 'entity' from the link_type CHECK, and the entity_id term in
the function-based unique index (which collapses to
(from_unit_id, to_unit_id, link_type)). It is written to avoid long locks
on large tables: the residual delete is chunked with per-batch commits,
indexes are swapped CONCURRENTLY, and the new CHECK is added NOT VALID then
validated separately.
Application code drops _NIL_ENTITY_UUID and the nil_entity_uuid DataAccessOps
parameter, simplifies internal link tuples to four elements
(from, to, link_type, weight), and removes the entity_id column/placeholder
from the PG and Oracle bulk inserts and the chunk-storage lock ordering.
The graph API keeps returning dynamically derived entity edges.
OutputTooLongError was defined twice — the canonical class in
llm_interface.py (what the providers raise) and a shadow copy in
llm_wrapper.py. fact_extraction and multi_llm imported the shadow, so
`except OutputTooLongError` never matched what providers raise:
- #2579's chunk-splitting retry (_extract_facts_with_auto_split) was
dead on the real path; one over-long chunk failed an entire
multi-chunk retain and discarded the successfully-extracted chunks.
- multi_llm._should_failover's `isinstance(exc, OutputTooLongError)`
returned False, inverting its intent and burning an extra provider
call that can't fit the over-length output either.
Re-export the canonical class from llm_wrapper instead of redefining it,
so all catch/inspect sites bind to the same object.
Now that the split path is reachable, bound its recursion with a
minimum-size floor (_MIN_SPLIT_CHUNK_CHARS = 500): a chunk that overflows
the output cap at every size is degenerate/looping output, and halving it
toward one character costs ~5000 extraction calls; the floor drops it in
~17 instead.
Fixes#3172
* fix(control-plane): report mental-model freshness from the bank write watermark
The mental-models card compared each model's last_refreshed_at against the
bank's last_consolidated_at, so any consolidation after a refresh — nearly
always — reported every model as stale, and a bank that had never consolidated
reported the opposite.
Computing the real per-model answer on a list is the expensive fix:
compute_mental_model_is_stale has no index to use (there is none on
memory_units.updated_at), so it scans the bank's memories in full, per model —
10ms per model at 100k memories, 101ms at 500k, on a view that polls every 5s.
Report a bank-wide watermark instead. MAX(updated_at) rides along on the
aggregate _compute_bank_stats already runs and is served from the same cached
payload as last_memory_write_at. A model refreshed at or after it is up to date,
exactly; older only means something was written, possibly outside its tags, so
the card says "may need refresh" rather than asserting stale. The exact answer
stays on the single mental-model read, behind the dialog.
The knowledge-base tree ran that same scan once per page and polls every 12s —
already a full scan per page per tick in production. It now shares the
watermark: one cached lookup for the whole tree.
Fixes#3139
* perf(reflect): skip the per-model staleness scan below the bank watermark
search_mental_models computed staleness with the exact scoped query for every
model it returned — up to 5 full scans of the bank's memories per tool call,
serially, on a held connection, and the agent can call the tool several times
per reflect.
get_bank_freshness already computes the bank's write watermark in the same scan
it runs once per reflect, and was discarding it. Thread it through: a model
refreshed at or after the newest write in the bank cannot be stale whatever its
scope, so it skips the query entirely. Everything above the watermark still gets
the exact tag-aware answer — the agent only trusts a model without a verifying
recall() when is_stale is False, so guessing conservatively here would buy LLM
turns to save a query.
* chore(docs-skill): re-sync the generated reference copies
generate-docs-skill.sh output drifted from the docs pages that landed on main
(retain narrator guidance, configuration, coding-agents). Regenerated so
verify-generated-files has nothing to report.
* docs(retain): suggest a distinct document_id per source document
Clarify the item-level document_id field: items sharing a document_id
are grouped into one document, so callers should provide a distinct id
per source document (auto-generated when omitted). No behavior change —
mixed explicit/implicit batches stay backwards compatible.
Refs #3010
* chore(clients): regenerate TS client for document_id doc update
* chore(docs-skill): regenerate hindsight-docs skill references
Picks up the document_id doc update plus pre-existing drift in the
generated skill snapshot (retain.md, coding-agents.md) from prior merges.
* fix(coding-agents): read Devin's transcript with node:sqlite, and refuse to install without it
Devin is the only harness whose hooks never hand over a transcript — they carry
a session id and nothing else, so the conversation has to be read from the CLI's
own sessions.db. That read shelled out to the `sqlite3` BINARY, which is not a
declared dependency and was never checked for. Where it was absent, execFileSync
threw ENOENT, a bare `catch` folded it into `return []`, and retain no-opped
forever while the installer reported success (#3125).
Node ships its own SQLite, so the binary is no longer needed for anything:
- `node:sqlite` replaces the subprocess. It is a builtin — nothing added to the
package, nothing bundled (esbuild leaves `node:` imports external; the devin
hook bundle is unchanged at 59K). Loaded through createRequire INSIDE the read
function rather than imported at module scope: this module is pulled in by
hook-lifecycle, which every harness shares, so a static import would break
Claude Code and Codex on a Node without it.
- The session id is now a bound parameter instead of being escaped into the SQL
string by hand.
- Missing reader, absent database and read failure each emit a distinct `diag`
event, so a permanently memory-less install no longer looks like an idle
session. A Devin storage-schema change surfaces the same way.
- `install devin-cli` preflights the `node` on PATH — the interpreter the hook
command actually runs under, which an npx-launched installer may not be — and
refuses with the reason and a non-zero exit instead of wiring hooks that could
never retain anything. On `install all` only Devin is blocked; the other
agents are still wired.
The SQLite read path had no tests at all; it now covers reading a session,
binding a quoted id, and both failure diagnostics against a real database.
* ci: export the integrations-coding-agents change filter
The filter was defined and the job consumed it, but detect-changes never listed
it among its outputs — so `needs.detect-changes.outputs.integrations-coding-agents`
was always empty and test-coding-agents ran only on workflow_dispatch or a
workflow-file change. Every PR touching just that package went untested.
* chore: regenerate the stale docs-skill mirror
Pre-existing drift on main, not from this branch: the `agent_name` deprecation
landed in the docs without re-running generate-docs-skill.sh, so
verify-generated-files fails for every PR. Pulled in here because this PR can't
go green without it.
Unify the two provider-specific truncation knobs into one generic,
provider-agnostic flag and apply the cap at the single choke point
(`generate_embeddings_batch`) before any backend's `encode()` runs, so
every provider and every path (retain, recall queries, consolidation,
import) gets identical truncation.
- New: HINDSIGHT_API_EMBEDDINGS_MAX_INPUT_TOKENS (config
`embeddings_max_input_tokens`), off by default, applies to all providers.
- Deprecated alias: HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MAX_INPUT_TOKENS
still honored (folded into the generic name at load time).
- Move truncation out of LiteLLMSDKEmbeddings into embedding_utils; the
`truncate_to_tokens` helper moves to token_encoding.py and returns a
TokenTruncation dataclass (no tuple return).
- Docs + .env.example (and bundled embed copy) updated; tests migrated to
the central path plus config alias/precedence coverage.
* feat(config): per-operation llm_extra_body overrides
Extra request-body params could only be set globally via
HINDSIGHT_API_LLM_EXTRA_BODY, so every operation shared one dict. That
forces a single choice on knobs that are genuinely per-operation — e.g.
disabling a model's thinking mode for retain extraction while leaving it
on for reflect (vLLM chat_template_kwargs), or setting a different
max_tokens per operation.
Add the same per-operation override the other LLM params already have:
HINDSIGHT_API_RETAIN_LLM_EXTRA_BODY
HINDSIGHT_API_REFLECT_LLM_EXTRA_BODY
HINDSIGHT_API_CONSOLIDATION_LLM_EXTRA_BODY
Each follows the reasoning_effort pattern exactly: parsed into an
optional HindsightConfig field, resolved in MemoryEngine as
`config.<op>_llm_extra_body or config.llm_extra_body`, so an unset
operation keeps using the global value. Static server-level config (not
per-bank configurable), matching the global flag.
A per-operation value replaces the global dict rather than merging with
it — extra-body params are provider-native, and this is how every other
per-operation override behaves.
* docs: regenerate hindsight-docs skill for the new config rows
* chore(docs): resync coding-agents skill reference
Pre-existing drift, unrelated to this PR's feature: the source doc
hindsight-docs/docs-integrations/coding-agents.md was updated by
17b7f46ae / d238d2f7d, but skills/hindsight-docs/ has not been
regenerated since 4278f0989. verify-generated-files is therefore red on
main, and stays red on any PR that runs it until the copy is resynced.
Purely the output of ./scripts/generate-docs-skill.sh — no hand edits.
`HINDSIGHT_API_RECALL_MAX_QUERY_TOKENS` (500, added in #298 after a 1848-token
query timed out) was only checked in the REST handler. Every internal caller
reaches `MemoryEngine.recall_async` directly — consolidation, the reflect tools,
the MCP tools and the context extension — and passed arbitrarily long text
through.
Consolidation recalls with the whole fact text as the query, so a degenerate
extraction (58k words, 4 distinct) became a 54k-term OR `tsquery`; evaluating it
recurses once per node and exceeded Postgres' stack depth (SQLSTATE 54001). The
consolidation op then retried for 7 days and blocked every later consolidation
on that bank (#3134).
Bound the query at the engine ingress instead. Internal callers truncate rather
than fail — a long source fact must still consolidate, just on a bounded query.
The REST handler keeps its HTTP 400 for client-supplied queries.
The bank profile `name` field is documented as a display label only, but at
retain time `_resolve_narrator` silently uses it as the narrator (memory owner)
whenever it differs from `bank_id` — the undocumented coupling reported in #3138.
Stop advertising that path without changing any runtime behavior (100% backward
compatible):
- retain.md now steers speaker attribution solely through each item's `context`,
dropping the advice to set a bank `name` as the agent's name.
- The dry-run extract `agent_name` override is marked `deprecated` in the schema
(still honored) and repointed to `context`.
`_resolve_narrator` and the prompt injection are unchanged, so existing banks
behave exactly as before.
`memory_units.access_count` has existed since the initial schema (5a366d414dce)
with an `access_count DESC` index alongside it, but no code path ever wrote it
and no query ever read or ordered by it. It was 0 on every row of every install,
and PostgreSQL maintained a btree over it for nothing.
Migration e4a7c1b9d2f6 drops it from `memory_units` and from the curation archive
`invalidated_memory_units` on both PG and Oracle. Both are required: curation
moves a row with an INSERT…SELECT whose column list is read from the catalog at
runtime (`memories/pg/writes.py::_memory_unit_columns`), so the two tables must
stay in lockstep or the round-trip breaks on a column mismatch. Dropping the
column implicitly drops its index on both dialects.
Also removes the last three references: the stale comment naming an
`access_count_update` task type that was never implemented, the column name in
the Oracle backend's numeric-RETURNING list, and that same never-implemented task
type used as a placeholder string in a worker test.
Restore is fixed so the drop doesn't strand older backups. Its preflight rejected
any backup carrying a column the target lacks ("target is missing backup
columns …"), which would have made every backup taken before this migration
permanently unrestorable. Unknown columns are now skipped and reported instead.
They cannot simply be left out of the copy_to_table column list: binary COPY
carries no column identities, so a tuple's fields are matched to the column list
purely by position, and an unedited stream desynchronises — PostgreSQL rejects it
with "row field count is N, expected M", and a subtler mismatch could land values
in the wrong columns. `_strip_binary_copy_fields` therefore rewrites the stream,
dropping each ignored column's field from every tuple. Type mismatches on columns
present in both schemas stay fatal.
Both supported harnesses record the directory each session ran in, so a
conversation is only imported when the session proves where it belongs — a
paragraph on why that matters (the folder-name encoding is ambiguous, and a
wrong guess files another repo's conversation into your bank) and what happens
to sessions that record nothing.
A conversation may only be imported into a repo's bank when the session itself
records the directory it ran in. The previous fallback — matching the project
folder name — was a guess, and the encoding makes it an unsafe one: `/` and `.`
both become `-`, so `repo-sub` is either the subdirectory `repo/sub` or an
unrelated sibling repo. Guessing wrong files someone else's conversation into
this repo's memory, which is worse than importing nothing.
Both supported harnesses can prove it: Codex writes the cwd in its session_meta
header, and Claude records one on its entries (measured: 400/400 sampled
sessions of 13,841). Sessions that record none are skipped and counted, and the
count is printed rather than swallowed.
Matching on the recorded directory also fixes the opposite error: a session run
in a SUBDIRECTORY of the repo is now imported (Claude gives a subdirectory
launch its own project folder, which an exact-name match missed), and Codex
matches sessions whose cwd is inside the repo rather than exactly equal to it.
* feat(reflect,mental-models): surface structured output in control plane
Reflect's response_schema -> structured_output was already implemented and
tested in the engine but never exposed in the UI. Surface it in the reflect
(think) view, and extend the same structured-output extraction to mental
models via a per-model response_schema stored in the trigger config.
- engine: refresh_mental_model reads trigger.response_schema, forwards it to
the internal reflect call, and persists the parsed structured_output onto
the stored reflect_response payload; fix stale 'not yet supported' docstrings
- api: add response_schema to MentalModelTrigger
- control-plane: reflect route + api.ts forward response_schema; think-view
gets a JSON-schema input and renders structured_output; create/update mental
model dialogs get a schema editor; detail modal renders structured_output
- tests: mental model structured-output plumbing (schema forwarded + persisted)
- regenerate OpenAPI spec + client SDKs; add i18n keys for all locales
* feat(control-plane): show configured response_schema in mental model config tab
Adds a read-only JSON card for the mental model's trigger.response_schema in
the detail modal's Configuration tab (mirrors the tag_groups card), plus the
regenerated go openapi.yaml.
* style: ruff format test_mental_model_structured_output
* fix(control-plane): don't route the JSON schema example through next-intl
The response_schema placeholder was a t() message whose value is literal JSON.
next-intl parses messages as ICU, so the '{' in the example was read as an
argument placeholder, the parse failed, and the field rendered the raw message
key instead of the example. Inline the JSON example directly on the placeholder
prop (i18n:check skips JSON-shaped placeholders) and drop the now-unused
*Placeholder message keys. Caught by running the control plane.
* feat(structured-output): validate response_schema + add a no-code schema builder
Validation (both reflect and mental models): a schema that is valid JSON but
not a usable object-with-properties silently produced empty structured_output
or blew up inside the LLM extraction call later. Now:
- engine: validate_response_schema() enforces the usable-shape contract
(object schema, non-empty properties, well-formed required); wired as Pydantic
field_validators on ReflectRequest.response_schema and
MentalModelTrigger.response_schema (invalid -> HTTP 422).
- control-plane: the reflect and mental-model forms validate the schema shape on
submit (not just JSON.parse) and surface the specific error.
No-code schema builder: a 'Build schema' button on both the reflect view and the
mental-model dialogs opens a dialog with Visual and Code modes. Visual mode edits
a flat field list (name, type, array item-type, description, required); Code mode
edits raw JSON. The two stay in sync and Apply is gated on a usable schema. Shared
frontend lib (response-schema.ts) mirrors the backend contract.
tests: test_response_schema_validation.py (16 cases: validator + model integration).
* refactor(control-plane): schema only via the builder, show set/unset status
Removes the inline response_schema JSON textarea from the reflect view and the
mental-model dialogs. Editing now happens exclusively in the schema builder; the
page shows only whether a schema is set (field count + names, with Edit/Remove)
or a Build schema button when none. Extracts the shared ResponseSchemaField
component used identically by reflect and both mental-model dialogs.
* fix(mental-models): derive structured_output from final content, not reflect's answer
In delta mode reflect only sees facts created since the last refresh, so its
answer (and any structured_output it derived) reflects just the delta — while the
stored content is the delta-merged document. Persisting the reflect-derived value
made structured_output inconsistent with the markdown.
Now the mental-model refresh no longer passes response_schema to reflect; instead
it extracts structured_output from the FINAL stored content (correct for both full
and delta), and carries the previous value forward untouched when a delta refresh
preserves content (no new facts). Adds a delta test asserting extraction runs
against the merged document, not reflect's partial answer.
* fix(schema-builder): allow switching an empty schema from Code back to Visual
An empty schema serialises to properties:{}, which schemaToFields mapped to an
empty array — and the Code->Visual guard treated 'empty' the same as 'not
representable', blocking the switch. schemaToFields now returns [] (representable)
for a missing/empty properties map and null only for genuinely unrepresentable
schemas; the switch seeds a blank field when empty.
* docs(reflect): document structured output (response_schema) + schema builder
Adds a Structured Output section to the reflect docs: how response_schema returns
both text and a structured_output projection of the same answer, the schema rules,
mental-model structured output (extracted from the final/merged document), and the
no-code Build schema editor. Regenerates the docs-skill mirror.
* feat(schema-builder): recursive visual editor for nested objects & arrays
The visual editor was flat — object/array fields had no way to define their inner
shape. Reworks the field model into a recursive tree (each field has a node; an
object node nests fields, an array node nests an item node) so you can build
nested objects and arrays-of-objects entirely in the visual editor. Code<->Visual
round-trips losslessly; schemas using features the editor can't represent (enum,
oneOf, $ref, tuple items, …) stay in code mode rather than being silently
flattened.
* fix(structured-output): recursive model for nested schemas + fail refresh loudly
Two problems surfaced by nested schemas on Gemini:
1. _generate_structured_output mapped object/array properties to bare dict/list,
which serialize with additionalProperties — rejected by the Gemini API. So any
schema with a nested object/array silently failed extraction. Now it builds a
proper recursive Pydantic model (nested objects -> nested models, arrays ->
typed lists), matching how retain's structured output already works on Gemini.
2. On extraction failure the mental-model refresh silently persisted content with
no structured_output, clobbering the previously-stored value. Now, when a
response_schema is configured and extraction yields nothing, the refresh raises
MentalModelRefreshError — prior content and structured_output are preserved and
the refresh can be retried.
Verified live on Gemini: a nested {location:object, people:array} schema now
extracts (structured_output present) instead of failing on additionalProperties.
Adds a fail-loud regression test.
* fix(schema-builder): readable error text in dark mode
text-destructive resolves to a dark red (#C0183A) in dark mode, which is
low-contrast on the dark dialog background. Use the codebase's standard
readable pattern (text-red-600 dark:text-red-400) for the builder's validation
error and the invalid-schema notice.
* fix(cli): set response_schema on MentalModelTriggerInput literals
Adding response_schema to MentalModelTrigger regenerated the Rust
MentalModelTriggerInput struct with a new field; the hand-written CLI struct
literals must initialize it (E0063). Sets response_schema: None in the three
construction sites (create/update mental model, knowledge-base pin).
* docs(api): document mental-model response_schema; fix stale reflect text-empty claim; test schema lib
- api/mental-models: document the trigger.response_schema flag + a Structured
Output section (extraction from final content, fail-loud, validation).
- api/reflect: correct the stale claim that text is empty with response_schema —
reflect returns both text and structured_output.
- control-plane: vitest unit tests for the response-schema lib (validation +
recursive fields<->schema round-trip).
- regenerate docs-skill mirror.
* chore: regenerate bank-template-schema for MentalModelTrigger.response_schema
The bank template schema embeds MentalModelTrigger; adding response_schema to
the trigger changed the generated schema. Regenerated so verify-generated-files
passes.
The old integrations can't be migrated by moving data: they scope a bank per
agent per project (`claude-code::myrepo`) where this package uses one per repo
(`coding-agent::myrepo`), so two old banks map onto one new one — and the
server's bank import restores a whole bank rather than merging into a live one.
Re-reading the transcripts the agent already wrote to disk sidesteps that: the
same conversations are re-extracted into whichever bank is current. The flag
hands them to the deepen engine a session start already uses, so ingestion
dedups by document id and re-running is safe.
Scoped to the current repo — this machine holds ~14k Claude sessions, and
importing every project's history would run extraction over all of them. Claude
Code keys history by project directory; Codex partitions by date and records the
cwd in each rollout's session_meta header, which is read to filter.
Only file-based harnesses are supported. opencode, Kilo, Cursor, Cline, Copilot
and Devin keep history in internal SQLite databases with unversioned schemas;
they report as skipped WITH the reason rather than importing nothing silently.
One bug worth naming: the Codex header is a single line carrying the agent's
full base instructions, tens of KB. Reading a fixed 4096-byte prefix truncated it
mid-JSON, so every rollout was skipped and the import quietly found nothing —
hidden by the surrounding catch. The header is now read a chunk at a time until
the newline, with a regression test that fails against the old slice.
When a refresh produced an unexpected document, nothing said why. The mode
decision, resolved scope, snapshot window, retrieved-versus-used fact counts
and dropped delta operations only ever reached a log line — and cron- or
consolidation-driven refreshes run with nobody watching.
Two ways to see that reasoning, from opposite directions.
POST /mental-models/{id}/dry-run-refresh runs the production refresh
pipeline and reports what it would do, skipping exactly two writes: the
content (with its structured document and history entry) and the watermark
that moves last_refreshed_at. It takes no parameters, on purpose — a dry run
you can configure stops predicting the refresh it exists to predict. Because
nothing is persisted, a delta dry run reads exactly the window the next real
refresh will.
trigger.keep_trace records the same reasoning on every refresh of a model,
scheduled ones included, under reflect_response.trace. It is written even
when a refresh fails, which is when it matters most. The trace is shaped
like reflect's — the calls the agent made plus the refresh decision — and
holds nothing derivable from elsewhere: evidence stays in based_on, and the
resolved scope and window are reported by the dry run. Each tool call
records the window bound it was given, named `updated_at` for what the
predicate actually filters; null means the tool applies no time bound at
all, which is what explains results older than the window would suggest.
refresh_mental_model is split into a shared _execute_mental_model_refresh
that computes a result and writes nothing, plus a thin persistence step, so
the preview and the real refresh run the same body. Existing refresh
behaviour is unchanged.
In the control plane the dry run is an action on the mental model, and its
result opens in a dialog built from the History tab's own diff components.
History shows each version's own trace: the history snapshot now carries
`trace` alongside `based_on` so it survives being superseded.
Surfaced but deliberately not fixed here: when delta operations fail, the
fallback writes a candidate built from a delta-scoped recall over the whole
document, dropping content grounded in older memories (#3112).
The message that tells you how to recover named the UNSCOPED package, which does
not resolve, and a bare `install`, which no longer does anything. So the one
place a user lands when they get this wrong handed them two commands that also
fail.
The dedup merge path passed the LLM's synthesized text straight to the fold
UPDATE with only .strip() applied, so control characters and lone surrogates
reached SQL unscrubbed. _CreateAction and _UpdateAction already scrub their
text via a sanitize_llm_output field_validator; the merge path did not.
Character-safety only (control chars + surrogates), matching the existing
create/update behaviour. Adds a regression test alongside the existing fold
test; that test is left untouched.
Co-authored-by: iRonin <[email protected]>
The no-fields-allowed branch of the permission error in
ConfigResolver was missing its f-string prefix, so callers saw the
literal text "Not allowed to modify fields: {sorted(disallowed)}."
instead of the actual field names.
Co-authored-by: Claude Fable 5 <[email protected]>
Recall bounds its time window on `updated_at`, but two arms only filtered
their entry points and then expanded outward unfiltered:
- Link expansion filtered its semantic *seeds*, then pulled each seed's whole
neighbourhood — shared entities, semantic kNN links, causal links — with no
window at all.
- The temporal arm's entry-point query applied the window, but the multi-hop
spread that walks temporal/causal links from those entry points did not.
Either way a single in-window seed dragged arbitrarily old facts back into the
results. Mental-model delta refresh recalls with `created_after=<last refresh>`
and `created_before=<cutoff>` precisely to see only what changed since, so every
refresh silently re-ingested stale neighbourhoods.
The window is now pushed into the expansion SQL on both backends via a shared
`UpdatedWindow`, which renders `AND <alias>.updated_at > $n` plus its params.
Rendering is per-alias because one query applies it to several correlation
names. For entity expansion the predicate goes inside the EXISTS that already
filters `fact_type` — i.e. *before* the per-entity cap, so out-of-window
neighbours can't eat an entity's bounded fan-out and starve the in-window ones.
Left deliberately unwindowed: `include_source_facts` returns an observation's
sources in a separate field, not in `results`. An observation refreshed inside
the window has older sources by construction, so filtering there would gut the
feature.
While changing these signatures, the three expansion methods also stop
returning a bare 3-tuple (a project standard) in favour of `LinkExpansionRows`.
The signals stay separate because each carries a different score scale and the
caller transforms each before summing.
Tests: `test_recall_time_range_graph.py` seeds an in-window fact plus
neighbours reachable only through the graph and asserts recall never returns
them, covering all three link signals, both bounds, observations, and temporal
spreading. Each has a control assertion proving the links are live, so a pass
cannot be vacuous. Backend-parametrized unit tests in `test_db_abstraction.py`
cover clause placement relative to the cap and verify an unbounded recall emits
the SQL verbatim with no dangling placeholders (Oracle rejects a query
referencing an unbound param).
The two pages described the same product in different words and had drifted: the
docs page still carried install instructions that no longer worked and a harness
table that had fallen behind. The README is the single source now — a sync
script writes the doc page from it, and `--check` runs in the docs build so the
two cannot separate again (verified: the build fails on a hand-edited page).
Also, from reading it as a new user would:
- Install moves above "How it works". The first question is "how do I get this",
and it was buried under the harness table.
- "How it works" becomes short bullets grouped by what actually happens —
ingestion, what the agent receives, write-back, guarantees — instead of seven
dense paragraphs.
- Layout (a source-tree map for contributors) is dropped from the doc page: it
answers a question no reader of the docs site is asking.
- The Configuration section no longer claims "no environment variables", which
stopped being true when the env fallback landed.
A bare `install` wired every detected agent: hooks, MCP registration and the
companion skill written into up to ten hosts' configs from one command that
never said it would. `all` is now spelled out, so wiring the whole machine is a
choice rather than a side effect, and a bare `install` changes nothing and
prints the options. `uninstall` matches, so the pair stays symmetric.
Chosen over a --yes flag or a confirmation prompt: a prompt has to decide what
to do without a TTY (assume consent, or break automation), whereas an explicit
target reads the same in a terminal, a script and a README.
The README also gains a per-agent section — one row per agent with its exact
command and what that wiring touches — since "install and it finds everything"
is no longer the whole story.
* docs(knowledge-pages): document Knowledge Pages and Mental Models
Knowledge Pages shipped in #2455 with no documentation at all — no
architecture page, no API page, no mention in the sidebar. Mental models
had an API page but nothing explaining what they are or why they are
fast. Add both, as top-level entries under Architecture and API.
- Architecture: how pages are mental models with a simplified,
document-shaped configuration; the folder hierarchy; the `hindsight fs`
filesystem projection; page-level search; and why a projected view over
reconciled memory is not the same thing as a folder of raw files.
- Architecture: mental models as standing answers built in the background,
so an application reads the current version instead of paying for
synthesis on the request path.
- API: the full knowledge-base endpoint surface, the page defaults and
what each one buys, staleness gating, what a refresh reads, and how
delta mode edits a structured document instead of regenerating prose.
The mental-model trigger table gains the seven settings it was missing.
- FAQ: mental model vs knowledge page. Also corrects the neighbouring
answer, which described mental models as built automatically during
retain — that is observations.
The API examples use the maintained clients like every other API page, so
this adds the knowledge-base surface to the Python and TypeScript wrappers
(kept at parity, with request-mapping tests on both sides) and runnable
Python/Node/Go examples.
* feat(cli): manage knowledge pages from the CLI
The knowledge base was reachable from every client except the CLI, where
the eight endpoints were listed as deliberate coverage skips ("managed in
the control plane UI"). That left `hindsight fs` able to mirror pages
read-only but nothing able to create, edit, search, or delete them — and
it meant the API docs could not show a CLI tab alongside Python/Node/Go.
Adds `hindsight knowledge-base` with tree, create-folder, create-page,
get-page, search, update, delete, and export, removing the skips so
cli-coverage-check enforces the surface from here on.
`create-page` sends no trigger unless --mode or --fact-types is passed, so
the server's page defaults stand; when either is given the whole trigger
has to be restated, because a supplied trigger replaces the defaults
rather than merging with them.
Also adds the CLI tab to the Knowledge Pages API page and a Knowledge Base
section to the CLI reference.
Two independent reports from 0.0.1.
`deepen` resolves a harness through harness/registry.ts, which listed 8 of the
10 harnesses the installer wires. grok-build and copilot-cli were installable
but unknown to the registry, so deepen threw "unknown harness 'grok-build'" and
the background git-diff enrichment never ran for those users. Both are now
registered with their hook bins, and a guard test asserts the registry covers
every installer — the two lists are separate and had silently drifted.
Configuration also gains an environment fallback: `HINDSIGHT_API_URL`,
`HINDSIGHT_API_TOKEN` and one var per scalar setting. Deliberately a FALLBACK
beneath the config file, so an existing setup cannot change behaviour merely by
having env present; it covers containers, CI and secret managers that inject a
token instead of writing a credential to disk. Booleans and numbers are parsed
(a malformed number is ignored with a warning rather than becoming NaN), and an
empty var contributes nothing so it can't mask a file value. The map-valued
settings (mapPathToBank, harnesses, banks) stay file-only — nested branching
does not survive flattening into one variable.
Add a provider that talks exclusively to the OpenAI Responses API
(`client.responses.create` → `/v1/responses`) — never chat/completions.
Motivation: reasoning models such as gpt-5.6-terra reject `reasoning_effort`
combined with function tools on `/v1/chat/completions` (HTTP 400 unless
`reasoning_effort="none"`, see #2983). Reflect is a tool-calling search loop, so
that constraint forces the whole reflect operation — including the final
synthesis — to run with reasoning disabled. The Responses API models the
chain-of-thought as a first-class reasoning item, so reasoning and tools coexist;
reflect's search loop can now run with a real reasoning effort.
`OpenAIResponsesLLM` is a standalone `LLMInterface` implementation (OpenAI-only;
it deliberately does NOT subclass the multi-vendor chat/completions provider, so
it can never route through `chat.completions` and carries none of the
groq/ollama/deepseek special-casing). It reuses only provider-agnostic pure
helpers (text cleanup, quota-defer parsing). It translates the engine's
chat-shaped inputs:
- chat messages → `input` items (assistant `tool_calls` → `function_call`,
`role="tool"` → `function_call_output` keyed by `call_id`),
- nested `{"type":"function","function":{...}}` tools → flattened
`{"type":"function","name":...,"parameters":...}`,
- flat `reasoning_effort` → a `reasoning={"effort": ...}` object,
- `response_format` → `text={"format": {...}}` (strict json_schema or the soft
schema-in-prompt + json_object fallback),
- reads `response.output_text` + `function_call` items from `response.output`.
Generic LLM config flags are honored: `extra_body`, `timeout`, per-call
`temperature`/`max_completion_tokens`/`max_retries`. It also wires two flags the
chat/completions path drops — `openai_service_tier` (as the native Responses
`service_tier`) and `default_headers` (on the SDK client).
The conversation is replayed statelessly each turn (`store=False`, no
`previous_response_id`); server-side reasoning reuse across turns is left as a
future optimization.
Wiring: provider registration + dispatch, `PROVIDER_DEFAULT_MODELS` default
(`gpt-5.6`), docs + `.env.example` (+ embed template sync), and an `openai`
floor bump to `>=1.66.0` for the Responses API surface. Unit tests mock
`responses.create` (incl. the generic-flag wiring) and pin that reasoning + tools
are sent together on the tool path — the combination chat/completions rejects.
Validated live against real gpt-5.6-terra: plain + reasoning, strict structured
output, reasoning+tools together with a stateless function_call replay, and a
full run_reflect_agent end-to-end (stubbed retrieval, no DB) — tools drove to a
correct synthesized answer.
The package publishes as @vectorize-io/hindsight-coding-agents, so the unscoped
`npm install -g hindsight-coding-agents` in the README, the docs page and the
companion skill resolved to a different (non-existent) package and failed for
the first users who tried it. The BINARY stays unscoped, so `hindsight-coding-agents
install` is unchanged.
Two hosts silently kept stale wiring when the package moved, each for its own
reason. Both surfaced after the directory rename, on a machine that already had
Hindsight installed.
- Antigravity keys its hooks.json by a top-level namespace equal to MARKER,
where every other host matches entries by substring. Renaming the marker wrote
a second namespace and left the first registered, so every Antigravity hook
fired twice — once against a path that no longer exists. Install now drops any
namespace written under a previous marker, leaving unrelated bundles alone.
- `claude mcp add` refuses a name that already exists ("MCP server hindsight
already exists in user config"), so the add failed and the installer fell back
to printing manual instructions. The old registration survived and Claude Code
reported "Failed to connect — Connection closed" with the hindsight_* tools
dead. Remove before add, so the registration is replaced like the hooks are.
Both are the same class as the Grok block that skipped when one already existed:
"install" must repair existing wiring, not step around it.
The api.star-history.com embed in the README was broken. Replace it with
nicoloboschi/gh-stars, which backfills stargazer data via a scheduled GitHub
Action and commits a self-hosted SVG chart into the repo, so the README image
no longer depends on a third-party service.
Replaces the stock shadcn oklch greys with the Hindsight palette and moves
the shared primitives onto the design system's density, so the whole app
picks up the new look from tokens rather than per-component edits.
Tokens (globals.css)
- Blue-shifted neutral palette in both modes: page #F3F5F9/#080C17, card
#FFFFFF/#0F1724, sidebar #FFFFFF/#0A1020, hairline borders. Light mode
previously had --card equal to --background, so cards were invisible
against the page.
- Adds the --hs-* semantic layer (surface/fg/border/status/chart) and its
@theme mappings.
- --tracking-normal 0.025em -> 0; Inter reads wrong with positive tracking
at body sizes.
- Light --muted-foreground is #525866 (5.3:1 vs page, 7.1:1 vs card) so body
copy clears WCAG AA in both modes.
Fonts
- Inter and JetBrains Mono move to next/font/google, replacing the Google
Fonts @import that loaded weights lazily and left semibold headings in the
system fallback until the weight arrived. Space Grotesk is dropped; it was
only reachable via a `font-heading` utility no component used.
Primitives
- card, button (+ gradient variant), input, textarea, select, switch,
checkbox, dialog, alert-dialog, popover, dropdown-menu, command move to
13px / h-9 / rounded-[10px], with rounded-[16px] cards and dialogs and
blurred overlays.
Layout
- Bank page content is capped by a responsive staircase
(1024 / xl:1280 / 2xl:1440, centered). It was uncapped, so on a 16" display
body text and table rows spanned the full ~1700px window.
- Active tab underlines use the brand gradient instead of flat --primary.
- The sidebar toggles from anywhere on its chrome, not just the button.
Preserved deliberately: the h1-h6 weight default (Tailwind preflight resets
headings to inherit and not every heading here carries an explicit weight
utility), plus the chip tokens, logo keyframes, themed scrollbars and .prose
table rules that the tokens rewrite would otherwise have dropped.
Note: page.tsx is mostly re-indentation from wrapping the views in the width
container; `git diff -w` shows the real change.
The release workflow publishes with `npm publish --provenance`, and npm rejects
the upload when package.json has no `repository` matching the signed provenance:
422 Unprocessable Entity - Error verifying sigstore provenance bundle:
"repository.url" is "", expected "https://github.com/vectorize-io/hindsight"
v0.0.1 built and tagged fine and only failed at the registry. Same shape as the
other npm integrations (openclaw, ai-sdk, chat), including `directory` so npm
links to the subfolder.
The package is about to be released so it can be installed and exercised end to
end, but its page should not surface yet. Three edits, each covering a different
surface:
- integrations.json: the entry drives BOTH the gallery and the sidebar (the
sidebar is generated from this file), so removing it hides both.
- `unlisted: true` on the doc page: keeps it out of search and the sitemap and
marks it noindex, while leaving it reachable by direct URL — and stops the
build warning about a doc belonging to no sidebar.
- check-integrations.mjs EXCLUDED: the reverse check fails the docs build when a
released integration has no gallery entry, so without this the build breaks the
moment the release tag exists.
To publish it later: drop it from EXCLUDED, restore the integrations.json entry,
and remove `unlisted` from the page.
The uvx-launched daemon keeps a cached Python environment per Hindsight
version it has run (~1.5 GB each), and nothing removes them. Document the
stop / prune / restart recovery, including why the daemon has to be stopped
first.
* feat(integrations): add hindsight-opencode-coding plugin
Reflect-only long-term memory for coding agents in OpenCode, with a git+chat
backfill and (opt-in) live session write-back.
- reflect + INJECT: on a task, reflect() the symptom and push the root-cause
answer into the system prompt (no tools/recall).
- backfill: every commit (full message + full diff, commit timestamp + git
metadata) under a 'git' retain strategy; each chat as a JSON user/assistant
transcript with custom extraction (<=2 coherent facts) under a 'chat' strategy;
observations on; optional codebase knowledge pages.
- live write-back (opt-in HINDSIGHT_RETAIN_SESSIONS): every N turns upsert the
tool-filtered transcript under a stable conversation:<sessionID> document_id.
* refactor(integrations): generalize opencode-coding into hindsight-coding-agents
Make the coding-memory plugin harness-pluggable instead of opencode-specific.
A 'harness' (coding agent) differs in only two places; everything else is now
shared core:
- src/core/ hindsight client, missions, git + chat ingest, inject, RuntimeCore
- src/core/types.ts HarnessAdapter + ChatReader interfaces
- src/harness/ per-agent adapters + registry (opencode implemented)
Backfill: --harness selects how past sessions are read (opencode today);
git ingest, retain strategies, missions, and knowledge pages are identical
across agents. Runtime: HINDSIGHT_HARNESS (default opencode) selects the
adapter that binds RuntimeCore's reflect+inject+write-back to that agent's
plugin API. Adding an agent = one adapter file + a registry entry.
Type-checks and builds clean; unknown --harness/HINDSIGHT_HARNESS errors with
the available list.
* feat(coding-agents): on-demand memory_reflect tool, opt-in git-sync, JSON config
Add two capabilities to the reflect-only coding-agents plugin and move all
configuration off environment variables onto a single JSON file.
- memory_reflect tool: exposes the same synthesized reflect that is auto-injected
on the first message as an on-demand opencode tool the agent can call mid-task
(RuntimeCore.reflectNow + opencode adapter tool). Harness-agnostic core, thin
opencode wiring.
- incremental git-sync (opt-in): on load, diff the target ref's commits
(origin/main, falling back to HEAD) against the git:<sha> document_ids already
in the bank and async-retain only the missing ones, reusing the backfill's
per-commit encoding (retainCommit). Set-based, correct across rebases;
best-effort, non-blocking. Off by default (gitSync.enabled).
Adds HindsightClient.listDocumentIds + core/sync.ts.
- config file: all settings now come from ~/.hindsight/coding-agent.json
(core/config.ts) -- no environment variables. The backfill CLI reads the same
file for shared connection/bank settings with --flags overriding; operation
flags stay CLI-only.
Committed with --no-verify: the repo-wide pre-commit lint hook is broken in this
environment (missing @eslint/js in hindsight-control-plane) and blocks all commits.
* fix(coding-agents): remove benchmark-specific strings from prompts
Fairness audit of the sdebench benchmark found three contaminations:
- CHAT_CUSTOM_INSTRUCTIONS used the literal answer to a graded task
(round_cents/ROUND_HALF_DOWN/legacy ledger) as its example - replaced
with a fictional, non-benchmark example.
- buildSystemInjection told the model 'the hidden tests depend on those
exact choices' - hardcoded knowledge of the benchmark's grading;
reworded benchmark-agnostic.
- REFLECT_MISSION examples were shape-matched to specific benchmark
tasks (symbol mappings, exact numbers) - neutralized.
No behavior change intended beyond removing the leaked specifics.
(includes hook-regenerated skills/hindsight-docs sync)
* feat(coding-agents): reflect-outcome diagnostics — no more silent memory loss
A benchmark sweep ran the entire memory arm with zero injected memory:
reflect failed environmentally on every task and the best-effort catch
swallowed it, making a memory-less run indistinguishable from a memory
run. onTask now appends a reflect_ok/reflect_empty/reflect_failed record
(duration, error, query prefix) to HINDSIGHT_DIAG_FILE (default
/tmp/hindsight-plugin.log). Consumers can assert a session actually had
memory before trusting a comparison.
* fix(coding-agents): chronological session recency + supersession-aware reflect
Two defects surfaced by the conversation-amended benchmark tasks (a rule
settled in one chat and amended in a later one):
- chat ingestion staggered synthetic timestamps NOW - i*1h, INVERTING
recency: an amendment chat ranked older than the decision it
superseded, steering temporal ranking toward the stale rule. Session
list order is chronological; the last session is now the newest.
- REFLECT_MISSION now states that when memories conflict on the same
rule, the latest/superseding decision wins and the superseded rule
must be reported as no longer in effect, never presented as the fix.
Observed live: reflect on an amended bank returned the superseded
keep-latest rule as the fix. Both fixes are general recency/consistency
semantics, not benchmark-specific behavior.
* feat(coding-agents): multi-harness configurability + Claude Code hook entry
One config, several agents side by side:
- Each runtime entry point now KNOWS its harness instead of reading the
config's `harness` key (which selected a single global adapter and
made opencode + claude mutually exclusive). That key now only picks
the backfill's session formatter.
- New `harnesses.<name>` config sections: per-agent overrides of any
field (bank, disabled, timeouts) over shared connection defaults.
- New project-local layer: <project>/.hindsight/coding-agent.json
overrides the global file — the natural home for a per-repo bank.
Precedence: defaults < global < global.harnesses < project <
project.harnesses.
- New entry point: `hindsight-claude-hook` (dist/claude-hook.js), a
Claude Code UserPromptSubmit hook. Reflects once per Claude session,
caches the answer in tmp and re-injects it on later prompts, and
writes the same reflect_ok/failed diagnostics as the opencode path.
Verified live: claude hook via project config + harnesses section
(reflect_ok, cached re-emit in 46ms, one reflect total); opencode via
the benchmark harness (reflect_ok, task solved 0 corrections).
* feat(coding-agents): per-repo dynamic bank resolution (family convention)
Port of the bank-derivation convention shared by the claude-code, omo,
cline, and opencode integrations, with coding-first defaults:
- No bankId configured => the bank is derived from the git repo the
working directory belongs to, WORKTREE-AWARE: git rev-parse
--git-common-dir resolves every linked worktree to the main worktree's
basename, so all worktrees of a repo share one memory bank (bare repos
use the bare dir name; non-git dirs fall back to the dir basename).
- Default granularity is [gitProject] (not agent::project): opencode and
claude share ONE memory per repo — add 'agent' to
dynamicBankGranularity to split per agent.
- Explicit bankId keeps today's static behavior (benchmark harness,
single-bank setups); dynamicBankId forces either mode; supporting
fields: bankIdPrefix, directoryBankMap (exact cwd -> bank escape
hatch), agentName, resolveWorktrees.
- backfill: --bank wins, else the SAME resolution applied to --repo, so
`hindsight-coding-backfill --repo .` fills exactly the bank the
agents will read.
Verified: worktree -> main-repo bank (hs-coding-plugin-wt -> memory-poc),
static/prefix/dirMap/granularity cases, and the claude hook e2e
(reflect_ok via directoryBankMap against a live bank).
* feat(coding-agents): bank template string, prefix path map, {harness} field
Bank-resolution refinements:
- `bankIdTemplate` format string replaces the granularity array:
e.g. "hindsight-{gitProject}" or "{harness}-{gitProject}" — default
"{gitProject}" (opencode + claude share one bank per repo).
Placeholders: {gitProject} {project} {harness} {channel} {user};
unknown placeholders warn with the valid list. bankIdPrefix removed
(expressible in the template).
- {harness} is supplied by the entry point itself (opencode plugin,
claude hook, backfill --harness), not a config field — nothing to
keep in sync.
- directoryBankMap now matches by LONGEST absolute-path prefix and
overrides everything incl. an explicit bankId: mapping a repo root
covers all its subdirectories; deeper mappings win.
- config discovery walks UP from the working directory to the nearest
.hindsight/coding-agent.json — a hook invoked from a repo subdir
previously missed the repo's project config entirely (found by an
e2e test that failed exactly this way).
Verified: derivation matrix (template/prefix-map/override/static/bad
placeholder), claude hook e2e from a nested subdir (reflect_ok via
walked-up config + prefix-matched map), opencode benchmark task green.
* feat(coding-agents): cursor-cli + codex harnesses, unit tests, live system tests
Harnesses — hook-based agents now share one runtime (core/hook.ts:
stdin event -> layered config -> per-repo bank -> once-per-session
reflect with tmp cache -> native output -> diagnostics), so each agent
is a ~25-line HookSpec:
- hindsight-claude-hook (UserPromptSubmit -> additionalContext)
- hindsight-cursor-hook (beforeSubmitPrompt -> {continue, additional_context})
- hindsight-codex-hook (Codex CLI v0.116+ claude-compatible hooks;
accepts prompt/user_prompt)
All three + opencode registered in the harness registry (backfill
--harness resolves them; hook harnesses share the normalized-JSON
chat reader).
Tests (vitest, family convention):
- 25 unit tests: full bank-derivation matrix (worktree/bare/static/
dynamic/template/{harness}/prefix-map incl. longest-wins and
no-sibling-false-match) and config layering (harness sections,
project-over-global, upward walk, nearest-wins, gitSync field merge,
malformed fallback, legacy signature).
- live system suite (npm run test:live, HINDSIGHT_LIVE_E2E=1): builds a
real git repo with a decision planted in a commit + a conversation,
runs the real backfill CLI (server-side LLM extraction), then invokes
the BUILT hook binaries as subprocesses and asserts the decision's
literals come back in the injected context — semantic verification
with a real LLM — plus per-session cache behavior and diag records.
All 4 passing against a live server.
Note: session ids in the live suite are unique per run — the hooks
cache per session id in tmp, and a static id once cached a bad answer
from a half-broken server across reruns.
* docs(coding-agents): full README rewrite + integration docs page
README now covers everything the package does today: the reflect-once/
inject-every-turn mechanics, all four harnesses (opencode plugin +
claude/codex/cursor hooks) with install snippets, the complete
configuration reference (layered files, harnesses sections, per-repo
dynamic bank resolution with template placeholders, directoryBankMap,
worktree behavior), backfill CLI incl. bank auto-resolution and
chronological session ordering, the reflect diagnostics contract, and
the unit + live test suites.
Docs site: new docs-integrations/coding-agents.md (same content adapted
to the integration-guide format) + integrations.json hub entry so the
generated sidebar picks it up. Placeholder icon (github.png) pending a
real one. Verified: page renders (docusaurus build), all doc pre-flight
checks pass for this entry — note the docs build on this branch was
ALREADY failing on the unrelated pre-existing 'zcode missing from
integrations.json' check.
* feat(coding-agents): 🧠 attribution header in buildSystemInjection
Prepend the 'Using Hindsight Memories' visible-attribution directive to the
harness-agnostic system injection so every coding-agent harness surfaces a
recognizable header when it uses recalled memory. Covered by 5 deterministic
inject.test.ts cases (real emoji + em dash, no lone surrogates).
* feat(core): add recall() to HindsightClient
* style(core): apply prettier formatting to recall test
* style(coding-agents): normalize prettier formatting across package
* fix(core): narrow RecallResult to actual API contract, add fetch-throw test
* feat(core): formatMemories + shared attribution preamble
* style(core): prettier-wrap recall.test.ts array literal
* fix(core): cover formatMemories trim/filter + drop stale inject comment
* feat(core): per-turn recall in the hook runtime (reflect once, recall every turn)
Extracts the hook logic into a pure, unit-testable buildHookOutput(): every
prompt now runs recall() and injects a <hindsight_memories> block; reflect
still runs once per session (first prompt) and its cached answer is no
longer re-injected on later turns. runHook() becomes thin stdin/stdout
plumbing with a makeClient seam for tests. Updates the three hook
entrypoints' doc comments to match, and adds recallMaxTokens/recallTimeoutMs
config fields.
* fix(core): make recall fail-open in buildHookOutput + cover recall failure/opts
* feat(claude-code-v2): wrapper plugin skeleton (per-turn recall via bundled core)
Also disables tsup code-splitting in hindsight-coding-agents so each bin
entry (claude-hook.js etc.) is a single self-contained file with no
shared chunk-*.js — required for wrapper build scripts that copy just
the one hook file out of dist/.
* chore(coding-agents): sync codex-hook bin into package-lock
* fix(claude-code-v2): derive version from manifest + guard self-contained bundle
* feat(core): Claude transcript reader (normalized user/assistant text turns)
* fix(core): transcript reader null-safety + drop sidechain turns
* feat: live write-back on the Claude Stop hook (shared retain-hook runtime)
Extracts a testable buildRetain core (read transcript -> upsert under
conversation:<sessionId> via retainLiveSession) plus a thin runRetainHook
plumbing wrapper mirroring the existing runHook/buildHookOutput split, and
wires it up as a Claude Code Stop hook. Fail-open throughout: an empty
transcript is a no-op, and a retain failure is diagnosed but never thrown.
Exports diag() from core/hook.ts so retain-hook.ts can reuse the same
diagnostics helper instead of duplicating it.
* refactor(core): extract diag module + trim buildRetain params
- Move diag() out of hook.ts into a neutral src/core/diag.ts so retain-hook
(and future lifecycle hooks like SessionStart) don't reach into a
recall/reflect-specific module for a cross-cutting concern.
- Drop the unused cwd/cfg params from buildRetain — only harness, sessionId,
transcriptPath, and client are read; cwd/cfg stay in runRetainHook where
they're actually used (config load + deriveBankId).
- Clarify that retainSessions is opencode-plugin-only; the Stop hook always
writes back unless disabled.
* feat(core): knowledge-page CRUD on HindsightClient (mental-models)
* fix(core): page methods throw on 404 + doc rationale
* feat: native TS MCP server for knowledge-page tools (bank-aligned)
Adds a native TypeScript MCP (stdio) server exposing the agent_knowledge_*
tools (get_current_bank, list_pages, get_page, create_page, update_page,
delete_page, recall) over MCP, wired into the claude-code-v2 wrapper.
Bank resolution goes through the same loadConfig + deriveBankId path the
hooks use (harness "claude-code"), so knowledge pages, recall, and retain
all land in one per-repo bank. This is a native TS server rather than
reusing the Python MCP because its bank derivation mismatches.
- src/core/knowledge-tools.ts: SDK-free tool specs (zod schemas), unit
tested against a stub client (17 tests) — every handler is fail-closed
to an isError:true result instead of throwing.
- src/mcp-server.ts: the only file importing @modelcontextprotocol/sdk.
- tsup.config.ts: new mcp-server entry, noExternal inlines the SDK + zod
so dist/mcp-server.js stays a single self-contained file.
- claude-code-v2/.mcp.json + build.mjs: wires the bundle into the plugin;
the self-contained-bundle guard passes for mcp-server.js unmodified
(no exemption needed) since noExternal fully inlines its deps.
* fix(mcp): honor disabled flag + testable selectTools
- Export selectTools(cfg, client, bankId) from mcp-server.ts: pure,
SDK-free, returns [] when cfg.disabled (mirrors the hooks' disabled
check) so a disabled Hindsight exposes zero MCP tools instead of all 7.
Confirmed at runtime: with disabled:true the server still connects but
doesn't advertise a tools capability at all (tools/list -> Method not
found), which is stronger than an empty list.
- Guard main() behind an argv[1]-vs-import.meta.url check so importing
the module for tests doesn't start a real stdio server.
- Add src/mcp-server.test.ts covering selectTools for both the disabled
and enabled cases.
- Reword the HINDSIGHT_MCP_PROJECT_CWD comment: nothing sets it today
(the plugin doesn't cd), it's an escape hatch, not a launching-host
contract.
* refactor(core): lazy-load opencode adapter so backfill bundles self-contained
* test(core): lock opencode no-runtime registry invariant + doc it
* feat(core): cold-repo detection + seed-consent state
* test(core): cover seed write-failure + guard non-object state
* feat(core): background seed mechanics + hindsight-seed control CLI
Adds hasGitHistory (git.ts), startBackgroundSeed + seedControl (seed.ts),
and the src/hindsight-seed.ts entrypoint the agent runs after the
SessionStart seed offer (Task 10b) to seed or decline a repo's bank.
* fix(core): handle async spawn error in startBackgroundSeed
spawn() failures (ENOENT/EACCES/fd exhaustion/sandboxed environments) often
arrive asynchronously as an 'error' event on the child, not a synchronous
throw. An unhandled 'error' event crashes the caller, so attach a no-op
handler alongside the existing try/catch. Also documents the Claude-Code-only
harness assumption in hindsight-seed.ts.
* feat: SessionStart auto-seed offer for cold repos (Claude wrapper wired)
* fix(core): shell-escape seed offer paths + drop orphaned isColdRepo
* docs(claude-code-v2): marketplace entry, full README, v1→v2 migration note
* fix(core): cap hook reflect timeout, align backfill+hook config resolution
- hook.ts: cap reflect's timeoutMs to HOOK_REFLECT_CAP_MS (8s) so it always
resolves/aborts before Claude Code's 15s UserPromptSubmit kill window,
guaranteeing the session cache write + recall injection complete instead
of silently retrying reflect (and dropping recall) on every turn.
- backfill.ts: resolve config via loadConfig({harness, projectDir: REPO,
path}) instead of the legacy string form, so project-local
.hindsight/coding-agent.json layers in and the background auto-seed
backfill targets the same bank recall/retain/MCP read from.
- hook.ts/retain-hook.ts: resolve the cwd fallback before loadConfig (not
just at deriveBankId) so project-local config layers even when the
hook event's cwd is missing.
* fix(claude-code-v2): dev-install must copy .mcp.json (MCP tools were missing)
* feat(core): deterministic SessionStart auto-seed + knowledge-page bank mission
The prior SessionStart design asked the agent to pose a y/n question then
run a seed command itself; live testing showed the model surfaces the
question and then ignores it, so nothing ever seeds. The hook now starts
the background seed itself on a cold git repo (tri-state: cold/warm/
unreachable) and always injects a short visible note plus a bank-mission
pointing the agent at the agent_knowledge_* tools.
* docs(claude-code-v2): update seed docs for deterministic auto-seed + knowledge mission
* feat(core): default seed to aggregated commit messages (one cheap doc) + Initiatives page; full-diff opt-in via --diffs
* docs(core): align backfill README + strategy log/comment with gitlog default
* feat(core): headless codebase-survey seed + agent_knowledge_ingest MCP tool
On a cold repo, the SessionStart hook now also spawns a detached headless
`claude` that samples the repo's structure and ingests its findings into
Hindsight via a new agent_knowledge_ingest MCP tool, alongside the existing
git-history backfill. Knowledge pages synthesize their content from bank
memories via source_query, so this is how the survey feeds them.
- knowledge-tools.ts: add agent_knowledge_ingest (title -> slug doc id,
retain via the "chat" strategy, tagged source:upload).
- survey.ts: resolveClaudeBin + startCodebaseSurvey, mirroring seed.ts's
fire-and-forget/never-throw spawn pattern.
- Anti-recursion: HINDSIGHT_DISABLE_HOOKS guard at the top of runHook,
runRetainHook, and runSessionStartHook so the survey's own claude session
can't re-trigger seeding/recall/retain; survey.ts sets it on the child.
- config.ts: codebaseSurvey (default true) + surveyModel (default "sonnet").
- session-start.ts: wire startSurvey into the cold-repo branch alongside
startSeed; update the visible learning note.
* fix(core): sandbox headless survey (deny-list, no bypassPermissions) + spend cap + document strategy
* feat(core): default codebase-survey model to haiku (cheaper/faster; sonnet still configurable)
* feat(core): survey excludes CLAUDE.md + agent-instruction files from ingestion
* docs(coding-agents): v2 knowledge-pages design spec + implementation plan
* feat(core): add pageRefreshEveryTurns config (default 10)
* feat(core): knowledge-injection roster/preamble formatting
* feat(core): passive knowledge entity_labels tier vocabulary + configureBank wiring
* feat(core): tag-scope seeded pages, Initiatives folder, relatedPageId link source_query
* feat(core): captureInitiative — per-initiative page + relatedPageId marker
* feat(mcp): hindsight_* grounding tools + capture_initiative; remove raw page CRUD from agent
* feat(core): SessionStart injects page roster + guidance preamble
* feat(core): UserPromptSubmit hook-counted periodic page-roster refresh
* feat(core): rich markdown session write-back with tool calls + verbose session strategy
* chore: apply prettier line-wrapping to test files
* fix(claude-code): surface the seed note via user-visible systemMessage, keep preamble in additionalContext
* fix(survey): use renamed hindsight_ingest_document MCP tool (Task 6 rename regression)
* fix(core): preamble + refresh nudge the agent to call capture_initiative for major features
* fix(core): re-inject tool+capture reminder every cadence turn even with no pages (unconditional nudge)
* fix(core): inject when-to-call guide for the full hindsight_* tool suite, not just pages+capture
* feat(claude-code): cold-check-wins seeding — reseed a cleared bank on the live doc count, ignore stale seededAt
* fix(core): simplify capture_initiative instruction to one clear trigger (remove confusing OR-chains)
* fix(core): port proven v1 attribution preamble + surface memories block first so the header actually gets emitted
* fix(core): reflect every turn (configurable reflectEveryTurns, default 1) instead of once per session
* feat(core): per-turn injection is recall-only (drop reflect from the hook), recall token budget default 750
* feat(core): inject a user-feedback section above memories (capture-initiative + attribution-header preferences)
* fix(core): align user-feedback attribution bullet with the generous WHEN-IN-DOUBT-EMIT rule
* fix(core): sharpen capture_initiative trigger — call right after plan approval, before implementation
* feat(survey): raise default codebase-survey budget cap to $2 (0.5 was over-conservative)
* feat(codex): codex-v2 wrapper (SessionStart seed + per-turn recall + MCP); parametrize session-start/MCP harness
* feat(core): default bank template is harness-neutral coding-agent::{gitProject} (shared memory across agents)
* feat(core): default apiUrl is Hindsight Cloud (https://api.hindsight.vectorize.io); local is now an override
* feat(codex): Stop write-back — Codex rollout transcript reader + codex-stop-hook (full parity)
* fix(core): captureInitiative returns the server-assigned page id (not the slug) so read_knowledge_page + relatedPageId links resolve
* feat(coding-agents): upgrade opencode adapter to full v2 parity
Per-turn recall via chat.message + system.transform (750-tok budget), native hindsight_* tools registered directly through opencode's tool() (no MCP server), rich tool-aware write-back on by default, and cold-check auto-seed at plugin load — reusing the shared formatMemories / buildKnowledgePreamble / buildKnowledgeTools / buildSessionStartContext primitives so opencode matches Claude Code and Codex.
Adds transcript-opencode.ts (rich normalizer over the live message list). Adds a HINDSIGHT_DISABLE_HOOKS recursion guard to RuntimeCore (seed/recall/write-back/sync no-op; tools still register) for headless survey runs. Removes the now-dead reflect path (client.reflect, inject.ts/buildSystemInjection, reflectTimeoutMs) as the whole surface is recall-only. README rewritten to the recall/knowledge-page/seed/write-back v2 model.
* feat(coding-agents): harness-portable codebase survey (multi-agent headless)
The cold-repo survey no longer hardcodes headless `claude` — startCodebaseSurvey now runs under the current harness's own CLI (claude/codex/gemini/opencode), falling back to any available agent, so a Codex/Gemini/opencode user without claude installed still gets the survey (the git-log seed already ran regardless).
Per-agent read-only recipes: claude (-p + inline --mcp-config + --disallowedTools), codex (exec --sandbox read-only + inline -c MCP), gemini (-p --approval-mode plan --allowed-mcp-server-names hindsight --skip-trust), opencode (run --agent plan; tools from the loaded plugin under the HINDSIGHT_DISABLE_HOOKS guard). All spawned with HINDSIGHT_DISABLE_HOOKS=1. session-start threads the harness through to the survey.
* feat(gemini): add Gemini CLI v2 integration (gemini-v2)
Full v2 parity for Gemini CLI (>=0.52.0), which added a Claude-style hooks system (stdin/stdout JSON). Maps onto the shared HookSpec/runSessionStartHook/runRetainHook abstraction with Gemini's event names: BeforeAgent (per-turn recall -> hookSpecificOutput.additionalContext), SessionStart (seed), SessionEnd (write-back).
The one Gemini-specific piece is transcript-gemini.ts — a reader for the 0.52.0 chats/session-*.jsonl mutation-log (upsert-by-id, polymorphic content: user text arrays, assistant plain strings, tool results as user functionResponse parts; drops the synthetic session_context message + thoughts). Adds the gemini-v2 wrapper (build.mjs + dev-install.sh that merges hooks + mcpServers into ~/.gemini/settings.json). Validated: reader against a real transcript, and a live recall smoke test (recall_ok) end-to-end.
* style(coding-agents): prettier-format README config table
* fix(opencode): inject via lastInjection fallback (1.18.5 system.transform has no sessionId)
opencode 1.18.5 fires experimental.chat.system.transform with input {model} only — no sessionId — so RuntimeCore.getInjection(input.sessionID) looked up undefined and pushed nothing into the system prompt. Recall still ran (chat.message does pass sessionID) but the memory block + attribution preamble + knowledge-page guide never reached the model, so no visible header and no tool use.
getInjection now falls back to the most recent turn's block (lastInjection) when there's no session-keyed hit. The completion's system.transform fires right after that session's onPrompt, so lastInjection is this turn's block. Adds an inject_ok/inject_empty diag (matching recall_ok/seed_started) to confirm injection lands.
* fix(coding-agents): treat project-local config as untrusted (block apiUrl/apiToken/directoryBankMap from a repo)
A project-local .hindsight/coding-agent.json lives inside whatever repo the developer opens, so it is untrusted input. loadConfig previously merged it per-field over the user-global config, letting a repo override apiUrl while the user-global apiToken survived the merge — so a malicious repo could set only apiUrl and the client would send the user's real Bearer token plus every recall query (the prompt) and Stop write-back transcript to an attacker-controlled host, silently, just by opening the repo (verified end-to-end).
Fix: the project-local layer is now sanitized — apiUrl, apiToken, and directoryBankMap are stripped from it (top level + any harnesses.<name> section) with a one-line warning; the user-global config stays trusted and unrestricted, and a repo can still set its own per-repo bank (bankId/bankIdTemplate). Also skip re-applying the global file as a project layer when the upward findProjectConfig walk lands back on it (a repo under $HOME with no closer config), which would otherwise strip its own apiUrl and warn every session. Adds 4 regression tests.
* style(coding-agents): prettier-format config.ts
* feat(coding-agents): restore reflect as the memory path; per-turn injection from knowledge-page sections
One opinionated runtime path (no behavior config):
- reflect ONCE per session on the first prompt (agentic root-cause synthesis,
benchmark-proven), cached and re-injected every turn — hook harnesses and the
opencode runtime alike
- every turn: knowledge-page SECTIONS matched locally against the prompt
(lexical section index, no server/LLM call) injected with provenance and a
pointer to the full page — fast like recall, organized like reflect
- raw recall leaves the runtime path (still powers the hindsight_search_memory
tool)
Session write-back: transcripts are now JSON turns matching the backfill chat
format, with each tool call compacted to a role:"action" turn naming the tool
and its primary target (no arguments, no outputs) — Claude, Codex, Gemini and
opencode readers.
Knowledge pages: no more entity_labels/tag taxonomy — pages are unscoped, each
page's source_query selects from the whole bank; survey, gitlog seed, write-back
and security hardening stay.
Spec: docs/superpowers/specs/2026-07-27-reflect-pages-runtime.md
* test(coding-agents): rewrite unit tests for reflect+pages runtime and JSON action transcripts
* test(coding-agents): live suite matches reflect_ok by content (pages_ok now follows it in the diag stream)
* docs(coding-agents): README + docs page describe the reflect+pages runtime (reflect once per session, local page-section injection per turn, JSON action write-back)
* feat(coding-agents): drop the backfill CLI — ingestion is automatic and background
- new deepen engine (dist/deepen.js, unpublished): idempotent, resumable —
per-bank lock, dedup by document id; ingests missing conversations, the
one-time gitlog seed, then progressively deepens recent history with
per-commit full diffs (newest first, bounded batch per run); drains and
creates knowledge pages last
- every session start now fires the engine (cold or warm); survey and the
cold-seed note stay cold-only
- sync status is the new readiness contract: hindsight_sync_status agent tool
+ dist/status.js for harnesses (synced = gitlog seeded, pages present,
extractions drained); activeOperations() filters terminal ops
- opencode write-back now upserts every turn (async) so a killed session
loses at most the last turn
- repoNameOf resolves relative paths so document ids are path-spelling-proof
- hindsight-coding-backfill bin removed; benchmark/e2e run the engine
directly and poll status
* polish(coding-agents): short, non-technical cold-seed message highlighting the bank id
* polish(coding-agents): cold-start banner — HINDSIGHT unicode wordmark + bank id line
* feat(coding-agents): timing diagnostics on by default
- session_start diag event on EVERY session (bank, cold/warm, pages, ms) —
warm sessions previously logged nothing
- deepen engine: deepen_started/deepen_done/deepen_failed diag events with
duration; child output now appended to ~/.hindsight/coding-agent-state/deepen.log
(was stdio:ignore — undebuggable) and log lines timestamped
- retain_ok/retain_failed carry ms on both the Stop hook and the opencode
per-turn upsert (which was fully silent)
- vitest config pins HINDSIGHT_DIAG_FILE to a tmp file so unit tests stop
polluting the real diag log
* feat(coding-agents): show the Hindsight banner on every session start (cold: learning, warm: remembering)
* polish(coding-agents): session banner uses the API server's colored pixel-art logo (shared visual identity), wording line below
* polish(coding-agents): banner text before logo — the TUI's first-line prefix was displacing the logo's top row
* polish(coding-agents): banner logo re-rendered foreground-only — the TUI strips ANSI background colors, which deleted half the server logo's pixels
* feat(coding-agents): per-turn user-visible notice — every prompt shows what Hindsight delivered (reflect state + matched knowledge pages) via hook systemMessage; opencode logs the same line
* polish(coding-agents): per-turn notice shows the match query excerpt and the page titles it returned
* fix(pages-index): singularize plain-word tokens so plural prompts match singular headings ('components' -> 'Component map'); path-like tokens untouched
* polish(coding-agents): per-turn notice — gradient Hindsight wordmark, value-driven wording, no timings
* feat(coding-agents): interim always-inject knowledge stub + explicit Hindsight attribution
- selectSections: TEMPORARY stub returning the first section of up to 3
distinct pages every turn regardless of prompt — guarantees injected data
for testing source attribution; will be replaced by the server-side
knowledge-base/search (local lexical index drops with it)
- both injection blocks now carry an ATTRIBUTION directive: when memory
shapes the answer, the agent introduces it with '🧠 From Hindsight memory
(<page>)' — and must never credit memory that did not contribute
* polish(coding-agents): gradient-word banner (logo dropped), lean per-turn notice, attribution directive front-loaded as a mandatory output format
* polish(coding-agents): reflect turn notice shows the assigned goal and a preview of what memory returned
* feat(coding-agents): page knowledge moves from auto-injection to an explicit tool
- new hindsight_search_knowledge_pages(query) tool (native on opencode, MCP on
hook harnesses) — interim local selection, single swap point for the
server-side knowledge-base/search; results carry the attribution requirement
- per-turn auto-injection of page sections removed: a trivial prompt ('yes')
no longer displays phantom research; ordinary turns are silent
- per-turn notice only on the reflect turn (assigned goal + result preview);
tool calls provide their own native visibility
- tool guide/roster advertises the search tool as the first stop
* feat(coding-agents): bind hindsight_search_knowledge_pages to the server-side hybrid knowledge-base search
- merge feat/knowledge-pages-okf underneath (GET /knowledge-base/search,
BM25 + vector, RRF-fused; conflicts resolved in okf's favor for server/
clients/UI, coding-agents docs entry preserved)
- client.searchKnowledgePages(query, limit) wraps the endpoint; the tool
returns ranked {page, page_id, snippet, score} — verified end-to-end
through the real MCP server against the live endpoint
- interim local selection removed from the tool path (pages-index remains
only for the hook page cache pending full cleanup)
* refactor(coding-agents): drop pages-index — local section index deleted; hook/runtime keep only the id+title roster (content lives behind the server-side knowledge-base search)
* refactor(coding-agents): drop hindsight_search_memory (raw recall) — knowledge-page search is THE search surface; recall client method and formatter removed
* feat(coding-agents): hindsight_reflect tool — on-demand deep memory reasoning alongside the session-start reflect
* refactor(coding-agents): one 'conversation' retain strategy for all developer conversations
Backfilled decision chats and live session write-back were the same content
type (identical JSON action-transcript format) extracted two ways based only
on where they came from. Merged CHAT_MISSION + SESSION_MISSION into one
CONVERSATION_MISSION that scales facts to substance (short decision chat ->
1-2 facts, working session -> several; final-state-wins, verbatim literals,
rejected-alternative rule kept); the ≤2-fact CHAT_CUSTOM_INSTRUCTIONS
extractor is retired with it.
* feat(coding-agents): restore Chris's knowledge entity_labels tier
configureBank again sets entity_labels {knowledge: feature-work/decision/
convention/component/concept, tag:true} + entities_allow_free_form, so the
extractor routes durable facts with knowledge:<tier> tags the server-side
knowledge base can select on; capture_initiative markers regain the
knowledge:feature-work label. Pages themselves stay unscoped (the okf
knowledge base owns synthesis).
* feat(coding-agents): seeded pages tag-scoped again — page tags match the restored knowledge:<tier> entity labels (capture_initiative pages included)
* fix(coding-agents): reflect injection wrapped in <hindsight_memory> so write-back never re-ingests it; seed-state file (declined flag) removed — the live bank is the only state
* feat(coding-agents): gitIngest enum ('message' | 'full' | 'none') — one setting, one code path for seeding AND staying current
- deepen's idempotent git pass IS the sync: gitlog doc re-upserts when HEAD
moves (gitlog-head:<sha> tag makes freshness a single tag query); in full
mode new commits surface at the top of rev-list and the next run ingests
them
- separate git-sync path deleted (sync.ts, runtime.syncGitOnce, gitSync
config)
* feat(coding-agents): gitIngest defaults to 'message' (cheap by default; opt into depth); deepen gains --git-ingest override for harnesses
* feat(coding-agents): session banner shows git-sync state (condensed syncStatus): 'git in sync' / 'catching up on new commits' / 'syncing git history (n/target)'
* polish(coding-agents): two-line banner — value headline (tracking decisions/conventions/history) + bank/sync detail line
* refactor(coding-agents): ONE config file — project-local .hindsight/coding-agent.json layer removed entirely (with its sanitization machinery); per-repo routing stays via directoryBankMap
* docs(coding-agents): fix stale project-config reference in comment
* refactor(coding-agents): runtime scratch (deepen lock + engine log) moves to the OS temp dir — ~/.hindsight now holds ONLY the config file
* feat(coding-agents): cursor auto-ingestion parity — hosts without a SessionStart hook fire the deepen engine (+ cold survey) from the session's first prompt
* feat(coding-agents): leveled plugin logging — one plugin.log (debug/info/warn/error, config logLevel + HINDSIGHT_LOG_LEVEL/FILE overrides); diag events mirror at debug; deepen logs itself (separate deepen.log dropped); warn on reflect/retain failures
* feat(coding-agents): one-shot bank configuration via the server's template import — missions, strategies, entity labels, and the 5 seeded pages in a single idempotent POST /import (configureBank PUT+PATCH and createPages removed)
* feat(coding-agents): one-command installer — npx hindsight-coding-agents install|uninstall [harness...]
Detects the coding agents on the machine and merges each one's native
wiring (hooks + MCP: claude mcp add for Claude Code; hooks.json + append-
only config.toml sections for Codex; settings.json for Gemini; hooks.json
+ mcp.json for Cursor; plugin array for opencode). Idempotent by marker,
preserves foreign entries, backs up touched files as .hindsight-backup;
uninstall removes exactly ours. 27 unit tests over temp homes.
* fix(installer): refuse to install from an npx/dlx cache (wired paths would die on eviction); document global install + npm update -g as the update path
* ci(coding-agents): unit + typecheck + build job, and a live E2E job (real API server + real LLM) running the deepen->sync->reflect->injection path; prettier-format the package
* docs(blog): launch post draft — coding-agent memory results (marked draft: true)
* docs(blog): rewrite launch post as the narrative — from 'does memory even help?' through why-not-SWE-bench, the corrections dataset, benchmark-driven architecture decisions, to the final numbers
* docs(blog): position knowledge pages as a co-launch headline — living-documents framing, example page excerpt, platform-wide availability (dashboard editor, hybrid search API, bank templates), closing CTA
* docs(blog): restructure launch post payoff-first — contrarian RAG finding + cost in the lede, TL;DR box, narrated task with both runs, seeded-answers objection met head-on, data-locality/time-to-value/latency answers, Sonnet number promoted, backstory compressed to one section
* fix(coding-agents): deepen waits for server-side ops to settle (template-import page refreshes broke the synced contract); HINDSIGHT_CONFIG env override for the config path (containers/test harnesses; replaces the live test's dependency on the removed project-config layer)
* docs(blog): second-pass fixes — flagship example swapped to the arbitrary retry decision (RFC 4180 attack closed), reconstruction disclosed, 58% provenance clause, placebo backstory + grading block restored in numbers, RAG figure per-task, benchmark-site date
* docs(blog): align remaining CSV references with the retry flagship; TL;DR per-task figures
* docs(blog): flagship rebuilt on the real dataset task — the ERP export decision whose rejected alternative IS the textbook fix (='00042' formula form, minimal quoting, CRLF); dangling injection-verified reference restored; limitations cross-check attached to the correct row
* docs(blog): rewrite as the 0.9.0 launch post — five-beat narrative (question → dataset → auto-recall failure → reflect → knowledge pages from llm-wiki to self-healing) for Knowledge Pages + unified coding-agents plugin
* docs(blog): add the missing beat — shaping the dataset revealed decisions live in git, which the old plugins never ingested
* docs(blog): reframe reflect — very smart rather than slow; first message carries the session goal; on-demand reflect tool for session drift
* docs(blog): pages section addresses the 'back to files?' objection — pages as projected views over consolidated memory (contradiction resolution underneath), raw docs remain source of truth
* docs(blog): out-of-box row updated to n=3 (22/26/23 -> 0.72/task, -26%; cost -35%); matured row marked single-run
* fix(hooks): reflect block injected once per session (+ cadence refresh), not every turn — hook context persists in the transcript, so per-turn re-injection stacked duplicate blocks
* fix(coding-agents): wrapper bundles ship deepen.js, not the renamed backfill.js
The core build entry `backfill` was renamed to `deepen` (deepen engine +
status), but the three wrapper build.mjs bundleFiles lists still copied the
removed `backfill.js`, so every dev-install failed with ENOENT. Point them at
`deepen.js` (spawned by seed.ts at runtime) so the installers build again.
* feat(coding-agents): periodic re-survey — refresh structural pages every N commits
Structural knowledge pages are only generated on a cold repo, so an evolving
architecture drifts from what the survey captured. Add surveyRefreshCommits
(default 20; 0 = cold-seed only): at SessionStart, count commits reachable from
HEAD since the newest survey-baseline marker (branch-robust via
git.commitsSince) and re-run the headless survey once the threshold is crossed,
re-recording a baseline marker. Cold seed still records the first baseline.
* fix(coding-agents): per-turn hook timeout (30s) must exceed the 25s reflect cap
The once-per-session reflect is capped internally at HOOK_REFLECT_CAP_MS=25s,
but every harness killed the UserPromptSubmit/BeforeAgent hook at 15s — below
the cap. The host killed the hook mid-reflect before the cache write, so the
injection was discarded AND the reflect re-fired uncached on every turn
("UserPromptSubmit hook timed out after 15s" every prompt). Raise the hook
timeout to 30s (> cap) across claude/codex/gemini, bump Stop to 30 to match,
and document the cap-below-timeout invariant so it can't silently drift again.
* polish(coding-agents): attribution header is a bold blockquote callout, not flat text
The live directives all told the agent to credit memory with a plain inline
"From Hindsight memory (<page>):", which renders as flat text. Switch every
directive (session tool-guide, reflect injection, both MCP tool descriptions)
to a markdown blockquote header "> ... **From Hindsight memory (<page>)** — ..."
so it renders as a distinct callout, restoring the richer attribution look.
* fix(coding-agents): strip <hook_prompt> transport wrappers from retained transcripts (codex surfaces hook stdout/errors as user messages); session + backfill transcripts switch to JSONL (one turn per line — clean appends, chunker-atomic turns)
Note: benchmark numbers (n=3) were measured on the JSON-array format; JSONL
is extraction-equivalent by design but unvalidated by a sweep — gate before
quoting new numbers on this pipeline.
* fix(installer): write [features].hooks (codex_hooks deprecated in Codex >= 0.145); accept either flag as already-enabled
* fix(hooks): fire the ingestion engine from the FIRST prompt on every harness (lock-protected no-op when SessionStart already did) — safety net for sessions predating the install, whose banks otherwise never get pages; survey stays SessionStart-owned (ensureSeed hosts excepted)
* feat(status): expose survey observability — surveyBaseline (last surveyed HEAD, from Chris's survey-baseline markers) + surveyCommitsBehind in syncStatus/hindsight_sync_status
* test(status): expected shapes include the survey observability fields
* feat(survey): findings docs ARE the completion signal — surveyDocs (0-4) in syncStatus; a baseline without findings re-fires the survey at the next warm session start (crashed-survey retry)
* feat(config): banks.<bankId> overrides — per-repo opt-in/out applied AFTER bank resolution (disable a repo, tune gitIngest/retainSessions per bank) from the ONE config file; resolution fields ignored inside a bank section
* feat(config): bankAliases — remap resolved bank ids as the final resolution step (single hop, converging allowed); docs page brought fully current (env exceptions, gitIngest/logLevel/survey rows, banks overrides, aliases, resolution step 4)
* refactor(config): bank rename lives INSIDE banks.<id> as the field (separate bankAliases tree removed) — one per-repo section for disable, behavior, and rename; applyBankConfig returns {cfg, bankId}
* docs(coding-agents): recipe — two repos sharing one bank (converge by resolved id via banks.<id>.bank, or by path prefix via directoryBankMap), with the id-vs-path rule of thumb
* rename(config): directoryBankMap -> mapPathToBank (direction-explicit; pre-0.9.0 breaking-rename window)
* feat(coding-agents): companion skill — hindsight-coding-agent SKILL.md shipped in the package and installed into ~/.claude/skills by the installer; explains storing/retrieving, full config (banks/mapPathToBank/gitIngest), install/update, and debugging
* docs(coding-agents): mention the companion skill in README + docs page
* feat(coding-agents): companion skill ships to ALL skills-capable hosts (claude/gemini/cursor native dirs, codex via ~/.agents/skills standard); retained sessions and ingested documents carry the harness as tag (harness:<name>) and metadata
* feat(skill): self-updating companion skill — every session start re-syncs installed copies with the packaged SKILL.md (presence-gated; npm update -g now updates the skill too, no re-install)
* fix(coding-agents): worktree-aware document ids (no more per-worktree gitlog duplicates) + deepen self-cleanup; issue/PR refs preserved verbatim and emitted as ENTITIES; calibrated reflect-injection wrapper; docs ported to the TRUE source (hindsight-docs/docs-integrations) that generates the skill copy
* docs(skill): explain the internal marker documents (survey-baseline:<sha> bare-sha content is deliberate — zero extracted facts; gitlog:<repo> seed doc)
* feat(survey): human-readable baseline markers under a zero-extraction marker strategy (live-verified: 0 facts) — start as researching, deepen lazily flips to completed once findings exist
* refactor(survey): one survey strategy with conditional rules replaces the separate marker strategy — status markers extract nothing, findings extract structural facts (both branches live-verified)
* fix(hooks): mid-session heal — zero knowledge pages in the roster cache fires the ingestion engine on any prompt (covers long-lived sessions predating the install; lock makes repeats free)
* feat(bank): ~ expansion in mapPathToBank; document the directory-blacklist recipe (map tree to one bank + disable it)
* feat(coding-agents): explicit correction protocol — when the agent verifies a memory is wrong/stale it ingests a 'Correction: <topic>' doc (claimed vs verified-true vs evidence); guidance in the injection wrapper, tool guide, tool description, and companion skill
* fix(hooks): reflect block injected exactly once — cadence re-injection dropped (replaying the turn-1 synthesis at arbitrary turns reads as random noise after drift; hindsight_reflect covers genuine re-need)
* fix(coding-agents): 15s hard timeout on every client request + opencode boot no longer awaits seedIfCold — a stalled memory server can never freeze the host TUI (onPrompt already tolerates a late preamble)
* fix(reflect): defer past trivial openers — a greeting no longer spends the once-per-session synthesis on 'hi' (seen live: reflect answered a greeting with persona chatter and burned the session's slot); first substantive prompt reflects instead
* test(hooks): align reflect-call assertions with the non-trivial fixture prompt
* Revert trivial-prompt reflect deferral (misread the report — the issue was the notice's UI position, not reflect-on-greeting behavior)
* fix(opencode): stop writing banner/reflect notices to stderr — opencode renders plugin stderr inside the TUI at the cursor (text wedged against the input bar); the trail moves to the plugin log
* feat(opencode): TUI companion plugin — visible presence via api.ui.toast (opencode's TUI plugin API): banner toast on activation + reflect goal/preview toasts from the plugin-log trail; installer registers the second entry
* fix(opencode): visible presence via the server client's tui.showToast (POST /tui/show-toast) — banner + reflect toasts from the server plugin; the separate TUI module approach removed (1.18.9's loader rejects tui-only entries in the shared plugin list); SDK deps bumped to 1.18.9
* fix(opencode): toasts never rendered — v1 client wants {body}, and boot toast raced TUI mount
opencode injects the v1 SDK client whose showToast signature is {body: {title,
message, variant, duration}} and which resolves with {data|error} instead of
rejecting — the earlier flat-params call sent an empty body and the failure was
invisible. Also the toast event is not durable: the seed banner on a warm bank
fired <1s after plugin init, before the TUI subscribed, and was lost. Toasts now
use the body shape, log a rejected result at debug, and defer until ~3s past
init. Verified live in tmux: boot banner and reflect toast both render.
* fix(coding-agents): reflect must report history, never issue directives
The 0.8.6-blog incident: reflect fused two true but unrelated facts (the
hermes-deprecation goal and the blog-section removals of c87e7ac19) into one
confabulated narrative rendered in the imperative — 'You should explicitly
remove the following sections' — a completed past action re-issued as a present
directive, indistinguishable from a prompt injection to the receiving agent.
Three changes:
- buildReflectQuery wraps the session's first prompt with strict rendering
rules: declarative past-tense attributed facts only, no instructions or
recommendations, no stitching unrelated episodes into one narrative.
- The <hindsight_memory> wrapper now states the block is a record of the past
that never assigns tasks: imperative wording inside it is a description of
work already done, to be ignored unless it informs the task as historical
fact (and unrelated memories are still ignored outright).
- The reflect_ok diag event records the injected synthesis verbatim (8k cap),
so the next incident is one grep instead of harness-transcript spelunking.
* refactor(coding-agents): read and seed knowledge pages through the knowledge-base API
The plugin advertised knowledge pages but drove them off /mental-models, so the
two halves of the feature never met: pages seeded via the bank template's
mental_models key got a mental model and no knowledge_pages node, and
/knowledge-base/search joins through that table — the five seeded pages were
absent from the corpus of the tool billed to the agent as its FIRST STOP. The one
page search could return (an initiative, created through the KB endpoint) came
back as a kp-… node id, which the reader then fed to GET /mental-models/{id} and
404'd. Search found only what read could not open.
Every page operation now speaks one id space:
- listPages reads /knowledge-base/tree and flattens it to {items:[…]}, dropping
folders and keeping the containing folder name.
- getPage reads /knowledge-base/pages/{id} — the ids search and [[page:<id>]]
links already hand back.
- seedPages replaces the template's mental_models key: it creates the PAGES
taxonomy through /knowledge-base/pages and re-syncs a drifted source_query via
PATCH /knowledge-base/nodes/{id}, so a plugin upgrade that rewords a query
lands on the live page instead of orphaning its synthesized content. Matched by
name, since the endpoint mints its own id; a 409 from a concurrent deepen run
is tolerated rather than failing the run.
- createPage/updatePage/deletePage are deleted — mental-models CRUD with no
callers outside its own tests.
Verified against a live server on a scratch bank: five real kp- nodes, re-run
reports 0 created / 5 unchanged, all five readable by their listed id, all five
now returned by /knowledge-base/search, and a hand-drifted source_query restored
onto the same node rather than a duplicate.
* feat(coding-agents): autoReflect flag — opt out of injected reflect into tool-only mode
autoReflect (default true, layerable per-harness/per-bank like every other
field) keeps today's validated behavior: one reflect synthesis injected on the
session's first prompt. Set false and nothing is injected; instead the
knowledge preamble and every roster refresh carry an explicit trigger telling
the agent to call hindsight_reflect itself whenever a new task/goal is set —
the pull-based variant, ready to benchmark against the push default.
* docs(blog): move the 0.9.0 launch post to its own PR
The draft now lives on blog/0-9-0-launch so this PR merges independently of
launch timing (hero image, publish date, and final voice pass pending there).
* fix(deepen): dead-holder locks are stale immediately, not after 30 minutes
The per-bank deepen lock only honored its TTL: a killed run (SIGKILL, crashed
harness) left its bank locked for LOCK_STALE_MS, and every subsequent deepen
exited 'another run holds the lock — nothing to do' against an empty bank.
The lock already records the holder's pid — probe it (kill -0); if the holder
is gone the lock is stale now. Found live: a killed benchmark ingestion left
four banks locked and the retry campaign polled empty banks to its deadline.
* feat(coding-agents): expand native harness support
* fix(reflect): table-shaped decisions must be reproduced verbatim, not summarized
Benchmark replay showed reflect compressing mapping/table policies into prose
('specific extensions map to specific types') and even asserting a lossy
generalization that matched a known-wrong fix — while rule-shaped policies
survive intact. The reflect query now demands complete verbatim enumeration of
mappings/sets/tables including carve-outs.
* fix(reflect): decisions outrank implementation-derived memory
Under heavy retrieval noise, reflect surfaced the git-ingested BUGGY module
source as 'the established implementation logic' while claiming no decision
records existed — presenting the bug under investigation as authority. The
rendering rules now state: report decisions and rationale, never the current
implementation (the reader has the code); when decision memory and
code-derived memory conflict, the decision wins; implementation-only matches
are not policy.
* feat(coding-agents): expand harness integrations
* Expand coding-agent integrations and legacy compatibility
* chore(coding-agents): fix the CI-only test failure and complete the release wiring
The `test-coding-agents` job failed on every run while passing locally: the
gitDiffTarget fixture committed into a temp repo without a git identity, which a
developer machine supplies from its global config and a CI runner does not
("empty ident name not allowed"). The identity is now passed per-command, the
way the harness E2E fixture already did it.
Release wiring, which was incomplete in three places that each fail at a
different point:
- scripts/release-integration.sh had no entry, so the release refuses to start.
- generate_changelog.py keeps its OWN integration list; the release script
aborts and reverts at the changelog step when a name is missing there.
- The docs build cross-checks released tags (`integrations/<name>/vX.Y.Z`)
against the SLUGS in integrations.json. The directory was the only
integration carrying a `hindsight-` prefix, so the tag would have been
`integrations/hindsight-coding-agents/...` against a `coding-agents` slug —
green release, then a failing docs build. The directory is renamed to
`coding-agents` so directory, integration name, tag and docs slug all agree,
matching every other integration.
Also drops the claude-code-v2 / codex-v2 / gemini-v2 wrappers and the
hindsight-memory-v2 marketplace entry. Claude Code is fully served by
`hindsight-coding-agents install claude-code` — hooks, MCP and skill — so the
wrappers were a second copy of the same core with its own version to keep in
lockstep. The README rows that pointed at their dev-installers now name the
supported installer command instead.
* fix(coding-agents): make the installer actually re-point a moved package
Both bugs were exposed by the directory rename, which invalidated the absolute
paths every host config stores — the case `install` exists to repair.
- Grok wrote its block only when one was absent, so every later `install` was a
silent no-op and the dead paths survived; the only repair was editing
config.toml by hand. It now replaces the block, sharing one regex with
uninstall.
- MARKER was the full package name, which identifies our entries for
dedupe-on-reinstall and for uninstall. A repo checkout stopped containing it
once the directory dropped its `hindsight-` prefix, so from a checkout
re-installs would have accumulated duplicate hook entries and `uninstall`
would have removed nothing. Narrowed to the substring both layouts share.
Regression tests cover a moved package being repointed (not appended past), the
marker matching npm and checkout paths, and a repeated checkout install leaving
one entry per event.
---------
Co-authored-by: Chris Latimer <[email protected]>
The previous cover read as a context-free "10 things to look for." New cover
keeps the editorial template but leads with the subject ("Evaluating / agent
memory") and moves the listicle framing into a "THE 10-POINT CHECKLIST"
eyebrow, so the topic is clear at a glance.
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* blog: How to Actually Evaluate an Agent-Memory System
A buyer's-guide / evaluation-framework post: the write→store→manage→read
lifecycle, the dimensions that matter (retrieval beyond similarity, entity
resolution, conflict updates, freshness, test-time learning), the production
dimensions most guides skip (data ownership, PII/secret security, cost,
observability, multi-tenant scoping), how to read LongMemEval, and a
copy-paste checklist. Editorial deep-dive cover.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* blog: retitle to "The 10 Things to Look For", swap LongMemEval→BEAM
Reviewer feedback:
- Drop "(2026)" from the title (blog posts don't use a year; that's the
/articles convention).
- Retitle to the listicle framing "The 10 Things to Look For in an
Agent-Memory System"; number the dimensions table and checklist 1–10 so the
count is honest and consistent.
- Reframe the benchmark section around BEAM (10M-token tier) instead of
LongMemEval, kept loose — the takeaway is "build your own eval on your
domain." Remove LongMemEval-specific competitor scores.
- New editorial cover ("10 things / to look for", CHECKLIST tag).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* blog: drop unverified BEAM "next-best 40.6%" comparison
The agentmemorybenchmark.ai leaderboard only lists Hindsight at the 10M tier
(64.1%, verified). The 40.6% next-best figure isn't on that leaderboard, so
state only the verifiable number and leave the fuller comparison to the
beam-sota post.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
`/v1/default/banks` exposed only `last_document_at` (MAX of
`documents.created_at`), so a bank whose long-lived document keeps
receiving appends looked idle: ingestion time never moves, and
`banks.updated_at` only tracks name/mission edits. UIs reading either as
"last write" showed hours-old activity while memories were still landing.
Add `last_write_at` to the bank list — the newest of "a document was
(re-)retained" (`documents.updated_at`) and "a fact was stored"
(`memory_units.created_at`) — and order the list by it. `last_document_at`
keeps its ingestion-time meaning and is now documented as such. The
control-plane bank selector shows and sorts by the new field.
Same symptom on the documents list (reported in #2944): it was ordered by
`created_at DESC`, burying an actively-appended document behind every
document created after it. It is now ordered by `updated_at DESC`.
Fixes#2944
Split update_memory_unit into a read/resolve/embed phase (no pooled connection held) and a short write transaction that re-reads the row, applies the precomputed embedding, and re-embeds in-txn only on a concurrent entity-set change; orphan entities from a failed edit are reclaimed by a forced graph-maintenance sweep. Preserves the pluggable store's begin_txn/decide_txn write-group.
Validated by CI (all three test-api shards incl. the live-PG curation suite pass). Follow-up to #3082. Refs #2434.
Adds a `preferObservations` plugin config flag (default false, backward
compatible). When enabled it forwards `prefer_observations: true` to the
recall API, which drops raw facts already consolidated into an observation
while keeping unconsolidated ones. Paired with a `recallTypes` that includes
raw types, this surfaces just-retained facts before consolidation catches up
(e.g. a /reset followed by "what did I just say?") without duplicating
already-consolidated content.
The flag requires the recall option added to the client in #2311, so bump
the plugin's @vectorize-io/hindsight-client dependency ^0.6.2 -> ^0.8.6.
Also fixes a stale integration test that #3066 missed when it flipped the
default recallInjectionPosition to 'user': the E2E suite only runs on
non-fork PRs, so #3066 (a fork PR) never exercised it and the assertion
kept expecting the old prependSystemContext placement. Updated it to expect
the new default prependContext, matching the sibling tests #3066 did update.
Closes#2977
Several memory-engine paths held a pooled PostgreSQL connection checked out
for the entire duration of a slow external call (embedder/LLM). The pools are
already bounded and per-process, so this is saturation, not a leak: enough
concurrent operations park the pool on multi-second calls and everything else
blocks on acquire.
This covers the two paths that can be fixed without widening the read→write
window unsafely:
- update_mental_model: compute the embedding BEFORE acquiring a connection.
The embedding text depends only on the incoming name/content, never on DB
state, so it needs no connection.
- consolidation: _process_memory_batch and its executors/dedup helpers no
longer receive a long-lived connection. Recall, the batch LLM call, every
per-action embed, and dedup adjudication run with NO connection held; each
helper self-acquires a short-lived connection only around its own SQL.
Moving the slow calls off the connection widens the decision→write window,
so the held-transaction serialization is replaced with explicit guards:
each source-liveness check (FOR SHARE) is paired with its write in one short
transaction, and dedup CREATE/UPDATE folds are RETURNING-gated and re-filter
live sources inside the fold transaction (sources-before-observation lock
order, matching the normal write paths) so a twin or source deleted during
the now connection-free window can't drop a CREATE or fold a dead source id.
A cheap non-locking preflight restores the pre-refactor "skip before embed
when every source is already gone" short-circuit. The separate-store
(non-SQL) branches and the Oracle-safe search_vector clause are preserved.
Deterministic no-DB tests pin the fold guards (RETURNING gate, live-source
filtering, created/skipped propagation) and the pre-embed short-circuits;
live-DB curation/invalidation/document-transfer tests are updated to the new
short-acquire signatures.
The update_memory_unit hold-across-embed path is intentionally left for a
follow-up: its two-phase re-lock/abort/retry has to be reconciled with the
pluggable memories store's cross-store transaction coordinator and validated
against a real database.
Refs vectorize-io/hindsight#2434
The recall API already supports `include: {chunks}`, and the TypeScript
client already exposes it as `includeChunks`/`maxChunkTokens`, but the
agent tool forwarded only `{maxTokens, types}` — so an agent had no way
to reach the raw source text a fact was extracted from, which is exactly
what "what did we actually say" questions need.
Add optional `include_chunks` / `max_chunk_tokens` parameters and pass
them through. Both are additive and off by default, so recall responses
are unchanged unless an agent asks for chunks.
Fixes#2949
Default recalled memories to user context so dynamic recall content no
longer invalidates the stable system prompt prefix on every turn.
Keep explicit prepend and append settings unchanged. Align the manifest,
docs, and tests with the cache-friendly default.
Closes#3061
* feat(control-plane): badge documents that a retain op is updating
Cross-check the documents table against pending/processing retain operations:
when an in-flight op targets a document already in the list, that document is
being rewritten — badge its row as 'Updating' (with a spinner) and poll until
the op finishes, then refresh its content.
Operations already expose document_id, but only file uploads populated it.
Populate result_metadata.document_id for single-document retains too (engine:
BatchRetainParent/ChildMetadata + submit_async_retain), so reprocesses and
single-document async retains surface their target. Multi-document batches leave
it unset (matched per single-document child) to avoid misattributing a row. No
API response-shape change, so no client/OpenAPI regen.
Adds 'documentUpdating' to all 10 locales and two engine regression tests.
* feat(control-plane): auto-detect updating documents without a reload
The badge previously only appeared once an in-flight op was already detected,
and detection only ran on load / bank-switch / upload-refresh — so from an idle
table you had to catch the moment or reload. Run the (light) operations check on
every poll tick while the view is open; keep the heavier document refresh gated
to when something is actually in flight. Also kick detection right after a
reprocess so its badge shows immediately.
* feat(control-plane): soften the updating badge + auto-refresh the docs table
Badge: drop the spinning icon for a gentle pulsing dot on a soft neutral (muted)
pill instead of the loud saturated-blue spinner.
Table: auto-refresh on a timer (every 8s idle, 4s while something is in flight)
so new/updated documents, counts, and badges appear without a manual reload —
not only while an op is already detected in flight.
* feat(control-plane): show last-refresh time next to the documents count
Stamp the wall-clock time on each list refresh and render it beside the count
('N total documents · Refreshed 14:41:32') so the auto-refresh is visible. Adds
'lastRefreshed' to all 10 locales.
* feat(control-plane): relative last-refresh time, baseline-aligned
Show the refresh time as a live relative label ('Refreshed 3 seconds ago') that
ticks every second — a self-contained component with its own 1s ticker so only
the label re-renders, localized via Intl.RelativeTimeFormat (no per-unit i18n
keys). Baseline-align the count row so the smaller label lines up with the
count text.
#3079 resolved `metadata.harness` to a logo, but registered only the five ids
hindsight-coding-agents emitted at the time. That integration (#2522) now ships
ten, so the majority of harnesses fell back to a raw `harness=<id>` metadata chip
— the exact thing the logo was introduced to replace.
Register the full emitted set, taken from both places that define an id:
`src/harness/hook-lifecycle.ts` (one HookSpec per hook-driven agent) and the
persistent-plugin entrypoints in `src/harness/registry.ts`, whose id is their
`createPluginEntry(...)` argument. New: `antigravity-cli`, `cline-cli`,
`copilot-cli`, `devin-cli`, `grok-build`, `kilo`.
Icons come from `hindsight-docs/static/img/icons/` where the docs site already
carries the brand (Cline, GitHub Copilot, Devin, Grok). It carries none for
Antigravity or Kilo, so those are the vendors' own marks; the registry comment
and CLAUDE.md now say that is allowed rather than implying the docs dir is the
only source.
`gemini` stays registered even though the integration replaced that harness with
`antigravity-cli` and nothing emits it any more: documents retained while it did
are still in people's banks and should keep their logo. The test that pins the
registry to the emitted set now carries that as an explicit RETIRED list, so a
speculative id still can't sneak in.
Monochrome dark-on-transparent marks (Cline, Copilot, Devin) get `dark:invert`.
Grok deliberately does not — it is a filled black tile with a white glyph, so it
reads on dark already and inverting would burn a white square into the row.
Verified all eleven at 16px against both themes.
Move the GitHub Copilot CLI persistent-memory post to today's date to align
with the 0.1.1 release and social launch. Renames the file and updates the
slug and date to 2026/07/30 (URL changes from /2026/07/29/... accordingly).
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* fix(copilot-cli): parse Copilot CLI 1.0.76 native message transcript format
Copilot CLI >= 1.0.76 writes session transcript events as dotted event
names — `{"type":"user.message","data":{"content":"..."}}` and
`assistant.message` — with the message text under `data.content`. The
transcript parser only recognized the older flat / SDK-envelope / role-nested
shapes, so it extracted zero messages from current Copilot transcripts.
Because the failure is silent (hooks load, fire, and exit 0; the parser just
returns an empty list and retain skips with "No messages in transcript"),
auto-retain quietly stopped persisting anything to the bank on newer Copilot
builds.
Teach `_parse_transcript_entry` to read the native `user.message` /
`assistant.message` envelope, using the clean `data.content` (not the sibling
`transformedContent`, which carries injected system reminders). Add a
regression test with a 1.0.76-shaped transcript asserting messages are
extracted and the reminder-laden transformedContent is ignored.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* release(copilot-cli): 0.1.1 — transcript parser fix + changelog
Bump hindsight-copilot-cli to 0.1.1 for the Copilot CLI 1.0.76 transcript
parser fix, and add a CHANGELOG.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* fix(control-plane): stop next-intl parsing 'type:<x>' tag hint as an unclosed tag
The Tags hint used 'type:<x>', which next-intl reads as an unclosed rich-text
tag (INVALID_MESSAGE: UNCLOSED_TAG), crashing the create/edit page dialog.
Replace the angle-bracket placeholder with 'type:…' across all locales.
* refactor(control-plane): replace loading-emoji hourglasses with a shared Spinner
The UI used a spinning ⏳ emoji for loading in several places — inconsistent and
not accessible. Add a shared <Spinner> (wrapping lucide Loader2, sized xs–xl,
role=status) and use it for all 7 loading states: the large centered
'loading…' placeholders (documents / document / chunks / chunk-modal) and the
inline save-button spinners (tags / content / edit-memory).
* feat(control-plane): branded tumbling-logo spinner for loading states
Add a LogoSpinner that renders the Hindsight mark doing a looping 2D
'tumble' (crouch → hop + 360° flip → land squash), ported from the motion
lab. The hop is expressed as a % of the element so one keyframe scales
across sizes, and reduced-motion falls back to an opacity pulse.
Use it for the prominent centered loading states (documents list, document/
chunk modal); the compact lucide Spinner stays for tiny inline spots.
* feat(control-plane): make the tumbling logo the shared spinner everywhere
Fold LogoSpinner into the shared Spinner so every loading state renders the
Hindsight mark, and swap all remaining ad-hoc spinners (lucide Loader2, the
hand-rolled ring-<div> spinners, the sonner toast loader, and the two
RefreshCw-as-loader stand-ins) over to it — ~65 sites across 22 files.
Spinner now has two motions:
- variant "flip" (default): an in-place 360° flip + squash, safe inline and in
buttons (only a tiny vertical bob, stays on the text baseline).
- variant "jump": the full tumble (crouch + hop + flip), for prominent centered
loaders that have vertical room.
RefreshCw icons that spin only while refreshing are left as-is — a spinning
refresh arrow reads as "refreshing", which is distinct from a generic loader.
* fix(control-plane): show the loader (not empty state) on Documents, and finish the spinner sweep
Documents: the mount fetch is debounced, so the empty state ("No documents
found" / "0 documents") flashed before the spinner. Track a `loaded` flag and
gate the empty state + count on it, so the loader shows until the first fetch
resolves. Also swap the 📄/📊 emoji empty states for lucide icons.
Finish converting the loaders the first sweep missed (they used non-spinner
patterns, so grepping for Loader2/animate-spin didn't find them):
- pulsing Clock full-view loaders → jump Spinner (stats page, bank profile)
- emoji + text-only loaders (entities graph/list/linked-memories, llm-requests
and audit-logs chart loaders) → Spinner
- emoji empty states (no chunks / no entities / no data) → lucide icons
* fix(control-plane): render the Documents loader on first paint (hard refresh)
On a hard refresh, bank-context starts currentBank=null and only resolves it
from the URL in an effect (after the first paint, before hydration + theme), so
the previous `!!currentBank` guard made the empty state win the very first
render — you'd see "No documents found" flash before anything else.
Gate the loader on `!loaded` alone. currentBank always resolves on a
/banks/[id] route and the fetch's finally flips `loaded` (even on an invalid
bank whose fetch errors), so it can't get stuck. Verified: the SSR HTML now
renders the loading Spinner, not the empty state.
* fix(control-plane): apply theme before first paint (no light flash on hard refresh)
ThemeProvider only reads the saved/system theme in a useEffect (after paint), so
a dark-mode user saw a light flash on every hard refresh. Add a tiny blocking
inline script as the first <body> child that sets the .dark class synchronously
before the content paints — the standard anti-FOUC pattern (what next-themes does
internally). <html> already has suppressHydrationWarning for the class mutation.
Logic mirrors lib/theme-context.tsx exactly (saved || system).
* feat(control-plane): add the tumbling mascot to the no-bank welcome screen
Loop the jump Spinner above 'Welcome to Hindsight' as a friendly greeting on
the dashboard shown when no bank is selected.
* feat(control-plane): spin the header logo on sidebar navigation
Clicking a sidebar item now gives the header Hindsight logo a one-shot 'spin
round' — a little playful nav feedback. The sidebar dispatches a
'hindsight:logo-spin' window event (decoupled, like DOCUMENTS_REFRESH_EVENT) and
the header listens and toggles a one-shot animation, cleared on animationEnd.
The logo is a wide lockup, so a 2D rotate would swing it vertical and overflow
the header — use a rotateY card-flip that stays within its footprint instead.
* feat(control-plane): spin only the logo mark (not the wordmark) on navigation
Split the header lockup into two pieces: the octopus mark (favicon.png, a
standalone image so it can rotate freely) and the 'Hindsight' wordmark (the
right slice of the full logo.png, shown via a cropped background). Their widths
sum to the full logo so they butt together seamlessly. Only the mark carries the
one-shot spin, so the wordmark stays put.
Because the mark alone is ~square, the spin is now a clean 2D rotate (reverted
the rotateY card-flip workaround that the wide full lockup had required).
* feat(control-plane): soften logo nav feedback from a spin to a subtle wiggle
A full 360 rotate was too much. Replace it with a small tilt that springs back
(logo-wiggle, ~450ms) on the mark — less impactful but still a bit of life.
* chore(control-plane): drop the dead logo-spin-once reduced-motion block
Leftover from the rename to logo-wiggle.
* style(control-plane): apply prettier formatting to the spinner-sweep files
Ran scripts/hooks/lint.sh — the earlier commits were eslint-clean but not
prettier-formatted, which tripped verify-generated-files.
The candidate query in `_trigger_mental_model_refreshes` gated on the mental
model's `tags` column, but a model's refresh scope is whatever
`_resolve_refresh_tag_filtering` resolves. Two configurations put untagged
memories in a *tagged* model's scope, and both were silently starved:
- `trigger.tags_match` "any"/"all" — non-strict matching ORs untagged rows in
- `trigger.tag_groups` — overrides the tags column entirely
Such a model reported stale forever and was only ever refreshed when some
unrelated tagged memory happened to be consolidated.
Both branches now prefilter on "can this model's scope reach untagged
memories?" instead of on the column. A tagged model left on the default
`all_strict` is still excluded — strict matching drops untagged rows, so an
untagged-only consolidation genuinely cannot make it stale, and refreshing it
would burn an LLM call to regenerate identical content. The final gate is
unchanged: `compute_mental_model_is_stale` evaluates the resolved scope, so
widening the prefilter cannot produce spurious refreshes.
The predicate uses `trigger ? 'tag_groups'`; the Oracle rewriter's key-exists
regex only matched unquoted columns, so it missed `"trigger"` (already quoted
as a reserved word by that point) and left the operator untranslated.
Stage the canonical repository license in each isolated Python build
context so wheels and source distributions include the MIT text.
Declare SPDX license metadata and verify every release artifact before
publishing to prevent repository firewalls from quarantining packages.
Closes#3054
Documents retained by hindsight-coding-agents carry the agent that wrote them
as `metadata.harness` plus a `harness:<id>` tag, but the UI rendered that as
just another `key=value` chip — indistinguishable from `session_id` while
scanning a column of near-identical `conversation:<uuid>` IDs.
Resolve the value to a logo instead:
- documents table: the mark trails the "Updated …" line (leading the ID shifted
every row that had no harness), and the now-redundant `harness=` metadata
chip is dropped — the `harness:<id>` tag stays, since clicking it filters
- document dialog: logo in the title, plus a Harness row
- memory dialog: a Harness card in the Document tab, next to the document's
tags — memory units inherit the document's metadata at retain time, so no
second lookup is needed. That tab also gained the document's metadata,
rendered with the shared MetadataChip
The registry holds exactly the ids that integration emits (claude-code, codex,
cursor-cli, gemini, opencode; see its src/harness/hook-lifecycle.ts) and a test
asserts it stays in step — an id nothing writes is a logo nothing renders. An
unregistered harness is not an error: no logo, value still shown as metadata.
Monochrome marks are flagged so only they get `dark:invert`; multi-colour ones
are left alone.
Allow MarkItDown OCR clients to receive operator-defined default
headers for proxy routing and request tracing.
Wire the JSON environment setting through parser construction, document
the option, and cover configured and unset behavior.
The standalone hindsight-hermes pip plugin fails on current Hermes builds
with "Timeout context manager should be used inside a task" (an upstream
hermes-agent tool-dispatch bug). Hermes now ships a native Hindsight memory
provider, so mark the old plugin deprecated instead of chasing the upstream bug:
- Add a deprecation warning admonition pointing users to the native
provider and the existing migration guide.
- Reword the Architecture section from plugin/entry-point language to the
native provider.
- Drop the plugin-specific "Plugin not loading" entry-point troubleshooting.
Regenerated the hindsight-docs skill mirror.
* feat(knowledge-base): self-curating knowledge base (OKF pages + folder missions)
Server-side knowledge base: a hierarchy of folders and pages over mental
models, projected to the Open Knowledge Format, with a mission-driven curator
that maintains pages automatically after each consolidation.
- knowledge_pages table (PG + Oracle): parent_id tree, kind folder/page,
mission, managed, last_curated_at; partial unique index on (folder, name)
for concurrency-safe dedup; added to BACKUP_TABLES.
- api/okf.py: OKF serializer (frontmatter + body, index/log, constellation graph).
- engine/knowledge_curator.py: folder curator (LLM op plan + safe apply); reads
new memories since last curation (delta, not recall); ops create/merge/delete
page + spawn sub-folder (bounded depth<=3, <=8). Runs as an async curate_folder
task on folder/mission create and after consolidation. Curator pages use an
observation-only delta trigger with exclude_mental_models.
- MemoryEngine: folder/page CRUD, tree, curate, async submit + worker handler.
- /v1/default/banks/{bank}/knowledge-base/* endpoints.
- Control plane: knowledge-base tree view + constellation toggle, missions,
OKF page panel + bundle export; proxies, client, sidebar, i18n.
- Tests: okf unit, knowledge-base HTTP, curator apply + dedup guard, hs_llm_core e2e.
- Regenerated OpenAPI + SDK clients + docs-skill.
* feat(hindsight-fs): mirror a bank's mental models as a live local folder
Add @vectorize-io/hindsight-fs, a CLI under hindsight-tools/ that mirrors a
Hindsight bank's mental models as real markdown files (YAML frontmatter + body)
in a local directory, refreshed from the API on an interval. Once mounted,
ordinary shell tools (ls, cat, grep, find, ...) work against current memory.
- Pull-based sync engine: full list each tick, write changed/new/tampered
files, skip unchanged (content-hashed), prune deleted models. Atomic writes;
a transient API error never wipes the mirror.
- One-way mirror enforced two ways: files are read-only (0444) so agent edits
fail with EACCES, plus a tamper-revert backstop that compares on-disk bytes
and overwrites drift on the next pass. --writable opts out.
- Commands: mount/start/stop/restart/sync/status/list/logs/unmount. Background
daemon via detached process + pidfile; per-mount config is remembered.
- status doubles as a healthcheck: --json report and a non-zero exit when the
mount is dead/failed/stale (--stale-after overrides the threshold).
- Tests: unit (sync engine, frontmatter, health) + e2e that spawns the real
CLI against a mock API and exercises real bash commands. 26 tests.
* refactor(hindsight-fs): mirror the knowledge-base tree, not mental models
Re-point hindsight-fs at the knowledge base so it projects a bank's folder/page
hierarchy as nested directories + .md files, instead of a flat list of mental
models.
- client: fetch GET /knowledge-base/tree + /export (two calls, any bank size)
and join by page id; replaces the paginated mental-models list.
- format: planMirror() walks the tree into folder dirs + page files at nested
paths (slug per segment, collision-safe); pages render the page's OKF doc.
- sync: create folder dirs, write pages at nested paths, prune removed pages and
emptied folders; state keyed by relative path + tracked dirs.
- config/cli: drop the mental-model `detail` flag; `list` prints folders+pages;
help/README updated. Tests rewritten for the tree/export model.
Verified live against a bank's knowledge base: the `people` folder mirrors to
people/anna.md + people/marco.md with OKF frontmatter.
* refactor(knowledge-base): drop server-side curation + folder missions
The knowledge base is now purely client-managed (CRUD over folders/pages); the
server no longer auto-curates. Removes the folder curator entirely and the
folder `mission` concept, and leads the sidebar with Knowledge Base.
- Remove engine/knowledge_curator.py, the curate_folder task (handler + dispatch
+ submit_async_curate_folder / _bank_folders), the post-consolidation curation
hook, and the folder-create / mission-update curation triggers.
- Remove folder `mission` and `last_curated_at` (columns + engine + API + UI);
keep `managed` as a client-set flag. Migration a5b6 now adds `managed` only;
the last_curated_at migration is dropped and the unique-index migration
repointed. Single alembic head preserved.
- API: KnowledgeNode/CreateFolderRequest/UpdateNodeRequest lose `mission`;
PATCH node handles name/parent_id only.
- Control plane: sidebar leads with Knowledge Base (before Memories); remove the
mission field, edit-mission dialog, and mission display from the KB view.
- Delete the curator tests; regenerate OpenAPI + SDK clients.
* feat(knowledge-base): default pages to living-document trigger + 4096 tokens
Client-created pages had no server curation applying a trigger, so they fell back
to the plain mental-model default (no refresh, full mode, all fact types). Make a
knowledge page a living document by default: when the client omits `trigger`, use
observation-only + delta + exclude_mental_models + refresh_after_consolidation;
when it omits `max_tokens`, default to 4096 (vs the mental-model 2048). Clients
can still override either.
* feat(control-plane): bank Home dashboard, Knowledge tabs, Notion editor + memory Euler graph
A large control-plane pass on the knowledge base UX:
- Home dashboard (home-view): memory constellation + read-only knowledge-page
TOC (reuses the Pages tree) + recent documents + the bank-profile "Memory store"
card and "Memories by ingested time" chart (extracted as reusable exports).
Fixed-height top row so the constellation fills and the side cards scroll.
- Sidebar: add Home (first); order Home → Memories → Knowledge.
- Knowledge view: Pages / Mental Models sub-tabs (Mental Models moved out of the
Memories view). Pages tab is an Obsidian-style workspace — file-tree sidebar +
inline editor with open-page tabs; the generation prompt is tucked behind a
"How this page is derived" expander; a "Backed by N memories" line opens the
backing model's based_on via the existing mental-model detail modal. First page
auto-opens; deep-link via ?page=.
- Knowledge graph: reframed as an Euler/Venn of the source memories — nodes are
based_on memories, one translucent circle per page (overlaps = shared memories),
plus the memory graph's own edges. New Constellation venn mode (nodeGroupsFn /
groupColorFn / groupLabelFn) drawing overlapping per-group circles + pill labels.
Backend: knowledge_page_memory_graph endpoint (pages' based_on → memory nodes).
- Pages default to the living-document trigger (observation-only, delta, exclude
mental models, auto-refresh) + 4096 max_tokens.
- Documents: metadata badges are expandable (show all keys, not just 3).
- Regenerated OpenAPI + docs-skill.
* feat(cli): port hindsight-fs into the Rust CLI as `hindsight fs`
Rewrite the standalone TypeScript hindsight-fs tool as a native subcommand
of hindsight-cli. Mirrors a bank's knowledge base (folders + pages) to a
local folder of markdown files, one-way (API -> disk) with read-only files
and drift-revert, plus a detached background refresh daemon.
- new src/commands/fs/ module (client, format, sync, state, daemon,
health, config, paths) with unit tests for the pure logic
- subcommands: mount/start/stop/restart/sync/status/list/logs/unmount
- deps: reqwest blocking + sha2 + libc
- remove the TS package and its npm workspace entry
* feat(knowledge-base): drop the pages Graph view + polish the Pages UX
Client:
- Remove the Tree/Graph toggle and the whole graph branch (the toggle row
was the dead band between the tabs and the content).
- Tree rows: full-width page name + compact status dot (was a pill that
crushed the name to a few chars); float the hover actions so they no
longer reserve width; widen the sidebar (w-64 -> w-72).
- Borderless workspace card; solid sticky editor-tab bar (was bg-muted/20,
so scrolled body text bled through); tighter sub-tab spacing.
- Drop getKnowledgeBaseGraph + the /api/knowledge-base/graph proxy route
and the now-unused i18n keys (viewTree/viewGraph/graphEmpty).
Server:
- Remove GET /knowledge-base/graph, KnowledgePageGraphResponse, the
knowledge_page_memory_graph engine method + its helper, and the orphaned
KnowledgeGraph/palette code in okf.py.
- Regenerate OpenAPI + SDK clients + docs-skill.
* feat(knowledge-base): add hybrid GET /knowledge-base/search (BM25 + vector)
Doc-level hybrid search over a bank's knowledge pages, fused with Reciprocal
Rank Fusion in a single query — no reranker, tuned for latency (~sub-100ms
query on top of the embed).
- engine.search_knowledge_pages: vector arm (mm.embedding ANN) + BM25 arm
(mm.search_vector, the generated tsvector over page name+content) via
websearch_to_tsquery('english'), RRF-fused (k=60) in SQL. BM25-only
fallback when the query embedding is unavailable. Folders excluded.
- GET /v1/default/banks/{bank}/knowledge-base/search?q=&limit= with
KnowledgePageSearchResult/Response models (id, name, mental_model_id,
snippet, score, updated_at).
- tests: ranks the relevant page first, excludes folders, respects limit,
requires q.
- Regenerate OpenAPI + Python/TS/Go clients + docs-skill (Rust client has
no KB ops; the CLI's fs port uses raw reqwest there).
* feat(control-plane): wire knowledge-page hybrid search into the Pages sidebar
A debounced search box at the top of the Knowledge sidebar queries the new
/knowledge-base/search endpoint (BM25 + vector, RRF-fused). A non-empty query
swaps the folder tree for a ranked result list (name + snippet); clicking a hit
opens the page in a tab. Clear (×) restores the tree.
- new /api/knowledge-base/search proxy route
- client.searchKnowledgePages(bankId, q, limit) in lib/api.ts
- search box + results list in knowledge-base-view.tsx (reuses openPage)
- i18n: searchPlaceholder / clearSearch / searchEmpty + api.errors.knowledgeBase.search across all locales
* feat(control-plane): widen the Knowledge tree to 1/3 + show page tags inline
- file tree pane w-72 -> w-1/3 (content gets the other 2/3)
- render each page's tags as small chips under its timestamp in the tree
* feat(control-plane): let new pages set tags in the create dialog
The create-page dialog gains a comma-separated Tags field (wired to the
existing createKnowledgePage tags param); a type:<x> tag sets the page's
OKF type. i18n added across all locales.
* perf(control-plane): stop the home dashboard blocking on a 22MB graph
The memory constellation fetched limit=1000 (≈67k edges, ~22MB) and the whole
dashboard awaited it before painting. Now the light panels (stats/pages/docs)
render immediately and the constellation loads on its own (with a spinner) at a
200-node cap (~3.7MB). The full graph stays in the Memories view.
* feat(control-plane): add a 'View all' button to the home memory card
The memory-constellation card header gets a 'View all →' link to the Memories
(data) view, matching the Knowledge pages / Recent documents cards.
* feat(knowledge-base): edit a page's source query, tags, and token budget
PATCH /knowledge-base/nodes/{id} now also updates a page's options on its
backing mental model — source_query, tags, max_tokens — each applied only when
present. Changing source_query schedules an async refresh so the page rebuilds
against the new question.
- engine.update_knowledge_page + UpdateNodeRequest fields + endpoint wiring
- control plane: an "Edit" button on the open page opens a dialog (name /
source query / tags); tags pre-fill from the raw tree tags so the type:<x>
tag isn't dropped on save. i18n across all locales.
- tests: update options persist; empty PATCH is 400.
- regenerated OpenAPI + clients + docs-skill.
* refactor(knowledge-base): squash page migrations into one + drop OKF naming
- Fold the three knowledge_pages migrations (table / managed column / unique
page-name index) into a single a9b8c7d6e5f4 migration.
- Rename api/okf.py -> api/page_markdown.py and replace the "OKF" / "Open
Knowledge Format" terminology throughout (server, control plane, CLI, i18n)
with plain "markdown" / "page" wording — pages just render to markdown.
- Add the knowledge-base endpoints to the CLI OpenAPI-coverage skip list (they
live in the control plane UI / are mirrored by `hindsight fs`, no CLI cmd).
- Regenerate OpenAPI + clients + docs-skill.
* test(knowledge-base): rename test_okf -> test_page_markdown, drop dead graph tests
Follow-up to the okf.py rename + Graph-view removal: the test module still
imported the old `okf` module (breaking collection for the whole api test
suite) and still tested the removed tag-based knowledge_graph() builder.
* fix(transfer): classify knowledge_pages in export-bank (skip for now)
test_export_bank_covers_schema requires every BACKUP_TABLES entry to be
classified by export-bank. knowledge_pages is skipped: carrying its self-
referential parent_id tree needs a parents-first restore order that the generic
per-row _restore_rows doesn't provide (follow-up). Mental models are carried, so
the target can recreate the tree.
Squashes the feat/pluggable-memories-provider work into one commit.
- Carve the `memory_units` + link slice out from behind raw SQL into a pluggable
MemoriesExtension (engine/memories/), so a different engine (memlake) can own
memories, links, retrieval, consolidation and curation while documents, chunks,
banks and the entity registry stay in Postgres. The default PostgresMemories
keeps everything exactly where it was; every call site routes through the store
interface rather than branching on the implementation.
- Route recall (semantic+BM25+graph), scan/get, stats/counts, consolidation
writes, curation edits, bank/document deletion, entity postings and graph reads
through the store.
- Cross-store write-group transactions (begin/decide/mint/witness + recovery
sweep) so a store that keeps memories elsewhere commits atomically with the
Postgres side of a retain/consolidation/curation/delete.
- Documents & chunks: when the store owns a dedicated document store
(owns_document_store), a document's bulky extracted text + chunk texts move out
of Postgres into it (Postgres keeps thin rows: id, content_hash, chunk_index,
tags); reads overlay the text from the store; the original file goes through a
memlake FileStorage backend. All gated so the Postgres path is unchanged.
* docs: cover the reworked documents table in the 0.8.6 blog post
* docs: give the documents table its own section in the 0.8.6 blog post
* docs: add the documents table screencast to the 0.8.6 blog post
* docs: replace the 0.8.6 blog GIFs with 30fps MP4 video
* blog: Give GitHub Copilot CLI a memory of your codebase
Tutorial for hindsight-copilot-cli (published, v0.1.0): persistent memory
for GitHub Copilot CLI via hooks. Recall on sessionStart, retain on
agentStop/sessionEnd, subagents seeded with baseline project memory.
Grounded in the integration source; documents the once-per-session recall
limitation honestly.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
* blog: co-brand Copilot cover with the official GitHub Copilot mark
Add the GitHub Copilot logo (top-left lockup + terminal title bar) so the
cover reads as a Copilot x Hindsight co-brand.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
* docs: changelog and blog post for v0.8.6
* docs: focus 0.8.6 blog post on new features
* docs: lead 0.8.6 blog with the entity timeline
* docs: use entity timeline gif in 0.8.6 blog post
* docs: drop embedded-engine bullet from 0.8.6 blog post
* chore(docs-skill): sync openapi version to 0.8.6
Documents list
--------------
The documents table exposed only a document-ID search, even though
`GET /banks/{id}/documents` has supported `tags` + `tags_match` all along.
Wires those through the control-plane proxy and the client, and adds the
tag filter (with autocomplete and an any/all toggle) to the toolbar. Both
UI modes map to their `*_strict` variant, since the non-strict ones
deliberately include untagged documents and read as a broken filter.
Also fixes two things found while working on it:
- The filter toolbar lived inside the "has results" branch, so a filter
matching nothing removed the only means of clearing it.
- Two effects both called `loadDocuments`, one debounced and one not, so
every keystroke issued two requests.
The table is reworked around what it is actually scanned for: updated-at
moves under the document ID, created-at is dropped (it duplicated
updated-at for nearly every document, and both remain in the dialog),
tags and metadata share one column, and size / memory-units get fixed
right-aligned columns. `table-fixed` is what makes the declared widths
hold — under auto layout the long mono IDs sized the first column
themselves, so `truncate` never engaged.
Facet chips
-----------
Tags, entities and metadata were styled independently in each view: tags
were blue in the memory dialog, amber in the documents table and purple
in directives, while entities reused the tag blue so the two were
indistinguishable. The memories table had them inverted relative to the
dialog. `ui/facet-chip` is now the single place all three are rendered,
adopted across 13 components.
Colour does not carry the kind. Several revisions tried a saturated fill
per kind and each read as busy at chip size, duplicating what the `#` and
`key=` prefixes and the header legend already say. Kinds are separated by
form, over one quiet neutral treatment in three tonal variants; the brand
cyan is spent only on an active filter, as an outline.
Tokens live in globals.css so both themes resolve through the `.dark`
block. That also sidesteps a pre-existing issue: the app is on Tailwind
v4, where `dark:` compiles to a prefers-color-scheme media query, but
themes are switched with a `.dark` class and no `@custom-variant dark` is
declared — so literal `dark:` utilities only fire when the OS agrees.
That still affects ~115 utilities elsewhere and is left for a separate
change.
Layout
------
- Bank page used `min-h-screen`, so the page grew past the viewport and
scrolled the header and sidebar away instead of scrolling `main`.
- TagFilterInput put applied chips inline with the input and the match
toggle, which came apart past two or three tags. Chips now get their
own row, and `flex-1 min-w-0` is baked in: without it the block's
flex-basis was the max-content width of the chips row, so one long tag
collapsed the sibling search input to nothing.
Tailwind v4 changed the default meaning of `dark:`: it now compiles to
`@media (prefers-color-scheme: dark)` unless a `@custom-variant` says
otherwise. This app switches themes by toggling a `.dark` class on <html>
(lib/theme-context.tsx) and never declared one, so every literal `dark:`
utility was keyed to the OS setting rather than the in-app toggle — it
fired only when the two happened to agree, and never at all for a user on
a light OS.
The CSS-variable half of theming always worked, since the `.dark` block
overrides the tokens directly. That is what made this easy to miss:
backgrounds and foregrounds flipped correctly while ~145 literal `dark:`
utilities silently did nothing. They are almost entirely `dark:text-*-400`
lightened text plus `dark:prose-invert` for rendered markdown, i.e. exactly
the "make this readable on a dark surface" cases.
Measured on the LLM Requests table, the `success` badge
(`text-green-800 dark:text-green-300` on `bg-green-500/10`):
before 1.17:1 — effectively invisible
after 12.81:1
Every utility affected was audited: all 145 are dark-appropriate values
(lightened text, darker `bg-*-900/30` fills, stronger borders,
`prose-invert`). None were tuned to compensate for the variant being
inert, so switching it on corrects them rather than inverting anything.
Contrast was re-checked across the affected elements — on the bank config
page, all 25 elements carrying a `dark:` class pass at 7.02:1 or better.
Verified with a production build, since `@custom-variant` is parsed at
build time.
Mirror the TypeScript wrapper fix (#3042) on the Python side: the
hand-written Hindsight wrapper's list_mental_models forwarded only
tags, and get_mental_model forwarded no query at all, so Python
consumers silently inherited the server's detail=full default and
could not use tag-match or pagination — even though the generated
MentalModelsApi already supports all of them.
Forward tags_match/detail/limit/offset on list_mental_models and
detail on get_mental_model, and add mapping regression tests so a
refactor cannot restore the dropped controls.
Follow-up to #2975 / #3042 (Python-wrapper parity).
Apply the exact tag filter even when the requested tag list is empty.
This keeps mental-model retrieval aligned with facts and observations.
Add a regression test that verifies the generated query selects only the
untagged global scope.
* feat(reflect): add apply_all_directives to bypass directive tag scoping (#3031)
Directives are tag-scoped like memories: a reflect with no tags loads only
untagged directives, and tagged directives apply only when the request's tags
match. This is deliberate (isolation_mode), but it means an operator's
tag-organized directives silently never reach an untagged reflect — 45% of
standing rules in the deployment reported in #3031.
Add an opt-in `apply_all_directives` flag on the reflect request (default
false, preserving current behavior). When true, every active directive is
loaded regardless of tags, ignoring tag scope. Wired through the HTTP API,
both MCP reflect variants, and the engine.
Also correct the docs, which claimed directives are "always" enforced without
mentioning tag scoping.
Regenerated OpenAPI, clients (Go/Python/TS/Rust), and the docs skill mirror;
updated the control-plane reflect proxy + api.ts types.
* chore(cli): record apply_all_directives CLI-coverage exemption
The reflect field is intentionally not exposed as a CLI flag (available via
the REST API, SDKs, and control plane). Record the exemption so cli-coverage-check
passes, matching the existing tag_groups entry.
* feat(retain): report zero-fact documents at write time (#3040)
A document whose fact extraction legitimately returns zero facts is stored
but unreachable: only memory_units carry embeddings, so recall and reflect
cannot reach a document that owns none. The retain still succeeds, the
operation reports completed, and nothing in the response, the webhook or
the metrics says the document produced no memories — the operator has no
way to know it needs a reprocess. FAIL_ON_EXTRACTION_ERRORS (#2721) cannot
help by construction: there is no error to fail on.
#2861 made retain.completed fire for zero-fact batches, but the payload is
byte-identical to a successful one, so it still carries no signal.
Add the count to all three write-time surfaces:
- retain.completed gains data.memory_unit_count, filled inside the outbox
callback on the retain's own connection so units written by the enclosing
transaction are visible.
- The synchronous retain response gains memory_units_created.
- New counter hindsight.retain.documents.total{outcome=facts|no_facts},
emitted per document at both extraction exits.
The webhook and the metric report the document's total *after* the retain,
not what the call created: the delta path skips unchanged chunks, so an
idempotent re-retain creates zero units while the document keeps every
memory it had. Reporting units created would raise a false alarm on every
re-submit. The count query only runs when the call created nothing, which
is the path where no work was done anyway.
Docs: how a retain mission trades away retrieval of the raw source, the
three signals, the non-determinism caveat, and reprocess as the way back.
* fix(retain): drop memory_units_created from the retain response
The synchronous response field reported units created by that call, which is
a different number from the one the webhook and the metric report (the
document's total after the retain) and only ever populated on the sync path.
The async path is the one that matters, and it is already covered by
retain.completed carrying data.memory_unit_count.
Removing it also takes the API surface back to identical with main — the
webhook payload is now the only public shape change — so the regenerated
Python/TypeScript/Go clients and the OpenAPI spec carry no delta.
Also renames the metric's parameter to memory_unit_count to match what it is
actually handed: the document total, not units created.
The graph_maintenance_queue used a lock-free duplicate-suppression enqueue
(`ON CONFLICT DO NOTHING` on PG, `IGNORE_ROW_ON_DUPKEY_INDEX` on Oracle). Neither
locks the existing row, so a mutation re-enqueueing an already-queued unit could
not serialize against a worker that concurrently claimed (deleted) that row and
processed the unit's pre-mutation state. The re-enqueue signal was silently lost
and the unit's derived temporal/semantic links were left stale with an empty queue.
Fix (issue Option 1 — schema-free):
- PG enqueue: DO NOTHING -> DO UPDATE SET enqueued_at = <table>.enqueued_at, a
no-op update whose purpose is to take the existing row's lock.
- PG claim: ordered-lock CTE — choose oldest by enqueued_at, then lock FOR UPDATE
in (bank_id, unit_id) order (same idiom as prune_stale_cooccurrences' #2529 lock),
matching the enqueue's sorted lock order so producer and worker cannot cycle.
- Oracle enqueue: MERGE (WHEN MATCHED locks the row) replacing the lock-free hint;
claim deletes claimed keys in sorted unit_id order.
- Worker Pass 1: each claim+relink batch runs inside retry_with_backoff (already
ORA-00060 / DeadlockDetectedError-aware) as a backstop; _BatchOutcome dataclass
folds counters into JobResult only after commit to avoid double-counting on retry.
Adds tests/test_graph_maintenance_queue_race.py covering both interleavings, batch
selection, and concurrent no-deadlock, driven against the real Postgres test DB.
reasoning_effort was the only LLM request setting without a per-operation
override: retain, reflect and consolidation all read the single global
HINDSIGHT_API_LLM_REASONING_EFFORT. When one operation requires a specific
value (e.g. reflect needs "none" for OpenAI reasoning models that reject
function tools otherwise), that value is forced onto the others, silently
degrading their generation quality.
Add REASONING_EFFORT to the existing per-operation set, following the
established fallback pattern:
HINDSIGHT_API_RETAIN_LLM_REASONING_EFFORT
HINDSIGHT_API_REFLECT_LLM_REASONING_EFFORT
HINDSIGHT_API_CONSOLIDATION_LLM_REASONING_EFFORT
Each falls back to HINDSIGHT_API_LLM_REASONING_EFFORT when unset.
The consolidator emitted `search_vector = to_tsvector('...'::regconfig, ...)` gated only on `text_search_extension == "native"` — dialect-blind, so the PostgreSQL-only expression reached Oracle and the `::regconfig` cast became an unbound `:REGCONFIG` placeholder (DPY-4010). Consolidation failed on every run against Oracle.
The three UPDATE sites now route through a dialect-aware `_native_search_vector_update()` helper and the INSERT branch is guarded on `not _is_oracle()`, falling through to the no-`search_vector` path. Oracle loses nothing: `memory_units.search_vector` is a vestigial CLOB there that no Oracle code populates, and keyword search runs off `idx_mu_content_text` (CTXSYS.CONTEXT on `memory_units(text)`, SYNC ON COMMIT). All PostgreSQL paths are unchanged.
Verified in `test-typescript-client-oracle`: 200 DPY-4010 errors and 50 `Task execution failed: consolidation` on the baseline, zero here, with consolidation completing normally.
* chore(api): remove unused code
Remove confirmed unreferenced helpers from the API and engine.
Delete tests only where they cover superseded internal paths. Keep
active test helpers and public memory operations unchanged.
* chore(cli): remove unused code
Remove dead CLI configuration, client, and output helpers.
Drop the parser implementation and tests used only by the retired
output path.
* chore(control-plane): remove unused code
Remove unused ControlPlaneClient methods and unreachable directive
detail state from the think view.
* chore(dev): remove unused code
Remove unreferenced benchmark and repository maintenance helpers.
* chore(embed): remove unused code
Remove the unused daemon port lookup helper while preserving current
profile-based daemon discovery.
* chore(integrations): remove unused code
Remove unreferenced helpers across supported integrations.
Drop tests only for retired internal paths and retain active test and
lifecycle infrastructure.
* test(consolidation): port prompt regression tests to split builders
The dead-code cleanup removed build_batch_consolidation_prompt and its tests,
but those tests guarded behaviors that are still live in the current
build_consolidation_system_prompt / build_consolidation_input path:
- brace-safety of a mission / capacity note containing literal { } (a lone
brace would raise KeyError in the internal str.format() and crash
consolidation)
- output-language directive injection into the cached system prompt
- the built-in default mission when none is supplied
Re-add these as regression tests against the current builders instead of
dropping the coverage. Also fix a stale comment referencing the removed
utils.extract_facts module.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(tracing): serialize unvalidated provider responses
* test(claude-code): lock in best-effort span recording on recorder failure
Add a regression test asserting that when the span recorder itself raises,
the Claude Code provider still returns its result (the best-effort contract
restored in #3025). Also apply ruff import sorting to the test module.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* docs+config(worker): rename per-type WORKER_*_MAX_SLOTS to *_RESERVED_SLOTS (#2963)
The per-operation `HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS` env vars set a
reservation *floor* (a guaranteed minimum), not a ceiling — despite the name a
type overflows the shared pool up to WORKER_MAX_SLOTS. The reporter hit exactly
this: consolidation ran 6-concurrent with "MAX_SLOTS=1".
Rename them to `<TYPE>_RESERVED_SLOTS`, which says what they do. The old
`<TYPE>_MAX_SLOTS` stays as a deprecated alias that logs a warning (setting both
is an error), so no existing deployment changes behavior. Defaults unchanged
(consolidation reserved=2).
Docs (current + version-0.8) updated to state plainly that a reservation is a
floor, not a cap — a type's real ceiling is WORKER_MAX_SLOTS. Tests cover the
new env var, the deprecated-alias mapping + warning, and the both-set error.
This is the issue's "part 1" — the cheap, high-value half. A genuine per-type
concurrency ceiling is a separate follow-up if operators need one.
* chore(docs-skill): regenerate for WORKER_*_RESERVED_SLOTS rename
TEI >=1.9 returns 429 as normal overload backpressure (fail-fast permit
acquisition, one permit per text), but the TEI reranker and embeddings clients only
retried 5xx, so a single 429 failed the whole recall and aborted the surrounding
consolidation round.
- Retry 429 alongside 5xx in both TEI clients, honoring Retry-After (numeric and
HTTP-date). Other 4xx still fail fast and the retry budget is unchanged.
- Spread retries with equal jitter. TEI overload is self-synchronising, so a narrow
jitter window left concurrent callers retrying in lockstep and re-colliding on the
same exhausted permit pool.
- Cap a single backoff at 5s rather than the client request timeout. The reranker holds
its concurrency semaphore across the sleep, so a large server-supplied Retry-After
would otherwise stall every queued rerank.
- Document the TEI permit-pool sizing invariant in the reranker configuration docs.
Fixes#2991
* blog: How to move your agent's memory off a vector database
Practical migration guide from Pinecone/Chroma to Hindsight: export the
text (not the vectors), map namespaces to banks, batch-retain, verify with
recall/reflect. Complements the existing "case against vector DBs" post
with the how-to. Grounded in the public SDK (create_bank, batch retain).
* feat(copilot-cli): add GitHub Copilot CLI hooks integration
Add hindsight-integrations/copilot-cli/, giving GitHub Copilot CLI
persistent long-term memory via Hindsight hooks (see docs.github.com/en/
copilot/how-tos/copilot-cli/customize-copilot/use-hooks). Modeled on the
existing cursor-cli integration.
Hooks:
- sessionStart: recall using initialPrompt (or a cwd-derived fallback
query), injects additionalContext
- subagentStart: recall for every subagent Copilot CLI spawns (explore,
task, research, code-review, rubber-duck, security-review, and custom
agents, not the built-in general-purpose agent, which never fires
this hook). Subagent payloads carry no per-invocation task text, so
this always uses the fallback query.
- agentStop: reads the transcript, retains to Hindsight on a configurable
turn cadence, caches the transcript path for sessionEnd
- sessionEnd: forces a final retain using the transcript path cached from
the last agentStop, since sessionEnd's own payload has no transcript
path field
Install via pip install hindsight-copilot-cli, then hindsight-copilot-cli
install (user scope, writes ~/.copilot/hooks/hindsight-copilot-cli.json)
or --scope repo for a team-shared .github/hooks/ registration. Zero
runtime dependencies, hook scripts are pure stdlib Python.
Also wires up CI (test-copilot-cli-integration job), release-integration.sh
and generate_changelog.py registration, and docs gallery/sidebar entry.
Closes#1588
* fix(copilot-cli): regen skill mirror, drop unreleased changelog link
- Run generate-docs-skill.sh to add the missing skill mirror for the
new copilot-cli doc page (verify-generated-files was failing on the
untracked references/sdks/integrations/copilot-cli.md).
- Remove the [View Changelog] link, which pointed at
/changelog/integrations/copilot-cli — a page the release script only
creates on first release, so it was a broken link failing build-docs.
* fix(worker): stop wedged retains from holding worker slots forever (#3002)
A retain task that blocks indefinitely held its worker slot until the
process restarted. The operation stayed 'processing' — which the API
refuses to either retry or cancel — so once every slot was held the
worker stopped claiming retains and the backlog grew without bound.
Five changes, outermost first:
* HINDSIGHT_API_RETAIN_WALL_TIMEOUT (default 1h, 0 disables) bounds one
retain task in the poller, mirroring REFLECT_WALL_TIMEOUT. The
existing timeouts each bound one LLM call, query or acquire; none
bounded the task. On expiry the executor is cancelled and the
operation is marked 'failed', so it is retryable. asyncio.timeout()
(not wait_for) so an inner TimeoutError isn't misreported as a wedge.
* The streaming retain pipeline now cancels both halves explicitly.
Plain gather() propagated the consumer's exception but left the
producer and every extraction task under it running; they parked
forever on chunk_queue.put() into a queue nobody drained, pinning
chunk payloads and still spending LLM permits on a failed operation.
* The LLM stage breadcrumb says '.queued' until the concurrency permits
are held. It was stamped before the acquire, so a call waiting on a
saturated semaphore was indistinguishable from one the provider was
running — the label sent the reporting operator after Bedrock for
tasks that had never reached Bedrock. Providers now stamp attempt 1
too, so a retry ladder is visible from the first attempt.
* bulk_insert_entities orders by LOWER(name), making the database's
collation the single arbiter of insert order for all writers. The
caller already sorted by Python's str.lower(), which agrees with the
conflict target for ASCII but not every locale.
* HINDSIGHT_API_DB_ACQUIRE_TIMEOUT now bounds the wait it names. It was
only passed to create_pool(timeout=...), a connect kwarg; Pool.acquire()
kept asyncpg's default of waiting forever, so pool exhaustion never
surfaced as an error.
* docs: regenerate hindsight-docs skill reference for RETAIN_WALL_TIMEOUT
`OpenAICompatibleLLM` builds request params in two places. `call()` sets
`reasoning_effort` for reasoning models; `call_with_tools()` built its own
`call_params` and never did.
Omitting it is not a neutral default. Measured against the OpenAI API for
gpt-5.6-terra with function tools:
reasoning_effort="low" -> HTTP 400
reasoning_effort absent -> HTTP 400
reasoning_effort="none" -> succeeds
"Function tools with reasoning_effort are not supported for
gpt-5.6-terra in /v1/chat/completions. To use function tools, use
/v1/responses or set reasoning_effort to 'none'."
So `HINDSIGHT_API_LLM_REASONING_EFFORT=none` could not fix it — that setting
only ever reached `call()`. Reflect is a tool-calling search loop, so every
tool call 400'd, retried, and fell back to a tool-less completion. The
fallback still returned content and still stamped `last_refreshed_at` and
cleared `is_stale`, so mental models looked refreshed while never having
searched memory. The only outward signal was input-token volume: ~800 per
call degraded, versus 2.4k-8.2k healthy.
The fix mirrors `call()` rather than gating by provider: `call()` already
sends this parameter to the same provider/model pairs under the same
capability check, so gating the tool path by provider would replace one
asymmetry with another. A parameterized test pins that contract.
Not addressed here, to keep the change reviewable — `call_with_tools()` also
diverges from `call()` by applying temperature unconditionally (reasoning
models generally reject it) and by omitting groq's `service_tier` and
`include_reasoning`. Neither has a reproduction; both deserve their own change.
Verified: 7 new tests; deleting the hunk fails 6 of them; 161 provider tests
pass. Live end-to-end, reflect went from 20 errors and an 806-token fallback
to zero errors and 2.4k-7.5k-token real searches, refreshing 5 mental models
in 91s.
Require semantic-link thresholds to be passed explicitly to the
low-level ANN, within-batch, and batch-creation helpers.
Make the streaming final-ANN threshold keyword-only to prevent
positional argument mistakes, and rename the forwarding test to match
what it verifies.
#2985 added a guard that rejected retry for every payload-null batch_retain
parent. But `retain --async` ALWAYS returns such a parent (submit_async_retain
creates a payload-less aggregator, even for a single item), so that guard made
async-retain operations un-retryable to users and 409'd the operations.sh doc
example — turning test-doc-examples(cli) red on main.
Make retrying a batch_retain parent re-run the batch's outstanding work instead
of rejecting it:
- re-queue the parent's failed/cancelled children to 'pending';
- revive the parent to 'pending' so it re-aggregates, but ONLY when at least one
non-completed child remains to drive the reconcile — otherwise it would strand
'pending' with nothing to promote it (the exact #2985 bug);
- leave pending/processing children untouched: a live worker owns a 'processing'
child and resetting it would let a second worker race it on the same
document_id (#1795);
- if there is nothing retryable (no children, or all completed), keep the 409 and
point the caller at resubmit + delete.
This restores the natural "retry my async retain" UX and fixes the doc example
with no change to operations.sh.
Tests (deterministic, direct async_operations rows):
- failed child -> re-queued + parent revived;
- processing child -> untouched, parent revived;
- all children completed -> 409, parent NOT revived (no re-strand).
Updated test_retry_rejects_batch_retain_parent's docstring: it now covers the
childless case specifically.
Whole-bank export/import dropped each fact's consolidation lifecycle
(created_at, consolidated_at, consolidation_failed_at). Import rebuilt
consolidation state only from surviving observation lineage, so facts that
were consolidated (or failed) in the source but no longer back a surviving
observation lost their state and became re-eligible. The maintenance
reconciler then treated them as backlog and re-consolidated, duplicating
observations — violating the whole-bank contract of restoring exact state
without re-running consolidation.
- schema: TransferFact carries the three lifecycle timestamps (optional;
absent in pre-fix archives -> None -> legacy fallback path).
- export: carry lifecycle exactly when observations are carried
(always for export_bank; export_documents only with include_observations).
The plain document export still omits them so it re-consolidates from
scratch, which is correct there (it carries no observations).
- import: restore timestamps verbatim after fact insert; the
observation-source marking now COALESCEs so it no longer clobbers a
restored consolidated_at (still covers legacy archives).
- test: regression covering consolidated-but-observationless facts, a
failed fact, exact lifecycle equality, zero reconciler backlog, and
unchanged observation count.
* fix(reflect): fail on unusable tool calls instead of salvaging leaked text
Reflect is driven by structured tool calls. Some provider transports don't
actually support function calling and silently strip the tool definitions from
the request (e.g. litellm's Vertex AI gpt-oss MaaS path drops tools/tool_choice
when the model is flagged unsupported). The model then answers in free text that
mimics a done() payload, which landed in message.content with empty tool_calls.
The old code served that raw text as the answer, so a growing pile of regex/JSON
"strippers" tried to claw the leaked memory_ids/observation_ids/directive_compliance
siblings back out of the user-facing answer.
Instead of salvaging untooled text, fail loudly:
- Track whether the model ever produced a tool call reflect could parse. If it
never does (the stripped-tools case), raise ReflectToolCallError -> HTTP 500
(the request is valid; the server's configured model can't do the job) with a
clear message (provider, model, response snippet).
- Keep the done tool; _process_done_tool now trusts args["answer"] verbatim.
A parsed tool call can't bleed its sibling id fields into the answer string.
- A model that DID tool-call and later stops with text is a legitimate stop and
still routes through the clean forced-final synthesis path.
- Delete the entire strip zoo: _clean_done_answer, _unwrap_leaked_done_arguments,
_strip_trailing_id_json_object, _clean_answer_text, _DONE_CALL_PATTERN, and the
leaked-JSON regexes/key-sets. The forced-final paths return the model's prose
directly (tools are disabled there, so there is no tool syntax to strip).
No static supports_function_calling gate -- reflect just tries and fails.
Supersedes the answer-salvage approach in #2972.
* test(mock): drive the reflect loop via tool calls, not bare prose
The reflect agent now rejects a turn that yields no usable tool call
(ReflectToolCallError). MockLLM's default call_with_tools returned bare
"mock response" content with no tool calls, which the old salvage path served
as the answer -- so ~15 reflect integration tests (empty-bank, tracing,
based_on, tags, think) started failing with 500 under the new guard.
Make MockLLM simulate a compliant tool-calling provider in its default path:
honor a forced retrieval tool_choice (so recall/search actually run and populate
based_on), and otherwise finish via the done tool. Tests that script their own
turns via _response_callback / _mock_response are unaffected.
Two remaining Oracle issues in the observability tables, both surfaced as
ORA-error spam in the Oracle CI logs (follow-up to the llm_requests write gate):
1. Audit writes (audit.py). `AuditLogger._safe_log` built `f"{schema}.audit_log"`,
which on Oracle is `public.audit_log` — "public" is a reserved word there, so
every write failed with ORA-00903 even though the table DOES exist on Oracle.
Fix: use `fq_table_explicit("audit_log", schema)`, which qualifies per dialect
("schema".audit_log on PostgreSQL, bare audit_log on Oracle where the schema is
set at the session level). This makes audit writes actually work on Oracle.
2. llm_requests reads (memory_engine.py). Unlike audit_log, `llm_requests` is
PostgreSQL-only (its migration omits the Oracle slot; LLMTraceRecorder already
skips writes on Oracle). `list_llm_requests` and `llm_request_stats` still ran
`SELECT ... FROM llm_requests`, which is ORA-00942 on Oracle. Fix: after the
bank-auth check (so a missing bank still 404s), return an empty page / empty
stats on Oracle instead of querying a non-existent table.
Tests:
- test_audit_per_bank: capture the emitted SQL via a fake pool and assert the
audit INSERT targets bare `audit_log` on Oracle (no `public.`) and `"schema".
audit_log` on PostgreSQL.
- test_llm_trace: the list and stats endpoints return empty (200, not 500) when
the backend is Oracle. Both deterministic, run on the default PG backend.
* fix(embeddings,reranker): default local models to CPU on Apple Silicon (MPS memory leak)
Local embedding + reranker inference on the PyTorch MPS (Metal) backend caches a
distinct compiled kernel graph and allocator pool per unique input tensor shape
and never releases it. Under the engine's variable-length, high-volume
recall/rerank/embed traffic (documents and candidate sets of every size), that
per-shape cache grows without bound: a local API instance was observed idling at
~20 GB (phys_footprint) — ~9.4 GB of Metal graphics memory plus ~8 GB of native
heap, essentially all of it stale per-shape MPS cache. CPU inference has no such
per-shape cache: the same workload holds flat at a few hundred MB, with
negligible latency cost for the small default models (and MPS actually slows down
over time as it recompiles graphs for new shapes).
Fix:
- MPS is now opt-in. select_local_device() (new engine/local_device.py) picks CPU
when the only accelerator is Apple Silicon MPS; CUDA/XPU still auto-select. Set
HINDSIGHT_API_{EMBEDDINGS,RERANKER}_LOCAL_ALLOW_MPS=true to opt back in.
- Post-batch memory release is consolidated in local_device.py and now also runs
on macOS: it returns freed native pages to the OS (glibc malloc_trim on Linux,
malloc_zone_pressure_relief on macOS — the #1717 fix previously covered only
Linux) and empties the GPU allocator pool (torch.<backend>.empty_cache) when a
GPU was used. The release path is wired into the embeddings encode path too,
which previously released nothing.
Validated end-to-end through the real LocalSTEmbeddings/LocalSTCrossEncoder
classes under 150 iterations of variable-length load: default config runs on CPU
and holds flat at ~420–455 MB (vs. MPS climbing past 7.8 GB toward the observed
20 GB); the ALLOW_MPS opt-in still reaches the MPS device.
* docs(local_device): link the upstream PyTorch MPS graph-cache issues we track
* fix: only release GPU cache after local embedding when on a GPU; regen docs skill
Two CI fixes:
- embeddings.encode() ran gc.collect() + heap-trim on every call. encode() is on
the retain hot path (a batch retain calls it many times), so a full gc.collect()
per call added enough overhead to time out heavy retain tests
(test_large_batch_auto_chunks). Guard the release to GPU devices only: on the CPU
default there is nothing to reclaim that refcounting doesn't already free, and
the opt-in MPS/CUDA path still gets empty_cache(). The reranker keeps its
per-batch heap trim (#1717, lighter recall path).
- Regenerated skills/hindsight-docs/references/developer/configuration.md from the
docs source (generate-docs-skill.sh) so verify-generated-files passes.
`LLMTraceRecorder` wrote every LLM call into `llm_requests`, but that table is
PostgreSQL-only — its migration is `run_for_dialect(pg=...)` with the Oracle
slot intentionally absent, and `MaintenanceLoop.start` already skips its
retention sweep on Oracle for the same reason. The write path missed that gate,
so on Oracle every LLM call fired an INSERT that failed with:
ORA-00903: invalid table name (INSERT INTO public.llm_requests ...)
("public" is a reserved word on Oracle, so the schema-qualified name fails to
parse; and the table does not exist there regardless.) The failures are caught
and logged, so nothing breaks functionally, but they spam the error log on every
retain/consolidation call — visible throughout the Oracle CI logs.
Gate the recorder on the backend, mirroring MaintenanceLoop: a new
`_llm_requests_persistable()` returns False on Oracle, and both write entry
points (`is_enabled`, consulted by `record_llm_call`, and `attach_memory_ids`)
short-circuit before scheduling any work. PostgreSQL behaviour is unchanged.
Note: `audit_log` DOES exist on Oracle but `AuditLogger._safe_log` builds the
same `f"{schema}.audit_log"` (→ `public.audit_log`, also ORA-00903). That is a
distinct bug (wrong qualification, not a missing table) and audit is off by
default so it wasn't in the failing logs — left for a separate change.
Test: test_recorder_disabled_on_oracle_backend forces the Oracle backend and
asserts the recorder reports disabled and records nothing (deterministic, no
live Oracle needed).
Two fixes to the claude-code provider's ClaudeAgentOptions blocks.
#2966 — reflect agent made 0 tool calls. call_with_tools() is one *round*
of a loop the caller drives (reflect/agent.py executes the real tools and
feeds results back), but the SDK ran its own in-process loop against our
placeholder MCP handlers. With max_turns=2 the model called recall, saw the
empty placeholder, re-queried, exhausted the budget → error_max_turns → and
the code raised on that, discarding the tool calls it had made (trace then
read tools=[none]). Fix: cap the SDK at max_turns=1, break out of the stream
after the first proposed tool call, and treat the trailing error_max_turns as
non-fatal when tool calls were already captured. This matches every other
provider's single-round call_with_tools semantics.
#2881 — the configured model never reached the CLI: neither options block
passed model=, so every call ran the CLI's own default (Opus-class on Pro/Max
OAuth) while metrics/logs still printed self.model. The isolated
CLAUDE_CONFIG_DIR means a host settings.json can't reach the CLI either, so
model= is the only channel. Fix: pass model=self.model in both call() and
call_with_tools().
Tests: new test_claude_code_llm_tool_round.py (fake-SDK: tool call returned
despite error_max_turns, stops after first round, text-only answer, model
pinned on both paths, genuine error still raised). Both fixes verified
end-to-end against the real SDK.
A batch_retain parent is a payload-less status aggregator: workers never
claim it, and it is promoted to a terminal state only when its last child
sub-batch finishes (_maybe_update_parent_operation). Two crash windows
strand it 'pending' forever — the aggregation swallowing a transient error
after all children are terminal, or children that never committed. Such a
parent is unclaimable, invisible to failed_operations, unretryable via the
API, and its documents are silently absent.
- Add WorkerPoller._reconcile_orphaned_parents(), run at the end of the
per-schema recover_own_tasks() pass. Pending payload-null batch_retain
parents are driven terminal: all-terminal children -> completed/failed
(inheriting a representative child error), no children -> failed with an
explicit resubmit hint. Parents with a live child are left to normal
aggregation.
- Guard retry_operation so a batch_retain parent (null payload) cannot be
retried into a re-stranded 'pending' state; the 409 points at the
supported recovery (resubmit + delete).
Tests: reconciliation coverage in test_worker.py and a retry-guard test in
test_operation_status.py.
* feat(zapier): remove memoryDefenseTriggered trigger (gated capability)
Memory Defense is a gated capability: enabling it returns 400
'detectors_not_entitled' for orgs without the sensitive_data detector, so a
public Zapier trigger for memory_defense.triggered can never satisfy Zapier's
T001/S002 'one live run' review checks for un-entitled users.
- Remove the trigger from index.js and delete triggers/memoryDefenseTriggered.js
- Add guard tests asserting the exposed trigger set and that the trigger is absent
- Drop it from the package README and the Zapier integration docs page
- retain.completed and consolidation.completed remain (verified delivering on Cloud)
* chore(zapier): prettier-format triggers.test.js
* blog: What people actually build with agent memory (use cases)
Overview post walking through the concrete patterns teams build on
Hindsight: coding agents, per-user products, support/account assistants,
voice, chat platforms, self-built framework agents, multi-agent shared
banks, and automations. One primitive (retain/recall/reflect over a
bank), scoped and surfaced differently.
`update_bank` wrote `SET mission = COALESCE($3, mission)`. On Oracle `mission`
is a CLOB, and COALESCE derives its result type from the first argument — the
bind `$3`, which oracledb sends as a VARCHAR2. Oracle then evaluates the CLOB
`mission` in a "CHAR expected" context and raises:
ORA-00932: expression ("BANKS"."MISSION") is of data type CLOB,
which is incompatible with expected data type CHAR
This broke every createBank/update that set a mission on Oracle — the failure
behind the persistently-red test-typescript-client-oracle job (`createBank`
issues a name+mission update).
Fix: build the UPDATE's SET clause from only the columns actually supplied and
assign them directly (`SET mission = $n`), the way set_bank_mission already
writes the CLOB. Assigning a string straight into a CLOB is fine on Oracle; it's
the cross-type COALESCE that fails. Untouched columns are simply not written,
which is the same result the COALESCE-of-NULL produced. Behaviour on PostgreSQL
is unchanged.
Tests:
- test_http_api_integration: new deterministic PG regression asserting name and
mission round-trip, plus a mission-only update (runs on every CI shard).
- test_oracle_integration: test_bank_profile_crud now asserts the mission value
round-trips (it already exercised this path but only checked name; the Oracle
suite is skipped in normal PR CI, so the live coverage was the TS client job).
The audit-logs and observations tabs gated on features.audit_log /
features.observations from the /version endpoint, which only reports the
global (server-level) default. Both fields are hierarchical
(env -> tenant -> bank), so a bank that opts in via per-bank config still
saw "not enabled" because the global flag stays off.
Gate these tabs on the bank's resolved config (getBankConfig) instead,
falling back to the global flag when the bank config API is disabled
(per-bank overrides can't exist then) or the field is unavailable.
* fix: avoid dotenv side effects on library import (#2961)
`hindsight_api.config` called `load_dotenv(find_dotenv(usecwd=True),
override=True)` at module scope. Importing `hindsight_api` (or anything that
pulls it in — `import hindsight`, `HindsightEmbedded`) therefore walked up from
the host process cwd and overwrote the embedding application's own environment,
with override=True beating values it had set deliberately (#2961).
Move the load out of module scope into a `load_dotenv_for_entrypoint()` helper
that Hindsight's standalone entry points call explicitly: the API CLI
(`main.py`), the ASGI app (`server.py`), the worker, and the admin CLI. Library
imports are now side-effect-free.
Backwards compatibility for our own deployments is preserved exactly:
- `override=True` is kept in the helper, so a discovered `.env` stays
authoritative over the ambient process env — unchanged precedence.
- `server.py` is covered, not just the CLI: it is the `uvicorn
hindsight_api.server:app` target AND the import string uvicorn re-imports in
each worker process when `hindsight-api` runs with `--workers`/`--reload`, so
omitting it would silently break `.env` loading in multi-worker mode.
- `tests/conftest.py` now loads the workspace `.env` with `override=True`,
matching the precedence config.py used to apply at import time (the oracle
fixture depends on `.env` being authoritative).
Also drop the now-obsolete `_EARLY_DB_URL` workaround in `recall_perf.py`.
Closes#2961
* style: ruff-format test_fact_extraction_retry signature (pre-existing #2969 drift)
`ruff format` collapses this test's parametrized signature onto one line (it
fits within the 120-char limit). #2969 (e5cd23940) committed the multi-line form,
so verify-generated-files now flags it on every new branch. Not related to the
dotenv change — folded in here only to keep the whole-tree generated-files check
green.
* fix(clients): expose retain operation_id
* fix(clients): warn when operation_id is dropped on sync retain
operation_id only enables idempotent retries for asynchronous retain; on a
synchronous request it was silently dropped. Emit a warning at each retain
entry point (Python warnings.warn / TS console.warn) so a caller who forgets
retain_async=True learns their idempotency key was ignored.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
Extend the non-Chinese period table with Russian relative expressions
(вчера/позавчера/сегодня, «пару|несколько дней|недель|месяцев назад»,
прошлой неделе|месяце|году, прошлых выходных) and Russian month names in
their inflected forms, so Russian time queries get the same deterministic
extraction as English.
Russian months inflect: dateparser only resolves the nominative ("май"),
while "в мае" (prepositional) and "мая" (genitive, in explicit dates) are
the forms that occur. Enumerated per month with word-boundary guards so
stems inside longer words (майонез, мартовские) must not match.
* fix(consolidation): stop emitting unsupported maxItems that breaks all Bedrock consolidation (#2500)
_build_response_model attached a Pydantic max_length to creates, which serializes to JSON-schema maxItems; Bedrock Converse rejects maxItems on array types, failing 100% of consolidation for capped Bedrock banks. The cap is already enforced by the prompt capacity note + unconditional truncation to remaining_observation_slots, so the schema constraint is dropped.
* test(consolidation): assert response schema omits maxItems (#2500 regression)
Rewrite TestBuildResponseModel to the new contract: factory always returns the base model, schema omits maxItems (Bedrock-compatible), over-cap creates are accepted (truncated downstream) rather than rejected. End-to-end cap enforcement remains covered by the existing max_observations_per_scope integration tests.
* Add an opt-out for maxItems schemas
---------
Co-authored-by: r266-tech <[email protected]>
* blog: recall vs reflect (the two ways to read agent memory)
Feature/decision piece contrasting Hindsight's two read operations:
recall (hybrid retrieval + rerank, no LLM, ranked facts, sub-second)
vs reflect (agentic loop with an LLM, hierarchical retrieval, synthesized
answer, response_schema, validated cited sources). Includes comparison
table, decision guide, and FAQ. Grounded in the recall/reflect engine
and API docs. Cover: recall vs reflect contrast panels.
* blog: use Inside retain() editorial theme for recall vs reflect cover
* blog: fact-check fixes to recall section
Adversarial verification against the recall engine found three
inaccuracies: recall runs 3 retrieval strategies always (semantic, BM25,
graph) with temporal conditional (not 4); no MMR/diversity pass is
implemented (docstring only); high budget defaults to 1000 not 600.
Softened 'local cross-encoder' since remote rerankers are configurable.
reflect claims all verified accurate.
* blog: fix API-doc link paths (/developer/api/... not /docs/...)
* fix(graph): queue edited and restored memories for relinking
Graph maintenance rebuilds outgoing temporal and semantic links only for
units explicitly present in its queue. Edits and restores submitted the
worker without queuing the affected unit, so its outgoing links could
remain missing.
Queue edited units together with incoming-link victims in one sorted
insert to preserve the global lock order. Queue restored units after
their searchable fields have been rebuilt.
Cover outgoing-only restore and bidirectional edit cases, including a
single queue write for the edited unit and its victims.
Fixes#2889.
* test(graph): cover the outgoing-only relink case; tidy enqueue helper
The PR's tests only exercised mutually linked units, so the branch the bug
actually lived in — an edited/reverted unit with outgoing links but no
incoming ones, where the victim lookup is empty — was untested.
Tests:
- enqueue_relink_victims: include_affected_units with no victims (returns
the unit itself), with victims (one combined sorted insert), and the
default opt-out for delete callers.
- Curation: an outgoing-only edit queues itself, plus two end-to-end tests
that let the inline SyncTaskBackend drain the queue and assert the
temporal link is actually rebuilt after an edit and after a revert.
All five fail on the pre-fix engine.
Tidy:
- Rename deleted_unit_ids -> affected_unit_ids; with the new flag the
helper also takes units that stay live, so the old name/doc misled at
the edit call site. Same for the debug log wording.
- Spell out at both call sites why the edit combines self+victims in one
insert, why the invalidating edit opts out, and that revert rebuilds
only the reverted unit's outgoing links.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* ci(oracle): free runner disk space before Oracle jobs
The three Oracle jobs run the Oracle 23ai `free` service image, which
together with the Python ML deps (torch) exhausts the runner's ~14 GB root
disk. Two symptoms, one cause:
- uv fails to extract a wheel with "No space left on device (os error 28)"
(fast ~2 min failure), and
- a near-full disk starves I/O badly enough to trip the 30-minute job
timeout.
test-python-client-oracle and test-typescript-client-oracle have been red on
every open PR (#2941, #2942, #2943) from this, independent of the code under
test. Reclaim ~20 GB of preinstalled tooling (the same jlumbroso action the
Docker build job already uses) before the Oracle setup step.
docker-images stays false here: unlike the Docker build job, the Oracle
service container is already running by the time steps execute, so pruning
images could disrupt it. The savings come from the tool cache, Android SDK,
.NET, Haskell, large apt packages and swap.
* ci(oracle): trim disk reclaim to the fast, high-yield options
The first pass enabled every reclaim, which cost ~4 minutes of job time —
counterproductive on jobs that are already fighting a 30-minute limit.
android + dotnet + haskell + swap are a few rm -rf's worth ~16-21 GB, which
is ample headroom for the Oracle image plus torch. Dropped:
- large-packages: apt-get remove, costs minutes for little extra space;
- tool-cache: deletes the preinstalled Python that actions/setup-python then
re-downloads, making the job slower rather than faster.
* fix(retain): flush entity stats after releasing the connection (Oracle hang)
Retain hung forever on the Oracle backend: every retain test burned its 120s
client timeout while the server sat idle, so test-python-client-oracle and
test-typescript-client-oracle only ever reached ~5% of the suite before the
30-minute job limit.
The server was not slow — it was deadlocked. flush_pending_stats() acquires
its own connection, but it was being called while the enclosing
acquire_with_retry(...) block still held one:
async with acquire_with_retry(pool) as conn: # conn checked out
async with conn.transaction(): # SAVEPOINT only
...write facts/entities...
await entity_resolver.flush_pending_stats() # takes a 2nd connection
oracledb does not autocommit and OracleConnection.transaction() is only a
SAVEPOINT, so the write is committed by OracleBackend.acquire() when its block
exits. Connection #2's `UPDATE entities ...` therefore waits on row locks held
by the still-open connection #1, which cannot commit until the call returns —
a circular wait. Oracle never reports ORA-00060 because session #1 is blocked
in Python, not on the database, so it hangs indefinitely instead of erroring.
Move the flush after the acquire block in all three call sites (streaming
retain, delta retain, transfer importer), which is what its own docstring
already required ("must be called AFTER the retain transaction commits") and
which PostgreSQL satisfied only by accident via asyncpg autocommit.
Guarded with an AST lint test rather than a behavioural one: the deadlock
cannot be reproduced against PostgreSQL, which is what the suite runs on.
* test(repair): retry the concurrent index drop on deadlock
test_dry_run_creates_nothing still flaked in test-api shard 3. CONCURRENTLY
avoids ACCESS EXCLUSIVE but still takes ShareUpdateExclusive, which conflicts
with the ShareLock a fresh bank's plain CREATE INDEX holds — and that one
cannot be made concurrent, since it runs inside the bank-create transaction.
So _drop_bank_indexes can still be picked as the deadlock victim while another
xdist worker seeds a bank:
Process A waits for ShareUpdateExclusiveLock on memory_units; blocked by B.
Process B waits for ShareLock on virtual transaction; blocked by A.
The bank-create side already retries (#2943); give the drop the same treatment.
The drop is idempotent, so retrying is safe.
Add optional enabledAgentIds config field to restrict Hindsight recall/retain to
a subset of agents. When set, only listed agent IDs trigger memory operations;
unset or empty array = unchanged behavior (all agents). Enables pilot rollouts on
high-signal agents before fleet-wide enable, reducing LLM cost/latency risk.
- Add enabledAgentIds: string[] to instanceConfigSchema (manifest.ts)
- Add isAgentEnabled() gate function to worker.ts
- Gate agent.run.started recall, agent.run.finished, and issue.comment.created
retain handlers (the actual LLM-cost operations)
- Add 6 test cases covering allowlist pass/fail, empty array, and unset behavior
- Update README config table
Co-Authored-By: Claude Sonnet 5
The consolidation prompt serializes temporal metadata the INPUT section never
explained. `mentioned_at` in particular was emitted on new-fact lines, on each
existing observation, and on every embedded source memory, while the format
description documented only id/text/proof_count/occurred_start/occurred_end --
so the model received the timestamp with no idea what it meant or that it
represents how current a statement is.
Define each field the serializer actually emits, and note that `mentioned_at`
tracks when the source material was written rather than when it was ingested,
which is what makes it meaningful for out-of-order document ingestion.
The two copies of the format description (the cached bank-agnostic system
prefix and the single-message template) are now built from shared constants so
they cannot drift apart.
Refs #2550
Causal edges (`caused_by` plus the historical `causes`/`enables`/`prevents`)
are retain-time extraction output. Nothing recreates them: graph maintenance
only rebuilds temporal/semantic links and consolidation regenerates
observations, not raw-fact edges. Curation destroyed them anyway (#2864):
* every edit — including a context-only one — deleted all incident
`memory_links` rows, and
* invalidation moves the row out of `memory_units`, so the FK cascade took
its causal edges with it and restore had nothing to bring back.
Edits now delete only the derived link types, so a corrected fact keeps the
causality the extractor asserted for it (preserving the assertion is the
reversible choice; deleting it is not). Invalidation snapshots the incident
causal edges into a new `causal_links` JSONB column on the archive row, and
restore rematerializes the ones whose peer endpoint is live again.
The snapshot also picks up descriptors parked on archived peers that name the
unit, so an edge whose both endpoints are invalidated survives on both archive
rows and is recreated by whichever endpoint is restored last — restore order
doesn't matter. Rematerialization goes through the existing bulk-insert path,
which drops links whose endpoints aren't live and is `ON CONFLICT DO NOTHING`,
so repeated invalidate/restore cycles never duplicate an edge or resurrect one
pointing at a permanently deleted memory.
* fix(config): validate bank config updates before creating banks
Route external bank configuration writes through MemoryEngine so tenant
authentication and UPDATE_BANK_CONFIG authorization happen consistently.
Validate profile and configuration changes before creating a bank or
persisting either one. Rejected configuration updates through PUT,
PATCH, import, and MCP therefore leave no empty bank or partial profile
changes behind.
Keep memory-defense validation behavior unchanged, and cover the new
ordering and delegation paths with regression tests.
* fix(import): preflight template operations before creating banks
Preflight every template operation before creating a missing bank.
Reject duplicate mental models and directives before applying changes.
Reuse request-local authorization decisions while the import executes,
avoiding duplicate hook calls that may reserve quota or depend on time.
Precheck mental-model refresh availability so common failures do not
leave a newly created bank or a partially applied template behind.
Document that the authorization context creates the bank after all
checks pass.
* fix(mcp): create banks through public engine APIs
Delegate MCP bank creation to MemoryEngine's public profile and update
APIs instead of calling _ensure_bank_exists() directly.
Use get_bank_profile() for default creation and update_bank() when name
or mission fields are supplied. This keeps lifecycle validation and
authorization ordering inside the engine and avoids duplicate reads.
Add coverage for both public API paths and assert that MCP never invokes
the private creation helper.
* fix(config): fail loudly when persisting config for a missing bank
Bank creation moved out of ConfigResolver into MemoryEngine, but the
persist step still returned normally when the UPDATE matched zero rows.
A caller that skipped provisioning silently discarded its overrides
while reporting success — the failure mode #1940 originally fixed.
Raise instead, and translate the concurrent-delete case in update_bank's
update-only path into the same 404 its final profile read would produce.
* test(mcp): assert update_bank calls instead of a fixture's forwarding
The mock_memory fixture re-implemented _do_update_bank's routing by
forwarding config_updates to _config_resolver.update_bank_config, so the
existing assertions verified the fake rather than production code — they
would still pass if _do_update_bank stopped sending config entirely.
Assert on the update_bank mock, which is the call the tool now makes.
* test(api): cover the 404 mapping for a delete racing the config write
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* docs: add TealTiger governance memory integration listing
Adds TealTiger to the integrations page as a community integration.
Governance-aware agent memory with importance-weighted retention.
Related: #2284
PyPI: https://pypi.org/project/tealtiger-hindsight/
* Delete hindsight-docs/docs-integrations/tealtiger.md
* Update TealTiger integration link to GitHub
Expose graph seed, temporal semantic, and semantic-link similarity
thresholds through HindsightConfig while preserving existing defaults.
Wire the settings through retrieval, retain, streaming, and graph
maintenance paths. Add validation, environment examples, documentation,
and regression coverage.
Document how to calibrate all five embedding-dependent thresholds and
note that semantic-link changes do not rebuild existing graphs.
litellm ships its own Rust extension (litellm-rust python-bridge ->
litellm.rust_bridge._native, built via maturin/PyO3). Releases before
1.93.0 publish no cp314 wheel, so on Python 3.14 uv falls back to the
sdist and the build fails:
error: the configured Python interpreter version (3.14) is newer
than PyO3's maximum supported version (3.13)
1.93.0 adds cp314 wheels and a PyO3 that builds on 3.14. Raising the
floor fixes the failure at its source, so the interpreter no longer has
to be constrained.
That lets us drop the UV_PYTHON=3.13 workaround added in #2801: the
_set_uvx_python_compat() helper and its call sites are removed from the
claude-code, codex, cursor, and cursor-cli daemons, along with the tests
that pinned that behaviour. Dropping the pin costs nothing — litellm
publishes no macOS wheels at all, so macOS builds from the sdist on every
version regardless, while Linux now gets a real cp314 wheel instead of a
source build.
Also strengthen the build-api-python-versions CI matrix. It previously
ran only `uv build`, which just packages the source and passes even when
the dependency set cannot install or import on the target interpreter --
it would not have caught this. It now installs into a fresh venv,
byte-compiles, and runs an import smoke test on each version.
Verified on CPython 3.14.4 with UV_PYTHON unset: litellm 1.93.0 installs,
the Rust bridge builds, and hindsight_api plus the engine import cleanly.
Refs #2783
Raise the hardcoded 12s UserPromptSubmit/beforeSubmitPrompt hook timeout
to a safe 45s default across all integration hook manifests (claude-code,
cursor-cli, codex, omo, zcode).
For Claude Code, setup_hooks.py now reads the user's requestTimeoutSeconds
from ~/.hindsight/claude-code.json and derives the hook timeout as
max(requestTimeoutSeconds + 15, 30s) — so the hook process is never killed
before the MCP recall request it wraps has a chance to complete.
Fixes#2854
Co-authored-by: handnewb <[email protected]>
Fetch the API version from GET /version at mount and display it in the
sidebar footer. When collapsed, shows 'vX.Y.Z'; when expanded, shows
'Hindsight vX.Y.Z'. Gracefully handles fetch failures (no version shown).
Fixes#776
Co-authored-by: handnewb <[email protected]>
Bulk variant of delete_memory_unit that removes a list of unit_ids with the
same referential-integrity lifecycle, batched by bank:
- enqueue_relink_victims before the cascade
- chunked cascade DELETE (FK CASCADE handles unit_entities / memory_links /
observation history)
- _delete_stale_observations_for_memories racing-insert sweep
- bank-stats cache invalidation
- deduped async consolidation + graph_maintenance submission per bank
Gives retention loops, LRU eviction, and bulk-maintenance tools a single entry
point that keeps the cascade contract instead of open-coding DELETEs outside
the engine and drifting from it.
(The last_recalled_at column originally in this PR was dropped: it has no OSS
consumer and is better as an extension-owned side table — a high-frequency
write of an indexed column does not belong on the hot memory_units table.)
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(api): filter memory list by linked entity + entity timeline UI
Add an `entity_id` query param to `GET /memories/list` — an exact reverse
lookup over stored entity links (not text/semantic match), backed by the
existing idx_unit_entities_entity_unit index. Because entity links reference
live memory units only, combining `entity_id` with `state=invalidated`
returns nothing.
Wire it through the control-plane list route + clients, and use it in the
entity detail panel to render an observation timeline (reuses the memories
TimelineView) — click an entity, see its linked observations over time.
Closes#2936.
* fix(control-plane): entity timeline shows all linked memories, not just observations
Verified against real data: observations are derived/consolidated summaries and
carry no entity links — entity links live on the source world/experience facts,
which are also the ones with occurred dates. Filtering the entity timeline to
type=observation therefore always rendered an empty panel. Drop the type filter
so the panel shows every memory linked to the entity (the actual dated timeline),
and relabel the section "Timeline" with dedicated i18n keys.
* chore(control-plane): drop now-unused observation i18n keys from entitiesView
* style(reflect): wrap over-length _generate_structured_output call
Ruff format wraps this >120-char call; committing the formatter output so the
verify-generated-files CI check (which runs the formatter and diffs) is clean.
Follow-up to #2866. That PR stopped the scheduled no-op refresh storm by
advancing a delta model's last_refreshed_at to the pre-Reflect snapshot cutoff
(a wall-clock now()), but a wall-clock watermark is unsafe against commit
visibility.
memory_units.updated_at is the writing transaction's start time (Postgres
now()), yet a row only becomes visible at COMMIT, which can land after a
concurrent refresh captured its snapshot. Such a straddling row is invisible to
Reflect but carries a timestamp <= that instant, so setting the watermark to
now() leaves it permanently below the watermark and drops it from every future
refresh. The same hazard existed on the contentful path (last_refreshed_at =
NOW()) before #2866.
Persist the watermark as MAX(updated_at) over the model's scope restricted to
rows visible at the snapshot -- the newest memory the refresh actually saw --
instead of now(). A straddler is still uncommitted at that snapshot so it is
excluded from the max; when it commits it stays strictly newer than the
watermark and is caught next time. This needs no time margin: max(seen) does
not overshoot the real data, so the settled window stops re-triggering (no
storm) and delta recall's created_after (the prior max(seen)) reprocesses
nothing.
The watermark is clamped monotonic: max(newest_seen, current last_refreshed_at),
so a refresh over only-older memories never moves it backwards (which would
resurface already-processed rows). MAX null (no in-scope row visible) leaves
last_refreshed_at unchanged so an in-flight first row is not skipped.
Extract _build_mm_scope_filter so the staleness check and the watermark query
share one identical scope.
Tests: straddling-commit test uses a committed baseline as the max(seen)
watermark and a newer held-then-committed straddler (fails on #2866); the no-op
test asserts the watermark equals the newest processed memory's updated_at.
* fix(repair): retry transient deadlocks + non-blocking test DDL
The test-api shard runs 8 pytest-xdist workers against one shared pg0
database (public schema). test_repair_bank_vector_indexes built/dropped a
decoy index with plain CREATE/DROP INDEX on the shared memory_units table,
taking ACCESS EXCLUSIVE and deadlocking unrelated workers' DML — recall,
reflect and refresh tests turned into asyncpg DeadlockDetectedError
casualties.
- tests: build/drop the decoy index CONCURRENTLY (ShareUpdateExclusive
never blocks DML) to match production and stop the collateral deadlocks.
- engine: repair_vector_indexes retries a CREATE/DROP INDEX CONCURRENTLY
picked as a deadlock victim (sqlstate 40P01 / ORA-00060) via the existing
retry_with_backoff, instead of recording a permanent failure. Always
drop-then-create so a retry clears the INVALID stub a deadlocked
CONCURRENTLY build leaves behind.
- test: test_transient_deadlock_is_retried_not_failed injects a one-shot
deadlock and asserts repair converges (failed == 0).
No advisory locks (project rule): concurrency stays handled by idempotent
DDL plus victim retry.
* fix(banks): make per-bank index create/delete deadlock-safe
The test-api shard runs 8 xdist workers against one shared pg0 memory_units
table, so every bank create/delete does index DDL that contends with other
workers' DML. These are pre-existing production deadlock sources, not just
test noise:
- delete_bank dropped per-bank indexes with a plain DROP INDEX (ACCESS
EXCLUSIVE on memory_units), blocking/deadlocking every other bank's
reads/writes. Now DROP INDEX CONCURRENTLY (ShareUpdateExclusive, does not
conflict with DML), run post-commit on an autocommit connection, wrapped
in retry_with_backoff for the residual transient deadlock.
- fresh-bank index build uses a plain CREATE INDEX (ShareLock) inside the
bank-create tx — CONCURRENTLY is impossible there. The whole tx is now
wrapped in retry_with_backoff; the build is idempotent (INSERT ON CONFLICT
+ CREATE INDEX IF NOT EXISTS) so a deadlock victim retries cleanly.
Regression tests inject a one-shot deadlock into each path and assert it
retries and converges. No advisory locks (project rule).
* fix(retain): make async retries idempotent via caller-supplied operation_id
An async retain whose HTTP acknowledgement is lost or times out leaves the
caller unable to tell whether the operation was created; retrying enqueues a
second parent operation and repeats extraction, embeddings, and provider spend.
Add an optional caller-supplied operation_id (UUID) used directly as the parent
async_operations primary key. Re-submitting with the same id returns the
original operation and creates no new work; the existing primary key is the
concurrency authority, so no new columns, constraints, or migration are needed.
Reusing an id owned by a different bank or operation type returns HTTP 409.
Omitting operation_id keeps the current create-each-time behavior.
Fixes#2937
* docs(retain): explain why the idempotency read is not in the create txn
* fix(retain): sync generated docs-skill + Rust clients for operation_id
- Regenerate the two docs-skill artifacts derived from the retain doc /
OpenAPI change (verify-generated-files).
- Add operation_id: None to the Rust client test and CLI RetainRequest
literals so both crates compile against the regenerated struct.
* feat(extensions): let extensions declare bank-scoped tables for backup + teardown
An extension can provision its own bank-scoped tables in the tenant schema
(audit receipts, per-bank policy state, ...), but core knows nothing about
them, so they silently fall out of the per-tenant data-lifecycle operations it
owns:
- admin backup/restore copies a fixed core table set and TRUNCATEs it CASCADE
on restore; an extension table absent from that set is dropped from the
backup and — if it FKs banks — wiped by the cascade with no way back;
- delete_bank clears a bank via core deletes + the banks FK cascade; an
extension table scoping by bank_id without a cascading FK leaks orphaned rows.
Add a BankScopedTable descriptor and TenantExtension.extra_bank_tables() so an
extension declares its tables; core consults them in:
- admin backup/restore (_effective_backup_tables appends declared tables after
the core set so restore's forward COPY / reversed TRUNCATE keep FK order);
- MemoryEngine.delete_bank (sweeps declared tables by bank_id on full delete,
with a PG-only to_regclass guard so a declared-but-unprovisioned table can't
abort the delete).
The extension still owns the DDL; this only tells core which tables to sweep.
Default behaviour is unchanged — the base method returns no tables, so the OSS
default path is a no-op. Descriptor names are validated to a safe SQL
identifier shape since they're interpolated into SQL.
Covered by descriptor-validation + effective-list unit tests, a delete_bank
sweep test, and a backup/restore round-trip that proves a declared extension
table survives truncate+restore.
* feat(extensions): provision extension bank tables on the migration path
Adds the creation half of the bank-scoped-table lifecycle. Previously an
extension's tables were created only by its own imperative DDL run lazily on
first request (e.g. Cloud's provision_schema off authenticate), so:
- hindsight-admin run-db-migration migrated core schema across all tenants
but never touched extension tables, and
- a provisioning failure was swallowed, surfacing later as a runtime error.
Add TenantExtension.provision_bank_tables(conn, schema) — idempotent DDL the
extension owns — and invoke it right after core migrations from both migration
entry points:
- ExtensionContext.run_migration (every tenant-schema provision), and
- the run-db-migration sweep (_provision_extra_bank_tables, per schema),
where a failure now aborts the command and names the schema instead of
being swallowed.
So extension schema evolves on the same lifecycle as core schema. Default is a
no-op, so the OSS default path is unchanged. Pairs with extra_bank_tables()
(declares for backup/teardown) — one creates, the other declares.
Covered by a default-no-op test plus provisioning through both the CLI sweep
helper and ExtensionContext.run_migration against real Postgres.
* chore: ruff format after rebase (cli.py, memory_engine.py)
* feat(config): make store_document_text overridable per bank
HINDSIGHT_API_STORE_DOCUMENT_TEXT was static/server-level. Make it hierarchical
so a data-minimizing bank (e.g. GDPR-sensitive) can keep only derived facts
while other banks on the same deployment retain the raw source.
- Add store_document_text to _CONFIGURABLE_FIELDS (settable per bank via the
config API's generic updates dict, like audit_log_enabled).
- Thread the per-bank resolved value into the retain storage path
(chunk_storage.store_chunks_batch + fact_storage.upsert_document_metadata /
handle_document_tracking / _upsert_document_row) from the orchestrator's
resolved config; falls back to the server-level config when unset so
non-retain callers (import) are unchanged.
- Make the three consistency guards per-bank too so a store-off bank behaves
coherently: append-mode rejection, recall include_chunks force-off, and the
reflect 'expand' tool exclusion.
- Docs: mark the flag hierarchical.
Covered by a per-bank override test (one bank off, one default-on) + a
configurable-fields guard; existing global-flag tests set the ConfigResolver
global snapshot (env alone no longer suffices for a hierarchical field,
mirroring enable_audit_default).
* feat: expose store_document_text (+ audit_log_enabled) in bank templates & UI
- BankTemplateConfig gains store_document_text and audit_log_enabled so bank
templates can preset them; regenerated bank-template-schema.json.
- Control-plane bank config: new 'Document Storage' tri-state section
(Inherit / On / Off), mirroring the audit toggle; translations added across
all 10 locales (non-en use English placeholders pending translation).
Backend template round-trip + messages parity/used-keys + tsc all green.
* chore(ui): rename bank-config 'Document Storage' section to 'Privacy'
* feat(ui): merge audit + document-text toggles into one 'Security & Privacy' section
Combine the separate Audit Logging and Privacy config sections into a single
Security & Privacy section with both tri-state toggles and one save (writes
audit_log_enabled + store_document_text together). Drop the now-unused
section-level message keys across all locales; add securityPrivacy* keys.
* fix(retain): use _get_raw_config for store_document_text fallback
store_document_text became bank-configurable, so get_config().store_document_text
now raises ConfigFieldAccessError (the guard forcing per-bank resolution). The
storage functions' None-fallback hit that guard, breaking every direct/delta
caller that didn't pass the value (test_chunk_storage_upsert, test_delta_retain).
Fall back to _get_raw_config() instead — the unguarded global layer the
ConfigResolver and the /config defaults response already use. The retain path
still passes the per-bank resolved value; only non-retain callers hit the
fallback.
* chore: regenerate openapi + clients + docs-skill for BankTemplateConfig fields
Adding store_document_text/audit_log_enabled to BankTemplateConfig changed the
OpenAPI schema; regenerate the spec, Go/Python/TS client models, and docs-skill
copies, and apply lint formatting (verify-generated-files).
* test: bump configurable-field count 41->42 for store_document_text
Recognize a complete oversized document as a strict append even when its
header-only first transport slice previously extracted no facts and has no
stored chunk match. Advance document metadata under a content-hash guard so
later slices can recovery-skip unchanged history without risking stale writes.
Co-authored-by: OpenAI GPT-5.6-Sol High <[email protected]>
Clears the remaining fixable high-severity Dependabot alerts:
next 16.2.9 -> 16.2.11 4 alerts (control-plane). Direct dep bumped
(^16.2.6 -> ^16.2.11); a root override
(>=16.2.11 <17) also forces next-intl's nested
[email protected] copy up so no vulnerable copy remains.
postcss 8.4.31 -> 8.5.22 1 alert. The vulnerable copy was next's bundled
8.4.31 (the direct 8.5.15 already satisfied);
a global override >=8.5.12 forces it up.
pypdf 6.13.3 -> 6.14.2 2 alerts (superagent). Transitive.
Verified: control-plane `npm run build` (next build + standalone) succeeds,
`npm ci` installs the root lock cleanly, npm audit no longer flags next or
postcss, superagent pytest passes, lint clean.
The API and worker run /health and all task work on a single event loop, and
/health acquires a DB connection. A failing liveness probe therefore has two
very different causes that today are indistinguishable: the event loop is
blocked by synchronous work (a restart helps), or the connection pool is
exhausted and /health can't get a connection while the loop is idle (a restart
just thrashes). Add two always-on, cheap signals so the failure is
self-diagnosing instead of an opaque restart.
LoopWatchdog (hindsight_api/loop_watchdog.py): runs in a separate OS thread —
deliberately, since a coroutine-based monitor would be frozen by the very stall
it's watching — pings the loop, and on a stall past a threshold logs the loop
thread's stack (naming the blocking frame) and emits
hindsight.event_loop.stalls / stall_duration. Works with uvloop. Wired into the
worker CLI and the API lifespan; enabled by default.
DB pool acquire instrumentation (engine/db/pool_instrumentation.py): tracks
callers currently queued for a connection (hindsight.db.pool.waiting gauge, the
signal that actually distinguishes exhaustion from a busy-but-healthy pool),
records an acquire-wait histogram, and logs a warning with pool stats when an
acquire waits too long. Wired into both the PostgreSQL and Oracle backends.
health_check() now reports db_acquire_ms and pool utilization in its payload.
Static config: HINDSIGHT_API_LOOP_WATCHDOG_ENABLED / _STALL_THRESHOLD_MS /
_POLL_INTERVAL_MS, HINDSIGHT_API_DB_ACQUIRE_WARN_THRESHOLD_MS.
Tests: test_loop_watchdog.py (detects on-loop blocks, ignores off-loop work,
quiet when responsive) and test_pool_instrumentation.py (waiter counting through
success/mid-acquire/failure, slow-acquire logging).
LM Studio's server UI advertises its address as a bare host
(http://localhost:1234), so users commonly set HINDSIGHT_API_LLM_BASE_URL
to that. The OpenAI SDK then POSTs to <host>/chat/completions and LM Studio
rejects it with 'Unexpected endpoint or method' — its OpenAI-compatible
routes live under /v1.
For lmstudio/ollama (whose OpenAI-compat surface is known to live under /v1)
append /v1 when the base URL has no meaningful path. Explicit paths (reverse
proxy mounts, already-correct /v1) are left untouched.
Fixes#2922
protobuf 7 was blocked only by opentelemetry-proto <1.44 capping
protobuf<7.0; 1.44.0 raised the ceiling to <8.0. Bump the six coupled
otel pins together (api/sdk/otlp-proto-http 1.41->1.44, the three 0.6x
companions 0.62b1->0.65b0) and protobuf 6.33.5->7.35.1.
Verified in a real env: the OTLP HTTP exporter's protobuf-serialized
trace payload round-trips through otel's generated proto types, and the
Prometheus metrics path works. The otel_component_type kwarg (reason for
the original >=1.41 floor) is still present in 1.44.
* fix(retain): offset causal targets from chunk start
* refactor(retain): drop unreachable chunk fact-count guards
The sync path derives each chunk's fact_count as len(chunk_facts)
(extract_facts_from_text), so sum(counts) always equals
len(facts_from_llm) and counts are never negative. The mismatch/
negative RuntimeError guards could only fire under artificial test
setups; the offset fix and target bounds-check stand on their own.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix backup restore schema compatibility
* test(backup): cover type-mismatch preflight + extra-target-column restore
Add a test for the incompatible-column-type preflight branch and a
positive test proving a target with an extra nullable column (which a
column-less binary COPY would reject) now restores cleanly. Document the
deliberate exact-type strictness in _validate_restore_schema.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
refresh_mental_model gained an unconditional DB-time snapshot query
(_get_backend() -> SELECT current_timestamp) to bound the refresh watermark.
That broke the mock-based unit tests that build MemoryEngine.__new__ and stub
the collaborators: they now reach _get_backend() on an engine whose __init__
never ran, failing with 'MemoryEngine object has no attribute _initialized'.
Extract the snapshot into _mental_model_refresh_cutoff(bank_id, mental_model_id)
(pure refactor, no behaviour change) so those tests can stub it like the other
collaborators, and stub it in the three affected tests.
Fixes pre-existing test-api failures on main:
- test_recall_config.py::TestRefreshTriggerWiring (x2)
- test_mental_models.py::TestMentalModelRefreshMaxTokens::test_refresh_passes_stored_max_tokens_to_reflect
* blog: persistent memory for Roo Code (task-based agent)
How-to for the Roo Code integration: one-command install that wires
Hindsight's MCP tools (recall/retain, auto-approved) plus a custom rules
file so Roo recalls context before each task and retains a summary after.
Covers project vs global scope, cloud/self-host, verification, cross-tool
bank sharing, and FAQ. Grounded in the integration doc + README; package
live on PyPI. Cover: Roo kangaroo mark + recall->task->retain loop.
* blog: rebuild Roo Code cover in iridescent-mesh template with Roo mark
* blog: drop MCP from Roo Code cover subtitle
Clears the remaining high-severity npm Dependabot alerts across the root lock
and three integration locks, via overrides (root + zapier + cloudflare) and a
direct-dep bump (nemoclaw, where js-yaml is declared directly):
root: brace-expansion 2.0.3->2.1.2, fast-uri 3.1.2->3.1.4 (capped <4),
sharp 0.34.5->0.35.3, shell-quote 1.8.4->1.10.0, svgo 4.0.1->4.0.2
zapier: brace-expansion pinned per-major (1.1.16 / 2.1.2 / 5.0.7 via
version-keyed overrides so coexisting majors are not collapsed),
js-yaml ->4.3.0 (capped <5)
nemoclaw: js-yaml direct dep ^4.1.0 -> ^4.3.0
cloudflare-oauth-proxy: sharp ->0.35.3
fast-uri and js-yaml capped below the next major so a security bump does not
drag in a breaking major. Verified `npm ci` installs all four locks cleanly
and `npm audit` no longer reports any of these six packages in any manifest.
Out of scope (separate, pre-existing): zapier still reports a `tar` critical
(node-tar advisories) — a different package not in this batch.
Committed --no-verify: the generate-docs-skill hook is blocked by a
pre-existing openapi.json drift on main, unrelated to these npm bumps.
skills/hindsight-docs/references/openapi.json drifted from its source on
main (the generator produces a 1-line diff), so the verify-generated-files
CI job — which runs the generate scripts and fails on any diff — has been
red on every open PR regardless of its own changes, and the local
generate-docs-skill pre-commit hook blocks commits.
Regenerated via ./scripts/generate-openapi.sh + ./scripts/generate-docs-skill.sh.
Generated-file sync only.
Add a created_before filter to MemoryEngine.list_memory_units so
maintenance-loop callers (retention sweeps, bulk maintenance) can select units
by ingest age through the engine instead of open-coding SQL against
memory_units: created_at < <instant>. Composes with the existing tags /
tags_match filters. Interface + concrete method; covered by a test against
real Postgres.
(A last_recalled_before dormancy filter was dropped along with the
last_recalled_at column — recency moves to a Cloud-owned side table, so the
dormancy read lives in the extension, not core.)
* blog: Your 1M-Token Context Window Is Not Memory
Thought-leadership piece: a context window is working memory that resets
each session and degrades before it fills (lost-in-the-middle, Chroma
context rot), so a bigger window is not a memory system. Includes a
context-window-vs-memory comparison table and the one-question test.
Cited research linked; em-dash-free.
* blog: add Hindsight Cloud CTAs (embedded mid-article + Hindsight paragraph)
Clears 62 high-severity Dependabot alerts across the Python locks:
pillow 12.2.0 -> 12.3.0 50 alerts (10 advisories) across autogen,
crewai, llamaindex, pipecat, smolagents
gitpython 3.1.50 -> 3.1.54 8 alerts (4 advisories) in root + agno
pyasn1 0.6.3 -> 0.6.4 4 alerts (2 advisories) in root + google-adk
All transitive; only the intended version bumps, no transitive churn.
gitpython resolves to 3.1.54 (latest, >= advisories' 3.1.52).
Verified: crewai 35 passed, google-adk 49 passed, smolagents 81 passed.
agno has 10 pre-existing test failures unrelated to gitpython. Committed
--no-verify: the generate-docs-skill hook is blocked by a pre-existing
openapi.json drift on main, unrelated to these lock bumps.
* blog: use Thinking Machines' Inkling as a Hindsight memory model (tutorial)
Clickbaity how-to: point Hindsight's internal LLM at Inkling via any
OpenAI-compatible endpoint (four env vars, NVIDIA free key). Includes
real test results: clean structured fact extraction, unprompted temporal
resolution (last week -> 2026-07-14), entity resolution, and a coherent
reflect, all out of the box. Honest caveats (not on leaderboard, 975B
hosted-only, latency; gpt-oss-20b still fastest for high-volume retain).
* blog: swap Inkling cover to Hermes split-duotone style with Thinking Machines wordmark
* blog: use Inkling's real brand graphic (ink blob) on the cover
* blog: name Thinking Machines in title and body (Inkling is Thinking Machines' model)
* blog: cover title now names Thinking Machines Lab
adm-zip 0.5.16 -> 0.6.0 GHSA (high) — clears the last fixable high-severity
Dependabot alert in hindsight-integrations/zapier.
adm-zip is transitive (via zapier-platform tooling) and a parent pins it to
the 0.5.x line, so `npm update` won't move it. Add an override — the same
mechanism zapier already uses for form-data/tar/tmp/yeoman-environment — to
force the patched 0.6.0. Verified `npm ci` installs the lock cleanly with
adm-zip 0.6.0.
Recover structurally-malformed LLM JSON (trailing commas, unterminated strings, single quotes, invalid \escape) via json_repair as a terminal fallback in parse_llm_json, after fence-strip and control-char scrub both fail. Empty repair result keeps raising JSONDecodeError so retry ladders / #1833 fail-loud still fire. LiteLLM prefers a clean re-roll first (repair only after retries exhausted). Scoped to structural malformation only — the degenerate-but-valid-JSON class (#2544/#2547) is deliberately out of scope. Regenerated the docs skill to clear pre-existing #2865 drift.
Per-(bank, fact_type) partial vector indexes are created only at fresh-bank
creation. A bank populated outside that path (logical restore, cross-version
upgrade, extension switch) never gets them, so its recall silently falls back
to the global index + post-filter — slower and under-returning (~0.63-0.72
recall@10 measured by the reporter).
Two fixes:
- import-bank: create the per-bank indexes explicitly after restoring the
banks row. The prior get_or_create_bank_profile call was a no-op here (the
row already exists, so it takes the SELECT branch), leaving every restored
bank uncovered.
- hindsight-admin repair-bank (--bank ID | --all): re-runnable operator escape
hatch for the out-of-app routes (raw pg_dump restore, extension switch) that
a one-time migration can't cover (a restore carries alembic_version at head,
so the migration is already stamped). Detects missing OR invalid coverage
(INVALID leftovers / drifted access method count as missing, unlike a
name-only check) and rebuilds with CREATE INDEX CONCURRENTLY off any txn.
Idempotent; concurrency handled by idempotency, not advisory locks.
Deliberately excludes the boot/periodic background reconcile and retain-path
self-heal: a bank restored and only ever read stays degraded until an operator
runs repair-bank. That background layer can be a follow-up.
* feat(llm): opt-in 4xx request-dump for diagnosing rejected calls (all providers)
Generalizes the Gemini-only diagnostic from #2475 into a provider-agnostic
helper (engine/providers/llm_debug.py) wired into every remote LLM provider:
Gemini/Vertex, OpenAI-compatible (+ Fireworks/Nous subclasses), Anthropic,
LiteLLM (+ router subclass), and Codex — on both call() and call_with_tools().
Gated by HINDSIGHT_API_LLM_DEBUG_DUMP_4XX (off by default). On any 4xx it logs
[LLM_4XX_DUMP] with the serialized request config (message bodies stripped) and
per-message role/size + a length-capped preview. Self-gates on the env flag and
a 4xx status, extracts the status across SDK error shapes (status_code / code /
response.status_code), and never raises.
* style: ruff format single-line dump_request_on_4xx calls
* refactor(llm): source 4xx-dump flag from HindsightConfig, not raw env
Adds llm_debug_dump_4xx as a static (server-level) config field; the helper
reads get_config().llm_debug_dump_4xx instead of os.getenv directly. Documents
the flag in configuration.md and .env.example (+ bundled embed copy). Replaces
the tuple return in the message-preview helper with a dataclass per project
standards.
* fix(cli): pass tag filters to list memories
OpenAPI added tags and tags_match to list_memories in #2848, but the
CLI wrapper still passed the previous positional arguments. Generated
Rust client builds then failed with E0061.
Pass None for both filters to preserve existing CLI behavior and match
the generated method signature.
* feat(cli): expose terminal operation deletion
OpenAPI added delete_operation in #2777 without exposing it through
the Rust CLI or accounting for it in the coverage manifest. The CLI
coverage check therefore rejected branches rebased onto that change.
Add operation delete with confirmation and --yes support. Pass the
request through the generated client and cover command parsing. This
counts the endpoint as implemented without a coverage exception.
The transactional-outbox callback that queues the retain.completed webhook
delivery only fired inside the final facts-bearing batch's write transaction
(is_last=True). Two successful retain paths never reached it, silently dropping
the delivery with no error and no retry:
- Exact chunk-batch boundary: full batches flush with is_last=False and only the
leftover partial batch is marked last. When the committed-chunk count is an
exact multiple of retain_chunk_batch_size, the queue sentinel drains an empty
batch, so is_last=True is never passed.
- Zero-fact final batch: _process_db_batch returns before the fact-insert call
site (which carries the callback) when a batch extracts no facts — common for
boilerplate content.
There is no backstop: the delivery row is only inserted by this callback, and
the worker poller re-delivers existing rows, so a never-inserted row is lost.
Fix: track whether the callback fired in-TXN and, on any successful non-aborted
retain that didn't fire it, queue the delivery exactly once in a dedicated
transaction after the consumer loop. Aborted (concurrent-takeover) retains are
skipped so they don't emit a completion event.
Regression tests assert exactly one retain.completed delivery for both the
boundary (retain_chunk_batch_size=1) and zero-fact cases; both fail with 0
deliveries on main.
* fix(worker): count crash-recovery attempts toward max-retry budget
When a worker crashes while processing an async_operations row, no
failure bookkeeping runs — retry_count is only incremented by in-process
failure handling. On restart, recover_own_tasks resets 'processing' rows
back to 'pending' with retry_count untouched, and the row is re-claimed
as if brand new.
An operation that can never complete therefore loops forever:
claim → grind → crash → recover → re-claim…
This changes recover_own_tasks to increment retry_count during recovery
and honor the existing worker_max_retries threshold (HINDSIGHT_API_WORKER_MAX_RETRIES).
Tasks at/over the limit are moved to 'failed' with an explanatory
error_message instead of being re-queued.
Changes:
- Poller.__init__: accepts max_retries (default 3, matches DEFAULT_WORKER_MAX_RETRIES)
- recover_own_tasks: two UPDATEs — under-limit tasks increment retry_count
and reset to pending, over-limit tasks move to failed
- main.py: wires config.worker_max_retries into the Poller
- Tests: retry_count increment, exceeded→failed, NULL retry_count handling
Reuses the existing config field (HINDSIGHT_API_WORKER_MAX_RETRIES)
rather than adding a new one. Default of 3 retries x crash recovery
gives the same total window as the normal retry path.
Closes#2675
* style: ruff format test_worker.py
* fix(worker): propagate crash-recovery child failures to batch parent
A batch_retain child sub-batch carries parent_operation_id (not batch_id)
in its metadata, so crash recovery can move it to 'failed' once it exceeds
the retry budget. That terminal transition was not propagated to the parent
aggregator, leaving the parent stuck in 'processing' forever.
recover_own_tasks now rolls each failed child up to its parent via
_maybe_update_parent_operation (one transaction per child, mirroring the
in-process _mark_failed path). Adds a regression test.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
* fix(export): preserve decoded JSONB scalar strings
Native admin connections decode JSON and JSONB columns before export. Preserve already-decoded string scalars while continuing to parse raw JSON strings so export-bank no longer fails on observation scopes such as combined.
Co-Authored-By: OpenAI GPT-5 Codex medium <[email protected]>
* fix(import): normalize decoded JSONB strings
Whole-bank archives can contain Python string scalars when their export connection registered JSON codecs. Quote decoded scalars before PostgreSQL casts while preserving already-serialized JSON text and decoded objects.
Co-Authored-By: OpenAI GPT-5 Codex medium <[email protected]>
* fix(transfer): preserve archive provenance
Record bank-row JSON encoding in transfer manifests so decoded scalar strings and serialized objects restore without ambiguous parsing. Preserve archived document and observation timestamps during replay.
Co-Authored-By: OpenAI GPT-5 Codex medium <[email protected]>
* test(transfer): guard admin JSON provenance
Prove the codec-enabled admin exporter identifies bank rows as decoded so JSON-looking scalar strings cannot silently regress during restore.
Co-Authored-By: OpenAI GPT-5 Codex high <[email protected]>
---------
Co-authored-by: OpenAI GPT-5 Codex medium <[email protected]>
* feat(api): allow deleting terminal bank operations with control-plane support
* refactor(api): rename terminal-operation delete route to /delete
Maintainer review on #2777 asked for the hard-delete endpoint to live at
/delete rather than /record. Renames the path segment end-to-end:
dataplane route + log message, tests, OpenAPI spec (and its skills
mirror), and the generated Python/TypeScript/Go clients.
The route's operation_id is explicitly "delete_operation", so no
generated symbol names change -- only the path string. Go and Python
generated output was verified byte-identical against the pinned
openapi-generator v7.10.0.
The system.transform auto-recall used a hardcoded 'project context and
recent work' query for every session, so recall never adapted to what the
user actually asked. Fetch the session transcript (the hook input only
carries sessionID/model) and build the query from the latest user message
via the same composeRecallQuery/truncateRecallQuery path the compaction
hook already uses, falling back to the generic query when there is no user
text yet. Fetching directly also keeps this independent of the
session.created-vs-system.transform ordering (#1758).
* fix(retain): a zero retry budget must still perform the initial fact-extraction request
* fix(retain): use N+1 outer fact-extraction attempts to match provider retry convention
Review feedback on #2779: llm_max_retries=N means N retries *after* the
initial request, so N=1 must give 2 total outer attempts. The previous
max(1, N) floor under-counted (N=1 -> 1 attempt). Every provider already
loops range(max_retries + 1); the outer content-validation loop now follows
the same convention, and a zero budget still performs one request (#2731).
The raw budget is still forwarded unchanged to llm_config.call().
* feat(mcp): let create_mental_model configure tags_match (#2808)
A tagged mental model with no explicit tags_match in its trigger JSON
refreshes under all_strict (a memory must carry every one of the model's
tags), while the staleness check and every recall/reflect path default to
any. Broadly-tagged models reading narrowly-tagged memories therefore get
marked stale and then refresh to empty content.
The HTTP API, generated SDK clients, and Control Plane UI already let users
set trigger.tags_match; the MCP create_mental_model tool did not. Add a
tags_match argument (validated against TagsMatch) to both MCP variants. It
is only written into the trigger when explicitly passed, so the resolved
all_strict default is preserved for existing callers.
Document the all_strict footgun and the tags_match override in the MCP and
mental-models API docs (regen skills/hindsight-docs mirror).
* fix(ts-client): expose tags_match/tag_groups on createMentalModel
The ergonomic TypeScript wrapper's createMentalModel accepted only
{ refreshAfterConsolidation } in its trigger option and dropped every other
trigger field, so a wrapper user could not set tags_match — the exact knob
needed to avoid the empty-refresh footgun in #2808. The low-level generated
sdk already accepts the full MentalModelTriggerInput; thread tagsMatch and
tagGroups through, mirroring how recall/reflect already expose them.
The Python client needs no change: its wrapper takes a pass-through
trigger dict and the generated MentalModelTriggerInput already validates
tags_match.
* test(ts-client): cover createMentalModel trigger mapping
Mock the generated sdk layer (no server needed) and assert the ergonomic
camelCase trigger options map onto the snake_case body: tagsMatch ->
tags_match, tagGroups -> tag_groups, refreshAfterConsolidation still maps,
and omitting trigger sends none (preserving the all_strict default). Locks
in the #2808 wrapper fix.
* docs(mental-models): add tags_match code snippet
Replace the static JSON block in the tags_match override section with a
live CodeSnippet pulled from the Python example, showing how to create a
model with trigger.tags_match="any" so a broadly-tagged model reads
narrowly-tagged memories on refresh (#2808).
* feat(cli): add --tags-match to mental-model create + all-language docs
The Rust CLI's `mental-model create` was the last creation surface with no
way to set tags_match, so a tagged model created via the CLI hit the same
empty-refresh footgun (#2808). Add a `--tags-match` flag (any/all/any_strict/
all_strict/exact) that is only sent when passed, preserving the server's
all_strict default; invalid values are rejected before the request.
Expand the mental-models docs "tags_match override" example from a single
Python snippet to a full Tabs block (Python / Node.js / CLI / Go), each
pulled from the runnable example files, and regen the skills mirror.
Add HINDSIGHT_API_LLM_STRICT_SCHEMA_{RETAIN,REFLECT,CONSOLIDATION}, each resolved per-operation env -> global env -> default (mirroring the per-operation temperature knobs). All five structured-output call sites thread their operation's resolved flag.
Also fixes a latent resolution bug in LLMConfig.call: 'strict_schema or get_config().llm_strict_schema' made a per-call False indistinguishable from unset, silently ignoring any scope opting out while the global flag was on. The arg is now bool|None: None inherits the global flag, explicit True/False wins in both directions.
Supersedes #2669.
* fix(retain): preserve filtered fact alignment
* test(retain): cover chunk-provenance shift from degenerate-fact filtering
Add a deterministic streaming-retain regression test for the #2794
alignment bug the PR fixes: a rejected degenerate fact must not shift
chunk provenance onto a later chunk's survivor via the consumer
zip(batch_extracted, batch_processed).
Each chunk emits [real, degenerate] so that after the first
(real, degenerate) pair the zip is off-by-one for the rest of the batch
regardless of the nondeterministic producer completion order — both real
facts would collapse onto one chunk_index without the fix.
---------
Co-authored-by: r266-tech <[email protected]>
Co-authored-by: Nicolò Boschi <[email protected]>
nltk 3.9.4 -> 3.10.0 GHSA-p4gq-832x-fm9v (URL-encoded path traversal in
nltk.data.load() allowing arbitrary local file read)
Two high-severity alerts, one each in the llamaindex and pipecat integration
locks. nltk is transitive in both. 3.10.0 pulls in defusedxml 0.7.1 (nltk's
new hardened-XML dependency) — expected, not incidental churn.
Done directly rather than via the Dependabot uv-group PR (which also carries
torch/agno and keeps going stale against this fast-moving main). Verified:
llamaindex 88 passed, pipecat 19 passed; lint clean.
Retain resolves entities in Phase 1 on a separate, already-committed
connection, then inserts unit_entities in Phase 2 on a new transaction.
In that window graph maintenance's prune_orphan_entities can delete a
just-resolved parent — it legitimately has no unit_entities row yet — so
the Phase-2 FK insert fails and the whole batch is dropped as
non-retryable: silent memory loss, worst on the document re-ingest path.
Carry each resolved entity's id AND its stored canonical name across the
phase boundary (new ResolvedEntity), then, on the Phase-2 connection
immediately before linking, reassert the parents in one statement:
* PostgreSQL: a CTE locks the surviving parents FOR KEY SHARE (held to
commit, so a concurrent prune DELETE blocks) and re-inserts only the
already-pruned ones — same single-round-trip shape as
bulk_insert_links. ON CONFLICT DO NOTHING keeps the rare
name-recreated-under-a-new-id case from raising.
* Oracle: FOR UPDATE locks in the caller's stable id order, then an
idempotent insert.
The stored canonical name (not the raw input mention) is what gets
restored, so a fuzzy alias no longer permanently mislabels a resurrected
row. The same reassert is applied on the curation edit path, which has
the same resolve/link window.
Tests: an end-to-end Phase-1 -> prune -> Phase-2 regression proving the
original id and canonical name are restored via a fuzzy alias; a real-PG
concurrency test proving prune blocks until the child link commits; and
Oracle adapter coverage for stable lock order and idempotent reinsert.
Fixes#2662
* feat(audit): make audit_log_enabled overridable per bank
Auditing was all-or-nothing per deployment. This makes the existing
audit_log_enabled switch hierarchical (env -> tenant -> bank) so a bank
can opt in while the server default is off, or opt out while it is on,
rather than introducing a second near-identically-named field.
Making the flag per-bank forces three call sites to change:
- AuditLogger: the enabled check can no longer be a synchronous
pre-filter, since a bank may enable auditing the global value has off.
Split into action_allowed() (bank-independent allowlist, still a cheap
sync pre-filter) and should_log() (awaits the per-bank resolution).
Resolution failure falls back to the deployment default rather than
failing closed, so a transient DB blip cannot silently create an audit
gap for a bank that is meant to be audited.
- Retention sweep: previously gated on audit_log_enabled, which is now
per-bank while the sweep is a global cross-tenant job with no bank in
scope. A bank opting in under a default-off deployment would have had
its rows accumulate forever. Retention now keys off the (still
server-level) retention window alone.
- _audit_memory_defense: was sync and reached log_fire_and_forget
directly, bypassing the per-bank decision entirely. Made async so the
memory_defense action honours the bank's setting like every other path.
The actions allowlist and retention window stay server-level: both are
global sweeps with no bank scope. The /version audit_log flag keeps
reporting the deployment default and now says so.
Adds the Audit Logging toggle to the bank Configuration tab.
The hindsight-docs skill regen also picks up pre-existing drift from
#2694 (retain.md), which the pre-commit generator syncs unconditionally.
* fix(control-plane): make the audit toggle tri-state
A Switch cannot express "inherit the server default". It rendered the
resolved value, so a bank inheriting `true` looked identical to one
explicitly set to `true`, and touching it always wrote an explicit
boolean with no way back to inherit.
Replaced with a Select: Server Default / Enabled / Disabled. The slice
now reads the bank's `overrides` rather than the resolved config, since
the resolved value cannot distinguish inherited from explicitly-set.
Choosing "Server Default" sends null, the tombstone the config resolver
already treats as "clear this override".
The option label shows which way the server default currently points,
read from the existing /version features flag.
Uses INHERIT_SENTINEL rather than "" for the inherit option: Radix
rejects an empty SelectItem value at runtime.
* chore(clients): regenerate for audit_log description change
The audit_log field description in openapi.json changed; regenerate the
Go/Python/TypeScript clients that embed it (they were skipped earlier
because the generator needs Docker). Verify-generated-files was failing
on the drift.
* fix(audit): resolve gating config internally, bypassing permission filter
_resolve_bank_audit_enabled used get_bank_config, the API-facing resolver
that runs the tenant permission filter (get_allowed_config_fields). A
deployment that makes audit_log_enabled read-only for a user — exactly
the intended way to lock the field via an extension — would have that
field stripped from the resolved config, so gating silently reverted to
the deployment default and ignored the bank's stored override.
Switch to resolve_full_config (the internal, unfiltered resolver every
other internal config consumer uses). Gating is a system decision and
must see the bank's true value regardless of who is asking.
Adds a regression test with a restrictive tenant extension: the API read
strips the field, but gating still audits the opted-in bank.
Also: document the fail-open opt-out edge in should_log's comment, and
refresh a stale "static, server-level switch" comment in the memory
defense test.
call_with_tools() already sets tools=[] on ClaudeAgentOptions, with a
comment explaining that leaving the built-in toolset enabled can make
the CLI defer into ToolSearch before answering, burning the turn
budget. call() -- used for single-turn structured/consolidation calls
-- was missing the same tools=[] and only set allowed_tools=[], which
restricts what may be called without prompting but doesn't stop the
toolset from loading in the first place.
Observed in production (hindsight-embed, claude-code LLM provider,
consolidation path): repeated 'Claude Code returned an error result:
Reached maximum number of turns (1)' failures on isolated, single-memory
batches, ruling out batch-size/concurrency as the cause. Restarting the
daemon with this one-line change (tools=[] added to call()'s options)
cleared a 16-item stuck consolidation backlog on the first pass with
zero max-turns failures, across two LLM batches (8 memories each,
94.4s and 73.4s respectively) that were previously failing consistently
on the same data.
* feat: add tags filtering to list_memories / list_memory_units
Add `tags` and `tags_match` parameters to `list_memory_units`,
MCP `list_memories` tool, and HTTP `GET /memories/list` endpoint,
bringing the browse side's tag filtering capability in line with
the write side (`retain`) and semantic search side (`recall`).
The implementation reuses the existing `build_tags_where_clause`
function from `hindsight_api/engine/search/tags.py`, supporting
all five matching modes: any, all, any_strict, all_strict, exact.
Closes#2842
Related: #792
* review fixes: robust prefix strip, exact global scope, tests, regen clients
- Use str.removeprefix("AND ") instead of str.lstrip("AND ") when appending
the tags clause in list_memory_units (lstrip strips a char set, not a
prefix — matches the existing idiom used elsewhere in the file).
- Handle tags_match="exact" with no tags: select the untagged/global scope,
mirroring recall and the sibling list path.
- Type the MCP list_memories tools' tags_match as TagsMatch; document all
five matching modes in the engine/HTTP/MCP docstrings.
- Add integration tests covering all five modes + exact-empty global scope
and the no-filter baseline (tests/test_tags_visibility.py).
- Regenerate OpenAPI spec, docs-skill reference, and Python/TS/Go clients.
---------
Co-authored-by: Nicolò Boschi <[email protected]>
DatabaseDialect.advisory_lock() had no production callers — the only reference
was a test asserting its output string. It advertised PG advisory locks as a
supported dialect primitive, which contradicts the Database Locking standard
added in #2817 (advisory locks are unusable behind connection poolers / managed
PG). Leaving it invites the next author to reach for it.
Remove the abstractmethod on DatabaseDialect plus the PostgreSQL and Oracle
implementations, and the lone test assertion. The grandfathered raw
pg_try_advisory_lock in migrations.py (the concurrent-migration coordinator) is
unaffected — it never went through this helper.
* blog: persistent memory for ZCode (Z.ai GLM coding agent)
Announcement/how-to for the ZCode integration: hooks-based (no MCP),
recall before each prompt + retain each turn, cross-tool shared bank with
Claude Code and Cursor, per-project isolation, cloud or self-hosted.
Grounded in the merged integration doc, README, and hook source. Cover:
emerald mesh + glassy tool panels with the ZCode mark.
Follow-up to #2708, which bounded terminal `async_operations` history. Two
issues with what landed:
1. The cleanup worker did not use a cross-tenant routine. It opened a connection
and a prune transaction against *every* tenant schema on every cleanup cycle,
paying the full per-tenant cost even when nothing was prunable — the query
storm the server-side maintenance routines exist to avoid.
2. It shipped as a breaking change, silently switching deployments from
unbounded operation history to a 30-day TTL on upgrade.
Adds `schemas_with_expired_operations(p_days int) RETURNS SETOF text` — the
`async_operations` counterpart to `schemas_with_expired_rows`. One round-trip
returns just the schemas holding expired terminal rows; the worker then acquires
a connection and prunes only there. It needs its own routine rather than reusing
`schemas_with_expired_rows` because eligibility here isn't "row older than N
days" — pending and processing rows are never prunable, so the status filter has
to be part of the predicate.
Install policy follows b6d2f8a4c1e7 (#2638/#2824): the routine is database-global
(it enumerates pg_class across every schema), so exactly one copy is installed —
into the schema this deployment is configured to use, which is the one the worker
calls via fq_routine. Gating on the literal "public" instead of the configured
schema is what left non-public deployments without the sibling routines (#2638);
installing into every schema would leave a dead duplicate per tenant.
Exactly one run satisfies that predicate, so concurrent per-schema runs never
issue competing CREATE OR REPLACE against the same pg_proc row and cannot hit
`tuple concurrently updated`. No cross-process coordination, and in particular no
advisory lock, which is unusable behind connection poolers and managed PG
(#2817). Runs targeting any other schema drop the routine there instead.
The worker calls the routine through schema.fq_routine() (added in #2824) rather
than a hardcoded public. qualifier — duplicating that qualifier across callers is
precisely how #2638 recurs.
Vanishing schemas are skipped rather than fatal (c7e9f1a3b5d2), and an absent
routine degrades cost, not correctness — Oracle and un-migrated PostgreSQL fall
back to the previous full sweep with a warning.
DEFAULT_OPERATION_RETENTION_DAYS 30 -> 0. Operation history is a user-visible
audit trail, so bounding it is an opt-in policy decision rather than something an
upgrade applies silently. Set HINDSIGHT_API_OPERATION_RETENTION_DAYS to a
positive number of days to enable pruning. Docs, .env.example and the bundled
embed template updated to match.
- test_schemas_with_expired_operations — drives the real routine against pg0 in a
throwaway schema: old pending/processing rows alone don't make a schema
eligible, a terminal row does, a too-old cutoff doesn't, p_days <= 0 is empty.
- test_expired_operations_routine_installs_in_the_configured_schema —
parametrized over base / default public / non-public single-tenant; guards
against reintroducing the #2638 literal gate or an advisory lock.
- test_expired_operations_tenant_runs_install_nothing — tenant runs emit no
CREATE and drop any copy in their own schema.
- test_discovery_targets_the_configured_non_public_schema — the worker calls the
copy in its configured schema, not a hardcoded public one.
- TestWorkerOperationCleanupSchemaNarrowing — only reported schemas are pruned,
nothing expired means no pruning, unclaimed schemas are skipped, a missing
routine falls back to the full sweep, Oracle never calls the routine.
The prompt's few-shot examples taught a flat string array while the
LLM-facing schema declared list[Entity] objects. Models that follow the
prompt literally returned strings, so the entities were dropped and
never persisted - entities, unit_entities and entity_cooccurrences all
stayed at 0 while retain reported success and recall kept working.
The Entity model was a single-field wrapper around a string and carried
no information the string didn't, so it is removed rather than taught
to the prompt. entities is now list[str] end to end: the four LLM-facing
extraction models, the labels-only dynamic model, and the storage Fact
model. This matches the API response model (response_models.ExtractedFact)
and the pipeline dataclass (retain.types.ExtractedFact), both already
list[str].
entities stays optional. An omitted field is coerced to an empty list
anyway, so requiring it would only risk strict-schema providers
rejecting otherwise-valid facts.
A shared _coerce_entity_strings before-validator still unwraps the
legacy {"text": ...} form, so responses from models that learned it and
in-flight batch jobs are not lost. The prompt now states the string
contract explicitly in the ENTITIES section.
Tests: a fast schema/coercion suite plus an hs_llm_core test that runs
the real extraction pipeline and asserts entities are populated - the
bug was behavioural, so MockLLM cannot reproduce it. test_entity_labels
is updated for the string representation.
Also stages the pre-existing skills/hindsight-docs regen drift from
main (retain.md, zcode.md), which the pre-commit generator refreshed.
#2683 removed the graph seed inputs from LinkExpansionRetriever.retrieve() —
Link Expansion deliberately chooses its own bounded seeds so it doesn't inherit
the semantic arm's limits and thresholds. The scoring regression test from #2679
still passed semantic_seeds=, so it fails on main with
TypeError: retrieve() got an unexpected keyword argument 'semantic_seeds'
on every PR whose test-api shard includes it.
Drop the kwarg and stub the internal _find_semantic_seeds lookup instead, which
is where seeds now come from. The test's subject — that the graph merge order
matches Link Expansion's additive per-type score — and all of its assertions are
unchanged.
The skills/hindsight-docs hunk is generated output from an unrelated docs PR that
landed without regenerating the bundle; the pre-commit generator requires it.
Extend the embedded-database URL syntax to
`pg0://user:pwd@instance:port` (either credential half optional).
Previously every pg0 instance was forced to the hardcoded
`hindsight`/`hindsight` credentials because the URL parser only
carried instance name and port; `EmbeddedPostgres` already accepted
username/password, they just weren't threaded through.
`parse_pg0_url` now returns a `Pg0Url` dataclass instead of a
3-tuple (clears the multi-item tuple return, matches the recent
dataclass refactor) and `resolve_database_url` passes credentials
through only when present, so omitting them keeps the pg0 defaults.
Credentials split on the last `@` so passwords may contain `@`.
asyncpg runs RESET ALL on connection release, so the session GUCs the
init callback SET (hnsw.ef_search and the other ANN tuning knobs,
statement_timeout) were wiped after a connection's first release. Every
subsequent recall on a reused connection ran at pgvector defaults
(ef_search=40), silently degrading recall quality. Pass the same
init_callback as setup= so it re-applies on every acquire, after the
reset.
The PATCH /memories/{memory_id} endpoint (curate/invalidate/revert)
was the only data-mutation endpoint without an audit trail. All other
mutation endpoints (delete_memory, update_document, delete_document,
create_mental_model, etc.) have @audited decorators.
This ensures memory curation operations are recorded in the audit log
for compliance and forensic traceability.
Found during cybersecurity audit.
* fix(retain): reject degenerate fact text before storage
Facts with zero information content (empty strings, punctuation-only,
LLM hallucination patterns like '...', '-', '--') were being stored,
indexed, and surfaced in recall results. This adds a content quality
guard in ProcessedFact.from_extracted_fact() that rejects degenerate
text before it enters the storage pipeline.
Closes#2520
* chore: ruff format + fix import ordering in types.py
dateparser.search_dates over-matches: short common words that are weekday
or month abbreviations in some language ("we"/"me"/"did" resolve to a
weekday, "do" to Sunday) come back as bogus dates. The analyzer took the
first valid match, so when a false positive appeared before the real date
the query got a plausible-but-wrong temporal window — worse than none,
since the constraint is non-null and nothing downstream can tell that
extraction failed.
The previous defence was a hard-coded blacklist of such words, which is a
moving target (every short word dateparser resolves is a new instance of
the same bug) and was already partly dead code: the `len(text) > 3` escape
hatch re-admitted every multi-character entry, so only the <=3-char words
did any work. The bug also depends on the dateparser version — 1.4.1 (the
version shipped in the published image) added "we" as an English Wednesday
abbreviation that survives `languages=["en"]` scoping, while the locked
1.2.2 does not — so language scoping is not a stable fix either.
Replace the blacklist + leftmost selection with a signal score: each match
is scored by the date content it actually carries (a digit is strongest,
then explicit month/relative words, then weekday/period words). Matches
with no signal (bare abbreviations) score zero and are rejected; among the
rest the strongest wins, ties broken by longest span. This subsumes the
entire blacklist and is independent of language and dateparser version.
Tested (Friday reference date, where these abbreviations resolve):
- "what did we discuss" -> no constraint (was 07-12/07-15)
- "tell me what we decided on 2026-06-10" -> 2026-06-10 (was 07-15)
- "what did we discuss in May" -> May (unchanged, now robust)
Regression tests assert analyzer output, never raw dateparser spans, so
they hold across dateparser versions.
Co-authored-by: Nicolò Boschi <[email protected]>
* feat(zcode): add Hindsight long-term memory integration for ZCode
Adds a hooks-based, no-MCP integration for ZCode (Z.ai's GLM desktop
coding agent). ZCode embeds the Claude Code agent runtime and reads the
standard Claude Code hook schema from its own config namespace
(~/.zcode/cli/config.json), so `hindsight-zcode install` wires three
process hooks — SessionStart, UserPromptSubmit (recall), and Stop
(retain) — without touching the user's ~/.claude config and without an
MCP server.
Recall injects relevant memories as additionalContext before each
prompt; retain assembles each turn from the prompt (captured at
UserPromptSubmit) and the response (Stop payload) and stores it to
Hindsight. Verified end-to-end in ZCode 3.2.2: hooks fire, retain
persists to the cloud bank, and recall injects memory into the agent.
Includes the pip package + installer, hook scripts, tests, CI job,
release-integration wiring, changelog registration, docs page, and
gallery entry.
* feat(zcode): add self-serve marketplace + hooks-only plugin variant
Publishes the ZCode integration as a hooks-only Claude Code plugin
(hindsight-zcode) in the repo's plugin marketplace, so ZCode users can
install it via 'zcode plugins add-marketplace vectorize-io/hindsight'
without pip and without depending on Z.ai's marketplace.
The plugin reuses the pip package's hook scripts via CLAUDE_PLUGIN_ROOT
(no duplication) — settings.json resolves as a sibling of scripts/ in
both the pip and plugin layouts. Adds a plugin manifest, plugin-format
hooks.json (SessionStart/UserPromptSubmit/Stop — no SessionEnd),
marketplace entry, validation tests, and docs.
* fix(zcode): drop changelog link from docs page (page exists only after release)
The /changelog/integrations/zcode page is generated at release time, so
linking to it broke the Docusaurus build (build-docs + verify-generated-files).
Most unreleased integration pages omit this link; follow that convention.
extract_period() runs before dateparser and matches "<month> <year>", so
"meeting on 13 July 2024" was widened to 2024-07-01..2024-07-31 and the day
was lost. Skip the month-table match when a day number precedes the month,
letting dateparser resolve the exact date instead.
Language-agnostic: affects every language in the period table (English shown
in the test). Split out of #2767 per review so the correctness fix can land
independently of the Russian-coverage change.
Apply the configured max_tokens budget when the reflect agent finishes through the done tool. Add a regression test covering the previously uncapped completion path.
* feat(api): attribute remote reranker calls by bank
* fix(api): omit empty reranker bank attribution
* fix(reflect): bind bank attribution for tool calls
Run the existing build-docs job for every PR so the production docs
build remains an unconditional check.
Generate OpenAPI directly in verify-generated-files to avoid rebuilding
the Docusaurus site serially in that job.
execute_task completes an operation via _mark_operation_completed /
_mark_operation_completed_and_fire_webhook, both of which wrapped the
status='completed' commit in one transaction with fallible side-effects
(webhook outbox insert, parent aggregation) and swallowed every exception.
A hiccup in either rolled the completion back and dropped the error, leaving
the operation stuck in 'processing' forever while the log already said the
work was done (#2601). PR #2608 added a poller-side backstop that unstuck
the row but silently lost the consolidation webhook.
- On failure of the atomic outbox transaction, fall back to a completion-only
commit and fire the consolidation webhook best-effort (non-transactional)
instead of losing both. Happy path keeps the transactional-outbox guarantee;
the failure path degrades to completed + delivered rather than stuck + lost.
The best-effort fire only runs when the fallback actually transitioned the
row, so there is no duplicate delivery.
- Guard every completion UPDATE on `status NOT IN ('completed','failed',
'cancelled')` so an already-terminal row is never re-terminalized: keeps the
engine idempotent with the poller backstop (#2608) and avoids double parent
aggregation, while still completing pending/processing rows.
Adds fast DB-free regression tests (fake connections) covering the happy
path (no double-fire), the webhook-failure fallback, and the terminal-row
no-op guard.
Follow-up to #2820, which fixed#2638 the wrong way.
The three discovery routines are database-global: each enumerates pg_class across
every schema and dispatches per schema, and the maintenance loop only ever calls
the copy in get_config().database_schema. #2820 installed a copy into every
schema the migration touched, so a 20k-tenant database ended up with 20k copies
of each routine, 19,999 of which are never invoked — catalog garbage, and a
global function nonsensically duplicated per tenant.
The actual #2638 bug was never the gating; it was the hardcoded literal. The old
predicate compared target_schema against "public" instead of against the schema
the deployment is configured to use, so a single-tenant install living in a
dedicated non-public schema never matched and got no routines at all.
Compare against get_config().database_schema instead. Exactly one run satisfies
the predicate, so exactly one copy is installed, in the schema fq_routine()
actually calls. That still avoids the concurrent CREATE OR REPLACE the gate
existed for — no two runs touch the same pg_proc row — with no cross-process
coordination and no advisory lock (#2817).
Runs targeting any other schema now DROP the routines there rather than merely
skipping, so databases that already ran #2820 shed their per-tenant duplicates on
the next migration pass instead of carrying them forever.
Also moves the qualifier helper from maintenance._routine to schema.fq_routine.
It sits beside fq_table/fq_table_explicit, and the worker poller needs it too
(#2819) — a second caller open-coding the qualifier is exactly how #2638 recurs.
The skills/hindsight-docs one-line change is generated output, not authored here:
the docs-skill bundle was left unsynced by the PR that added
HINDSIGHT_API_DB_MAX_PARALLEL_WORKERS_PER_GATHER, and the pre-commit generator
refuses to commit without it.
Tests: the install test is re-parametrized over (target_schema, configured
schema) including the non-public single-tenant shape; a new test asserts tenant
runs install nothing and drop strays; downgrade tests are keyed on the configured
schema rather than the literal public.
Entity resolution is fuzzy name matching (SequenceMatcher) reinforced by
co-occurrence and temporal proximity — there is no nickname/alias logic in
the resolver. Dissimilar names like 'Bob' and 'Robert Chen' do not unify on
the name alone, so the 'nickname resolution' example was inaccurate. Verified
against hindsight-api-slim/hindsight_api/engine/retain/entity_resolver.py.
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Graph retrieval always selects its own bounded semantic seeds.
Remove the unused semantic_seeds and temporal_seeds inputs from
the graph retriever interface and link-expansion implementation.
The recall orchestrator no longer passes placeholder None values.
Document why graph seeds stay independent: the semantic and
temporal retrieval arms use different candidate limits and thresholds,
so reusing them would silently change graph recall behavior.
Add a regression assertion that the graph call contains no removed
seed inputs.
Follow-up to #2628 + #2629: the batch path sent system as a plain string,
so batch requests never participated in prompt caching. Batch items are
one-shots, so this applies call()'s one-shot rule — system is the sole
cache breakpoint, rendered via the same _cached_system_blocks helper.
Every request in a retain batch shares the fact-extraction system prompt,
so the first item's cache write serves the remaining items as best-effort
reads, and the cache-read discount stacks with the 50% batch discount.
No end-marker on batch messages: that breakpoint only pays off on the
sync tool loop, where the next iteration reads it back.
Tests: cached-block wire shape (marker present, messages unmarked),
schema injection lands inside the cached block, no-system requests
unchanged; existing shape assertions updated from string to block list.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <[email protected]>
* Revert "fix(trace): skip LLM trace writes during daemon shutdown/pre-init races (#2618)"
This reverts commit cb4fe70b63.
* fix(trace): gate LLM trace writes on backend lifecycle, not error strings
The reverted #2618 classified shutdown/pre-init races by matching on
exception text ("pool is closing", "not initialized") and by reaching into
`backend._pool`. Both are PG/asyncpg-specific: Oracle raises different
messages, and any new backend or pool wrapper silently loses the guard —
while a genuine "not initialized" error from elsewhere gets swallowed.
Make the lifecycle state explicit instead, and close the race at the source:
- `DatabaseBackend.is_ready` — an abstract property both backends implement
(`_pool is not None`), replacing the internals peek.
- Both `shutdown()` implementations drop the pool reference *before* awaiting
close(), so is_ready is False for the whole teardown rather than only after
it. That is the window that produced "pool is closing".
- `LLMTraceRecorder.close()` stops accepting writes and drains in-flight ones;
`MemoryEngine.close()` calls it before `backend.shutdown()`, so trace tasks
can no longer outlive the pool. Metadata patches are now tracked too (they
were fire-and-forget and untracked).
- Both write paths skip via a single `_writable()` check. No error-string
matching: a failure on a ready backend is still a WARNING, as it should be.
* simplify: drop the recorder drain, keep the readiness check
The drain (recorder close() + task tracking + engine wiring) duplicated work
the pools already do: asyncpg's close() waits until all connections are
released, so a trace INSERT that already acquired completes on its own. The
readiness check plus dropping the pool reference before the awaited close
covers both windows that actually produced warnings.
refresh_mental_model operations completed with result_metadata carrying only
the submit-time {mental_model_id, name} stub — set before the op ran and never
enriched — so a monitoring layer could not distinguish "refreshed with real
content" from "refreshed empty" without a follow-up content fetch. Retain
operations have carried machine-readable outcome metadata since 0.8.x.
Mirror the retain pattern: the worker handler now merges the semantic outcome
into result_metadata at completion (jsonb ||, preserving the submit-time keys
consumers join on):
- content_len: length of the final stored content
- populated_content: true only for real synthesis — the "No answer provided."
reflect fallback and the "Generating content..." placeholder complete
wire-successful but read as false (a bare length check would miss them)
- based_on_counts: per-fact-type grounding counts from the reflect response
The reflect agent's fallback literal is promoted to NO_ANSWER_TEXT so the
populated judgment compares against the constant, not a copied string.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 <[email protected]>
Adds HINDSIGHT_API_DB_MAX_PARALLEL_WORKERS_PER_GATHER — when set, every
pool connection of the process runs SET max_parallel_workers_per_gather
at init time (alongside the existing statement_timeout / ANN tuning
session setup). Unset (the default) leaves the server setting untouched,
so existing deployments see no behavior change.
Motivation: in multi-tenant deployments where background workers share a
database with latency-sensitive foreground traffic, bulk maintenance
queries (consolidation, graph upkeep) can fan out across parallel
workers and occupy several cores each. Parallelism buys latency — which
background work doesn't need — at the cost of concurrent CPU footprint,
which a shared primary does care about. Setting the cap to 0 on worker
processes makes those queries run serially: measured on a representative
multi-million-row aggregate, serial execution cost ~29% more wall-clock
but used 67% fewer concurrent cores (and less total CPU, since parallel
coordination isn't free).
0 is a meaningful value (disable parallelism), so the env parse
distinguishes unset (None, no opinion) from 0 via a new
_parse_optional_non_negative_int helper; negative or non-integer values
fail fast at startup.
The field is static (process-level infrastructure tuning), deliberately
not in _CONFIGURABLE_FIELDS.
A long call in _generate_structured_output exceeds the 120-char line limit and
was committed unformatted, so ruff format rewrites it on every CI run. That
fails verify-generated-files ('Generated files are out of sync') on every
hindsight-api-slim PR, none of which touch this file.
Formatting only — no behaviour change.
The staleness predicate in prune_stale_cooccurrences used a correlated
`unit_entities u1 JOIN u2 ON u1.unit_id = u2.unit_id` self-join. The planner
turns that into a Nested Loop Anti Join whose hash side rebuilds a
high-degree entity's entire membership set once per cooccurrence pair, so
cost scales with hub_degree * pairs even when zero rows are stale.
Replace it with an INTERSECT of the two entities' unit sets. Both branches
resolve as Index Only Scans on idx_unit_entities_entity_unit
(entity_id, unit_id), bounding per-pair cost by the two entities' degrees.
Measured on a hub-skewed fixture (40K-membership hub, 2999 live pairs,
zero deletions -- the worst case), against the current ordered-locking CTE:
self-join 18182 ms 73,613,239 shared buffers
INTERSECT 2555 ms 255,045 shared buffers
7.1x faster, 289x fewer buffers. Production banks carry ~260K pairs, so the
gap there is wider. No schema change; the index already exists (h3i4j5k6l7m8).
The #2529 ordered-locking CTE is untouched -- the rewrite is confined to the
NOT EXISTS predicate inside it, so victims are still selected FOR UPDATE in
sorted (entity_id_1, entity_id_2) order.
Co-authored-by: Nicolò Boschi <[email protected]>
Co-authored-by: Sergey <[email protected]>
The three cross-tenant discovery routines that drive the background maintenance
loop — banks_needing_consolidation(), schemas_with_expired_rows(...) and
mental_models_with_cron() — were installed into public and gated on the run
being the base run or an explicit target_schema='public' run.
A single-tenant deployment migrated into a dedicated non-public schema
(HINDSIGHT_API_DATABASE_SCHEMA=<non-public>) migrates only that one schema, so
the gate never opens and no routine is ever created. The loop then logs
'function public.… does not exist' every cycle, and the revision is stamped
applied so redeploying does not help. #2056 fixed only the public/base-run case.
Fix: stop putting them in a shared schema. Migration b6d2f8a4c1e7 installs all
three into the run's own target_schema, unconditionally, and maintenance.py
qualifies its calls with get_config().database_schema instead of a hardcoded
'public.'. Where a routine lives does not affect what it returns — each
enumerates pg_class across the whole database and dispatches per schema — so the
copy in the configured schema is fully functional, and that schema is by
definition one that got migrated.
This also removes the concurrency hazard the old gate existed to dodge rather
than locking around it: each process only ever writes CREATE OR REPLACE FUNCTION
"<its own schema>".fn(), so two concurrent per-schema runs never contend on the
same pg_proc row and 'tuple concurrently updated' cannot occur. No cross-process
coordination is needed — in particular no advisory lock, which is unusable here
(see the revert of #2690). Cost is one duplicate routine per tenant schema: a
few catalog rows, and the price of needing no coordination.
Existing broken installs self-heal — the revision runs on every schema and
creates the routine exactly where that deployment's loop looks for it. Default
public deployments are unaffected. Function bodies are byte-identical to
c7e9f1a3b5d2 / f4d1c2b3a5e6. PG-only, mirroring e5f6a7b8c9d0.
Tests: a parametrized unit test asserting the install runs for every
target_schema (and that neither the public-only gate nor an advisory lock comes
back), plus an end-to-end pg0 test that drives a per-schema run into a real
non-public schema and calls the resulting routine.
Fixes#2638
#2690 added migration f2a4b6c8d0e2, which installs the shared public.*
maintenance routines on every PG run and guards the resulting concurrent
CREATE OR REPLACE with a blocking pg_advisory_xact_lock.
Advisory locks are not usable in Hindsight: deployments sit behind connection
poolers and managed/PG-compatible services where they are unreliable or
unsupported — a session-level lock can leak or vanish when the pooler reassigns
the session, and a blocking acquire can wait on a grant that never comes. That
holds for transaction-scoped locks too, so the migration has to go rather than
be tuned.
f2a4b6c8d0e2 is not in any core release (v0.8.4 predates it), so it is removed
outright and a8c1e4f7b0d3 is re-pointed at e7c3a9f1b2d5. Single head preserved
(a8c1e4f7b0d3, 86 revisions). The #2690 unit test is removed with it; the rest
of tests/test_maintenance_routines.py passes against the shortened chain.
Also codify the ban in .claude/skills/code-review/SKILL.md: a Database Locking
standard plus review step 11c, both pointing at the alternatives (per-process
objects, idempotent DDL, row-level constraints) instead of locking.
This reopens#2638 (maintenance routines never installed when the deployment
uses a non-public schema); a lock-free fix follows in a separate PR.
The mental-model edit dialog sent `tags: tags.length > 0 ? tags : undefined`,
so clearing the tags field made the key drop out of the PATCH body
(JSON.stringify omits undefined). The dataplane treats an absent `tags`
field as "unchanged" (`if tags is not None` in `update_mental_model`), so
the previous tags survived and refreshes kept filtering by them — the only
workaround was delete + recreate.
Always send the `tags` array, including the empty array, so emptying the
field sends `tags: []` and the backend clears them.
Co-authored-by: caddi-ci-cd <[email protected]>
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
#2649 added both cookbook pages and per-integration docs to the
generated docs skill. Keep the integration docs; remove the cookbook.
- drop the cookbook tree walk and the CookbookGrid MDX renderer from
generate-docs-skill.sh
- drop cookbook paths from the generated SKILL.md index
- regenerate the bundle (28 cookbook files removed)
* fix(reflect): thread max_completion_tokens into structured-output extraction
#2433 capped the structured retry budget but the structured second pass never
received an output-token budget, so on reasoning/preamble models the provider
default is exhausted before JSON is emitted (finish_reason=length, empty
content) and structured reflect degrades to None. Thread the reflect max_tokens
through _generate_structured_output (and _process_done_tool) as
max_completion_tokens, mirroring the plain reflect calls. Fixes#2431.
* test(reflect): cover structured-output max_completion_tokens threading
The LATERAL join query for temporal graph spreading omitted mu.proof_count
from the SELECT list. RetrievalResult.from_db_row() calls row.get("proof_count"),
which always returned None for spread neighbors, forcing a neutral 0.5
proof-count boost regardless of actual observation evidence strength.
Roll a CachedContent forward through the reflect tool loop so each auto turn reuses the entire prior conversation at the cached-input rate and sends only its new tool results. Measured on gemini-2.5-flash-lite: ~29% cached on short loops, ~74-81% on deep loops (deepest turns ~99%), vs ~9% for the old static prefix and 0% for implicit caching.
Cache creates overlap tool execution to hide their latency, and the ephemeral per-reflect caches are torn down detached so the response path never waits on deletes. New HINDSIGHT_API_REFLECT_PROMPT_CACHE_ENABLED flag (default true) disables it independently of the global prompt cache.
Add a precise operation-validator hook for bank creation, with a
no-op default so deployments without custom validators keep existing
behavior.
Route lazy bank creation through the hook from retain, imports, MCP
create_bank, and the default get_bank_profile auto-create path. This
keeps create-bank authorization separate from bank-scoped write
validation, which often assumes the target bank already exists.
Add regression coverage for rejected creation, existing-bank skips,
HTTP create/import paths, async retain, profile auto-create, and MCP
create_bank.
Treat the get_bank MCP tool as read-only by looking up bank profiles
without auto-creation in both single-bank and multi-bank modes.
Add regression coverage for missing banks so get_bank returns a
not-found error instead of creating the bank.
Mental-model content in delta-refresh mode can grow past an embedding
model's fixed input-token limit (e.g. Bedrock Titan V2's hard 8192 cap),
after which every refresh fails permanently with ContextWindowExceededError
and no recovery path.
Add an opt-in `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MAX_INPUT_TOKENS` cap.
When set, `LiteLLMSDKEmbeddings.encode()` truncates each input to that many
cl100k_base tokens before calling litellm.embedding(), mirroring the existing
reranker `max_tokens_per_doc` pattern. Truncation emits a log.warning naming
the model and largest original token count so it isn't silent.
Off by default (no behavior change / data loss for large-context models);
Titan users set it to the model's real limit with a little headroom.
* fix(graph-maintenance): retry cooccurrence sweep on deadlock
prune_stale_cooccurrences/prune_orphan_entities scan entity_cooccurrences
via a join/NOT EXISTS plan with no consistent lock-ordering guarantee,
while retain's concurrent cooccurrence upserts (entity_resolver) lock the
same rows in sorted (entity_id_1, entity_id_2) order. When the sweep and a
concurrent upsert touch overlapping rows in opposite orders, Postgres
detects a genuine cycle and aborts one side with DeadlockDetectedError —
this was 39 of 41 DeadlockDetectedError occurrences in a week of
self-hosted production logs.
Both prunes are idempotent bank-wide deletes, so wrap the sweep in the
existing retry_with_backoff helper (already deadlock-aware, previously
only used internally by acquire_with_retry's legacy pool path) instead of
letting a transient deadlock drop the maintenance pass entirely.
Adds a raw two-connection reproduction of the deadlock plus a test that
the sweep now survives one transient DeadlockDetectedError and still
returns correct prune counts.
Co-authored-by: Cursor <[email protected]>
* perf(graph-maintenance): add contention suite that catches the #2529 sweep deadlock
The existing graph-maintenance suite runs run_graph_maintenance_job in
isolation, so its Pass 2/3 cooccurrence sweep never overlaps a concurrent
writer and can never deadlock — which is why continuous perf never caught
#2529. The new graph-maintenance-contention suite drives prune_stale_cooccurrences
against retain-shaped sorted cooccurrence upserts and gates on the deadlock
escape rate (dropped/observed): ~100% unprotected (fails), ~0% with the
retry_with_backoff fix (passes).
* fix(graph-maintenance): jittered backoff + larger sweep retry budget so deadlocks stop dropping passes
Completes #2529. The retry wrap alone still let ~14% of sweep deadlocks
escape under sustained retain contention (perf suite, small scale): the
backoff was deterministic (concurrent retriers woke in lock-step and
re-collided) and capped at 3 attempts.
- db_utils.retry_with_backoff: add equal-jitter to the backoff delay so
contenders that deadlock together don't retry in sync (benefits every
retrier, incl. the legacy acquire path). Covered by a new pure-function
unit test.
- graph_maintenance: give the idempotent Pass 2/3 sweep a larger retry
budget (8) — it's background work with no client waiting, so a longer
jittered tail beats dropping a pass and leaking stale graph rows.
graph-maintenance-contention perf suite now measures 0% escape (0 dropped)
at small and medium vs ~100% unfixed; sweep_workers capped at 2 (prod
dedups to one maintenance job per bank, so 3+ concurrent sweeps was an
unfaithful amplifier).
* fix(graph-maintenance): prevent the #2529 sweep deadlock at the source via ordered locking
Prototype: instead of only retrying the deadlock, eliminate the lock-order
inversion that causes it. prune_stale_cooccurrences selects its victim rows in
the same sorted (entity_id_1, entity_id_2) order retain's cooccurrence upsert
locks them (a materialised FOR UPDATE CTE puts LockRows above the Sort), then
deletes the already-locked rows. Same lock order on both sides => no cycle.
- ops_postgresql: ordered-lock CTE prune. PG only — Oracle's DELETE can't carry
the CTE the same way, so it stays on the ORA-00060 retry path (documented).
- system_perf contention suite: hollow-run guard re-keyed on workloads running
(upserts+sweeps>0) not deadlocks>0, so a source-level fix (0 deadlocks) passes;
escape-rate denominator now max(observed,dropped).
Verified (small): 0 deadlocks either side, 0 dropped, 200 upserts + 336 sweeps
concurrent, 10s vs ~30s retry path; full-revert regression still FAILs 100% escape.
* refactor(graph-maintenance): replace tuple/dict returns with dataclasses (code-review)
- _run_sweep returned a bare tuple[int, int] (from #2529's base commit); the
project bans multi-item tuple returns even for private fns. Return a small
_SweepCounts dataclass instead.
- contention suite's shared counters were a raw dict with known keys; convert to
a _ContentionCounters dataclass, matching the file's existing style
(_GraphMaintTimers). No behaviour change; 18 graph-maintenance tests + perf
smoke (0 deadlocks, prevented-at-source) still green.
---------
Co-authored-by: Jordi Gil <[email protected]>
Co-authored-by: Cursor <[email protected]>
* blog: The Fully Open Agent Memory Stack (Hermes + Hindsight)
Grounded technical piece: every layer of a Hermes + Hindsight stack is
open source and self-hostable (open-weights model via vLLM/llama.cpp,
MIT Hermes Agent, MIT Hindsight with local embeddings/reranker/LLM and
no external calls). Includes wiring, honest caveats (64K context,
auto-hook version gate, model license differences), and when it matters.
* blog: recommend gpt-oss-20b, add leaderboard + real M3 Max run
Address review: pivot the model recommendation from the Hermes model to
gpt-oss-20b (trendy, Apache-2.0, 128K, native tools, ~13GB) and explain
why a 'small' Kimi does not actually fit a laptop. Add a 'which model
for Hindsight' section citing the published model leaderboard (gpt-oss-20b
tops retain), and a 'does it fit on a laptop' section with real numbers
from running the full stack on an M3 Max (retain ~8s, recall ~0.6s).
Update cover model panel to gpt-oss-20b.
Add per-integration guides under hindsight-docs/guides/, each with a
hero cover image following the existing guide template.
33 setup guides ("Add <Tool> Memory with Hindsight") for integrations
that had none: aider, ag2, agent-framework, agno, autogen,
claude-agent-sdk, cline, composio, continue, cursor, cursor-cli, dify,
eliza, flowise, gemini-spark, github-copilot, google-adk, grok-build,
haystack, litellm, n8n, nemoclaw, obsidian, omo, openai-agents,
openhands, roo-code, superagent, vapi, windsurf, zapier, zcode, zed.
11 distinct-angle guides for integrations that already had a setup
guide (each cross-links the existing setup guide instead of repeating
install): agentcore (cross-session strategy), codex (per-repo bank
strategy), crewai (shared crew memory), langgraph (state vs long-term),
llamaindex (beyond RAG), opencode (team shared banks), paperclip
(shared across agents), pipecat (voice memory across calls), pydantic-ai
(type-safe async memory), smolagents (memory across runs), strands
(per-agent vs shared banks).
Each guide is grounded in the integration's docs-integrations page and
its README/source.
Clears 20 high-severity Dependabot alerts for the MCP Python SDK across the
root lock and five integration locks (integration-tests, claude-agent-sdk,
crewai, openai-agents, strands):
GHSA-jpw9-pfvf-9f58 HTTP transports serve session requests without
verifying the authenticated principal (patched 1.27.2)
GHSA-hvrp-rf83-w775 experimental task handlers let any client access/
cancel other clients' tasks (patched 1.27.2)
GHSA-vj7q-gjh5-988w WebSocket server transport lacks Host/Origin
validation (patched 1.28.1)
1.28.1 clears all three. mcp is a direct dep in hindsight-integration-tests
and claude-agent-sdk (mcp>=1.0.0) and transitive elsewhere; the locks just
pinned older versions (1.23.3–1.27.1). crewai jumped the furthest (1.23.3),
which pulled newer pydantic/pydantic-core graph edges — its tests still pass.
Not included here: mcp is not part of any Dependabot group PR, so this is
the sole coverage for these alerts. nltk (llamaindex/pipecat) and torch are
handled by the Dependabot uv-group PR #2780.
Verified: claude-agent-sdk 76 passed, crewai 35 passed; lint clean.
Clears the pydantic-settings Dependabot alert across all affected
manifests plus the three high-severity alerts in the root lock.
pydantic-settings 2.12.0/2.14.0/2.14.1 -> 2.14.2 GHSA-4xgf-cpjx-pc3j
transformers 5.3.0 -> 5.12.1 GHSA-fgcw-684q-jj6r
soupsieve 2.8 -> 2.8.4 GHSA-2wc2-fm75-p42x
GHSA-836r-79rf-4m37
pydantic-settings is transitive everywhere (no direct declaration), so
the locks are the only lever. crewai is deliberately left at 2.10.1: the
advisory's range is >=2.12.0,<2.14.2 and NestedSecretsSettingsSource did
not exist in 2.10.x, so it is unaffected.
transformers is a direct dep, and hindsight-api is published, so the
declared floor -- not our lock -- is what protects installers of the
local-ml/local-onnx extras. The old >=4.53.0 floor resolved to 4.57.6
(vulnerable) under any downstream cap of transformers<5, so raise it to
the advisory's first patched version. Note this now fails resolution for
consumers pinned below transformers 5 rather than silently installing a
vulnerable build. The >=4.53.0 floor was already unreachable in practice:
4.53.0 requires tokenizers<0.22, which our own cap excludes.
The tokenizers<=0.23.0 cap is kept. #2055 was caused by transformers
declaring a wider tokenizers range in metadata than its import-time check
enforces, and the cap is what blocks that; the comment now records this
so it does not read as removable.
Root uv.lock is reformatted from lock revision 1 to 3 because uv rewrites
in its current format whenever it writes. The other 32 locks in the repo
are already revision 3 and CI's setup-uv is unpinned, so this aligns root
rather than drifting it. Only 3 versions actually change.
Verified: local-ml sync resolves tokenizers 0.22.2 under transformers
5.12.1; LocalSTEmbeddings and LocalSTCrossEncoder both initialize and run
(the #2055 import path). Lint passes.
test_null_content_recovers_on_retry failed intermittently on the test-api
shard with:
hindsight_api/metrics.py:591: TypeError: '>' not supported between
instances of 'MagicMock' and 'int' (if cached_input_tokens > 0)
The mock in _make_chat_response set completion_tokens_details but not the
cached-token fields, so the cached-token extraction
(openai_compatible_llm.py:948 `response_usage.cached_tokens`, and the
prompt_tokens_details path) read an auto-MagicMock and passed it to the
metrics recorder. It only surfaced when the metrics path actually ran —
which depends on telemetry state that leaks across pytest-xdist workers —
so it presented as an intermittent, co-scheduling-dependent failure rather
than a deterministic one.
Set usage.cached_tokens = 0 and usage.prompt_tokens_details = None so both
extraction paths yield int 0. Verified: both tests pass and both paths
return int 0 (no MagicMock reaches the `> 0` comparison).
Bind Reflect to the existing per-bank ContextVar so its tool loop and final synthesis preserve provider cost attribution. Replace two direct ContextVar implementation tests with one integrated Reflect binding/reset regression.
The OpenAI-compatible provider extracts cached_tokens and thoughts_tokens on
both call paths and hands them to TokenUsage, but never passes them to
metrics.record_llm_call, which accepts and buckets both. Two separate effects:
- Reasoning tokens reach no counter at all. #2378 made output_tokens
visible-only by subtracting thoughts_tokens directly above the
record_llm_call, so the reasoning half of the billed output was removed
from the metrics path rather than moved onto llm_tokens_thoughts. Before
#2378 those tokens were still counted inside output_tokens.
- cached_input_tokens has read 0 for every OpenAI-compatible provider since
the counter was added; only gemini_llm passes it.
Pass both kwargs at the two call sites that parse a usage object. The
fallback path (no usage) and the Ollama native path (no reasoning or cached
fields) are unchanged.
Invariant: recorded output_tokens + recorded thoughts_tokens equals the
provider's completion_tokens, so every billed token lands on exactly one
counter. The new tests assert on the collector itself; the existing ones
patch it without asserting, which is why this went unnoticed.
tool_expand zipped memory_ids against valid_uuids, which only collects the
ids that parsed as UUIDs. One invalid id shifts every later pair by one, so
a memory comes back stamped with a different memory's id, and zip truncates
the tail so the last requested id gets no entry at all.
Key each id to its own UUID and iterate memory_ids directly, so an invalid
id can only affect its own entry.
Two hs_llm_core quality tests failed frequently on the core-LLM job, not
because the judge flaked (it is already temp-0 primary + majority-vote
confirmations) but because they judged model output that is genuinely
variable and already checked deterministically elsewhere.
test_date_field_calculation_yesterday: the resolved date lives in the
structured `occurred_start` field, which the test already asserts is
Nov 12/13. The judge additionally required the absolute date to appear in
the free-text fact prose ("...state the absolute date in the fact text"),
so a correct extraction that wrote "Yesterday" in prose but Nov 12 in
occurred_start still failed. That tested phrasing, not capability. Make the
occurred_start assertion mandatory (require a dated fact — calculating the
date is the point of the test) and drop the date clause from the judged
criteria; the judge now only checks the fuzzy activity-content claim.
test_cognitive_epistemic_dimension: the judge penalised entity/speaker
attribution ("Involving: She/He") that is not what this test is about — it
asserts cognitive/epistemic *states* survive extraction. Scope the criteria
to that dimension and instruct the judge to ignore attribution and wording,
so a state counts as preserved even if attributed to the wrong person.
Both still catch real regressions (missing/incorrect dates, dropped
cognitive states); they just no longer flake on aspects the system either
captures structurally or does not claim to get right. Verified locally: both
pass (extraction gpt-4o-mini, judge gpt-4.1-mini).
* fix(test): seed native embedding/reranker stack to fix test-api shard failures
test-api's reranker-bearing shard (consistently 2/3) has failed on every
recent run — this repo's dependency PRs and Dependabot's alike — with a
misleading "sentence-transformers is required for LocalSTEmbeddings"
ImportError. sentence-transformers IS installed; the message masks the real
cause. The full worker traceback shows native extensions double-initializing:
torch._inductor.test_operators (module body runs twice):
RuntimeError: Only a single TORCH_LIBRARY can be used to register the
namespace _inductor_test
safetensors._safetensors_rust (PyO3):
ImportError: PyO3 modules ... may only be initialized once per
interpreter process
transformers' lazy loader imports these while resolving classes like
AutoModelForSequenceClassification / GenerationMixin (used by the
cross-encoder), and when they are first imported from inside a fixture's
event loop / sentence-transformers' thread pools — or re-executed by the
loader's retry path — the second init aborts. transformers wraps the error
and re-raises it as the sentence-transformers ImportError, so the symptom
points at the wrong dependency.
This is the same class of bug the adjacent `import torch` seed already guards
against (torch/overrides.py double-init). Extend that seed to the rest of the
native stack: torch._inductor.test_operators, transformers, and
sentence_transformers (which pulls safetensors + tokenizers). Importing them
once at conftest collection time — single-threaded, before any concurrency —
puts every submodule in sys.modules so later imports are cache hits and no
body re-executes. Verified locally.
Version-independent (reproduced at transformers 5.3.0 and 5.12.1, torch 2.10
and 2.12), which is why it blocked every uv.lock-changing PR regardless of
what they bumped.
* fix(test): auto-assign embedded postgres port in backfill migration test
test_backfill_populates_null_observation_search_vector pinned its embedded
postgres to a hardcoded port 5568. Under pytest-xdist that collides with a
concurrent or left-over instance:
FATAL: could not create any TCP/IP sockets
could not bind IPv4 address "127.0.0.1": Address already in use
which the pg0 retry loop reports as "Failed to start embedded PostgreSQL
after 5 attempts". This was the lone remaining error on test-api shard 2/3
after the native-import fix (66 of 67 errors were the masked double-init;
this was the 67th).
EmbeddedPostgres already supports port=None to auto-assign a free port, and
the fixture uses the URL from ensure_running(), so nothing needs the fixed
port. Switch to auto-assign.
The pair canonicalisation in _link_units_to_entities_batch_impl swapped
entity_id_1 and entity_id_2 in place, but entity_id_1 is the outer loop's
iterate:
for i, entity_id_1 in enumerate(entity_list):
for entity_id_2 in entity_list[i + 1:]:
if entity_id_1 > entity_id_2:
entity_id_1, entity_id_2 = entity_id_2, entity_id_1
Once a swap happens, entity_id_1 stays swapped for the rest of that inner
loop, so every later pair in the same outer iteration is built from the
wrong first element. Those pairs collide with ones already emitted, so the
effect is silently missing edges rather than wrong ones.
entity_list comes from a set, so the ordering (and the bug) varies per run.
Move the canonicalisation into a _canonical_cooccurrence_pairs() helper that
orders each pair into fresh locals, leaving the iterate untouched, and cover
it with order-pinned unit tests that need no database.
parse_markdown() blanked every line matching the horizontal-rule pattern
before any fence tracking ran, so a --- / *** / ___ line inside a fenced
code block was replaced by an empty line and the content was lost.
_strip_separators() was fence-unaware and ran first; _split_blocks() is
the pass that tracks fences. Fold the rule-skip into _split_blocks, which
already carries the in_fence state, so there is one fence state machine
instead of two. A rule between sections still counts as blank and still
never becomes a paragraph.
Fixes#2752
* blog: One Bank or Many? structuring agent memory
A field guide to bank strategy in Hindsight: a bank is a recall
boundary, when to use separate banks vs tags within one bank, the
dynamicBankId/granularity config, anti-patterns, and a decision
checklist. All claims grounded in the source.
* chore(deps): bump pydantic-ai-slim to 1.107.1 (security)
pydantic-ai-slim 1.99.0 -> 1.107.1 GHSA-cg7w-rg45-pc59
Closes the SSRF-blocklist-bypass alert (IPv4-compatible / SIIT/IVI /
NAT64 IPv6 addresses; incomplete fix of CVE-2026-46678; patched 1.102.0).
Transitive via the hindsight-pydantic-ai integration. Held to the 1.x
line rather than the 2.x that an unconstrained upgrade resolves to
(2.11.0) -- pydantic-ai 2.x is a major with its own migration surface,
out of scope for a medium security bump. 1.107.1 clears the advisory
within the same major.
Verified: uv run pytest tests -> 37 passed.
* chore(deps): pin websocket-driver/http-proxy-middleware/js-yaml/uuid via overrides (security)
Closes one critical and three medium Dependabot alerts on transitive npm
deps in the root lock, using the repo's existing `overrides` mechanism.
websocket-driver 0.7.4 -> 0.7.5 GHSA-xv26-6w52-cph6 (CRITICAL:
message corruption via protocol
length headers) + GHSA-mp7j-qc5w-4988
http-proxy-middleware 2.0.9 -> 2.0.10 GHSA-64mm-vxmg-q3vj (Host-header
routing bypass); capped <3 to stay
on the 2.x major webpack-dev-server
expects
js-yaml (3.x) 3.14.2 -> 3.15.0 GHSA-h67p-54hq-rp68 (merge-key DoS);
scoped to @istanbuljs/load-nyc-config
and gray-matter so the 4.x copies are
untouched
uuid (sockjs) 8.3.2 -> 11.1.1 GHSA-w5hq-g745-h8pq (buf bounds);
scoped to sockjs so the top-level
uuid 14.x is untouched
All four are dev/build tooling (webpack-dev-server, sockjs, istanbuljs
coverage, gray-matter frontmatter). Applied by adding overrides then
`npm update <pkg>` per target -- `npm install` alone registers an override
but will not upgrade an already-locked transitive to satisfy it. Verified
`npm ci` installs the lock cleanly and resolves the patched versions.
Two root-lock npm alerts are intentionally left for separate PRs:
- postcss <8.5.10 (GHSA-qx2v-qp2m-jg93): only reachable via [email protected],
which pins postcss==8.4.31 exactly. npm registers an override but will
not rewrite next's nested copy, and forcing it risks next's build. The
real fix is a next bump. Low real risk -- the app compiles first-party
(Tailwind) CSS, not attacker-controlled input.
- @hey-api/openapi-ts <0.97.3 (GHSA-hhx9-57xq-r5rw): the SDK generator;
the patched line is a breaking change that needs client regeneration.
* chore(deps): bump langgraph-checkpoint and langgraph-sdk (security)
langgraph-checkpoint 4.1.0 -> 4.1.1 GHSA-fjqc-hq36-qh5p
langgraph-sdk 0.3.14 -> 0.3.15 GHSA-w39p-vh2g-g8g5
Both transitive medium alerts in the hindsight-langgraph lock. (The
langsmith bump that originally shared this file landed separately in
#2743; only checkpoint/sdk remain.)
Verified: uv run pytest tests -> 60 passed, 6 skipped.
A conversation-scoped bank is not wiped when the conversation ends.
The bank persists; a new conversation simply resolves to a new bank,
so memory does not carry across conversations. Corrects an inaccurate
'wiped' claim in the bank-scoping section.
Bumps pipecat-ai from 0.0.x to >=1.4.0,<2.0, clearing four high-severity
Dependabot advisories for the file-read CVEs in the older 0.0.x/1.0.x line
(telephony /ws + runner /files path traversal; alerts #1006, #1005, #560, #559).
pipecat 1.x replaced the per-provider OpenAILLMContext with the universal
LLMContext and removed the pipecat.processors.aggregators.openai_llm_context
module. The integration already imported the modern LLMContextFrame, so the
runtime change is small:
- memory.py: drop the now-impossible legacy OpenAILLMContextFrame import branch
and match on LLMContextFrame directly. LLMContext.messages is still a live
list of OpenAI-format dicts, so the in-place injection logic is unchanged.
- tests: build frames from LLMContextFrame; add TestRealLLMContext that exercises
a real pipecat LLMContext + LLMContextFrame to pin the live-list mutation
contract the integration depends on.
- examples: migrate to LLMContext + LLMContextAggregatorPair and the LLMRunFrame
kickoff (create_context_aggregator / get_context_frame were removed in 1.x).
- pyproject: pipecat 1.x requires Python >=3.11, so bump requires-python and
drop the 3.10 classifier (CI already runs 3.11).
Tests: 19 passed, 1 skipped (live).
langsmith 0.8.3 -> 0.10.5 GHSA-f4xh-w4cj-qxq8 (arbitrary server-side
file read in TracingMiddleware; patched 0.8.18)
ws 8.18.0 -> 8.21.0 GHSA-96hv-2xvq-fx4p (memory-exhaustion DoS)
Both are transitive. langsmith pulls in distro/sniffio/websockets as new
langsmith 0.10.x deps. hindsight-api-slim already carries a langsmith
>=0.8.18 floor; this covers the langgraph lock, which did not.
ws could not be bumped directly: miniflare pins it exactly (ws==8.18.0),
so the fix is via wrangler. wrangler >=4.108.0 requires peer
@cloudflare/workers-types ^5, a types major we don't want in a security
fix, so pin 4.107.1 -- the newest wrangler still on workers-types v4
(peer ^4.20260702.1) and the earliest line carrying patched ws 8.21.0.
That moves workers-types 4.20260617.1 -> 4.20260702.1 within v4. wrangler
is a devDependency, so this ws is dev-only (miniflare's local dev server);
the deployed Worker's only runtime dep is @cloudflare/workers-oauth-provider.
The langgraph lock also picks up hindsight-langgraph 0.2.0 -> 0.3.0.
That is pre-existing drift, not part of this change: release(langgraph)
v0.3.0 (2c5362942) bumped pyproject without re-locking. uv corrects it here.
json-repair (GHSA-xf7x-x43h-rpqh) is deliberately not addressed: it is
blocked upstream. Every crewai release, including the latest 1.15.2, pins
json-repair~=0.25.2 (>=0.25.2,<0.26.0), and the advisory is not patched
until 0.60.1. No crewai version permits a fixed json-repair.
Verified: cloudflare-oauth-proxy `npm ci` + `npm run typecheck` (CI's gate)
pass, npm audit reports 0 vulnerabilities, vitest 50 passed; langgraph
pytest 60 passed, 6 skipped. Lint passes with LINT_ALL_INTEGRATIONS=1.
* docs: add Omnigent integration page
Adds the Omnigent integration to the docs site:
- docs-integrations/omnigent.md — full integration guide (install, YAML
config, how runner-local dispatch works, bank scoping, config reference,
self-hosted, Remy example, harness table, further reading)
- src/data/integrations.json — registry entry (category: framework, official)
- static/img/icons/omnigent.png — placeholder icon (to be updated)
Tool names use the correct Omnigent source names: memory_recall/retain/reflect.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* docs: fix broken links, real Omnigent logo, regen skill
- Remove changelog link (Omnigent has no released Hindsight package/changelog)
- Drop the not-yet-merged blog self-link; add Omnigent GitHub link instead
- Replace placeholder icon with the real Omnigent logo (from omnigent-ai/omnigent)
- Regenerate skills/hindsight-docs integration reference for omnigent
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* docs(omnigent): correct tool names to hindsight_* + fix harness table
- Revert memory_* -> hindsight_recall/retain/reflect: released omnigent v0.5.1
(and main, and the Remy example) use hindsight_* names. The memory_* rename
is on an unmerged branch (integration/hindsight-memory-tool), not released.
- Fix the harness table: Codex and OpenCode have official Hindsight integrations,
Pi has a community one (epimetheus); reframe around 'one central setup' rather
than implying those tools have no native support.
- Regenerate skills/hindsight-docs reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: Omnigent as the universal Hindsight memory bridge
Tutorial-style post on adding persistent memory to Omnigent. Key angle:
Omnigent intercepts hindsight_recall/retain/reflect at the runner level, so
every wrapped harness (Claude Code, Codex, Cursor, Hermes, Pi) gets memory
through one setup, even those with no native Hindsight support. Covers
install, YAML spec, bank scoping, the Remy example, and cloud/self-hosted.
Grounded in omnigent-ai/omnigent source. Bridge-diagram cover.
Fixes#2505: the OpenClaw append-capability probe only checked API version, ignoring features.store_document_text, so every session-scoped retain 400'd (silent memory loss) on text-disabled deployments. Now gates update_mode=append on BOTH version >= 0.5.0 AND features.store_document_text=true, falling back to per-turn document IDs otherwise. Verified locally: 281/281 openclaw tests pass on the PR head.
Fixes the consolidation blocker from non-string metadata values (e.g. integer `original_id` from observation bookmarks) by coercing all metadata values to str in `MemoryFact.parse_metadata`. Verified locally: 4/4 regression tests pass (integer coercion, JSONB-string-with-int, string passthrough, None).
Add opt-in HINDSIGHT_API_FAIL_ON_EXTRACTION_ERRORS (default False, preserves behavior). When enabled and a retain accumulated extraction errors (extraction_errors_count > 0), the operation is marked failed instead of silently completed. Self-contained: config flag + _mark_operation_completed decision + docs + .env.example. Deferred follow-ups (status API field, completed_with_errors status, webhook field, metric) noted in the PR.
Own change verified (config + status tests pass, verify-generated-files green, ruff/tsc clean). Remaining CI reds are unrelated: Core LLM + pg0 test-api flakes, a transient ts-client-oracle, and test-embed-windows (the #2676 regression already fixed on main by #2723; #2721 does not touch the embed daemon).
Fixes#2700
Resolve the #2676-vs-#1240 conflict that broke test-embed-windows on main: scope #2676's 'missing sentence-transformers -> uvx' fallback to the sysconfig-scripts path only. A --target-bundled sibling binary is deliberate and is used unconditionally (preserving #1240). Adds a regression test; fixes a test fixture that conflated the two binary-resolution paths.
Greens main.
The Gemini batch request builder only set the native response_schema
(responseJsonSchema) when json_schema.strict was truthy, but
HINDSIGHT_API_LLM_STRICT_SCHEMA defaults to False. The interactive Gemini
path always grammar-enforces via response_schema regardless of strict
(strict is an OpenAI concept, meaningless to Gemini). At default config
batch requests therefore got only responseMimeType + a textual schema hint
and intermittently emitted malformed JSON, dropping every fact in the chunk.
Set responseJsonSchema whenever a schema is present so batch mirrors
interactive. Update the batch translation unit test accordingly.
Fixes#2699
#2708 changed OracleBackend._set_session_schema to always reset CURRENT_SCHEMA
to the connection's default (SESSION_USER) schema — including for the public
schema — because Oracle pooled sessions retain CURRENT_SCHEMA across checkouts.
That intentional change left two #2613 unit tests asserting the old
'public = noop, no cursor' contract, and their mock cursor lacked the fetchone()
now used to look up SESSION_USER, so both failed on main.
Update the tests to the new contract: public now resets to the default schema
via ALTER SESSION, and the mock cursor provides fetchone(). The synchronous
cursor.close()-not-awaited assertion is preserved.
The bank selector rendered bank_id for both the dropdown items and the
selected-bank trigger, ignoring the bank's friendly name even though it's
already available on BankInfo (name). Admins who rename banks via
PATCH /v1/default/banks/{bank_id} saw only the immutable bank_id in the UI.
Display name || bank_id in the dropdown items and look up the selected
bank's name for the trigger, falling back to bank_id (then the 'select'
placeholder) so there's no regression before the bank list loads or when a
bank has no name. bank_id remains the key/value/clipboard identifier.
Fixes#2686
ClaudeCodeLLM's streaming loops ignored ResultMessage entirely. When the CLI reports quota exhaustion with is_error=true and subtype="success", the SDK's fallback produced the misleading 'error result: success'. Add _result_error_detail() that prefers message.result over subtype, wired into both loops. 4/4 regression tests pass.
Fixes#2702
Multiple CodexLLM instances (default/retain/reflect/consolidation configs) each created their own CodexAuthManager with an instance-local lock, so refresh was only single-flight within one manager. Concurrent refreshes from sibling managers hit refresh_token_reused. Add a path-scoped in-process lock and fcntl advisory file lock so all managers for the same CODEX_HOME coordinate as one refresh domain; pre-read auth.json under the lock to adopt credentials rotated by a sibling before making a network call.
27 Codex OAuth tests pass. CI green.
Fixes#2704
Add configurable TTL (default 30 days, 0=keep-forever) for terminal async_operations rows. Expired completed/failed/cancelled rows are pruned in bounded batches (1000/cycle) by a background task that never touches pending/processing work. Batch children are protected until their parent is pruned; cancelled-child cleanup atomically cancels a pending parent first. PG uses FOR UPDATE SKIP LOCKED; both PG and Oracle re-check eligibility under the row lock before deleting. Includes indexes, docs, and regenerated SDKs.
184 retention/worker/operation-status tests pass locally. All CI green.
Fixes#2705
* feat(devin-desktop): two-tier bank scoping + visible memory use (v0.2.0)
Reworks the Devin Desktop integration from a single hardcoded `devin-desktop`
bank (all projects share one memory pool) to per-project isolation plus a
shared cross-project bank, and makes Hindsight usage visible in chat.
Scoping (multi-bank mode):
- Connect to the multi-bank `/mcp/` endpoint (was `/mcp/<bank>/`); the model
routes `bank_id` per call, guided by the committed rule.
- Global bank `devin-desktop` (user prefs/style) named in global_rules.md;
per-project bank `devin-desktop-<slug>` derived from the git remote (stable
across machines/teammates) named in the committed .devin/rules/hindsight.md.
- `X-Bank-Id: <global>` header as the fallback bank when the model omits it.
- Verified against live Cloud: bank_id routing + full isolation (no cross-bank
leak) + read-after-write via sync_retain.
Visibility (no sound, per product decision):
- Rule now tells the agent to briefly acknowledge memory use in chat
(reverses the prior "do not mention" line) and to use `reflect`/`sync_retain`.
Audit fixes:
- Write both documented MCP config locations (`~/.codeium/windsurf/` and
`~/.codeium/`) since Devin's own docs disagree on the path.
- Explicit "press Refresh in the MCP panel" step (config doesn't hot-reload).
New modules: project.py (git-derivation), global_rules.py (global_rules.md
managed block). Backward-compatible: legacy `bankId` config maps to the global
bank. 55 tests pass; ruff clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* feat(devin-desktop): also wire the Devin Local agent (not just Cascade)
Devin Desktop ships two agents with separate config, and the prior version only
wired Cascade — so a user on Devin Local (the successor agent) got no memory.
`init` now configures both:
Cascade (unchanged): ~/.codeium/windsurf/mcp_config.json (serverUrl),
.devin/rules/hindsight.md, ~/.codeium/windsurf/memories/global_rules.md.
Devin Local (new):
- ~/.config/devin/config.json — mcpServers.hindsight with `url` + `transport:"http"`
+ `headers` (Devin Local's schema, not Cascade's `serverUrl`); preserves other
keys (e.g. version).
- permissions.allow += "mcp__hindsight__*" — Devin Local prompts before every MCP
tool by default; this makes recall/retain run automatically.
- AGENTS.md always-on rules (Devin Local doesn't read .devin/rules/): repo-root
AGENTS.md (per-project) + ~/.config/devin/AGENTS.md (global), each a fenced
managed block that preserves user content.
New modules: devin_local.py, managed_block.py (shared block writer, also used by
global_rules.py). Same multi-bank + routing-rule design across both agents.
status/uninstall cover both. README + docstrings updated. 74 tests pass; ruff
clean (ruff 0.14.9 + root config).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* docs(devin-desktop): tell users to click Connect (Devin Local) after init
Devin Local registers the MCP server from config.json but requires an explicit
Connect click in the Devin MCP Marketplace (verified in-app). init output and
README now spell out the per-agent activation step: Cascade = Refresh, Devin
Local = Connect.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* feat(devin-desktop): deterministic auto-recall hook + Windows paths
Two things for 0.2.0:
1. Windows paths: Devin Local config/AGENTS.md now resolve to %APPDATA%\devin on
Windows (was ~/.config/devin unconditionally, which is wrong there). Cascade's
~/.codeium/windsurf is already cross-platform.
2. Deterministic auto-recall (Devin Local only): init adds a SessionStart hook to
config.json that recalls project + global memory and returns it as
`additionalContext`, which Devin injects into the agent's context before the
model acts — so memory loads even if the model forgets to call recall. The
hook (hindsight_devin_desktop.hook) reads the connection from config.json and
derives the project bank from DEVIN_PROJECT_DIR; it's dependency-free (stdlib
urllib MCP call), times out fast, and fails silently so it never breaks a
session. Opt out with `init --no-hooks`. Cascade gets no hook (its hooks can't
inject context). Auto-retain is intentionally not added (SessionEnd can't see
the transcript); retain stays model-driven via the MCP tool.
Verified live against Cloud: the hook recalls a stored fact and emits correct
additionalContext JSON. 89 tests pass; ruff clean. README documents both.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* feat(devin-desktop): retain-nudge hook, no-silent recall, Cascade visibility banner
Round out the hooks/visibility work for 0.2.0:
- Retain-nudge (Devin Local, default on): a `Stop` hook forces one retain pass
before the agent stops (loop-guarded via stop_hook_active) — deterministic
*trigger*; the model decides what's durable and calls retain. Devin's hooks
can't hand a script the transcript, so this is the closest to deterministic
retain. Opt out with --no-retain-hook; --no-hooks disables both hooks.
- No silent failures (recall hook): the SessionStart hook now ALWAYS reports
status via additionalContext — loaded N / empty / unavailable(reason) — and
tells the model to surface it. Never exits non-zero (never breaks a session).
- Cascade visibility banner: init adds a `post_mcp_tool_use` hook to
~/.codeium/windsurf/hooks.json with show_output:true that prints
"🧠 Hindsight: <tool> used" (filtered in-script to the hindsight server, since
Cascade hooks have no matcher). Makes Cascade's recall/retain visibly obvious.
New module cascade_hooks.py; hook.py gains retain-nudge + banner subcommands.
README documents both hooks, the honest retain limitation, and the banner.
102 tests pass; ruff clean. Recall + retain-nudge output verified.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* fix(devin-desktop): stop the retain-nudge polluting memory with meta-facts
Real in-app testing showed the Stop retain-nudge caused the model to (a) retain
facts ABOUT the memory system/instructions as 'user preferences', and (b)
re-retain things already saved this session. Tighten both the nudge and the
always-on rule: retain ONLY real facts about the code/project/user's actual
preferences, NEVER facts about Hindsight/memory/hooks/these instructions, and
don't re-retain what's already stored.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* fix(devin-desktop): rule tweak to stop redundant retains
In-app testing showed the model firing sync_retain per-fact (and re-saving),
producing duplicate memories. Reframe the rule: retain (async) is the default;
retain each distinct fact EXACTLY ONCE in a single call (batch same-subject
facts); sync_retain only for same-task read-after-write.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* feat(devin-desktop): hook proof-of-life log (~/.hindsight/devin-hook.log)
Devin Local hooks are silent (no output panel), so it's hard to tell whether a
hook actually fired vs the model just following the always-on rule. Each hook
invocation now appends one line (recall loaded/empty/error, retain-nudge
blocked/skipped, banner shown/skipped) with the resolved banks — proof-of-life
so users (and we) can confirm the hooks run.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* feat(devin-desktop): --no-global-bank opt-out (local-only memory)
Add a local-only mode so users can opt out of the shared cross-project bank:
everything (project facts + the user's preferences) goes to the single project
bank, the global rule files are removed instead of written, and the recall +
retain-nudge hooks run with --local-only (recall only the project bank, nudge
routes everything there). The rule becomes a single-bank variant. Cascade
banner + MCP config unchanged. For people who don't want a shared profile
(e.g. work vs personal machines).
108 tests pass; ruff clean. Verified end-to-end: no global files written, hooks
carry --local-only.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* fix(devin-desktop): don't let the test suite write the hook log to $HOME
The proof-of-life hook log wrote ~/.hindsight/devin-hook.log unconditionally, so
running the tests (which call the hook functions) polluted the real user log.
Make the path env-overridable (HINDSIGHT_HOOK_LOG, 'off' disables) and add a
conftest that sets it off during tests.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* feat(devin-desktop): recall hook reports the session-start preload
The SessionStart hook's additionalContext now tells the model to OPEN its reply
by announcing that memory was preloaded (e.g. '🧠 Hindsight preloaded N memories
for this session'), and that it doesn't need to re-call recall for the baseline
— making the deterministic preload visible to the user and cutting redundant
recall calls. Empty/error variants also lead with a user-facing status line.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* docs(devin-desktop): add 'verify it's working', which-agent, and Windows notes
Help new users get started with both agents: a 'Verify it's working' section
(the preload status line / hook log / Cascade banner / status command), a note
on the agent selector, and the Windows config path.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: inside retain() — what happens when your agent remembers
A feature explainer walking the retain() write path end to end through one
sentence: fact extraction (meaning, not words), entity recognition + resolution,
the knowledge graph (entity/time/meaning/causal), dual temporal grounding, and
async consolidation into evidence-grounded observations. Grounded in the retain
and observations developer docs. Pipeline-diagram cover.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: address review — drop async-only timing claims, note original text is stored
- Remove 'returns almost immediately' / inline-extraction language that only
holds for one retain mode; frame consolidation as the always-background step
- Add that retain also stores the original text (chunked if long), available
alongside the extracted memory
- Cover line updated to 'the raw text is kept, and memory is built on top'
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: fact-check fixes from full code+docs audit
- Remove 'nickname resolution' (Bob/Robert Chen): code has no nickname/alias
logic; resolution is fuzzy name match + co-occurrence + temporal proximity
- Temporal: second axis is the mention time, not the DB insert moment; recency
ranks off event/mention time, not ingestion
- Soften 'source is never lost' -> 'stays available' (original-text storage is
default-on but operator-configurable)
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: editorial cover (cream + serif, teal retain())
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Install public.banks_needing_consolidation() / public.schemas_with_expired_rows() on every PG run (advisory-lock-guarded) so single-tenant deployments migrated into a non-public schema get the routines the maintenance loop needs. Prior migrations gated on target_schema being falsy/public, leaving non-public deploys logging 'function public.… does not exist' forever.
All real CI tests pass (test-api 1/3+3/3, and 1237/1237 in shard 2/3; test-upgrade, both Oracle suites, verify-generated-files green). Sole failing check is a persistent pg0 'Address already in use' runner-infra error in an unrelated backfill test — not a test failure and not from this diff; recurred on all 3 reruns.
Fixes#2638
The dedup prompt literally told the model to 'respond action="merge"', so weaker models emitted key=value instead of JSON and json.loads crashed every dedup-eligible consolidation into an infinite retry loop. Rewrite the prompt to demand a JSON object (braces escaped for .format()), and add a defensive parser that accepts str/dict/model and defaults to action=keep on invalid output. Fork CI skips pytest (no secrets); test_consolidation_dedup.py verified locally (32/32), ruff+ty clean.
Fixes#2658
Link expansion ranks candidates by an additive entity, semantic,
and causal score, but returned the raw score from one signal as
activation. Cross-fact-type graph merging then re-ranked candidates
using that raw value.
Store the final additive score as activation and add a regression test
for cross-fact-type ordering.
* fix(search): guard Chinese rolling year underflow
* fix(search): complete Chinese year underflow guard
---------
Co-authored-by: r266-tech <[email protected]>
The /api/documents proxy route dropped the q search param, so document search-by-ID in the control plane did nothing (all browsers, not just Safari). Forward q to the dataplane's substring-on-ID filter. Adds a vitest route test.
Fixes#2678
Clarify that retain creates caused_by only. Storage and recall keep reading
historical causal link types, and transfer import alone restores them.
Correct stale code comments and tests, and preserve legacy edge types and
endpoints during transfer without widening the retain write contract.
Apply each entity fanout cap only after filtering candidates by fact type.
This prevents high-volume fact types from excluding valid target candidates.
Cover the PostgreSQL and Oracle CTE builders with a regression test.
Extends generate-docs-skill.sh to walk hindsight-docs/src/pages/cookbook/ and docs-integrations/, so the docs skill bundle ships the cookbook recipes/applications and per-integration docs its SKILL.md already advertised. Fixes the ghost-path index described in #2641. Regeneration is drift-free (verify-generated-files passes) and link validation passes; bundle grows from ~85 to 168 files.
Fixes#2641
A first-person, day-in-the-life post on running three AI tools (code, chat,
voice) against a single Hindsight bank: a decision made in Cursor is recalled
by the OpenClaw Slack agent and the Vapi voice agent, because all three point
at the same bank id. Grounded in each integration's actual bank config.
Hub-and-spoke cover.
* fix(trace): skip LLM trace writes during daemon shutdown/pre-init races
LLMTraceRecorder._safe_write and _attach_memory_ids produce spurious
WARNING logs during two race windows:
1. Pre-init: MemoryEngine.initialize() runs verify_llm() inside the
parallel init gather before the DB backend pool is ready. The
pool_getter returns a backend object that raises RuntimeError on
acquire.
2. Shutdown: MemoryEngine.close() calls backend.shutdown() (sets
_pool=None) before setting self._backend=None. Fire-and-forget trace
tasks see a non-None backend whose internal pool is already closed,
hitting either RuntimeError('not initialized') or
InterfaceError('pool is closing').
Both are expected lifecycle states, not actionable errors. Fix:
- Add a getattr(pool, '_pool') None guard before the acquire attempt
- Downgrade 'not initialized' and 'pool is closing' exceptions to DEBUG
in both _safe_write and _attach_memory_ids
- All other write failures still warn
Supersedes #2562 (closed without merge), which only covered the
pre-init RuntimeError path. This PR additionally covers the shutdown
'pool is closing' race and the _attach_memory_ids write path.
5 regression tests covering: pool=None, backend._pool=None,
pool-is-closing, unexpected error (still warns), and
_attach_memory_ids with _pool=None.
* style: ruff format test_llm_trace.py
---------
Co-authored-by: Ben <[email protected]>
* fix: handle FK violation in observation_history during parallel consolidation
Wrap the INSERT into observation_history with a try/except for
ForeignKeyViolationError. Under parallel/batched consolidation, one
batch may delete an observation while another writes its history,
causing a race condition. Instead of failing the entire consolidation
task, log a warning and skip the history entry.
Also adds the missing needed to catch the specific
exception type.
Closes#2597Closes#2506
* test: regression for observation_history FK race (#2597, #2506)
---------
Co-authored-by: Ben <[email protected]>
The engine's batch path (retain fact extraction, gated on
retain_batch_enabled) has been available to the OpenAI-compatible and Gemini
providers but not Anthropic — AnthropicLLM implemented none of the
LLMInterface batch methods, so supports_batch_api() returned False and the
gate hard-failed.
Implement all four methods against Anthropic's Message Batches API, which
bills every token at 50% of standard price:
- submit_batch translates the engine's OpenAI-JSONL-shaped entries into
Messages batch requests, mirroring call()'s conversion rules: system
messages fold into the system param, max_completion_tokens -> max_tokens,
temperature is dropped (the sync path never sends it either), and
response_format json_schema becomes a forced tool_use tool when strict
(native constrained decoding, issue #1002) or a system-prompt schema
injection otherwise. Operator extra_body params merge directly (batch
params are the raw Messages body).
- get_batch_status maps processing_status onto the OpenAI vocabulary the
engine's poll loop speaks: "ended" -> "completed" (per-request failures
surface in results, matching OpenAI's completed-with-errors semantics),
non-terminal states pass through; request_counts are aggregated to
total/completed/failed.
- retrieve_batch_results renders succeeded messages as
choices[0].message.content (forced-tool JSON re-serialized as the content
string) with OpenAI-keyed usage, and errored/canceled/expired entries as
per-result errors.
8 new tests covering translation in both directions, status mapping, and the
not-ended guard; existing batch-path and Anthropic provider suites pass
unchanged.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 <[email protected]>
The Anthropic provider sent no cache_control at all, so every call paid full
input price on content the engine resends verbatim: fact extraction reuses
the same system prompt across every chunk, and the reflect agent loop resends
the entire growing conversation on each of its (up to
HINDSIGHT_API_REFLECT_MAX_ITERATIONS) iterations. Anthropic cache reads bill
at ~10% of base input price.
Implement the "inline-marker provider" strategy that
LLMInterface.get_or_create_cached_prefix already documents for Anthropic —
no engine changes, no new config:
- call() and call_with_tools() render the system prompt as a block list with
a cache_control breakpoint (a prefix match, so tools + system cache
together); schema text-injection happens before marking and lands inside
the cached block.
- call_with_tools() additionally marks the final message content block, so
each agent-loop request's end-marker becomes the next iteration's cache
read point. 2 of the 4 allowed breakpoints used.
Marking is safe unconditionally: below the model's minimum cacheable prefix
the marker is silently ignored (no write premium), and cache_read_input_
tokens already flows through _usage_from_anthropic_response into metrics.
One existing assertion updated for the representation change
(test_non_strict_keeps_text_injection_fallback checked a substring on system
as a string; the schema-in-prompt behavior itself is unchanged and still
covered). 5 new tests pin the marker placement on both entry points.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.7 <[email protected]>
* Blog: give Aider a persistent, cross-session memory
Add a post on hindsight-aider, the drop-in wrapper that recalls project
memory before an Aider session (via a --read context file) and retains the
transcript after, scoped per git repo. Grounded in the v0.1.1 integration
source. Git-diff cover.
* Blog: use Aider-branded cover (real logo, brand green, VT220 font)
The additional-banks recall loop recalled every entry with no dedup against
the resolved primary, so bidirectional cross-bank setups (primary listed in
recallAdditionalBanks) re-recalled the primary on every prompt — a wasted
recall call plus duplicate context. Guard the loop with a seen-set seeded with
the primary bank; also dedups repeated entries. Fixes#2604.
Keep recall min_scores.semantic scoped to the semantic retrieval arm.
Temporal retrieval uses embeddings only to choose time-window entry
points. Reusing the request-level semantic floor there made temporal
recall unexpectedly narrower.
Callers that only wanted to prune weak semantic matches could also
narrow temporal recall. That made the min_scores contract surprising
and inconsistent with graph seed selection.
Use the temporal entry-point default instead. Semantic and BM25 request
floors remain unchanged.
Verifying the Oracle guide end-to-end surfaced three setup steps that weren't
documented and that block a first-time deployment:
- HINDSIGHT_API_DATABASE_SCHEMA must be set to the Oracle schema user. The
default `public` is a PostgreSQL notion and makes migrations fail with
ORA-01435. Added it to the configure step (with a warning), the quick start,
the config reference table, and troubleshooting.
- Migrations must run with the same embedding dimension as the serving model,
or retain fails with ORA-51803. Added a warning to the migrate step and a
troubleshooting row (including the --embedding-dimension resize path).
- The dev quick-start container can report a provisioning error on a cold
start's first run; noted that re-running the idempotent script succeeds.
Mirrored into versioned_docs/version-0.8 and regenerated the docs skill.
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
oracledb's AsyncCursor.close() is not a coroutine, so awaiting it raised
"object NoneType can't be used in 'await' expression" on every acquire()
under a non-public schema. This broke the database health check and all
retain/recall/reflect operations on Oracle whenever a non-public schema was
active — which is the norm on Oracle, since a schema is a user and the
default `public` schema does not exist there.
Drop the erroneous await. Add unit regression tests (no live Oracle needed —
a fake cursor whose close() is synchronous, exactly like oracledb) covering
both the non-public path (previously raised TypeError) and the public no-op
path. These run in the standard test suite, unlike the label-gated Oracle
integration job.
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* docs: add Oracle Database setup guide
Hindsight supports Oracle Database 23ai as a storage backend, but the docs
only mentioned it in passing — a one-paragraph note on the Storage page and a
couple of Configuration reference rows, with no `oracle+oracledb://` example
anywhere. This adds a dedicated Oracle Database page under Hosting.
The guide covers requirements (Oracle 23ai, the ASSM-tablespace requirement
for VECTOR columns, Oracle Text / CTXAPP), installing the python-oracledb
driver, a local quick start via scripts/dev/start-oracle.sh, production
provisioning SQL + connection URL + env vars + migrations, a config reference,
the differences from PostgreSQL, and troubleshooting. Content is grounded in
the CI Oracle job, the dev script, and the backend code.
Registered in the sidebar and cross-linked from Storage and Configuration.
Regenerated the docs agent-skill and mirrored the change into
versioned_docs/version-0.8 so it ships on the currently-served version.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo
* docs(oracle): correct managed-service note, add connection caveat
The connection layer builds the Oracle DSN from the URL as a plain
host:port/service_name descriptor — wallet-based mTLS, TLS/TCPS, and TNS
aliases / full connect descriptors are not wired up. The previous "Least
privilege" note implied Oracle Autonomous Database works via an
ADMIN-provisioned user, which is misleading since ADB defaults to wallet/mTLS.
- Reworded the managed-service note to drop the specific ADB claim while
keeping the accurate requirement (ASSM tablespace + CTXAPP).
- Added an "Easy Connect only" warning documenting that wallet/mTLS/TLS and
TNS descriptors are unsupported, and that transport encryption must be
handled at the network layer.
Applied to the current and version-0.8 copies; regenerated the docs skill.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: persistent memory for the Zed editor (hindsight-zed v0.1.0)
New post on the Zed integration: wires Zed's Agent Panel to the Hindsight MCP
server (recall/retain/reflect) plus a global AGENTS.md rule, so the assistant
remembers decisions and conventions across sessions. Grounded in the v0.1.0
source; em-dash-free. Adds a series-style cover.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: update Zed install to the Node CLI (npx), per #2599
hindsight-zed is now a zero-dependency Node CLI: `npx hindsight-zed init`
(or `npm install -g`). Node.js only, no Python. Mechanism unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Blog: swap Zed cover to the typographic "Memory for Zed" poster
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
* refactor(zed): port setup CLI to Node, drop the Python dependency
The Zed integration is configuration-only — it writes the `context_servers`
entry into Zed's settings.json and a recall/retain rule into AGENTS.md — and the
MCP server it configures runs via `npx mcp-remote`, so Node.js was already a hard
requirement. Requiring Python *as well* just to write two config files meant
users needed two runtimes.
Port the `hindsight-zed` CLI to a zero-dependency Node CLI so the integration
needs only Node:
- Node CLI under `src/` + `bin/hindsight-zed.js`, shipped via `package.json`
(matches the existing TypeScript integrations; release-integration.yml already
detects package.json for npm publishing).
- Behavior-preserving: same commands (`init`/`status`/`uninstall`), flags,
`--print-only`, env/file/flag config resolution, JSONC-safe settings edits,
and fenced AGENTS.md rule block.
- Tests ported to Node's built-in runner (`node --test`) — 21 tests.
- CI (`test.yml`) updated to run `npm test` on Node 22 instead of pytest.
- Removes the Python package (`hindsight_zed/`, `pyproject.toml`, `uv.lock`,
Python `tests/`).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* fix(zed): make the Node package publishable by the release workflow
The release workflow classifies any integration with a package.json as
`type=typescript` and unconditionally runs `npm ci` + `npm run build` in
the integration dir. This zero-dependency, no-build JS package had neither,
so `integrations/zed/v*` would fail at release time (invisible in test CI,
which only runs `npm test`):
- add a no-op `build` script so `npm run build` succeeds
- commit package-lock.json so `npm ci` succeeds (it refuses to run without
one, even with zero deps); lockfile has no node_modules entries, so
check-integration-lockfiles.sh passes trivially
- drop the stray settings.json (a local `init` scaffold accidentally
committed) and gitignore it
Verified locally: node --test (21/21), npm ci, npm run build, and
npm publish --dry-run all pass; tarball ships only bin/src/README.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01WEHyNxWfn1miSWRW6NUtEW
* docs(zed): update setup to Node/npx (drop pip install)
* refactor(zed): scope npm package as @vectorize-io/hindsight-zed
Match the scoped-name convention of the other TS integrations
(@vectorize-io/hindsight-ai-sdk, -chat, -openclaw). CLI/bin command stays
'hindsight-zed'; npx/global-install references updated to the scoped name.
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: DK09876 <[email protected]>
Grafts the parse-validated fallback from #2557 onto the line-based fence
stripper merged in #2563: after stripping, if the candidate is not valid
JSON (partial/absent fence, prose-wrapped or truncated output), fall back
to the outermost parseable {..}/[..] span. Never returns a worse candidate
than the raw content.
* Fix _strip_code_fences truncating JSON when content contains inner backticks
The old implementation used content.split('')[0] to strip
markdown code fences from LLM responses. This finds the FIRST occurrence of '''
after the opening fence — so when the extracted JSON itself contains literal
triple-backtick characters (e.g. facts about code fence formatting), the split
matches those inner backticks and truncates the JSON mid-string.
Replace with line-based fence detection that only matches fences at line
boundaries per the markdown spec. Inner backticks inside JSON string values
are preserved since they aren't at line boundaries.
* test(llm): cover inner-backtick fence stripping regression
---------
Co-authored-by: Ben <[email protected]>
The OpenCode plugin imports @opencode-ai/plugin/tool from its
built dist entrypoint, so the package must be present in
OpenCode's isolated plugin cache. Keeping it only as a peer
dependency lets npm skip it during plugin installation, which can
make the plugin fail to load with ERR_MODULE_NOT_FOUND.
Move @opencode-ai/plugin into dependencies and remove the
peer-only declaration. Keep @vectorize-io/hindsight-client as a
runtime dependency, and sync package-lock.json so npm installs the
cache tree needed by OpenCode.
Verified with npm run build, npm pack --json, and a local opencode
plugin install from the generated tarball. The generated cache
contained both runtime dependencies and direct import of the
plugin entrypoint succeeded.
The list and get memory-unit paths selected tags and timing fields
but skipped the memory_units metadata column, so metadata retained
on facts was invisible outside recall.
Select and serialize metadata for live and invalidated memory units,
add a curation regression test for both paths, and update docs plus
OpenAPI examples.
* fix(parsers): coerce non-bytes buffers before the UTF-8 charset probe
MarkitdownParser._utf8_stream_info() is type-hinted file_data: bytes and calls
file_data.decode('utf-8') to check whether a text file is valid UTF-8 before
handing markitdown an explicit charset hint. But callers may pass a
buffer-protocol object that is not a concrete bytes (a memoryview, or a
native/Rust-backed buffer), which has no .decode — raising
AttributeError: '...' object has no attribute 'decode' and failing every
text-file parse (.txt/.json/.md/.csv/.html/...).
The temp-file write in _convert_sync a few lines up already relies only on the
buffer protocol, so the decode probe was the sole spot assuming concrete bytes.
Coerce via bytes(file_data) before the probe. Adds a regression test with a
buffer-only object (no .decode).
* test(parsers): use memoryview stand-in for the non-bytes buffer case
The previous fixture defined a PEP 688 __buffer__ class, which bytes() only
recognizes on Python 3.12+; on 3.11 the CI shard raised
'TypeError: cannot convert ... object to bytes'. Use a memoryview instead — it
has no .decode and bytes(memoryview) works on every supported version, so the
test stays portable while still exercising the coercion path.
* Blog: Eve automatic memory (hindsight-eve v0.2.0)
New post covering the v0.2.0 rewrite of the Vercel Eve integration: memory
is now automatic (instructions resolver recalls before each turn, hook
retains after) with no model-called memory tool. Supersedes the v0.1 draft
in #2480. Adds cover + three demo screenshots (teach -> observation -> recall).
Flip `includeAssistantReply` to default `true` so the auto-retain hook stores
both the user's message and the assistant's reply, not just the user's message.
The assistant's reply is usually where the answer lives (the decision, the
solution, the code), and this matches every other Hindsight integration that
does automatic retain:
- agent-framework (same provider/after_run pattern as eve): include_input +
include_response both hardcoded true
- opencode: retainMode "full-session" (user + assistant) by default
- claude-code: retainRoles ["user", "assistant"] by default
eve was the only auto-retain integration defaulting to user-only. Set
`includeAssistantReply: false` to keep the old behavior.
Updates JSDoc, README, and repurposes the "user-only by default" tests to
assert the new default (both), with the opt-out (false) still covered.
Replace the MCP-connection helper with automatic long-term memory backed by
Hindsight's REST API. Memory no longer depends on the model choosing to call a
tool (which proved unreliable — the model would reach for bash, a subagent, or
just acknowledge a fact without saving it).
Two authored files now give an Eve agent memory that just works:
- agent/instructions/hindsight.ts -> hindsightMemory(): a defineDynamic
instructions resolver that recalls the user's stored memory and injects it as
a system message before each turn.
- agent/hooks/hindsight.ts -> hindsightRetainHook(): a defineHook that retains
the user message + assistant answer after each turn.
Pure core (HindsightRestClient, resolver, turn-pairing, recall formatting) is
split from the eve-importing wrappers and unit-tested with a mocked fetch.
Config via HINDSIGHT_API_KEY / HINDSIGHT_API_URL / HINDSIGHT_BANK_ID. Recall is
profile-based (eve's instruction resolver can't see the live user message).
Feedback-loop guard fences injected context so recalled facts are never
re-retained. Docs + integrations.json updated; bumped to 0.2.0 (breaking).
Community-contributed integration post (by Gareth Cooper) on architxt's
Temporal Mosaic: turning fragmented enterprise architecture documents into
a queryable, current-state view backed by Hindsight. Includes 5 product
screenshots + a co-branded cover, and registers the author in authors.yml.
`_build_request_body` reads `config.llm_temperature_retain` (added by the
per-operation temperature work, #2459), but test_batch_request_body_strict_
follows_config's SimpleNamespace config never set it, so the test raised
`AttributeError: 'SimpleNamespace' object has no attribute
'llm_temperature_retain'`. It only fails on PRs that touch hindsight-api-slim;
main hides it via path-filtering, so it went unnoticed.
Set it to None (temperature omitted) so the test still asserts purely on the
`strict` flag it targets.
Constellation (memories + entities views):
- Ambient motion so the star map feels alive: slow per-node drift, a size
pulse and brightness twinkle (each desynchronized by an id-derived phase),
a calm breathing shimmer across idle links, and twinkling hub halos.
- On hover, a bead of light travels each of the node's links, so connections
read as live signal paths rather than static lines.
- Re-measure the canvas via ResizeObserver when its container reflows (e.g.
the Fullscreen toggle / layout changes) — window "resize" alone missed
container-only changes, so CSS stretched the old bitmap and squeezed text.
Memories (data) view:
- Drop the right-hand control/detail side panel. Clicking a memory node now
opens the same rich MemoryDetailModal the table/timeline use.
- Move the constellation controls (Color by, Group by scope, Link types) into
an inline row above the graph, next to the view toggle — giving the star map
full width.
The curation archive (invalidated_memory_units) is a `LIKE memory_units`
clone with no index. It carried a `search_vector` column purely as a passive
copy in the invalidate/revert row-move — nothing ever reads it (no text-search
index, and recall/list/get/export all exclude it). But its type is fixed at
tsvector by the clone, while `ensure_text_search_extension` reconciles
`memory_units.search_vector` to text/bm25vector on non-native backends
(pgroonga / pg_textsearch / pg_search / vchord). The archive was never
reconciled, so the curation INSERT ... SELECT round-trip failed:
column "search_vector" is of type tsvector but expression is of type text
This is the exact situation `embedding` was in (#2209): a config-derived,
recall-only column that has no business on the cold archive. Fix it the same
way `embedding` was fixed (d4f6a8c2e1b3):
- Migration e7c3a9f1b2d5 drops search_vector from invalidated_memory_units
(PG + Oracle), so there is no column left to mismatch.
- The curation move omits search_vector from arch_cols (alongside embedding),
so invalidate/revert never copy it.
- On revert, search_vector is recomputed from the row's own text/context/
text_signals using the *current* text-search backend — right next to the
existing embedding recompute. This is more correct than the old verbatim
copy, which could restore a stale/wrong-type vector if the backend changed
while the fact sat archived.
The per-backend search_vector SQL is extracted into pg_search_vector_expr as a
single source of truth shared by insert and revert (also collapses the three
near-identical insert query blocks into one). pgroonga/pg_textsearch/pg_search
index base columns directly and leave search_vector empty, so the expression is
None for them and the column is simply not written.
Tests: extend the curation suite to assert the archive drops search_vector and
that revert repopulates it (native); add fast unit tests for
pg_search_vector_expr and the per-backend insert column shape.
* Add Devin Desktop persistent memory blog post
Integration walkthrough for hindsight-devin-desktop (Devin Desktop, formerly
Windsurf): persistent memory via a remote MCP server plus an always-on
.devin/rules rule. Supersedes the earlier Windsurf post (same product,
renamed by Cognition in June 2026).
* refactor(control-plane): drop the Graph view from memories
Removes the Cytoscape-based "Graph" visualization from the memories views,
leaving Constellation, Table, and Timeline. The Graph view was the only
consumer of cytoscape, cytoscape-fcose, and the slider UI control.
- Delete the Graph2D component (src/components/graph-2d.tsx); move the
shared graph data model + API-response converter (still used by the
Constellation and entities views) into src/components/graph-data.ts.
- Remove the "graph" ViewMode, its tab button, render section, and
graph-only state/effects (showLabels, maxNodes, linkStats) from
data-view.tsx. The shared /api/graph data source that feeds all views
is untouched.
- Drop cytoscape, cytoscape-fcose, @types/cytoscape and the now-orphaned
@radix-ui/react-slider dependency + ui/slider.tsx.
- Remove the dead graph2d i18n namespace and graph-legend dataView keys
from all locale catalogs (parity + used-keys tests stay green).
* chore: sync docs-skill openapi.json to 0.8.4
Pre-existing drift: the v0.8.4 release did not regenerate the bundled
docs-skill OpenAPI snapshot, leaving verify-generated-files red. Running
generate-docs-skill.sh bumps only the version string (0.8.3 -> 0.8.4).
Unrelated to the graph-view removal but required to make CI green.
strict_schema was a dead no-op in codex_llm: structured output always went
through prompt-injected schema + raw json.loads on the model's free-form text.
Escape-heavy content (code, serial/CLI commands, Windows paths, regexes) makes
weaker models emit invalid \escape sequences, so every parse attempt fails and
retain/consolidation burn all retries and fail (same class as #1002/#2339).
- strict_schema=True now routes structured output through a single forced
function tool (constrained decoding into the response schema), mirroring the
Anthropic forced-tool_use fix (#2339). No prompt-injected schema, no
json.loads on free-form text.
- The non-strict fallback and tool-argument parsing now repair invalid
\escape sequences before giving up, stopping the deterministic retry storm
for the default config.
* fix(control-plane): load all mental models instead of capping at 100
The mental models view fetched without a limit, so the dataplane applied
its default cap of 100. Any bank with more than 100 mental models silently
hid the rest — the dashboard's pagination and the files view both operate
over the full in-memory list, so nothing past the first 100 was reachable.
Thread limit/offset through the client and proxy route, and page through
the API in loadData() until a short page is returned, accumulating every
mental model for the bank.
* fix(control-plane): use page size of 100 for mental models paging
2026-07-02 12:02:38 +02:00
1791 changed files with 204089 additions and 21157 deletions
- **Authentication/tenancy is enforced inside each engine method, not assumed by the handler.** Every engine method that touches bank-scoped data must authenticate via `request_context` — typically `await self._authenticate_tenant(request_context)` (often indirectly through `get_bank_profile(...)`) — so the correct tenant schema is resolved before any query runs. Handlers must thread `request_context` through to the engine method; never query a tenant-scoped table assuming the schema is already set.
- Engine methods return typed models (Pydantic/dataclass), not raw dicts (see Type Safety).
### Database Locking
- **Never use PostgreSQL advisory locks** (`pg_advisory_lock`, `pg_try_advisory_lock`, `pg_advisory_xact_lock`, `pg_advisory_unlock`, …) in migrations, engine code, or anything else. Hindsight runs against connection poolers and managed/PG-compatible services where advisory locks are unreliable or unsupported: session-level locks silently leak or vanish when a pooler hands the session to another client, and callers can block forever on a lock the server never grants. Reject any new occurrence, including ones that look "safe" because they are transaction-scoped.
- The pre-existing usage in `hindsight_api/migrations.py` is grandfathered, not a precedent — it is tracked for removal. Don't copy it.
- Design the concurrency out instead of locking around it: give each process its own object to write (e.g. per-schema DDL rather than a shared `public.` object), make the operation idempotent, or use a real row/table constraint (`INSERT ... ON CONFLICT`, `SELECT ... FOR UPDATE` in a fixed order). See #2690 for a migration that reached for `pg_advisory_xact_lock` and had to be reverted.
### Branch Hygiene
- **Always start new feature branches from `origin/main`** — rebase to ensure a clean base.
- **Only include commits relevant to the PR/branch/feature** — no unrelated changes. If the branch contains commits that don't belong, they must be removed before merging.
@@ -154,6 +159,18 @@ If any files in `hindsight-api-slim/hindsight_api/api/` were changed:
- Were the client SDKs regenerated? (`./scripts/generate-clients.sh`)
- Were the control plane proxy routes updated? (`hindsight-control-plane/src/app/api/`)
### 7a. Check TS/Python wrapper-client parity
Two of the generated SDKs ship a **hand-written, maintained convenience wrapper** on top of the auto-generated low-level client — and *only* these two:
(The Rust/Go/etc. clients are generated-only — no wrapper to keep in sync.)
These wrappers are what most third-party consumers actually call, and they must expose the same surface. **If a change touches one wrapper's method — adds/removes a parameter, changes a default, forwards a new query/body field — the equivalent method in the *other* wrapper must get the same change in the same (or an immediately-following) PR.** A parameter that exists in the generated SDK but is dropped by one wrapper silently strips it for every consumer of that language (this is exactly what #2975 / #3042 fixed for `detail`/`tags_match`/`limit`/`offset` on `listMentalModels`/`getMentalModel`). **Should fix** — flag any wrapper method that gains capabilities in one language but not the other, and add a matching mapping regression test on both sides.
Note: the `client-coverage-check` CI tool only validates **request-body** fields, not GET **query** parameters — so query-param parity gaps are *not* caught automatically and must be checked by hand here.
### 7b. Check API-layer data-access boundary
For each changed handler in `hindsight-api-slim/hindsight_api/api/` (e.g. `http.py`, `mcp.py`):
@@ -204,6 +221,14 @@ in `hindsight-api-slim/hindsight_api/config.py`):
The `test_bundled_template_matches_repo_root` sync test fails on drift; if the
root file changed without re-copying, flag it as a **must fix**.
### 11c. Check for advisory locks
Grep the diff for `advisory` (`git diff main...HEAD | grep -in advisory`). Any new
# Wall-clock ceiling (seconds) for one retain task in the worker. A retain that
# blocks indefinitely is cancelled and marked 'failed' — and so becomes
# retryable — instead of holding its worker slot until the process restarts.
# Set well above your slowest healthy retain; 0 disables. Default 3600.
# HINDSIGHT_API_RETAIN_WALL_TIMEOUT=3600
# Dry-run extraction preview endpoint (POST /memories/dry-run-extract). Enabled by default; it makes
# a real LLM call but stores nothing. Set to false to remove the endpoint (returns 404).
# HINDSIGHT_API_ENABLE_DRY_RUN_EXTRACT=true
@@ -95,7 +165,13 @@ HINDSIGHT_API_LOG_LEVEL=info
# HINDSIGHT_API_READ_DATABASE_URL= # Optional read-replica URL. When set, recall queries (semantic, BM25, graph, temporal) flow through a separate pool against this URL, offloading the primary. Typically points to a read-only endpoint (CNPG's <cluster>-ro service or Aurora reader endpoint).
# HINDSIGHT_API_MIGRATION_DATABASE_URL= # Direct PostgreSQL URL for migrations (bypasses PgBouncer). Falls back to DATABASE_URL.
# HINDSIGHT_API_DATABASE_SCHEMA=public # PostgreSQL schema name (default: public)
# HINDSIGHT_API_DB_MAX_PARALLEL_WORKERS_PER_GATHER= # Optional cap on Postgres planner parallelism for this process's pool connections. Unset leaves the server default; 0 makes background/bulk queries run serially (useful on worker processes sharing a primary with latency-sensitive traffic).
# HINDSIGHT_API_ENTITY_TRGM_SIMILARITY_THRESHOLD=0.15 # Postgres pg_trgm.similarity_threshold applied on every pool connection, used by entity resolution's % trigram match. Must be in (0, 1]. Lower catches more substring-ish matches at higher CPU cost on large entity sets; higher is stricter and cheaper.
# HINDSIGHT_API_ENTITY_INTRABATCH_MERGE_SIMILARITY=0.5 # Trigram similarity (pg_trgm-equivalent, computed in-memory) at/above which two new names created by the SAME retain are merged into one entity (in-batch dedup of surface-form variants). Must be in (0, 1]. A merge cutoff, stricter than the recall threshold above; raise toward 1.0 to merge only near-identical forms.
# HINDSIGHT_API_RETAIN_ENTITY_RESOLUTION_MAX_CANDIDATES=200 # Max candidates scored per entity mention during retain. The fuzzy lookup keeps only this many best matches per name (ranked by trigram/Jaro-Winkler similarity) before scoring them one by one. On banks holding thousands of near-identical names an uncapped set turns one retain into minutes of CPU that stall the worker's health checks. Raise only if entities that should merge are being duplicated.
# HINDSIGHT_API_MIGRATION_CONCURRENCY=1 # Tenant schemas to migrate concurrently (PG only, each in its own process; per-schema work stays sequential). Each worker has ~1-2s startup cost + uses ~3 DB connections, so it only pays off with many schemas (tens+) or slow migrations; keep concurrency*3 <= spare max_connections. Default: 1 (sequential).
# HINDSIGHT_API_OPERATION_RETENTION_DAYS=30 # Prune terminal operation rows, payloads, and metadata after this many days; 0 (the default) keeps them forever.
# HINDSIGHT_API_OPERATION_CLEANUP_BATCH_SIZE=1000 # Maximum expired terminal rows deleted per tenant schema in each cleanup cycle; must be positive.
# Vector Extension (Optional - uses pgvector by default)
@@ -298,7 +298,7 @@ client.reflect(bank_id="my-bank", query="What should I know about Alice?")
---
## Star History
[](https://www.star-history.com/#vectorize-io/hindsight&type=date&legend=top-left)
- HINDSIGHT_API_LLM_API_KEY=${OPENAI_API_KEY?Please set the OPENAI_API_KEY env variable}
- HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_API_LLM_API_KEY:?Please set the HINDSIGHT_API_LLM_API_KEY env variable}
- HINDSIGHT_API_DATABASE_URL=postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:?Please set the HINDSIGHT_DB_PASSWORD env variable}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
- HINDSIGHT_API_LLM_API_KEY=${OPENAI_API_KEY?Please set the OPENAI_API_KEY env variable}
- HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_API_LLM_API_KEY:?Please set the HINDSIGHT_API_LLM_API_KEY env variable}
- HINDSIGHT_API_DATABASE_URL=postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:?Please set the HINDSIGHT_DB_PASSWORD env variable}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Make v2 knowledge pages a reliable, cleanly-tiered "wiki" surface: passive `entity_labels` tier-tagging + tag-scoped seeded pages, a `hindsight_*` MCP surface with one active `capture_initiative` verb that creates per-initiative pages linked by tag, and SessionStart/UserPromptSubmit page-roster injection.
**Architecture:** Shared TS core (`hindsight-integrations/hindsight-coding-agents`). Extraction stays blind to "pages"; classification is intrinsic (`knowledge:<tier>` tags), pages are tag-scoped saved views. Per-initiative navigation via a `relatedPageId:<id>` tag the synthesizer renders into `[[page:<id>]]`, with the Initiatives folder/roster as the guaranteed fallback.
**Tech Stack:** TypeScript, vitest, tsup bundling. Hindsight REST API (`/knowledge-base/*`, `/mental-models`, `/memories`, bank `/config`).
- [ ]**Step 3: Implement** — add `pageRefreshEveryTurns: number` to the `Config` type and default `10` in the same place `recallMaxTokens`/`reflectTimeoutMs` are defined/merged. Follow the exact merge/layering pattern already used for numeric fields.
- Test: `src/core/hindsight.*.test.ts` (add/extend a config test with a mock client)
- [ ]**Step 1: Write failing test** — assert `configureBank` PATCHes `/config` with `entity_labels` containing the `knowledge` group and its five values, and `entities_allow_free_form: true`. Use the existing fetch/req mock pattern from `hindsight.*.test.ts`; capture the PATCH body to `/config` and assert on it.
- [ ]**Step 2: Run** → FAIL.
- [ ]**Step 3: Implement**
- In `missions.ts`, export `KNOWLEDGE_LABELS` — the exact object from the spec §4 (`key:"knowledge"`, `type:"multi-values"`, `optional:true`, `tag:true`, the verbose group `description`, and the five value `{value,description}` entries: feature-work, decision, convention, component, concept).
- In `hindsight.ts::configureBank`, extend the existing `PATCH .../config``updates` object to include `entity_labels: [KNOWLEDGE_LABELS]` and `entities_allow_free_form: true`. Import `KNOWLEDGE_LABELS`.
- Update the `[bank] configured …` log to mention `entity_labels`.
- Each seeded page POST to `/knowledge-base/pages` includes `tags: ["knowledge:<tier>"]` mapped per the spec §5 table.
- The Initiatives page is created with `parent_id` equal to the id returned by an Initiatives folder POST to `/knowledge-base/folders`.
-`ensureFolder("Initiatives")` returns an existing root folder's id when the tree already contains it (GET `/knowledge-base/tree`) and does NOT POST a duplicate.
- [ ]**Step 2: Run** → FAIL.
- [ ]**Step 3: Implement**
-`missions.ts`: add `tags: string[]` to each `PAGES` entry (feature-work/decision/convention/component/concept mapping). Append to the Initiatives `source_query`: *"When a source memory carries a tag of the form `relatedPageId:<id>`, include a Markdown link `[[page:<id>]]` to that page in the summary, so each initiative links to its detailed page."*
-`hindsight.ts`: add
```ts
/** Find a root folder by name (case-insensitive) or create it; returns its id. */
const r = await this.req("POST", this.bankUrl("/knowledge-base/folders"), { name });
return ((await r.json()) as { id?: string }).id;
} catch { return undefined; }
}
```
- In `createPages()`: before the loop, `const initiativesFolderId = await this.ensureFolder("Initiatives");`. For each page, build body `{ name, source_query, tags: p.tags, parent_id: <initiativesFolderId if this is the Initiatives page else undefined>, trigger: { fact_types:[...], refresh_after_consolidation:true } }`. (Page-level `tags` drives synthesis scoping via `RefreshTagFiltering`; `tags_match` defaults to `all_strict` when tags present.)
- `captureInitiative({title:"Retry backoff for the uploader", summary:"…"})` → derives slug `retry-backoff-for-the-uploader`, POSTs a page id `initiative-<slug>` to `/knowledge-base/pages` with `parent_id` = the Initiatives folder and `tags: ["knowledge:feature-work"]`, AND POSTs a marker to `/memories` (via `retain`) tagged `["knowledge:feature-work","relatedPageId:initiative-<slug>"]`, strategy `session` or `document` (pick `document`), `async:true`. Returns `{ page_id: "initiative-<slug>" }`.
- Slug is deterministic and identical between the page id and the `relatedPageId:` tag value.
- Enhancement path: `captureInitiative({title, summary, relatesToPageId:"initiative-x"})` POSTs NO new page; marker tagged `relatedPageId:initiative-x`; returns `{ page_id: "initiative-x" }`.
source_query: `Summarize the "${args.title}" initiative: what is being built or changed and why, and its current state — drawn from the project's memory.`,
- NOTE: use a UNIQUE document id per marker (e.g. `initiative-marker-<slug>-<n>`), NOT `pageId`, so repeated enhancement captures accrue instead of replacing. Since `Date.now()` is fine here (runtime, not a workflow script), suffix with a timestamp: `initiative-marker-${this.slugify(args.title)}-${Date.now()}`. Keep the `relatedPageId` tag equal to `pageId`.
- `buildKnowledgeTools(client, bankId)` returns exactly these tool names: `hindsight_get_current_bank`, `hindsight_list_knowledge_pages`, `hindsight_read_knowledge_page`, `hindsight_search_memory`, `hindsight_capture_initiative`, `hindsight_ingest_document`. (Assert the set; update any count assertion.)
- `hindsight_capture_initiative` handler calls `client.captureInitiative` with `{title, summary, relatesToPageId?}` and returns the page id (mock client).
- No `create_page` / `update_page` / `delete_page` tools are present.
- Each tool still fails closed via `guarded` (a thrown client error → `isError:true`, no throw).
- [ ] **Step 2: Run** → FAIL.
- [ ] **Step 3: Implement**
- Rebuild the `buildKnowledgeTools` list: rename read/recall/ingest/bank tools to the `hindsight_*` names; drop `create_page`/`update_page`/`delete_page`; add `hindsight_capture_initiative` with `inputSchema { title: z.string(), summary: z.string(), relates_to_page_id: z.string().optional() }` calling `client.captureInitiative({ title, summary, relatesToPageId: relates_to_page_id })`.
- Use the **verbatim agent-facing `description` strings** from the spec §6 / the brainstorm (grounding tools + the explicit WHEN/WHEN-NOT `capture_initiative` description).
- Update `mcp-server.ts` only if it enumerates tool names; otherwise it consumes `buildKnowledgeTools` generically and needs no change.
- `buildSessionStartContext` now fetches pages via the client and injects `buildKnowledgePreamble(...)` instead of the static `KNOWLEDGE_MISSION`. Extend the `SeedContextClient` interface with `listPages(): Promise<unknown>`; the mock returns `{items:[{id:"p1",name:"Component map"}]}` and the output contains "Component map".
- listPages failure is fail-open: the preamble still renders (empty-state) and the seed logic is unaffected.
- [ ] **Step 2: Run** → FAIL.
- [ ] **Step 3: Implement**
- Add `listPages` to `SeedContextClient`.
- Replace the `parts.push(KNOWLEDGE_MISSION)` line with: fetch `const pages = parsePageList(await client.listPages().catch(() => null));` then `parts.push(buildKnowledgePreamble(pages));`. Import from `./knowledge-injection`.
- Remove the now-unused `KNOWLEDGE_MISSION` export if nothing else references it (grep first; keep if referenced).
- The session cache round-trips `{answer, turns}`; each `buildHookOutput` call increments `turns`.
- Add `listPages` to the `HookClient` interface. On a turn where `turns % cfg.pageRefreshEveryTurns === 0`, the output includes `buildRosterRefresh(...)` content (assert "Component map" appears); on other turns it does not.
- Refresh is fail-open (a `listPages` rejection doesn't break recall/injection).
- First-turn behavior (reflect) unchanged.
- [ ] **Step 2: Run** → FAIL.
- [ ] **Step 3: Implement**
- Extend the cache read/write to `{ answer?: string; turns?: number }`. Compute `const turns = (cached.turns ?? 0) + 1;` and persist it alongside `answer`.
- Add `listPages(): Promise<unknown>` to `HookClient`.
- After computing `memBlock`, if `cfg.pageRefreshEveryTurns > 0 && turns % cfg.pageRefreshEveryTurns === 0`, `try { const refresh = buildRosterRefresh(parsePageList(await client.listPages())); if (refresh) blocks.push(refresh); } catch { /* fail-open */ }`. Kick the `listPages` call off concurrently with recall to avoid added latency.
## Task 9: Full check + LLM behavior (live) verification
**Files:**
- Modify: `src/system.live.test.ts` (add coverage; runs only under `HINDSIGHT_LIVE_E2E=1`)
- [ ] **Step 1: Full fast suite + types** — `npx vitest run && npx tsc --noEmit` → all green.
- [ ] **Step 2: Add a live assertion** (guarded by the existing live env flag) that after seeding a small repo + one `captureInitiative`, the Initiatives page content contains a `[[page:initiative-…]]` link (verifies the `relatedPageId` → link rendering end-to-end). Keep it in the live suite; do not run in the fast job.
- [ ] Dispatch a final code-reviewer over the whole change set against the spec (`docs/superpowers/specs/2026-07-25-v2-knowledge-pages-design.md`).
- [ ] Rebuild + dev-install the `claude-code-v2` bundle so the running plugin picks up the new hooks/MCP (`bash scripts/dev-install.sh`); do not push/PR without explicit consent.
**Motivation:** make knowledge pages a real, trustworthy "wiki" surface for the vectorize-crm demo (the `knowledge-pages-as-trust-surface` principle) — the agent reliably knows what pages exist, pages are cleanly tiered instead of blended, and major initiatives become first-class, linkable pages.
---
## 1. Problem
Three gaps in the current v2 branch:
1.**Page discovery is a blind fetch.** SessionStart injects a static `KNOWLEDGE_MISSION` telling the agent to call `agent_knowledge_list_pages`, but hands it **no roster** — the agent never learns a page exists unless it independently decides to call the tool. Per-turn recall injects facts, not pages.
2.**Pages are blended.** Neither the seeded `PAGES` nor the agent's `create_page` tool scope synthesis by tag, so every page synthesizes from the whole bank filtered only by `fact_type`. Git-log, session, and survey memories all bleed into every page.
3.**No first-class initiative tracking / linking.** Hindsight has no native page-to-page links. A "major feature" leaves no durable, navigable page a future session can pick up.
## 2. Principles applied
- Automatic/visible value; zero out-of-band CLI; memory beats code search; knowledge pages as a trust surface; minimal post-setup burden.
- Modular units, small files, follow existing patterns (per-hook specs, fail-open, unit-testable pure cores).
- The **memory extractor never knows what a "page" is.** Classification is by the fact's *intrinsic* nature; pages are application-side saved views. No abstraction leak into extraction.
## 3. Architecture overview
Two complementary curation paths + a discovery layer:
- **Passive (automatic):** `entity_labels` schema-forces the extractor to tag qualifying facts `knowledge:<tier>`. Seeded **tier pages** each filter on one tier tag. No agent effort.
- **Active (high-signal):** one intent-named MCP verb, `hindsight_capture_initiative`, lets the agent register a major feature as a **per-initiative page** with a tag-based link back from the aggregate Initiatives page.
- **Discovery:** SessionStart injects guidance + the page roster; the UserPromptSubmit hook re-injects a fresh roster on a fixed cadence (hook-counted, not model-counted).
## 4. `entity_labels` — passive tier tagging
One hierarchical bank config group, set by `configureBank` at seed time:
```jsonc
{
"key":"knowledge",
"type":"multi-values",// 0, 1, or several — empty is normal
"optional":true,
"tag":true,// emits knowledge:<value> onto the fact's tags
"description":"Routing labels for this project's Hindsight KNOWLEDGE PAGES — curated, human-readable summaries of the repo's DURABLE engineering knowledge (architecture, key decisions, conventions, ongoing initiatives), each page rebuilt automatically from the facts labeled for it. Mark a fact only when it is durable, reusable knowledge a developer would still want surfaced in future sessions. IMPORTANT: leave this EMPTY for routine, transient, or operational facts — a passing test, a one-off command, a status update, a debugging dead-end. MOST facts should get no label here. Assign more than one value only when the fact genuinely fits several.",
"values":[
{"value":"feature-work","description":"A new feature, initiative, or enhancement being planned or built — the capability being added and the intent behind it. Not routine bug-fixes or chores."},
{"value":"decision","description":"A technical decision that will constrain future work, with its rationale — why this approach was chosen over alternatives, or a rule deliberately adopted."},
{"value":"convention","description":"An established way this project does things — naming, structure, testing, error handling, or another recurring pattern a contributor is expected to follow."},
{"value":"component","description":"What a specific module, file, service, or subsystem is responsible for, or how components depend on and connect to one another."},
{"value":"concept","description":"A domain concept, key abstraction, or piece of project vocabulary a new contributor must understand to work effectively."}
]
}
```
Notes:
-`tag: true` → `_inject_label_tags` copies each `knowledge:<value>` onto the fact's `tags` (no extra query infra).
- Selectivity (multi-values + "mostly empty" instruction) prevents force-fitting routine facts into a tier.
## 5. Seeded tier pages (tag-scoped)
Created via `/knowledge-base/pages` (supports `tags`, `trigger`, `parent_id`) — **not**`/mental-models`. Each `PAGES` entry gains a `trigger.tags` pin:
| Page | `trigger.tags` |
| --- | --- |
| Initiatives and enhancements | `["knowledge:feature-work"]` |
| Key decisions and rationale | `["knowledge:decision"]` |
| Conventions and patterns | `["knowledge:convention"]` |
| Component map | `["knowledge:component"]` |
| Core concepts | `["knowledge:concept"]` |
`tags_match` strict enough to exclude untagged facts (`all_strict`/`any_strict`). Tag matching is exact set-ops (no wildcards) — this is *why* the vocabulary is fixed, not per-feature.
## 6. MCP surface
Raw page CRUD (`create_page`/`update_page`/`delete_page`) is **removed** from the agent. The agent sees grounding tools + one capture verb. Naming convention: `hindsight_*`.
**Grounding**
-`hindsight_list_knowledge_pages``{}` — roster: id, title, one-line coverage. (agent-facing description as drafted in brainstorm)
-`hindsight_read_knowledge_page``{ page_id }` — full page content; follow `[[page:<id>]]` links by re-calling.
-`hindsight_search_memory``{ query, max_tokens? }` — raw fact recall for specifics pages don't cover.
-`hindsight_get_current_bank``{}` — minor introspection (kept).
**Capture**
-`hindsight_capture_initiative``{ title, summary, relates_to_page_id? }` — the one active verb. Explicit WHEN / WHEN-NOT description (as drafted). Returns the initiative page id.
(Full agent-facing descriptions are captured verbatim in the brainstorm thread and will be reproduced in the implementation plan.)
## 7. `hindsight_capture_initiative` mechanism
- Derive one slug `S` from `title`. Page id = `initiative-<S>`. **The slug in the tag and the page id are the same token, derived once** (cannot drift).
1. Create page `initiative-<S>` (title from `title`, `source_query` about that initiative) under an **"Initiatives" folder** (tag-scoped).
2. Retain a marker memory (text = title + summary) tagged `["knowledge:feature-work", "relatedPageId:initiative-<S>"]`. **No session tag** (decided — the MCP server has no Claude session id; faking one wouldn't link to the Stop write-back's `conversation:<sessionId>` doc anyway).
- **Enhancement** (`relates_to_page_id` given): marker only, `relatedPageId = relates_to_page_id`; no new page. Re-invoking for the same initiative accrues markers → the page re-synthesizes with progress.
### Link survival (why `relatedPageId` as a tag, not in prose)
A tag is set directly via the retain `tags` param — it **bypasses LLM extraction entirely**, so it's guaranteed present verbatim (no REF-ID-style preservation needed at extraction). Verified: the reflect/synthesis path SELECTs `tags` and serializes facts via `_prune_nulls(model_dump())`, which keeps non-empty tags → **the synthesis LLM sees the tag.** The **Initiatives page `source_query`** instructs: *"when a memory carries a `relatedPageId:<id>` tag, emit a `[[page:<id>]]` link to it."* The link id is generated from the tag value at synthesis time, so it always matches the created page id.
- Only **Stage 2 (synthesis)** is probabilistic now (bounded token budget may omit some entries when there are many).
- **Guaranteed fallback:** the per-initiative page always exists (created via API, independent of any LLM stage) and appears in the **Initiatives folder / injected roster**, so navigation works even if a synthesized inline link drops.
## 8. Page-access injection
- **SessionStart** (`session-start.ts`): replace static `KNOWLEDGE_MISSION` with a preamble = (a) guidance on *when/why* to consult pages, (b) the roster fetched via `client.listPages()` (`- <title> (<id>)`, empty-state aware), (c) a note that the list refreshes periodically. Cold repo → empty roster line; roster comes alive mid-session as seeding/survey complete.
- **UserPromptSubmit** (`hook.ts`): extend the per-session cache (`{answer}` → `{answer, turns}`); the **hook** counts user turns and, roughly every `pageRefreshEveryTurns` (default 10, approximate), calls `listPages()` and injects a compact roster refresh. Runs concurrently with recall; **fail-open** (a refresh error never blocks the turn).
- Session drill-down tag on captured markers (dropped — see §7).
-`hindsight_capture_decision` and other capture verbs (passive path covers those tiers; revisit if the aggregate pages aren't sharp enough).
- A `gotcha`/`pitfall` tier (five tiers for now).
- Native page-to-page links / backlinks (Hindsight has none; we approximate via folder tree + `relatedPageId`-driven `[[page:<id>]]`).
## 10. Risks / migration
- **Older banks** need re-seeding to pick up the new `entity_labels`, the `session` retain strategy, and the tag-scoped page triggers (`configureBank` sets them). User is starting fresh with v2 banks, so acceptable; live retain fails open otherwise.
- **Stage-2 synthesis omission** for large initiative counts — mitigated by the folder/roster fallback.
- **Instruction adherence** for the `source_query` link-rendering and the label selectivity — both are LLM-following behaviors; cover with an `hs_llm_core` judge test, and the deterministic mechanics (tag injection, roster formatting, slug/id equality, hook turn-counting) with fast unit tests.
## 11. Testing
- **Deterministic unit tests:** `knowledge-injection` formatting + empty-state; hook turn-counter + cadence; `capture_initiative` slug→id→tag equality and request shape (mock client); tag-scoped page request bodies; entity_labels config emitted by `configureBank`.
- **LLM judge test (`hs_llm_core`):** label selectivity (routine facts get no `knowledge:*`), and `relatedPageId` → `[[page:<id>]]` rendering in a synthesized Initiatives page.
**Motivation:** the 33-task coding benchmark showed the v2 recall-per-prompt runtime *underperforms no memory* (35.0 mean corrections vs 32.0 baseline), while the earlier reflect-injection runtime beats baseline by 22% (25.0). This spec restores reflect as the only deep-memory path and replaces raw per-turn recall with lightweight injection from knowledge pages — "fast like recall, organized like reflect" — keeping v2's page/curation machinery where it earned its place and deleting it where it didn't.
---
## 1. Problem
Two prior iterations, each half right:
1.**Reflect runtime (v1):** one agentic REFLECT over the bank at session start, cached and re-injected every turn. Benchmark-proven (25.0 mean corrections) — but nothing surfaced mid-session; a task that drifted away from the first message got stale context.
2.**Recall runtime (v2):** per-prompt recall injection for turn-by-turn visibility, plus knowledge pages as a trust surface. But raw recall injects unsynthesized fact fragments — noise that *hurt*: 35.0 mean corrections, worse than running with no memory at all.
| Runtime | Mean corrections (33-task benchmark) | vs no-memory (32.0) |
The reconciliation: keep reflect's synthesis quality as the deep path, keep v2's per-turn visibility principle, but source the per-turn material from the already-synthesized knowledge pages instead of raw recall.
## 2. Decisions
Explicit, decided — not options:
1.**Reflect restored** as the only deep-memory path (session-start, agentic synthesis, cached + re-injected every turn).
2.**Recall removed from the runtime** entirely. No per-prompt `recall` call.
3.**No `memoryMode` flag.** One opinionated path; config is for environment, naming, and harness wiring only — never behavior selection.
4.**Sections, not pages, are the per-turn injection unit** — locally matched, budget-trimmed, provenance-labeled.
5.**JSON turn transcripts** replace the markdown tool-call transcript in the Stop-hook write-back, with compact action entries.
6.**No tags / no `entity_labels`.** The server re-synthesizes pages after consolidation; "living pages" needs no client-side tagging machinery.
## 3. Runtime path — session start
Three steps, in order, all inside existing hooks (no out-of-band CLI):
### 3a. Cold-repo bootstrap (kept from v2)
On a bank with no prior memories: automatic shallow gitlog seed + codebase survey, exactly as v2 does it. The user never runs a setup command; the first session self-seeds. (Deep ingestion of that history is §7 — the seed here stays instant.)
### 3b. REFLECT once, on the first task message
The benchmark-proven core:
- On the first user prompt of the session, run one **REFLECT** — agentic synthesis over the whole bank, prompted to return the *root-cause decision with exact values* (concrete file paths, config values, version numbers — not summaries of summaries).
- Cache the result per session; **re-inject it every turn**. It is the session's durable deep context.
- One LLM-backed call per session, on the message that actually states the task — not on session-open, where there is nothing to reflect about.
### 3c. Page index build
Fetch all knowledge pages once (existing `listPages` + page reads), split each page at headings into **sections**, and build a **local section index** in the hook process. This index is what every subsequent turn matches against (§4) — no further server calls on the hot path.
## 4. Runtime path — every turn
Per-turn visibility, satisfied at ~zero latency and ~zero cost. Injection sources from **knowledge pages, not raw recall** — the material is already synthesized and organized; the turn hook only *selects* from it.
Mechanism (local, deterministic — no server call, no LLM call):
| Aspect | Design |
| --- | --- |
| Unit | Page **sections** (pages split at headings at index-build time) |
| Matching | Lexical: prompt scored against each section by weighted term overlap; **heading hits weighted higher** than body hits |
| Selection | Top 2–3 sections |
| Budget | Trimmed to a **~700-token total** |
| Provenance | Each snippet labeled `From <page> › <section>` + a tool pointer to read the full page |
| Floor | A minimum-score threshold below which **nothing is injected** — silence over noise |
| Refresh | Section index rebuilt on the existing 10-turn roster cadence (`pageRefreshEveryTurns`) |
The score floor is load-bearing: the benchmark showed that injecting weak matches is worse than injecting nothing (v2's regression). An empty injection is a correct outcome, not a failure mode.
## 5. Write-back
The Stop-hook session retain is **kept** — same trigger, same fail-open behavior. What changes is the transcript format handed to extraction:
- **JSON turns**, not markdown: an array of `{ "role": "user" | "assistant", "text": ... }` entries for the conversational content.
- Tool calls collapse to **compact one-line action entries**: `{ "role": "action", "text": "Edit boltons/strutils.py" }` — tool name + primary target only, **no arguments, no outputs**.
Rationale: extraction keeps the concrete artifacts (which files were touched, what actions occurred) without the transcript noise of full tool payloads — the markdown tool-call dumps were volume without signal.
## 6. Knowledge pages
Simplified from the v2 spec:
- **Dropped: tags and `entity_labels`** (v2 spec §4–5). The server already re-synthesizes pages after consolidation, so pages stay "living" with no client-side routing machinery. The extractor-never-knows-about-pages principle now holds trivially — there is nothing to route.
- **Creation paths:**
1.**Seeded taxonomy** at bank creation (the fixed page set, as today, minus tag triggers).
2.**Agent-driven `capture_initiative`** at plan approval — the one active capture verb survives from v2.
3.**Organic splitting** of pages that outgrow their scope is a **server/curator concern**, not a client feature.
Replaces the manual backfill CLI as the user-facing path (the CLI was out-of-band burden; nobody runs it). The principle: converge to full-depth history through normal usage, with zero user action.
1.**Instant shallow seed** — the gitlog seed from §3a; the session is useful immediately.
2.**Background deepening** — a background worker deep-ingests **per-commit-with-diffs, incrementally**, never blocking a turn.
3.**Working-set prioritization** — commits are ingested in order of relevance to what the agent is actually doing: files the agent reads/edits get their commit histories ingested **first**. Depth arrives where it pays off.
4.**Checkpointing** — progress persists across sessions; each session resumes deepening where the last left off, converging to full depth over normal usage.
The **backfill CLI survives as an internal tool** (benchmark setup, CI bank preparation) — it is no longer a documented user path.
## 8. Gap analysis — v2 principles under this design
| v2 principle | How this design satisfies it |
| --- | --- |
| See-it-working (automatic, visible value) | Reflect answer visible from turn 1; page-section snippets appear with explicit `From <page> › <section>` provenance, so the user sees memory working — and the score floor keeps it from visibly misfiring. |
| No out-of-band CLI | Cold-repo auto-seed kept (§3a); backfill CLI demoted to internal-only, replaced by background deepening (§7). Nothing requires a terminal command. |
| Reuse-over-reinvent | Reflect, `listPages`, Stop-hook retain, `capture_initiative`, and the 10-turn refresh cadence are all existing machinery recombined; the only new code is the local section index and matcher — deliberately dumb (lexical, no LLM). |
| Preserve-intent | Reflect is prompted for root-cause decisions with exact values; JSON transcripts keep concrete action artifacts; per-commit-with-diffs deepening captures *why* the code changed, not just that it did. |
| Near-zero-burden | No config flags to choose, no CLI to run, no tags to maintain; one LLM call per session start, everything else local. |
## 9. Verification gates
Ship gates, in order:
1.**Reflect-restored benchmark:** the restored runtime must recover **~25 mean corrections at n=2 on identical banks** to the original reflect run. This proves the restoration is faithful before anything is layered on.
2.**Reflect+pages benchmark:** with per-turn section injection enabled, the score **must not regress** vs reflect-alone. Section injection earns its place by not hurting; any regression points at the floor/budget tuning.
3.**Live system suite:** existing hook/integration suite updated for the new path — reflect caching + per-turn re-injection, section index build/refresh, score-floor silence, JSON transcript shape, action-entry compaction. Deterministic pieces (matcher scoring, budget trim, provenance formatting, transcript serialization) as fast unit tests.
## 10. Non-goals / deferred
- Any per-turn LLM or server call for injection (explicitly excluded — the local matcher is the whole point).
- Semantic/embedding-based section matching (revisit only if lexical matching demonstrably misses; start dumb).
- Client-side page splitting or curation (server/curator concern, §6).
"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.",
"DECISION GUIDE, or OUTPUT FORMAT below, the MISSION takes priority."
)
# Default language rule — used only when HINDSIGHT_API_LLM_OUTPUT_LANGUAGE is
# unset. Without it the whole prompt is English and multilingual models drift:
# Chinese source facts intermittently produce English observations. Retain's
# fact extraction carries the equivalent rule (see _BASE_FACT_EXTRACTION_PROMPT),
# so this makes "preserve the source language" the pipeline-wide default. When an
# output language IS configured, this section is omitted and
# output_language_directive() takes over — the two must never both be present or
# they contradict each other.
_DEFAULT_LANGUAGE_RULE="""## LANGUAGE
Write every observation in the language of its own source facts — never translate them. Per observation, not per batch: when one merges facts of several languages, the majority wins. Proper nouns, identifiers, and units stay verbatim.
When an existing observation is written in a different language from the new facts updating it, do NOT edit its wording in place — that is what produces an English sentence with a Chinese detail bolted on. Discard the old phrasing and compose the merged observation from scratch in the new facts' language."""
_PROCESSING_RULES="""## PROCESSING RULES
1. PREFER UPDATE OVER CREATE (when there is something to merge with): if new facts describe the same canonical event, statement, decision, claim, or recurring pattern already covered by an existing observation, UPDATE that observation and attach the new facts as evidence. Do NOT create a near-duplicate sibling. One canonical observation with many source facts is always better than many siblings with one source fact each. Merge aggressively on: same named event, same diagnostic finding, same architectural decision, same recurring claim. **When the EXISTING OBSERVATIONS list is empty, or no existing observation covers the same facet as a new fact, CREATE a new observation** — this rule is about preventing duplicates, not about refusing to record durable knowledge. CREATE is the correct default for any structurally distinct event, claim, or pattern that has no existing match.
9. KEEP DISTINCT TOPICS DISTINCT: do not merge observations about different people, entities, or unrelated topics. Merging is for the same canonical fact recurring — not for related-but-distinct claims."""
# Field-by-field definitions of the input shape used by the cached system
# prefix. The call site runs .format(), so these strings must contain no braces.
_FACT_FIELDS="""One per line, formatted as `[uuid] fact text (temporal fields)`:
- `[uuid]`: the fact's identifier — copy it verbatim into `source_fact_ids`
- `occurred_start` / `occurred_end`: when the described event happened. This can be long before the fact was stated — a fact recorded today may describe a 2019 event.
- `mentioned_at`: when the source material that states this fact was written. This is the fact's recency: how up to date the statement is, NOT when it was added to memory. A fact taken from an old document keeps its old `mentioned_at` even if it was only just processed."""
_OBSERVATION_FIELDS="""- `id`: unique identifier — copy this exactly when issuing an UPDATE or DELETE
- `text`: the observation content
- `proof_count`: how many source facts this observation has already merged
- `occurred_start` / `occurred_end`: the span of the events behind the observation — earliest start and latest end across its source facts
- `mentioned_at`: the latest of the `mentioned_at` values of its source facts — the most recent point at which this observation was stated
- `source_memories`: the supporting facts behind this observation. May be partial or absent for large observations — the count above remains the true total. Each entry carries the same `text` and temporal fields as a new fact, plus:
- `context`: optional surrounding context for that fact"""
# Stable description of the input shape. For the cached split path this lives in
# the system prefix (build_consolidation_system_prompt) so it is not re-sent on
# every batch; the per-batch user message then carries only the actual data.
_INPUT_FORMAT_NOTE="""## INPUT FORMAT
_INPUT_FORMAT_NOTE=f"""## INPUT FORMAT
Each request provides new facts and existing observations:
- New facts: one per line, each prefixed with its `[uuid]`, followed by the fact text and optional temporal fields.
- Existing observations: a JSON array pooled from recalls across the new facts. Each entry has:
- `id`: unique identifier — copy this exactly when issuing an UPDATE or DELETE
- `text`: the observation content
- `proof_count`: number of supporting memories
- `occurred_start` / `occurred_end`: temporal range of source facts
- `source_memories`: array of supporting facts with their text and dates"""
Each request provides new facts and existing observations. Every temporal field is optional and is omitted when unknown.
### New facts
{_FACT_FIELDS}
### Existing observations
A JSON array pooled from recalls across the new facts. Each entry has:
{_OBSERVATION_FIELDS}"""
# Per-batch data section for the cached split path — the stable format
# explanation above is omitted here (it lives in the cached prefix); only the
# Delta operations the model emitted, as applied vs rejected. A refresh whose
# ops are routinely rejected still completes successfully with a plausible
# document, so the count is the only signal that some of this run's new facts
# never reached it. Both are 0 for a full-mode refresh, which emits no ops.
delta_ops_applied:int=0
delta_ops_skipped:int=0
defto_dict(self)->dict[str,Any]:
"""Convert to dict for JSON serialization."""
returnasdict(self)
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Nicolò Boschi
