local_embedded questions: port pinning, Knowledge Pages/fs mount support, standalone CLI upgrade path

[fanaticalfishing]

Running hindsight 0.9.0 in local_embedded mode (multiple profiles, each with its own embedded daemon) and hit a few things I couldn't find in the docs. Happy to split these up if you prefer.

1. Config port ignored — daemon binds a dynamic port

Each profile's config.json sets a port (e.g. 9817), but the embedded daemon binds a different, dynamically-assigned port (e.g. 9368), discoverable only from the log line "Daemon Started ( @ :9368)".

• Is the config port field honored at all in local_embedded, or vestigial?
• If I want a stable per-profile port (firewall rules, external health checks, a fixed hindsight fs mount target), what's the supported way to pin it?

2. Knowledge Pages / hindsight fs mount on local_embedded

The 0.9.0 Knowledge Pages feature is documented against server-mode banks. Does it work against a local_embedded per-profile bank?

• If yes: does hindsight fs mount need the daemon's runtime (dynamic) port, or is there a profile-aware invocation?
• Is there a minimum CLI version required to talk to a 0.9.0 daemon for fs mount?
• If it's server-only, a docs note would save local_embedded users some experimentation.

3. Standalone hindsight CLI binary — provenance and upgrade path

~/.local/bin/hindsight on my system is a ~3.6MB compiled ELF binary at version 0.8.2 — not pip/pipx-managed as far as I can tell — while the Python library in my venv is at 0.9.0.

• What's the canonical way to install/upgrade the standalone CLI?
• Does the CLI version need to stay in lockstep with the daemon's API version, or is it forward/backward compatible?

[nicoloboschi]

Answers to all three, verified against the code.

1. port in config.json — not read in local_embedded

That config.json is the Hermes memory-plugin config; the embedded daemon never reads a port from it. In local_embedded the port comes only from the Hindsight profile, resolved in hindsight_embed/profile_manager.py::_resolve_ports with this priority:

1. HINDSIGHT_API_PORT in the profile's .env — ~/.hindsight/profiles/<name>.env (or ~/.hindsight/embed for the default profile)
2. the default profile's fixed 8888
3. a legacy port in metadata.json (pre-0.9 profiles)
4. a fresh allocation

Your 9368 is case 4, and it isn't actually random: _allocate_port hashes the profile name into the 8889–9888 range (skipping ports other profiles already claim), so it is stable across restarts — just not chosen by you.

To pin it:

hindsight-embed profile set-env <profile> HINDSIGHT_API_PORT 9817
hindsight-embed daemon stop && hindsight-embed daemon start   # per profile

Equivalently, add HINDSIGHT_API_PORT=9817 to ~/.hindsight/profiles/<profile>.env. hindsight-embed profile list prints the effective port. The control-center UI port follows as API + 10000 unless you set HINDSIGHT_EMBED_CP_PORT.

2. Knowledge Pages / hindsight fs mount on local_embedded

Both work. The embedded daemon is not a reduced server — daemon_embed_manager spawns the real hindsight-api with --daemon --port <resolved>, so the knowledge-base endpoints are identical to server mode.

hindsight fs is a plain HTTP client with no profile awareness, so point it at the daemon's URL:

hindsight fs mount ./kb --api-url http://127.0.0.1:9817 --bank <bank_id>

With the port pinned per (1) that invocation is stable. <bank_id> is the bank_id from your Hermes plugin config.

Minimum version: 0.9.0 on both sides. hindsight fs and the knowledge-page endpoints landed together in #2455, first released in v0.9.0 — a 0.8.2 CLI has no fs subcommand at all, which is exactly what you are hitting.

3. The standalone CLI binary

It is the Rust CLI (hindsight-cli/), shipped as a prebuilt binary on GitHub Releases — independent of the pip-installed Python packages, which is why yours sits at 0.8.2 while your venv is at 0.9.0. Canonical install and upgrade (the installer overwrites in place, default ~/.local/bin):

curl -fsSL https://hindsight.vectorize.io/get-cli | bash
# pin a version:
HINDSIGHT_CLI_VERSION=0.9.2 curl -fsSL https://hindsight.vectorize.io/get-cli | bash

No strict lockstep is required — the CLI is generated from the OpenAPI spec and tolerates version skew — but it can only use endpoints the daemon actually exposes, so a CLI older than the feature you want (your case) fails. Keeping the CLI at ≥ the daemon version is the safe rule.

Agreed on the docs gap: the local_embedded port-pinning recipe and the fs mount --api-url invocation are not documented today. Closing this as answered — please reopen or file an issue if pinning the port does not stick for you after a daemon restart.