Raven-1/scripts/README.md
Kendrick-Song dca779640a feat(*): add hermes as a cold-start import source (#264)
## Summary

Adds Hermes as a cold-start import source, alongside the existing Claude
Code
scanner, across three kinds of data.

**Memory files.** `MEMORY.md` and `USER.md` are discovered through the
same
profile resolution Hermes itself uses (`HERMES_HOME`, then
`active_profile`
redirecting to `<root>/profiles/<name>`). `USER.md` entries are
additionally
mirrored into the native `user_memory/profile/user.md`: six host
consumers
(Curator, Personalizer, four Sentinel producers) read that file directly
and
never see EverOS-only content. An LLM picks each entry's H2 heading;
every
failure path lands the entry under `## Notes`, which injection always
includes,
so a misclassification costs tokens rather than visibility.

**Conversations.** Sessions are enumerated by shelling out to
`hermes sessions export --dry-run`, whose listing is capped at 100 rows.
The
scanner walks time windows until every session is covered rather than
silently
importing the first 100. Only ended sessions are candidates, and
`reopen_session()` can clear `ended_at`, so the window reconciliation
documents
the resulting race in both directions instead of assuming monotonicity.

**Skills.** Provenance is classified from on-disk evidence -- the
`.bundled_manifest` name-to-md5 map, `.hub/lock.json`, and `.usage.json`
-- with
a `package_hash` byte-identical to Hermes' own `_dir_hash`, so a skill
still
matching its factory content is left alone and only user-authored or
curator-managed skills are copied into the local skill pool. Skills
never travel
as ScanResults, so the menus, the confirm line and the final summary all
state
the skill count explicitly; without it a run that installs 12 of 82
reads as
having dropped 70.

Failure isolation: `scan_all` now reports a failing scanner through an
`on_error` callback and keeps the other platforms' results, and a Hermes
run
whose conversations cannot be enumerated still returns its memory files.

Two pre-existing defects found while working here are fixed in the same
branch:
a multi-line recall hit escaped its bullet in the context segment
renderer, and
a recalled EverOS profile was rendered as a Python repr and left
uncapped.

Also in this branch, from hands-on testing of the finished flow:

- `raven import run` could never reach its interactive path. The
selectors
called questionary's synchronous `ask()` from inside `asyncio.run()`,
and
prompt_toolkit drives `Application.run()` through `asyncio.run()`, which
  raises inside a running loop. No test covered it: every case passed
  `--platform` and `--tier`, bypassing the selectors.
- Import outcomes now render as one block after the progress display
closes.
Printing them from `_build_and_run` sent them to this module's Console
while
onboard's live progress belongs to its themed Console, and Rich's Live
can
only hold back writes on its own console, so they landed mid-bar and
left the
  bar duplicated.
- The `import run` selectors use the shared prompt style and glyphs
instead of
questionary's defaults; onboard's foreground import gains the phase
reporter
it never had, so the multi-second USER.md mirror is no longer silent
behind a
  bar reading 100%.

The EverOS backend moves with it. Agent-track recall turned out to be
dead:
agent-track HYBRID fuses `agent_case` and `agent_skill` through a rerank
cross-encoder, and with no rerank provider the server refuses the
request
outright, which `recall` catches and turns into an empty list against a
file-only logger. A live 1.1.3 probe returns `RuntimeError:
owner_type='agent'
with method='hybrid' requires a rerank provider`. The adapter now reads
`capabilities.rerank` from `/health` and asks for the LLM lane only when
the
cross-encoder is genuinely absent -- always sending it would make every
correctly configured user pay an LLM call per recall, never sending it
leaves
the track dead for anyone who skipped the optional rerank role in
onboard.

That capability is only readable from everos 1.2.1, so the pin moves
1.1.3 ->
1.2.1, skipping 1.2.0 (built from a branch missing the 1.1.4 fixes,
including a
knowledge-upload path traversal). Memory endpoints move to `/api/v2`,
canonical
since 1.2.0; `/api/v1` still resolves to the same handlers but is
documented as
a legacy alias. Only everos endpoints move -- the Skill Hub and
OpenRouter
clients have their own v1 surfaces.

That upgrade also broke an assumption Raven was making. "Server running"
and
"server can recall" used to be the same statement; 1.2.1 boots with
`[llm]` alone
instead of aborting, so a misconfigured provider answers 200 and quietly
serves
less. Raven decided a role was configured by reading model + api_key out
of
`everos.toml`, which cannot see that. Capabilities are now read from
`/health` at
all three points where it matters: the memory step (right after the
server it
already starts), `raven doctor` (which had no EverOS check at all), and
`backend.start()` -- the only one of the three on the path every session
takes,
which is where an expired key actually surfaces. It follows the
precedent already
set there for native Windows and prints to stderr rather than a log
nobody reads,
but does not drop to a no-op: writes still land, and `everos cascade
backfill`
gives those rows their vectors once the provider is fixed.

The same reading makes the embedding role genuinely optional. It was not
before:
recall sends no `method`, so it took the server default of HYBRID, which
everos
refuses without an embedding provider -- skipping the role produced a
memory that
stored everything and returned nothing. The adapter now asks for KEYWORD
when no
embedding capability is reported, searching the same rows lexically
instead of
semantically, and that also rules out the rerank fallback because
KEYWORD's agent
path never reaches the cross-encoder. So the wizard stops requiring
embedding and
states what each role buys before asking for it -- llm alone gets
keyword recall,
embedding adds meaning, rerank sharpens ordering -- and skipping
embedding is
reported in colour rather than dim, because skipping rerank costs
ordering while
skipping embedding costs semantic recall entirely.

Fault and degradation are now distinguished rather than lumped together:
only a
missing llm sets doctor's exit code, and `raven doctor` names what each
unconfigured optional role costs, per role, since "optional" alone does
not help
anyone decide. The wizard also stops asking whether to enable memory at
all --
everos is the only backend, so the question framed a choice that does
not exist,
and both of its answers were described wrongly (declining was said to
use "native
Markdown memory", which does not exist: `raven/plugin/memory/` holds
only everos,
and `ContextAssembler.owns_compaction` is a hardcoded True that stops
the
consolidator from ever updating user.md). Backing out is still possible
and now
states the real consequence in colour. The memory LLM field is
pre-filled with
the user's own main model rather than a recommended id, because a
recommendation
is only reachable if their key carries it.

Two rounds of review on this branch found defects worth naming, since
each was
invisible for the same reason -- no test covered the path:

- **Skills were copied before the run's own `Proceed?` gate.** The two
early
returns that install a skills-only import sit above it, so a machine
whose only
importable data is skills had directories copied before being asked
anything.
Both paths now name the count and ask; the wizard's `Start?` gate is
further
down still, so its two call sites ask as well. Every covering test
passed
  `--yes`, which is what hid it.
- **A cancelled run still ran both post-phases.** `run_import` returns
normally
once it sees the cancel file, so `raven import stop` halted the
conversation
loop and then started an LLM call per USER.md entry plus a full skill
copy.
- **Org-mirror skills were imported past a gate Hermes applies itself.**
Hermes
token-gates `_org/`: with no `.active_org` marker it prunes the whole
mirror,
and with one it descends only into the named org, so a stale mirror is
content
Hermes no longer loads. Discovery now mirrors that. Excluding `_org`
outright
would have been the opposite error -- it drops the active org's skills.
- **`doctor` and the wizard probed the default address.** Both took
`DEFAULT_EVEROS_BASE_URL` while the backend reads the configured
`base_url`, so
a user who moved everos off port 18791 was told it was not running -- by
the
  checks added to make a degraded server visible.
- **An unbuilt multimodal role was reported by nobody.** The
section-to-capability
  mapping had an entry both consumers skipped.
- **The USER.md progress line reached 100% before the last call.** Each
report
counted the call about to start; on a measured 9.4s run that left ~3s
sitting at
  100%, the exact symptom the phase reporter was added to remove.
- **Registry-name collisions were only checked within one run**, so a
name an
earlier import or the user's own skill already claimed produced the
invisible
  skill that `get(name)` never returns.
- **"All platforms" plus "run in background" could not work.** `import
run` has no
all-platforms flag, so the child reached its platform picker with
DEVNULL on
both streams and no terminal, after the wizard reported the import as
started.
  It now runs in the foreground and says so.

The e2e tests this branch made dead are fixed too: identity moved to the
host, so
`config={"agent_id": ...}` is ignored, and the agent-track test wrote
under the
services default while querying the tag -- `hits` was empty, its per-hit
assertions vacuous, and an `xfail` absorbed it. The plugin manifest
moves to
1.1.0, which the upgrade SOP in this same diff asks for.

Not in scope: Codex, KimiCode and OpenClaw remain placeholders;
cold-start
import stays an EverOS-only path with no native fallback.

## Type

- [x] Feature
- [ ] Fix

## Verification

```
uv run --all-extras pytest -q       5405 passed, 30 skipped, 13 deselected
uv run ruff check .                 All checks passed!
uv run ruff format --check .        873 files already formatted
make check-large-files              passed
```

Beyond the suite, the importer was run against a real Hermes install at
`--tier full`: memory files, conversations and skills all landed, EverOS
extracted agent cases from the imported conversations
(`quality_score=1.0` in
the server log), and a second run over the same data reported
`Submitted: 0, Skipped: 4`, confirming the checkpointing is idempotent.

The everos upgrade was verified against a live server holding real
imported
data: on 1.1.3 the agent track returns 500 and `/api/v2` returns 404; on
1.2.1
with this change the agent track returns an `agent_case` and the user
track is
unchanged at three episodes. Re-verified after killing the server and
cold
starting it, with the resolved binary printed to confirm which build
answered.
`raven doctor` and the wizard both report llm and embedding available
with
rerank absent against that server.

The suite was also run with HOME pointed at an empty directory, which is
how the
memory-probe and import-step tests were caught reading the developer's
own
configuration instead of their own fixtures. That pass also found the
test suite
waiting out `ensure_everos_server`'s 30s readiness timeout on every
machine
without a running server -- always, on CI -- which cost one file 34 of
its 35
seconds and is now stubbed.

The interactive flow was verified under a pty, comparing the two console
wirings directly, and each new assertion was mutation-tested: every
behavioural
change on this branch had its fix reverted and the covering test
confirmed red,
and only that test. Where a fix had a plausible wrong shape, that shape
was
mutated too -- excluding `_org` wholesale rather than token-gating it,
reporting
progress after the await instead of before, seeding the registry-name
check from
the pool without ordering it after the target resolution. Two of those
mutations
survived and were the more useful result: one showed a guard clause
could not
fire (`_target_for` only ever returns a path that does not exist, so
excluding it
from the pool lookup was dead code, now removed), the other showed the
wizard's
own confirmation sits below the returns it was supposed to cover.

- [x] Relevant tests pass locally
- [x] Relevant lint / type checks pass locally

User-facing docs are unchanged: this adds a platform to an existing
documented
command rather than a new surface. The developer docs move with the code
--
`docs/memory-plugin-architecture.md` (the everos pin, and the upgrade
SOP now
stating that a one-way migration belongs in the release notes) and
`scripts/README.md` (two deleted scripts).

## Risk

- [x] Security impact considered
- [x] Backward compatibility considered
- [x] Rollback path is clear for risky changes

The import writes to EverOS and to `user_memory/profile/user.md`, and
copies
skill directories into the local skill pool. EverOS has no delete
endpoint, so
an unwanted import is not undone by reverting this branch; the skill
copies and
the profile edits are plain files and can be removed by hand. Import
state
lives in `~/.raven/import_state.json` and can be deleted to start over.

Behaviour changes for existing users: the onboard wizard's import step
and
`raven import run` both look different (shared prompt style, skill
counts,
one summary block). `raven import run`'s interactive path changes from
"crashes immediately" to working. Rolling back restores the crash.

Three more, from the review round: a skills-only import now asks before
copying
(one extra prompt, skippable with `--yes`), an all-platforms import
chosen with
"run in background" runs in the foreground instead and says so, and
skills under
a stale `_org/` mirror are no longer imported -- Hermes does not load
them
either, but anyone who had them imported by an earlier build keeps them,
since
nothing here deletes.

Two consequences of the everos upgrade that operators need to know:

- **The index migration is one-way.** everos 1.2.1 migrates the LanceDB
schema
on first start and prunes older manifest versions, so once a machine has
run
this, its memory index can no longer be read by an older everos.
Reverting
  the branch does not undo it.
- **A missing provider no longer aborts startup.** 1.2.1 boots with
`[llm]`
alone. A misconfigured embedding provider used to fail loudly; it now
degrades
to keyword search, and rows written in that state carry no vector until
`everos cascade backfill` is run. everos itself only logs one warning
line,
which is why the wizard, `raven doctor` and `backend.start()` all
surface it --
the last of those runs every session, so an expired key is reported
rather
  than discovered.
- **Behaviour change for users who skip embedding.** Recall degrades to
keyword
matching instead of failing, and the wizard no longer stops them from
getting
there. That is the point of the change, but it means a user can now end
up with
  a working memory that is measurably worse at recall than the previous
  all-or-nothing setup would have allowed.

## Related Issues

N/A

---------

Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
2026-08-04 20:44:07 +08:00

1.7 KiB

Raven operational scripts

Standalone CLIs and admin utilities. Not part of the Raven wheel — these scripts are invoked directly from a checkout and don't ship to end users.

Layout

scripts/
├── README.md                     This file.
└── boxlite_cli.py                Direct CLI for the boxlite microVM library.

When to use

Script Purpose See
boxlite_cli.py Manage boxlite OCI images + VMs (pull / ls / create / start / stop / rm / shell). Independent of Raven — works even when no agent is running, can inspect VMs owned by another boxlite home. docs/sandbox/boxlite_cli.md

scripts/boxlite_cli.py is complementary to the raven sandbox sub-command group (in raven/cli/sandbox_commands.py):

  • raven sandbox … — agent-runtime debug interface (Unix-socket connection to a SandboxDebugServer inside a running Raven process; only sees VMs owned by that process).
  • scripts/boxlite_cli.py … — direct boxlite library CLI (manages images, creates / cleans up VMs, can target any boxlite home dir).

Use raven sandbox when you want to inspect / shell into the VMs your live agent is currently using. Use scripts/boxlite_cli.py for everything else (image management, post-mortem cleanup, cross-process inspection, Raven-not-running scenarios).

Where fixture generators live

Test / benchmark data generators are NOT in scripts/ — they live alongside the benchmark or test that consumes them. Examples:

  • benchmarks/skill_evals/fixtures/build_mock_library.py — synthetic SQLite mass-library DB for test_skill_forge_e2e.py and skill_evals/run_eval.py.