The bind-mount note told users to run the image as their host user with
`--user $(id -u):$(id -g) -e HOME=/home/hindsight` when the host directory
was not owned by UID 1000. That command crashes the container for every
host UID that is not 1000.
The image only creates the `hindsight` user (UID 1000), so any other UID
has no /etc/passwd entry. torch calls `getpass.getuser()` unconditionally
while resolving its inductor cache directory, which falls through to
`pwd.getpwuid(os.getuid())` and raises:
KeyError: 'getpwuid(): uid not found: 1042'
The reporter's directory was mode 0777 and owned by their UID, so the
pg0 writability pre-check passed and the failure surfaced later as an
opaque torch traceback rather than a permission error.
Replace the advice with the one supported option — chown the host
directory to 1000:1000 and run as the default user — and say explicitly
that --user with another UID is not supported, so the next person
recognises the getpwuid error. Point at a named volume for hosts where
chowning is not possible.
The same advice was printed by the pg0 writability failure message in
start-all.sh, so correct it there too.
Claude-Session: https://claude.ai/code/session_011KDT484YujNcBxHzbfzNbk
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.
* 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
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) <noreply@anthropic.com>
* 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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PginSDrapXsoDd6gN5Pszo
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
* feat(consolidation): add "shared" observation_scopes keyword
Add a "shared" value for observation_scopes that resolves to a single
global, untagged scope ([[]]). Memories consolidate into one observation
regardless of their tags, while the tags stay on the source facts for
recall filtering.
This is the supported way to deduplicate observations across volatile
per-call provenance tags (e.g. per-session ids): with combined/per_tag,
a unique session tag puts every retain in its own scope, so near-identical
facts never dedup and accumulate one observation per session. "shared"
keeps recall and the dedup probe on the same (empty) scope, fixing
consolidation quality rather than only the duplicate count.
- consolidator: _resolve_obs_tags_list -> [[]], _resolve_write_scopes -> [frozenset()]
- API/engine type literals + OpenAPI + regenerated Python/TS/Go/Rust clients
- CP client type kept in sync
- docs: retain.mdx 'shared' section (+ shared vs [[]] vs [] caveat),
observations.mdx dedup pointer; regenerated hindsight-docs skill mirror
- tests: unit scope-resolution + e2e parallel-consolidation scope correctness
* chore(opencode): apply prettier formatting to plugin.test.ts
Pre-existing lint drift unrelated to this PR — CI's verify-generated-files
job reformats all integrations (LINT_ALL_INTEGRATIONS) and flagged this file.
Folding the one-line reflow in here to get the gate green.
Nicolò Boschi