* fix(embedding): keep one bad item from dropping its whole batch
A provider-side request error rejects an entire batch, so a single over-limit
item used to cost the vectors of every item beside it. QwenPaw #8040 shows two
poison chunks turning into exactly twenty lost vectors, while the backfill loop
still reported full success.
Retry a rejected multi-item request one item at a time so only the item that
actually fails is left without a vector. Single-item requests keep their
previous behaviour, and provider-level failures (429 / quota) keep using the
existing retry paths instead of being split.
Also make the backfill loop report what it actually filled, and name the failing
chunk ids in the final reindex error. `processed` counts attempts, so it claimed
success after a partial loss.
* fix(embedding): stop quota failures and transient item errors from multiplying
Review follow-up on the two P2 findings in #579:
* quota exhaustion no longer falls into the per-item split. The store now gives
up explicitly when the provider reports insufficient_quota, including after
the opt-in quota retries are spent, because no single item is to blame and
splitting only multiplied the rejected requests (3 items -> 4 requests).
* the per-item fallback goes back through `_call_with_retry`, so a 429,
connection error or timeout on an isolated item keeps the existing backoff
and retry policy instead of silently dropping that item's vector. A one-item
request still cannot split again.
Regression tests cover both findings: a quota failure stays a single request
with the default policy and with exhausted quota retries, and a transient
failure on one item of a split batch still ends with every healthy sibling
embedded.
python -m pytest tests/unit/test_local_embedding_store.py tests/unit/test_file_store_consistency.py -q
-> 83 passed, 41 skipped
* style(test): hoist the sleeps collector out of the transient-failure loop
CI / Python quality failed on d5dc9b2: the pylint hook reported
tests/unit/test_local_embedding_store.py:935:16:
W0640: Cell variable sleeps defined in loop (cell-var-from-loop)
`fake_sleep` closes over `sleeps` while the loop rebinds it on every
iteration. The collector is now created once before the loop and cleared
at the top of each iteration, which keeps the per-iteration assertion
(`assert sleeps == [1.0]`) exactly as strict and removes the loop-scoped
rebinding.
Verification (repo hook arguments):
pylint -> Your code has been rated at 10.00/10, exit 0
black --check --line-length=120 --target-version=py311 -> clean
flake8 --extend-ignore=E203 --max-line-length=120 -> clean
* fix(embedding): keep provider-wide failures out of the per-item split
Review follow-up on the P2 raised against 4d8a3c5.
`_call_with_retry` sent every unrecognized exception to `_embed_individually`
whenever the request had more than one item. Only rate limiting and
`insufficient_quota` were excluded, so a 401, a 403 or a 5xx still split a
ten-item request into ten extra single-item requests, none of which can
succeed: credentials, permissions and server outages are properties of the
endpoint, not of any individual input.
The split path is now gated on a dedicated classifier,
`_is_provider_wide_failure()`, which recognizes 401/403 and 5xx by status
code (with the OpenAI SDK class names as a fallback for exceptions that do
not expose one). Transient server errors keep their retry policy through the
existing backoff; the remaining provider-wide failures stop the loop and
report unhealthy, like the quota branch. Input-dependent rejections such as
the per-item context-length limit are unchanged and still isolate one item
at a time.
Regression coverage: test_provider_wide_credentials_errors_are_not_split_into_per_item_requests
(401/403 -> a single request of size 10) and
test_provider_wide_server_errors_are_retried_without_splitting
(500 -> batch sizes [10, 10, 10] with sleeps [1.0, 2.0]). The existing
context-length, quota, 429 and per-item transient-retry tests are retained.
Local verification, using the repo's own hook arguments:
pylint -> Your code has been rated at 10.00/10, exit 0
black -> 2 files would be left unchanged
flake8 -> clean
Classifier discriminator check (old vs new split decision, extracted from the
production file and executed):
400 context-length -> SPLIT / SPLIT
401, 403, 500, 504 -> SPLIT / NO-SPLIT
429 and insufficient_quota keep their own earlier branches.
* fix(embedding): retry SDK transport failures instead of splitting the batch
Third review follow-up on #579.
`_call_with_retry` only caught the built-in `TimeoutError`, `ConnectionError`
and `OSError`. `openai.APIConnectionError` and `openai.APITimeoutError` do not
inherit from any of them (they go APIError -> OpenAIError -> Exception), so
they reached the generic handler: `_is_provider_wide_failure()` did not
recognize them either, and a multi-item request fanned out into per-item
requests that failed for exactly the same reason. The same gap meant a
single-item request got no ReMe-level retry at all after a transport failure.
Transport failures are now recognized by a dedicated classifier,
`_is_transient_transport_failure()`, covering the built-in socket errors as
well as the SDK/httpx exception types (matched across the MRO, so subclasses
such as `APITimeoutError` are included) without importing the provider SDK.
They retry the original request with the existing backoff and never split; the
retry budget is unchanged.
Regression coverage:
- test_sdk_transport_errors_are_retried_without_splitting
APIConnectionError / APITimeoutError -> batch sizes [10, 10, 10], sleeps
[1.0, 2.0], then failure with no single-item requests.
- test_sdk_transport_error_recovers_without_losing_the_batch
one APITimeoutError then success -> [[1.0, 0.0]] * 10, batch sizes [10, 10].
- test_isolated_item_retries_an_sdk_transport_error
context-length rejection, then APIConnectionError on one isolated item ->
that item's vector is retained.
The existing context-length, 401/403, 5xx, quota and rate-limit tests are
retained.
Local verification with the repo's own hook arguments:
pylint -> Your code has been rated at 10.00/10, exit 0
black -> 2 files would be left unchanged
flake8 -> clean
Branch-order discriminator check (classifiers extracted from the production
file and executed against each error type):
case old new
400 context-length SPLIT SPLIT
401 / 403 SPLIT STOP
500 SPLIT RETRY
SDK APIConnectionError SPLIT RETRY
SDK APITimeoutError SPLIT RETRY
builtin ConnectionError RETRY RETRY
builtin TimeoutError RETRY RETRY
429 RETRY RETRY
insufficient_quota STOP STOP
* fix(embedding): treat 404 as a provider-wide failure too
Fourth review follow-up on #579.
The classifier added in c9448ae covered 401/403 and 5xx, but not 404. A missing
model or a wrong embedding route answers with 404 (SDK `NotFoundError`), which
no individual input can explain, so the batch still fell through to
`_embed_individually()`: a ten-item request against a bad model name produced
eleven requests, all failing for the same reason.
404 is now part of the provider-wide set (`_PROVIDER_WIDE_STATUS_CODES`) and
`NotFoundError` joins the class-name fallback. Like 401/403 it is not
transient, so the request is reported as failed once instead of being retried
or split. The context-length `400` is deliberately left out of that set: an
over-limit item is the one status a single input can explain by itself, so it
has to stay isolatable.
Regression coverage:
- test_provider_wide_statuses_exclude_input_dependent_bad_request
401/403/404/500 -> provider-wide; an over-limit 400 -> not provider-wide.
- test_provider_wide_not_found_errors_are_not_split
404 -> batch sizes [10], no sleeps, no single-item requests.
The existing context-length isolation, 401/403, 5xx, quota, rate-limit and SDK
transport tests are retained.
Local verification with the repo's own hook arguments:
pylint -> Your code has been rated at 10.00/10, exit 0
black -> 2 files would be left unchanged
flake8 -> clean
Branch-order discriminator check (classifiers extracted from the production
file and executed against each error type):
case old new
400 context-length SPLIT SPLIT
401 / 403 SPLIT STOP
404 NotFoundError SPLIT STOP
500 SPLIT RETRY
SDK APIConnectionError SPLIT RETRY
SDK APITimeoutError SPLIT RETRY
builtin ConnectionError RETRY RETRY
builtin TimeoutError RETRY RETRY
429 RETRY RETRY
insufficient_quota STOP STOP
* fix(embedding): classify every provider status shape and split only input errors
The per-item fallback still multiplied service failures into one request per item.
Both gaps come from the fallback this PR adds, so they are fixed here.
Status extraction
- `_http_status()` reads the status from `status_code`, an integer `code` (Google GenAI
exposes the HTTP status there), `response.status_code` (httpx-style wrappers), and the
structured `status_code` embedded in the message (AgentScope's DashScope embedding turns
every non-200 response into a plain `RuntimeError`).
- Only integers are read from `code`. A string `code` names an error
(`insufficient_quota`, `rate_limit_exceeded`, `InvalidApiKey`); reading it as a status
would misclassify quota and rate-limit errors.
- `_is_provider_wide_failure`, `_is_transient_provider_failure`, `_is_rate_limited` and
`_is_input_dependent_failure` all classify through it.
Splitting
- The generic fallback splits only when `_is_input_dependent_failure()` matches: a
context-length rejection, the one error a single over-long item explains by itself.
Anything unrecognized is provider-wide and is never answered with one request per item.
- This narrows the isolation this PR adds. An input-dependent error that carries neither a
status nor an input-length signal is no longer split, so it costs its batch instead of
multiplying the requests. Erring towards the batch keeps one provider failure from
becoming N failures and losing the healthy vectors anyway.
- `_embed_individually()` drops the redundant `len(single) == 1` check: the
`_call_with_retry([text])` contract only returns a result of the expected length.
Verified against the real exception classes: `google.genai.errors.APIError.code` is an
`int`, and a real DashScope response yields a `RuntimeError` whose message carries
`"status_code"`. Regression coverage uses the real classes when available and mirrors
their shape otherwise.
* fix(embedding): stop per-item isolation on a provider-wide failure and read serialized codes
- `_embed_individually` now stops asking for the remaining items as soon as one isolated
item fails provider-wide (credentials, missing model, exhausted quota, exhausted
transient retries). No remaining input can explain that failure, so continuing only
multiplies the rejected requests. The vectors already recovered are kept and the items
that were never answered stay `None`.
- `_call_with_retry` reports that outcome through an optional `terminal_failure`
out-parameter, so its return type and every existing call site stay unchanged.
- `_error_code` reads the business error code from the attribute, the structured body, or
the serialized message. AgentScope's DashScope embedding raises a plain `RuntimeError`
with the response embedded in the message, so a quota error was classified as a rate
limit and never used the configured `quota_retry_delay`.
Regression tests cover both halves of the isolation boundary (a provider-wide failure
stops the loop; an input-dependent failure does not) and the serialized DashScope quota
path with quota retries enabled.
* fix(embedding): treat an input-length 413 as a per-item rejection
* fix(embedding): keep the health state after a partial success
`_compute_batch()` set `is_healthy = True` whenever the batch produced at least one
vector. Per-item isolation can recover an early item and then meet a provider-wide
failure (exhausted quota, authentication, exhausted transient retries), which
`_call_with_retry()` correctly records as unhealthy before it stops. The recovered
vector then overwrote that state, so a request that ended in an outage reported the
provider as healthy.
The terminal-failure flag is now threaded from `_embed_individually()` back to
`_compute_batch()`. The vectors recovered before the failure are still returned and
cached; only the health state now follows the failure. This matters because
`LocalFileStore._recover_after_real_request()` schedules missing-vector backfill off
the unhealthy-to-healthy transition: a hidden outage would either trigger backfill
while the provider is still unavailable or suppress a later genuine recovery.
Adds a regression test through `get_embeddings()` that checks both the retained
partial vector and the final unhealthy state. The existing isolation test covers
`_call_with_retry()` directly, so it never saw the overwrite.
* fix(embedding): leave provider 5xx retries to the layers that own them
A store-level retry for a provider 5xx stacked on top of the retries the
embedding wrapper and the provider SDK already perform, so a batch the SDK
answered after 12 attempts became 36. Retry ownership stays with those
layers; the store answers a provider-wide 5xx once and gives up.
Transport failures keep their retry because they describe a connection that
no lower layer has reported, and the opt-in quota policy is untouched.
Tests updated to pin the new boundary: a 503 is answered once for the
OpenAI-shaped, Gemini-shaped and DashScope-shaped errors, while a 429 keeps
its retry from the rate-limit branch.
* fix(embedding): make transport retry ownership explicit
The store retried a connection failure or a timeout on top of the embedding
wrapper and the provider SDK, which already retry both, so a persistent
timeout on a batch reached the provider 36 times instead of 12: the OpenAI
model retries a batch max_retries + 1 times and the SDK retries each of those
attempts.
Transport failures stay provider-wide -- the request is never split per item
-- but the retry is now owned explicitly instead of implicitly:
* a whole-batch request leaves it to the layers below, which already retry it;
* an isolated single-item attempt keeps the store's backoff, because that
attempt is the last chance to keep the one vector the isolation step is
recovering.
Rate limiting is unchanged. The transport cases now pin both budgets, and
three tests drive a real OpenAIAsEmbedding wrapper and a real
openai.AsyncClient over an httpx.MockTransport, so the provider attempt count
is measured rather than assumed.
* fix(embedding): check the failing error against the provider retry policy
* fix(auto-memory): serialize session transcript writes per session
_save_session_messages ran its read-merge-write on the per-session
JSONL transcript without any lock. Concurrent HTTP requests saving the
same session could interleave: two writers both appending against a
stale snapshot write overlapping history twice, and an append racing
a full rewrite can be overwritten by the rewriter's stale merge,
losing messages.
Hold get_path_lock(path) across the whole read, merge, and write,
consistent with the existing session image handling in the same file.
Merge, ordering, and can_append logic are unchanged.
Add deterministic regression tests that gate one writer's read between
snapshot capture and write: concurrent appends must merge disjoint
messages in created_at order, and an appended message must survive a
concurrent full rewrite. Both tests fail without the lock.
Closes#622
* test(auto-memory): make session-lock regression tests deterministic
Replace fixed sleeps with explicit synchronization: a shared operation
log records lock/read/write progress per writer, and writer A holds its
post-read pause until writer B is queued on the transcript lock. The
tests now assert the serialization order from the log (B reads only
after A's write completed) in addition to transcript content, so they
no longer depend on IO timing.
Also fix pylint findings from CI: use from-import for the auto_memory
module and drop unused tmp_path parameters.
* fix(agent_wrapper): release Codex threads after each turn
Loaded Codex threads and their per-thread MCP server subprocesses were
never unloaded from the app-server, growing file descriptors and child
processes monotonically until the wrapper was closed (fd exhaustion,
os error 24). Reply, streaming reply, and compact_session now
unsubscribe the thread in a turn-scoped finally block by default; the
new release_threads=False option restores the previous behavior.
Unsubscribe failures are logged and never break the turn, and threads
remain resumable after being unloaded.
Closesagentscope-ai/ReMe#609
* fix(agent_wrapper): keep tool-context guard on failed release and cover stream startup
A failed thread/unsubscribe left the thread loaded in the app-server
but dropped its tool-context entry, so a later resume with changed
tool_context_id or injected_job_kwargs would silently bypass the
constraint check. Keep the guard entry unless the unsubscribe request
succeeds.
reply_stream now releases the thread from an outer try/finally scoped
right after _open_thread, so threads are also unloaded when turn/start
raises or the caller is cancelled while awaiting it.
* fix(search): accept CLI queries that look like numbers
The CLI parses key=value arguments into typed values, so query=404 reached the search steps as an int and failed on .strip(), and query=NaN or query=Infinity became non-finite floats that the HTTP client cannot encode as JSON and the MCP client sends as null.
Read the query as text in the four search steps, as ChatStep already does, and keep values that float() reads as NaN or infinity as strings.
* fix(search): treat only a missing query as empty
str(query or "") turned query=0 and query=0.0 into an empty string, so those searches still failed with "query cannot be empty". Check for None before converting instead.
The BEAM and LME plugins replace the default search job with their own SearchV2Step, which still called .strip() on the raw value, so query=404 raised AttributeError when either plugin was enabled. Read the query the same way there.
The numeric-query test is now parametrized over the six steps and passes 404, 0 and 0.0 through parse_kwargs first.
* docs(operations): explain that reindex cannot refresh stale chunks
#524 reports that persisted chunks survive a chunker change and are never
re-chunked. Maintainers closed#528 with the position that automatic
invalidation stays out of scope and the recovery path is to clear derived
state and let the watchers rescan, but that path was only described in the
issue thread. The operations guide already warned that reindex does not
rechunk; add the missing half: reindex reuses stored chunks as-is, so a
chunker change requires the re-chunk recovery instead.
* docs(operations): narrow recovery scope and stop the service before cleanup
Review on #585: moving the whole metadata/ tree makes the resource
watcher treat existing resources as newly added, which can update daily
notes - so 'source files are never modified' was too broad, and the
cleanup should target only the affected store's derived state while
preserving unrelated catalogs. The recovery sequence now also stops the
service before moving anything, so shutdown persistence cannot write the
old in-memory state back over the cleanup.
The reindex paragraph drops the repeated 'does not rechunk' explanation
and focuses on when a rebuild from source is needed. English and
Chinese pages stay symmetric.
* docs(operations): simplify rechunk recovery guidance
---------
Co-authored-by: jinli.yl <jinli.yl@alibaba-inc.com>
* fix(stat): put mtime in the answer where the job description promises it
The ``stat`` job is advertised to agents as "Stat path (size, mtime, exists,
is_dir, is_file)", but the answer only ever carried the path, type and size —
``mtime`` lived solely in metadata, and MCP returns only ``response.answer``.
So an agent asking how fresh a file is got no answer, even though the tool
description told it the field was there.
Render mtime in both branches of the answer:
stat: topics/n.md (file, 20 bytes, mtime 2026-09-21T15:50:52.880316)
stat: topics (dir, mtime 2026-09-21T15:50:52.880316)
The value is hoisted into a local so the answer and ``metadata["mtime"]`` are
guaranteed to come from the same ``stat()`` call rather than two reads. The
module docstring claimed the agent receives "size, mtime, mime type, and ...
frontmatter"; it now states that size and mtime are in the answer while mime
and frontmatter stay in metadata, matching reality.
Metadata is unchanged, so programmatic consumers see no difference. This is
the same answer-completeness class as #564, found while auditing which
advertised job fields actually reach the LLM.
* docs(stat): say which consumers actually see mime and frontmatter
Review feedback on #566: the module docstring told the agent it gets
"mime type and ... the parsed frontmatter alongside in metadata", which
reads as though an agent can use those fields to decide whether to
download or parse a file. It cannot: the MCP service returns only
`response.answer` (`mcp_tools.py` -> `return response.answer`), so
`metadata["mime"]` and `metadata["frontmatter"]` reach direct `Response`
consumers but never an MCP caller.
Spell the split out instead of implying one audience: the answer carries
path, type, size and mtime, and an agent that needs the frontmatter has
to read the file rather than stat it. The envelope description below is
unchanged, since it already lists the full metadata shape.
* fix(reindex): return a readable summary so Studio stops showing a placeholder
`ReindexStep` assigned the store's report dict straight to
`response.answer`. ReMe Studio's settings panel already anticipates a string
answer:
typeof result.answer === "string" && result.answer ? result.answer : t("indexRebuilt")
(`reme_studio/app/settings-center.tsx`), so with a dict answer that branch was
unreachable and every rebuild reported the generic "index rebuilt" text. The
operator never saw which scopes ran or how many entries each indexed.
Render the report as one summary line — `Reindexed scope=all: bm25=7,
embedding=5, tag=2` for the composite scope and `Reindexed scope=bm25: 3
indexed` for a single one. The report itself still lands in metadata, so
programmatic consumers are unaffected, and Studio needs no change because its
string branch now fires.
`reindex` is the only answer-carrying consumer of this step; no test asserted
the answer content, only metadata, so nothing else moved.
* chore(reindex): tighten the renderer and deduplicate the summary test
Review on #565: the helper's docstring carried the Studio background
that already lives in the PR description; the intermediate per_scope
dict collapses into the join generator; and the all-scope delegation
test now uses distinct counts (7, 5, 2) so it alone pins both the exact
summary answer and the full metadata report, replacing the overlapping
summary test.
* refactor(reindex): share summary return formatting
---------
Co-authored-by: jinli.yl <jinli.yl@alibaba-inc.com>
* feat(integrations): add native Claude Code and Codex memory plugins
* docs(integrations): make plugin installation the coding agent entry point
* feat(integrations): configure plugin connections from user settings
* refactor(codex): use MCP tools and native plugin settings
* fix(codex): restore plugin hooks on current runtimes
* docs(codex): expand setup guide and reserve screenshot slots
* feat(codex): add configurable memory consolidation and status
* feat(codex): merge connection checks into a tabbed status app
* docs(codex): diagnose blocked status panel sandbox loading
* fix(codex): simplify status panel layout for narrow cards
* docs(codex): focus guides on connecting and using ReMe
* docs(codex): specify validated CLI and desktop version requirements
* feat(codex): add ReMe branding to plugin icons
* docs(codex): prepare manual screenshot workflow
* fix(codex): simplify ReMe status layout and activity
* docs(codex): explain Hook loading and local project context
* fix(codex): keep status refresh clear of host close control
* fix(codex): retain status resources for active MCP connections
* docs(codex): add real desktop screenshots to usage guides
* fix(integrations): address memory capture and consolidation review
* fix(codex): preserve capture endpoint during background delivery
* docs(skills): include image suffixes in the resource watcher list
The default resource_watch_loop has watched image suffixes since #526 and
auto_resource renders them into caption cards, but the skill still listed
only the seven text types. An agent reading the skill would conclude that
images dropped under resource/ are never processed.
* docs(skills): clarify image captioning requirements
---------
Co-authored-by: jinli.yl <jinli.yl@alibaba-inc.com>
benchmark.yaml's python_execute job advertised a `timeout` parameter, but
`timeout` is one of the CLI's client-selection kwargs (reme/reme.py pops it
before the payload is sent), so `reme python_execute code=... timeout=300`
never delivered the timeout to the job. The value silently became the HTTP
client's request timeout while the subprocess kept the 60s default, so
benchmark code that needs longer was killed at 60s with no hint why. HTTP
and MCP callers were unaffected.
Rename the parameter to `python_timeout`, mirroring how the shell job
already avoids the same collision with `shell_timeout`. The step prefers
the new name and still accepts the legacy `timeout` context key so
existing benchmark configs keep working. A new guard test fails if any
job in reme/config/*.yaml or a plugin plugin.yaml declares a
client-reserved parameter name again.
* fix(docs): publish OpenClaw and Hermes integration figures
The generated /en/integrations/openclaw, /zh/integrations/openclaw and
/en/integrations/hermes pages are built from the plugin READMEs, which
reference local figures/. Only the dsh and Studio READMEs had their
./figures/ links rewritten to site paths and their figure directories
copied into the build, so every screenshot on those three pages resolved
to /<language>/integrations/figures/*.png and 404'd. verify-build.mjs
only checks <a> links, never <img> sources, so the build stayed green.
Mirror the dsh pattern: rewrite the figure links to /figures/openclaw/
and /figures/hermes/, copy both figure directories into public/figures/,
add the missing language-cross link for the Hermes page, and cover all of
it in the generated-content tests.
* ci(docs): watch the new integration figure directories
The figures this PR adds under integrations/hermes_agent/figures/ and
integrations/openclaw/figures/ were not in either docs workflow's path
filter, so a follow-up commit that only touches a PNG would skip the docs
build and the broken-reference tests. Add both globs to the pull_request
filter in ci-docs.yml and the push filter in deploy-docs.yml, matching how
integrations/dsh/figures/** and reme_studio/figures/** are already listed.
Requested in review on #586.
* test(docs): validate all integration screenshot references
---------
Co-authored-by: jinli.yl <jinli.yl@alibaba-inc.com>
* feat(docker): add container deployment and multi-platform release workflow
* fix(llm): initialize providers on model access and preserve runtime injection
* test(llm): keep rejected model updates independent of credentials
