Skip to content

Merge upstream main (0.9.32, 0.9.33 and later fixes) into the fork - #4

Closed
GaryGTan-T2 wants to merge 92 commits into
mainfrom
merge-upstream-20261113
Closed

GaryGTan-T2 wants to merge 92 commits into
mainfrom
merge-upstream-20261113

Conversation

@GaryGTan-T2

@GaryGTan-T2 GaryGTan-T2 commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Brings upstream (rohitg00/agentmemory) main into the fork: 0.9.32 (2026-11-04), 0.9.33 (2026-11-09) and 16 later fixes, 91 commits since our base c6c476d. A merge rather than a rebase, so main's history and the two fork PRs (#1, #2) keep their commits; a rebase would hit the same badge conflict once per fork commit.

Conflicts: 37, all generated documentation (the test-count badge, "4,100+" here and "4,900+" upstream, in the READMEs, AGENTS.md, two SVGs and docs-sync.state.json); upstream's side taken, and npm run docs:sync afterwards changes nothing. Against upstream/main the merged tree differs only by the fork's two fixes (compress.ts, _fetch.ts, jsonl-parser.ts and their tests).

What upstream brings that matters here: CJK queries recall core observations again (rohitg00#1553); boot no longer races the state worker, and the keyword index retries instead of staying empty until a restart (rohitg00#1626, rohitg00#1627, rohitg00#1755); historical gaps in a partly embedded vector index are found at boot (rohitg00#1687); orphaned index generations are reclaimed (rohitg00#1256); the transport cap goes from 16 to 64 MiB and whole-scope reads page (rohitg00#1634, rohitg00#1636). Most of the rest is Windows, Docker, plugins and hooks we do not use.

Upgrade notes for our engine: the first start installs the pinned iii 0.25.1 (state 0.22.22, http 0.22.8), so it needs the network and an index backup first. An API key alone no longer turns on an LLM provider: production uses only embeddings (unaffected), but the LLM instance that recompress.py replays into needs AGENTMEMORY_LLM_PROVIDER=openai. GET /agentmemory/memories without limit can answer 413; the memsearch server only calls /search and /sessions with a limit.

Validation:

npm install --legacy-peer-deps && npm run build   ->  ok
npm test                                          ->  Test Files 362 passed | 4 skipped; Tests 4926 passed | 7 skipped
npm run docs:sync                                 ->  0 file(s) updated

Review: no agy/Codex loop over upstream's 91 commits (upstream's own reviewed code); our part is the doc-conflict resolution, checked by docs:sync and the suite above. Say if a review round is wanted anyway.

Not deployed: production still runs fork main 75be70e. Rollout when wanted: back up index/, npm pack this branch into a new sandbox/npm-<version> (keeping the current one for rollback), stop the engine, swap, start, then check livez, a CJK and an English memsearch and the eval.

🤖 Generated with Claude Code

dmazhukov and others added 30 commits November 3, 2026 21:59
…#1598)

subagent-stop, post-tool-failure, task-completed, session-end and
truncateCaptureOutput, which post-tool-use applies to tool output, cut
captured text with slice(0, n). An emoji at the limit was split, and the
hook sent a lone high surrogate.

The cut now goes through truncateText, which steps back one unit when it
would land inside a pair, as stop.ts and the server-side truncation
already do. Text within the limit is unchanged.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…#1645)

* fix(sessions): skip session rows without an id in the sweep

isStaleActive did not look at id, so a stale active row without a string
id reached kv.get(KV.sessions, candidate.id). The engine rejects a
state::get with no key, the row was counted as failed, and since the sweep
can never abandon it, every hourly run reported success: false.

The sweep now skips rows without a non-empty string id, the same check the
sessions endpoint and memory_sessions apply.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

* test(sessions): drop the any casts from the id-less sweep test

The override matches mockKV's own get signature and the typed sdk.trigger needs no cast, so the new test follows the no-any rule in CONTRIBUTING.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

---------

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>
…hitg00#1615) (rohitg00#1622)

* fix(cli): verify compose daemon process identity during reconcile (rohitg00#1615)

Signed-off-by: pei711 <199601925+pei711@users.noreply.github.com>

* fix(cli): keep Compose state unless the recorded PID is a foreign process

Reconcile cleared the lifecycle state whenever the identity check did
not return a match, so a live daemon lost its record when ps failed or
its binary was replaced while REST was still unready. Identity is now
match, foreign or unknown, and the state is cleared only for a PID
whose command positively belongs to another process. Unknown keeps the
existing error and the saved state.

---------

Signed-off-by: pei711 <199601925+pei711@users.noreply.github.com>
Co-authored-by: pei711 <199601925+pei711@users.noreply.github.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…0#1641)

* fix(compose): render cmd-safe worker commands and canonicalized paths on Windows

* test(windows): keep compose evidence when the Windows smoke gate fails

* test(windows): run npm via npm-cli.js and record smoke step outcomes

* fix(compose): match daemon-reported file paths across platforms and provision the Windows smoke engine

* ci(windows): build with bash and smoke-test the packed tarball under cmd

* fix(compose): match 8.3 short paths when verifying the owned Windows project

The Windows smoke gate failed on the second start: Worker Compose reports
the project as \\?\C:\Users\runneradmin\...\worker-compose.yaml while the
CLI holds C:\Users\RUNNER~1\... (an 8.3 short name taken from TEMP).
Stripping the verbatim prefix and lowercasing is not enough, so the CLI
exited with "Compose daemon does not report the owned worker-compose.yaml
project".

sameComposeFile now falls back to realpathSync.native on Windows, which
expands short names, before it normalizes both sides. The POSIX branch
called realpathSync without importing it, so the ReferenceError was
swallowed and symlinked data directories never matched; it is now
imported. Tests cover the short-name match and a POSIX symlink.

* test(windows): assert status lists compose workers and bound smoke subprocesses

The status step wrote agentmemory status output but never checked it, so
the empty "Compose workers:" list from the Windows path mismatch passed
the gate. It now runs after the workers are ready and requires state,
http and agentmemory in the listing.

Also from review: spawnSync calls get a 15 minute timeout and the engine
download a 300 second cap, so a stalled step still records results.json;
the leftover-process probe excludes its own PowerShell process; and a
Windows run without --tarball fails fast with a clear message unless
npm_config_script_shell points at a POSIX shell.

* fix(compose): wait long enough for compose::down to stop every worker

On Windows Worker Compose cannot stop a worker gracefully, so each one
waits out the full 20 second stop_timeout before it is killed. With three
containers compose::down needs about 60 seconds, which is the fixed
timeout agentmemory stop used. The smoke gate showed all three containers
reach "stopped" while the CLI had already reported
"compose::down failed ... TIMEOUT" and exited 1.

The stop timeout is now one constant shared by the render and the CLI,
and the down call waits stop_timeout times the container count plus 30
seconds. A test keeps the two in step.
…ets (rohitg00#1642)

* fix(facets): remove facet tags on lesson deletes and observation forgets

Signed-off-by: xh123637 <3324733895@qq.com>

* fix(facets): treat replay-imported lesson_ ids as lessons in the liveness check

isLiveTarget only recognized lsn_ ids as lessons. Lessons imported by replay use stable lesson_ ids, so facets of a live replay-imported lesson were judged dead and swept by deleteFacetsForTargets. Widen the guard to both prefixes and add regression tests covering a live and a deleted replay-imported lesson.

Signed-off-by: xh123637 <3324733895@qq.com>

* fix(facets): fall back to memory liveness for lesson and observation ids

A lesson_ or obs_ id with no live lesson or observation was treated as
dead without checking the memory and semantic stores. Imports and mesh
sync keep record ids unchanged, so a live memory with such an id lost
its facets on lesson deletes, decay sweeps and forgets. The lesson and
observation lookups now only short-circuit to live, and the memory and
semantic check runs for every id.

* fix(facets): judge facet liveness per target type

A memory that shares an obs_ id kept the observation-typed facets of a
forgotten observation alive. Liveness now records the observation and
the lesson, memory or semantic record separately. Observation facets
follow the observation only; memory facets stay while either exists.

---------

Signed-off-by: xh123637 <3324733895@qq.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…hitg00#1651)

* fix(deploy): retain local embedding dependencies in Docker images

Keep optional runtime dependencies and reject images where Transformers cannot load. Prune foreign ONNX binaries and set ownership during COPY to avoid duplicate dependency layers.

Signed-off-by: mothieras <feigan47743@163.com>

* test(deploy): cover pruning across multiple ONNX ABIs

Signed-off-by: mothieras <feigan47743@163.com>

---------

Signed-off-by: mothieras <feigan47743@163.com>
…#1626)

* fix(search): keep retrying while the state worker registers

Boot rebuilds the keyword index before the state worker answers
state::list, and the first listings fail with function_not_found. The
rebuild then finished with an incomplete index, and the completion flag
was cleared in a finally, so nothing retried.

Eight attempts with a growing delay cover the ~21s the worker needs on a
cold start. Memories take the same path: a failed listing no longer
counts the index as complete.

Signed-off-by: Tyxiel <128870773+Tyxiel@users.noreply.github.com>

* fix(search): report the rebuild incomplete when memories cannot load

The memories listing used to be skipped silently, so a boot that lost every
memory still reported a completed rebuild whenever the sessions listing
worked. The flag now follows a failed memories listing.

Covered by a test that fails the listing eight times and asserts the
incomplete flag; it fails without this change.

Signed-off-by: Tyxiel <128870773+Tyxiel@users.noreply.github.com>

* fix(search): retry only while the state worker is not ready yet

The rebuild listings are awaited during boot. Retrying every error for
up to 70 s meant a failure that waiting cannot fix, such as a listing
over the frame cap, added over a minute to each boot before the index
was marked incomplete.

Retry only function_not_found and timeouts. Any other error marks the
rebuild incomplete at once. The warning now reports how many attempts
ran.

---------

Signed-off-by: Tyxiel <128870773+Tyxiel@users.noreply.github.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
* fix: wait for state worker functions before boot reads (rohitg00#1623)

Worker Compose reports the state worker ready when its process starts, but the engine registers state::get/state::list a fraction of a second later. Boot reads fail with function_not_found and are not retried, so the vector checkpoint never loads and the keyword index skips sessions.

Probe both functions with a bounded 15 s poll before the first boot read. The wait returns immediately once they are registered; a non-readiness error or the timeout proceeds with a warning instead of blocking startup.

Fixes rohitg00#1623

Signed-off-by: cbsincool <cbsincool@163.com>

* fix: bound state readiness probes with a per-call timeout

A probe that reaches the state worker but never answers could block boot for the worker's 180 s invocation budget before the 15 s deadline was checked. Give each probe its own 2 s invocation timeout; a stalled probe now returns not-ready instead of holding startup. Add a regression test.

Signed-off-by: cbsincool <cbsincool@163.com>

* chore: sync docs source file count

Signed-off-by: cbsincool <cbsincool@163.com>

* fix: bound probes by the readiness deadline and fail fast (rohitg00#1623)

Each probe now uses the smaller of 2 s and the time left before the 15 s deadline, so the overall bound holds even when a call stalls. If the deadline expires, exit through main()'s fatal path instead of continuing into one-shot boot recovery that would load an empty index and still report Ready; a supervised worker restarts with the state worker registered. Update the regression test to assert the remaining-budget timeout.

Signed-off-by: cbsincool <cbsincool@163.com>

* fix: retry probe timeouts and test the fatal readiness path

Retry per-probe timeouts, which also cover a connection that is still opening, within the readiness deadline. Move the fatal decision into assertStateReady so it is covered by a unit test; main still exits through its existing fatal path when the state worker never becomes ready, instead of continuing into recovery that would report Ready with an empty index.

Signed-off-by: cbsincool <cbsincool@163.com>

* fix: wait up to 120 s for state functions and say so while waiting

Reports on larger stores show the state worker registering its functions
more than 15 s after the agentmemory worker connects. A 15 s bound made
those boots exit and restart instead of waiting.

- Raise the default readiness bound from 15 s to 120 s.
- Print one warning when the first probe misses, so a slow boot shows
  what it is waiting for even without --verbose.
- Log the "ready after" line only when the probe had to retry.
- Add a test for a 90 s wait under the default bound.

---------

Signed-off-by: cbsincool <cbsincool@163.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
rohitg00#1658)

* fix(cli): retry slow iii probes and skip the install prompt on Windows

A cold first run of iii.exe after a reboot can take longer than the
3 s --version probe. The probe then returned null, startEngine treated
the installed engine as missing and opened the install prompt. Under a
hidden launcher (Task Scheduler, wscript, cmd /c) stdin is still a TTY,
so the prompt waited forever and port 3111 never opened.

The probe now retries once with a 30 s timeout when the first attempt
times out. Other errors still return null at once. On Windows the
launcher no longer prompts, because auto-install is unavailable there:
it goes straight to the installer path, which prints the manual steps
and exits.

* fix(cli): probe a timed-out iii binary only once per run

startEngine probes the same paths several times (fallback logging,
compatibility pick, the PATH mismatch message). With the 30 s retry, a
binary that hangs on --version could add over a minute of startup.

A path whose probe timed out on both attempts is now remembered for the
rest of the process and returns null at once. A successful install
clears the entry for the installed path.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): memoize iii probes per startup scan, not per process

The previous change kept a timed-out path rejected for the rest of the
process. A binary that answers later, for example on a second start
from doctor, was then skipped and the installer ran instead.

startEngine now opens a probe memo for its own scan and drops it when
the scan ends. Within one scan each path is probed at most once, which
still bounds the repeated 30 s retries. Every later scan probes again.
A successful install removes the installed path from the memo.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* test(cli): restore the closing brace lost in the main merge

The merge of main placed the reconcile identity test inside the Windows
prompt test, so cli-engine-startup.test.ts no longer parsed and every
test job failed. Close the Windows test before the next one.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): drop the log-only fallback iii probe loop

scanAndStartEngine ran iii --version on every fallback path only to
write a verbose log line, before pickCompatibleIii probed the same
paths again for selection. With the longer retry that loop could cost
up to 33 s per hanging fallback even when PATH already had a compatible
iii. The verbose log now lists the fallback candidates, and probing is
left to selection.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…itg00#1660)

* fix: allow slow state probes and time the readiness wait monotonically

- Raise the per-probe cap from 2 s to 10 s, so a state worker that
  answers slowly on a cold start passes instead of failing every probe
  until the deadline.
- Measure the deadline with performance.now, so a system clock step
  cannot end the wait early or stretch it.
- Report waitedMs as whole milliseconds.

* fix(search): retry connection resets and share one retry budget

- Retry ECONNRESET, ECONNREFUSED and EPIPE in the boot rebuild
  listings, so a connection that recovers within the window still loads
  memories and sessions.
- Give the memories and sessions listings one shared 70 s budget, so a
  state worker that stays down holds boot for 70 s at most, not 140 s.
- Drop the wall-clock assertion from the non-retryable listing test;
  the attempt count already proves one attempt.

* fix(search): time the listing budget with a monotonic clock

A forward step of the wall clock could spend the shared retry budget in
one jump and leave the rebuild incomplete. Measure it with
performance.now. The budget test now also checks that the sessions
listing gets one attempt after the memories listing spends the budget.

* fix(search): list both scopes before indexing and stop at the budget

- Run the memories and sessions listings before indexing memories, so a
  large memory store does not spend the shared budget and leave the
  sessions listing without retries.
- Stop retrying when the next backoff would reach the deadline, so the
  listings stay inside the 70 s budget.
…00#1663)

_resolve_project ran git rev-parse with the worker's stdin. In a Hermes
Kanban worker on Windows that stdin is the gateway control pipe with a
synchronous read pending, so the git child blocked, the 5 s timeout only
killed the launcher, and communicate() waited forever for EOF. Every
card stayed "running" with no model call.

The probe now passes stdin=subprocess.DEVNULL.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…tal (rohitg00#1666)

When the readiness timeout fires, the CLI asks Worker Compose for status.
If Compose has already marked the crashed worker failed, the CLI reports
that failure, including the worker's "could not create its API secret"
error, instead of the generic "not ready after 3s" text. Which message
wins depends on how fast Compose records the exit, so the scenario
failed on unrelated pull requests on both Linux and macOS.

The scenario now accepts either message. It still asserts a non-zero
exit and that the worker log holds the secret error.
The second-start step only rejected a timeout and the ownership message,
so any other startup error that exits 1 still passed.
…hitg00#1659)

* fix(mcp): hide and guard slot tools when AGENTMEMORY_SLOTS is off

The slot functions (mem::slot-*) only register when AGENTMEMORY_SLOTS
is "true", but mcp::tools::list advertised the six memory_slot_* tools
in every mode. Calling one triggered a missing function and the client
got a bare 500 with no hint about the flag.

tools/list now drops memory_slot_* while slots are disabled, and
tools/call answers a slot tool with the same 503 "Memory slots not
enabled" body the REST slot endpoints already return, so clients that
cached the old list get an actionable error.

* fix(mcp): match only registered slot tools and read the flag at startup

Three follow-ups to the slot tool gate:

- Only the six registered memory_slot_* names count as slot tools, so a
  misspelled name such as memory_slot_lsit still gets the Unknown tool
  response instead of the slots-disabled 503.
- The flag is read once in registerMcpEndpoints, the same moment the
  worker decides whether to register the mem::slot-* functions. Editing
  ~/.agentmemory/.env later no longer makes tools/list advertise slot
  tools that were never registered.
- The packed live-daemon test expected 54 tools from tools/list. It now
  derives the count from the registry without the slot tools, which is
  what a default daemon serves. README states the same.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(mcp): accept sourceIds on memory_lesson_save

The REST lesson endpoint and mem::lesson-save both take sourceIds, but
the memory_lesson_save MCP tool had no such field and its handler never
forwarded it. Every lesson saved over MCP was stored with an empty
source list, and the viewer then told the agent to re-save with
sourceIds, which it could not do.

The tool schema now lists sourceIds as a string array. The handler
runs it through normalizeLessonSourceIds, the same validator the REST
endpoint uses, returns the same 400 when it is invalid, and passes the
normalized ids to mem::lesson-save.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(mcp): allow an items schema in tool property definitions

The sourceIds array schema on memory_lesson_save declares items, which
the McpToolDef property type did not allow, so tsc reported an excess
property error. The runtime schema is unchanged.

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…artial reasoning (rohitg00#1495)

* fix(openai): fail on a reply cut at max_tokens instead of returning partial reasoning

When a reasoning model spends the whole max_tokens budget on reasoning, an
OpenAI-compatible API answers 200 with finish_reason "length", no content and
a partial reasoning field. The reasoning fallback returned that fragment as a
successful result, so compression stored chain-of-thought as the summary.

Throw a clear error for that case and keep the fallback for replies that
finished normally.

Signed-off-by: Rex57 <203883624+Rex57@users.noreply.github.com>

* test(openai): cover truncated reasoning in the provider and the packaged gate

Provider tests now cover a reply cut at max_tokens with null or empty content
and only reasoning or reasoning_content, through both compress and summarize;
replies that finished normally with reasoning only (the fallback stays); and
nonempty content, which is still returned even when finish_reason is
"length".

The packaged summary-recovery gate gains a truncated-reasoning-is-rejected
scenario. Its loopback model returns finish_reason "length", null content and
partial reasoning that parses as valid XML. Against the installed archive,
summarize returns success: false with the max_tokens error, the compression
is stored as failed (compression_failed), and the reasoning marker appears
nowhere in the export. With the provider change reverted, the scenario fails
because the partial reasoning is stored as the session summary.

Signed-off-by: Rex57 <203883624+Rex57@users.noreply.github.com>

* fix(openai): drop explanatory comments and the dash in the max_tokens error

The max_tokens error now reads as two sentences. The fixture and
provider comments are removed; the tests already describe the behavior.

* fix(openai): treat whitespace-only content as missing

A reply cut at max_tokens with whitespace-only content was returned as a
success, so the truncation error never fired, the fallback chain did not
try the next provider and the circuit breaker recorded a success.
Whitespace-only content now counts as missing, so it reaches the
max_tokens error, or the reasoning fallback when the reply finished
normally.

---------

Signed-off-by: Rex57 <203883624+Rex57@users.noreply.github.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…rohitg00#1256)

* fix(state): sweep index generations no manifest names (rohitg00#1115)

Before bucketed vector storage (rohitg00#1416), each index save wrote a new shard
generation under mem:index:bm25:bm25:<gen>:<n> or :vectors:<gen>:<n>, then
deleted the previous one only when its manifest read had succeeded. A failed
read stranded the whole generation (one production store held 162 such
shards, 339.4 MB). The legacy cleanup on main deletes only the shards a
legacy manifest still names, so these generations are never reached.

Add a one-time sweep that runs after the legacy cleanup on every load path
that completes. It lists scopes through state::list_groups (new
StateKV.listGroups), keeps every generation either legacy manifest names,
and deletes the shards of the rest. It deletes nothing when scopes cannot be
listed, a manifest read fails, a manifest names no generation, or a scope
under a legacy prefix matches neither generation format ever written.
Completion is recorded at mem:index:bm25/legacy:sweep only when every
delete succeeds, so a partial run retries on the next boot. Each delete and
the summary go through the existing index_persist audit.

The 4100+ test count updates come from docs:sync.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(state): drop explanatory comments from the orphan sweep

The tests and the pull request description cover the generation formats
and the safety rules.

* fix(state): keep the orphan sweep open while a manifest protects shards

The sweep wrote its completion marker even when a legacy manifest still
named some shard scopes. If those shards later lost their manifest, for
example after a vector migration whose shard delete failed, the marker
blocked every later sweep and they stayed on disk. The marker is now
written only when every candidate scope was an orphan; otherwise the
next boot looks again.

Generations are also read from every manifest descriptor that has a
scope, not only from descriptors that pass validation, so a malformed
descriptor still protects its shard.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…he graph (rohitg00#1260)

* fix(mcp): read graph stats from the snapshot instead of enumerating the graph

agentmemory://graph/stats listed every node and every edge in order to produce
four aggregate numbers. On a real corpus that is a multi-hundred-megabyte frame
over the engine transport, against the 16 MiB limit this repo already defines in
state/frame-guard.ts. Measured on a deployed instance: the two scopes hold
112 MB and 80 MB, five and seven times the limit, so the read cannot succeed —
it closes the worker connection with 1009 Message Too Big every time. The
observed rate was 3.8 to 5.1 kills per minute, each followed by a reconnect that
registers a fresh worker id.

The counts were already precomputed. KV.graphSnapshot carries totalNodes,
totalEdges, nodesByType and edgesByType in a single small key, and the comment
introducing it in state/schema.ts names /graph/stats as the caller it was built
to spare. This resource simply never adopted it.

An absent snapshot now reports zeros with pending: true rather than falling back
to enumeration. The fallback is the failure mode, so there is no version of it
worth keeping.

Other enumerating callers remain and need separate treatment: cascade.ts needs a
sourceObservationId index before it can stop scanning, and the export route in
api.ts guards its response size but not the inbound read that already happened.

* docs(mcp): drop what-narrating comments from the graph stats read

AGENTS.md coding standards forbid comments that explain what code does.
KV.graphSnapshot and the `pending: true` spread already say what the two
blocks were narrating, so they carried no information the names do not.

The rationale is not lost. The frame-limit failure mode and the deliberate
refusal to fall back to enumeration are both recorded in the parent
commit's message and in the PR body, which is where a reader looking for
why will go.

Comment-only: nine lines removed, none added, no executable statement
touched.

* fix(mcp): delegate the graph/stats resource to mem::graph-stats

The MCP resource hand-rolled its own snapshot read rather than calling the
function the REST path already routes to. GET /agentmemory/graph/stats goes
through api::graph-stats to mem::graph-stats, which has read the snapshot
exclusively since rohitg00#814 v2, so the inline kv.get duplicated the shared
function instead of avoiding an enumeration it never did.

Duplicating it also dropped behavior. readSnapshot() rejects a stored value
whose version is not 1; the inline read cast whatever was there to
GraphSnapshot and trusted it. The shared function reports fromSnapshot, and
when no snapshot exists returns a warning naming the snapshot-rebuild and
reset endpoints; the inline version invented `pending: true` for the state
the codebase already calls `fromSnapshot: false`. A snapshot marked dirty
carries an eventual-consistency warning the resource never surfaced.

The payload gains fields rather than breaking. mem::graph-stats returns
totalNodes, totalEdges, nodesByType and edgesByType on both of its branches,
and `pending` had no other reference in src or test, so nothing observed the
old shape. The viewer already consumes the richer payload over REST. The
try/catch fallback is unchanged: sdk.trigger throws when the graph functions
are not registered, the same case api::graph-stats wraps.

Adds the graph/stats case test/mcp-resources.test.ts never had. Against the
inline path it fails on each of its three assertion groups independently:
the counts come back zero, there is no warning, and `pending` is set.

* test(mcp): cover graph/stats index states and generation changes

Drive agentmemory://graph/stats over a real StateKV with the graph,
snapshot, and import functions registered. Assert the resource reports
the unavailable shape while the graph index is missing, building,
paused, pending a record, or blocked by a dirty snapshot, and reports
the current generation's counts after reset, replace import, and
snapshot restore. Every read asserts that no state scope is listed.

Replace the override test's pre-merge payload with main's mem::graph-stats
shape and assert the resource returns it unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(graph): read MCP graph stats from the index in the surfaces test

The resource now delegates to mem::graph-stats, so register the graph
functions in the rig. The rotated case reports index counts without
listing nodes, which the armed list hook proves. The legacy case has no
graph index and reports unavailable counts. Both observe a reset on the
next read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(docs): sync generated test-count badges

Output of npm run docs:sync after the merge and new tests: the test-count
badge and README counts move from 4,000+ to 4,100+.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(mcp): make the graph/stats restore case detect stale reads

Grow the live graph after the snapshot so the pre-reset generation has
different counts from the restored one, and cover the default merge
import alongside the replace import.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: record the docs-sync state for the merged tree

* docs: restore the documented counts to main's values

The earlier docs:sync ran on a half-committed merge and counted extra
functions and lines. A sync on the committed tree matches main.

* fix(mcp): report unavailable graph stats when the stats call fails

When mem::graph-stats rejects, the graph/stats resource returned zero
totals, which reads as an empty graph. It now returns the unavailable
shape mem::graph-stats already uses: null totals, available false,
coverage unknown, and a warning.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…ves the page short (rohitg00#1669)

* fix(search): rank scoped smart-search again when the first window leaves the page short

With a project or agent filter, smart-search over-fetches at most 300
hybrid results and filters them afterwards, so a few hundred stronger
rows from other projects or agents left the scoped page empty even when
matching rows existed.

When the filtered page is shorter than the limit and the search index
holds more entries than the first window, rank once more with a
1,000-candidate window. Unscoped searches, scoped searches that fill
their page and indexes the first window already covers keep a single
ranking call.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

* fix(search): keep first-pass scoped hits when the deeper ranking returns fewer

The scoped retry replaced the first-pass results outright. Graph
retrieval has its own time budget on each call, so a retry that loses
graph-only hits could return fewer results than the first pass. The
deeper ranking now leads, and first-pass hits it missed fill the rest
of the page.

* fix(search): keep first-pass hits when the deeper scoped ranking fails

A failure in the deeper scoped retry rejected the whole smart-search
call and discarded the results the first pass had already found. The
retry now logs the error and keeps the first-pass results.

---------

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…#1553)

* fix(search): restore CJK recall for core observation search

Three structural gaps made core search near-zero-recall for CJK users
(rohitg00#1539): the BM25 document never included the user's own words, query
entity extraction was ASCII-only, and the vector-embedded text left
concepts out.

- extractTerms: index source.userPrompt (capped at 2000 chars) and a
  bounded prefix of source.assistantResponse (1000 chars) so a query in
  the user's language can hit the record it came from
- extractEntitiesFromQuery: emit segmented CJK runs (>= 2 chars) via the
  existing segmentCjk so the graph leg fires for non-English queries
- vector embed text: share observationEmbedText (title + narrative +
  concepts) across every embedding site — observe (restore + synthetic),
  compress, remember, evolve (relations), and both migrate-vector-index
  rebuild phases — so concepts anchor non-English content in the vector
  leg
- COMPRESSION_SYSTEM: keep concepts in the user's language, bilingual
  when the observation mixes languages

The prompt directive's effect needs a live model to observe; the other
three are covered by red-to-green tests in the search-index,
query-expansion, compression-validation and vector-index-populate test
files.

Fixes rohitg00#1539

Signed-off-by: akushonkamen <akushonkamen@163.com>

* fix(search): keep concepts in rebuild and backfill embed text

Review follow-up to 3166caa: indexRecords (search.ts:404, :413) and the
keyword rebuild's backfill queue (search.ts:602, :633) still embedded
title + narrative/content. Those are the shared channels for
rebuildIndex, reconcileIndex, snapshot restore, replay and import
(rebuildIndex clears the vector index first), and the backfill queue
feeds embedBackfillJobs — so any cold-start rebuild or backfill would
have re-embedded the whole store without concepts, including records
that live writes had already embedded with the concept-aware text. All
four sites now go through observationEmbedText (whitespace-trimmed, so
records without concepts embed the exact text they did before), which
also makes the previous commit's 'every embedding site' claim true in
fact: the migrate-vector-index rebuild it cited has no production
caller (no src/ importer), while these search.ts channels are the live
rebuild paths.

Regression tests assert the concept-bearing text on both channels:
indexRecords via a recording embedding provider, and the keyword
rebuild via the returned backfill jobs.

Part of rohitg00#1539

Signed-off-by: akushonkamen <akushonkamen@163.com>

* test: adapt embed-text assertions to guarded vector add callback

* fix: index bounded conversation tool output for recall

Signed-off-by: Jacques L'Heureux <jm_lheureux@yahoo.com>

* fix(search): put concepts before the narrative in the embedding text

The embedding input is clipped at 16,000 characters. With concepts after
the narrative, a long memory lost its concepts, including the CJK terms
this change adds. Concepts now follow the title, and the parts are
joined without empty gaps.

* chore: remove code comments and issue references

---------

Signed-off-by: akushonkamen <akushonkamen@163.com>
Signed-off-by: Jacques L'Heureux <jm_lheureux@yahoo.com>
Co-authored-by: Jacques L'Heureux <jm_lheureux@yahoo.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
* fix: preserve original memory types in search responses

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* fix(search): keep compact search alive on a failed type read and align fallback type

- A rejected read of the stored memory while building compact results
  rejected the whole smart-search call. The read now falls back to the
  memoryType already on the ranked observation.
- Standalone fallback compact results now report type "decision", the
  same as daemon results, with the saved category in memoryType.

* chore: remove code comments and issue references

---------

Signed-off-by: reevesc88 <calum@ai1auslutions.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…#1647)

* fix: exclude unscoped memories from project-filtered recall

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* fix: refill recall candidates after project filtering

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* fix: bound recall refill work and cache loaded candidates

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* fix: reject directory orphans and skip unloadable recall hits

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* fix: stop filtering recall candidates after a full result batch

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* fix: reuse recall request work across candidate windows

* fix: preserve recall results through transient retrieval failures

Signed-off-by: reevesc88 <calum@ai1auslutions.com>

* chore: remove code comments and issue references

---------

Signed-off-by: reevesc88 <calum@ai1auslutions.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…g00#1671)

agentmemory doctor showed the Fix/Skip/More/Quit select for every
auto-fixable failure even with CI set or without a terminal. It only
avoided hanging because clack gave up on a closed stdin.

Doctor now prompts only when stdin and stdout are terminals and CI is
unset. Otherwise it reports each failure, skips the fix, and prints
one hint to run `agentmemory doctor --all`.
…itg00#1672)

* fix(cli): keep iii SDK debug lines out of status and stop output

agentmemory status and stop printed "[OTel] OpenTelemetry is disabled"
and "[iii] Worker registered with ID: ..." between their own lines. Both
come from console.debug in the iii SDK while the CLI's short-lived
Compose control client connects.

composeCall now silences console.debug only while that client runs and
restores it afterwards, also on error. Warnings and errors still print,
and worker processes keep their own logs and telemetry.

* fix(cli): restore console.debug after overlapping quiet calls

Two overlapping withQuietSdkDebug calls each saved the console.debug
they saw. When the first finished before the second, the second
restored the no-op and left debug output off for the rest of the
process. The guard now counts active calls, saves the original once,
and restores it when the last call ends.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(mcp): record why the stdio shim dies

The standalone MCP shim had no uncaughtException or unhandledRejection
handler. When it died, the client only saw the stdio transport close,
with nothing on stderr and no log file, so a crash looked the same as a
client-side transport bug.

The shim now installs both handlers before it starts the transport.
Each writes the kind, the stack and the pid to stderr and appends the
same line to mcp-crash.log in the agentmemory data directory, with
credentials in URLs redacted. It then persists the in-memory store and
exits 1, the same exit as Node's default.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(mcp): keep the crash log private and the store snapshot whole

- The crash log is created owner-only (0600, directory 0700), since
  exception details can hold sensitive values.
- reportFatal names the crash log only after the append succeeds, and
  says so on stderr when it cannot write the file. A failed stderr write
  no longer skips the exit callback.
- InMemoryKV.persist writes to a temporary file and renames it over the
  snapshot, so a crash mid-write cannot leave a truncated store. The
  previous snapshot stays when the write fails.
- Tests cover save-then-crash recovery of the local store, the file
  mode, the failed-write notice, and the kept snapshot.
- docs-sync state updated for the new source file.

* fix(mcp): keep the store snapshot private and report a written crash log

- The temporary snapshot is created with mode 0600, so the rename can
  no longer replace a private snapshot with a world-readable one.
- Tightening the crash log mode is a separate step after the append.
  A failed chmod no longer reports that the crash log was not written.

* fix(mcp): always run the crash exit path and write it synchronously

- The crash handlers call the exit callback in a finally block, so the
  store is still saved when formatting the crash reason throws.
- Fatal lines go to stderr with a synchronous write on fd 2, so they
  are not lost when process.exit runs right after on a full pipe.
- A failed chmod of the crash log is reported instead of ignored.

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…and listing (rohitg00#1664)

* docs(plugin): describe data capture, opt-in providers and privacy for the directory listing

Add plugin/README.md as the directory listing body. It states that the
agentmemory server must be installed and running, what the 12 hooks record,
where data is kept and for how long, what can leave the machine and only
after which setting, and how to view, export and delete data.

Update the config, hooks, architecture, rest-api and mcp-tools skills to
match the explicit provider opt-in (AGENTMEMORY_LLM_PROVIDER and
EMBEDDING_PROVIDER), the default-off context injection, the Bearer token
requirement and the data-changing tools. Remove the claim of a registered
post-commit hook.

Expand the privacy policy to cover the local store, the capture spool,
retention, remote backends, opt-in providers, and viewing and deleting
data. Update the README provider sections for AGENTMEMORY_LLM_PROVIDER.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(privacy): send nothing to an outside provider unless the user chooses one

A provider key in the environment no longer turns on LLM or cloud embedding
calls. LLM summaries, compression, consolidation and reflection run only when
AGENTMEMORY_LLM_PROVIDER names anthropic, openai, gemini, openrouter or minimax
and that provider's key is set. Cloud embeddings run only when
EMBEDDING_PROVIDER names the provider. A key without a choice prints the exact
line to add at boot, in `agentmemory status`, in `agentmemory doctor` and in
the viewer. FALLBACK_PROVIDERS applies only after a provider is chosen.
OPENAI_API_KEY_FOR_LLM is obsolete and removed.

The PreCompact hook prints stored memory only with
AGENTMEMORY_INJECT_CONTEXT=true, the same gate as SessionStart and PreToolUse.

Every hook resolves its URL and secret through one helper. Claude Code plugin
options (CLAUDE_PLUGIN_OPTION_AGENTMEMORY_URL and _SECRET) win over the
inherited environment, and a hook never sends a secret to a non-loopback
http URL; it sends nothing instead. The Claude plugin declares
agentmemory_url and a sensitive agentmemory_secret in userConfig and passes
them to the MCP bridge. The Devin manifest no longer forwards
AGENTMEMORY_SECRET.

Every MCP tool carries readOnlyHint, destructiveHint, idempotentHint and
openWorldHint annotations. The setup wizard writes AGENTMEMORY_LLM_PROVIDER
for the chosen provider. The plugin no longer ships post-commit.mjs, which no
plugin hook registers.

* docs(plugin): add the marketplace install line to the listing README

* fix(plugin): keep a custom server URL and write one provider line

- An empty agentmemory_url plugin option now falls back to
  AGENTMEMORY_URL, then http://localhost:3111. The option no longer
  carries a default, so it cannot hide a custom-port server. An empty
  secret option still never falls back to an inherited secret.
- The onboarding wizard removes every AGENTMEMORY_LLM_PROVIDER line
  before it writes the chosen one, so a repeated entry cannot keep the
  old provider active.
- The summary-recovery and reflection release gates name
  AGENTMEMORY_LLM_PROVIDER=openai, since a provider key alone no longer
  turns on LLM calls.

* test(plugin): expect no default on the agentmemory_url option

* fix(plugin): close the review gaps in provider hints, transport and docs

- Hooks send nothing to a remote http:// URL, with or without a secret.
  Only loopback and https:// URLs receive events.
- llmOptInHint stays quiet while the Agent SDK fallback is active, and
  both opt-in hints name the env file the daemon actually reads.
- embeddingOptInHint and the doctor check report a chosen cloud
  embedding provider whose key is missing.
- Choosing Skip in onboarding removes AGENTMEMORY_LLM_PROVIDER from the
  env file and from the current process, and says so if it cannot.
- agentmemory status labels a noop provider "LLM features off".
- memory_profile is no longer read-only (it writes a refreshed profile);
  memory_action_update is marked destructive (it overwrites fields).
- README, plugin README, skills and privacy page name the Agent SDK
  fallback as the second way content can reach an LLM, use the npx form
  for status, explain where Claude Code stores the secret, describe the
  URL option fallback, and add the Redis cleanup step.

* fix(hooks): drop, not spool, captures refused over remote http

A capture blocked by the https rule went to the local spool, and a later
drain could send it over plain http. captureObservation now drops it, so
nothing is stored for later replay.

Status also tells an unchosen embedding provider apart from a chosen one
whose key is missing.

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(cli): install the pinned iii engine on Windows

A fresh agentmemory on win32 exited with "Auto-install unavailable on
win32" because the installer only handled tar.gz assets through sh,
curl and tar. Windows assets are zip files.

The zip path now downloads the pinned asset with fetch, checks it
against the same pinned SHA-256 table as every other platform, and
extracts iii.exe into the private bin directory with System32 tar.exe,
falling back to PowerShell Expand-Archive. Both run without a shell.
A missing checksum still downloads nothing, and a mismatch deletes the
archive before any extraction.

* fix(cli): isolate concurrent Windows iii installs and honor proxies

- Each install downloads to its own archive name (pid plus random
  suffix), so two starts into the same bin directory cannot delete or
  overwrite each other's download before verification.
- Archive cleanup never throws, so a failed delete after a successful
  extraction no longer turns the install into a failure.
- When HTTPS_PROXY, HTTP_PROXY or ALL_PROXY is set, the zip is fetched
  with System32 curl.exe, which honors those variables on every
  supported Node version. Without a proxy the built-in fetch is used.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): stage Windows iii extraction and keep installs cancelable

- Extraction now writes into a per-install staging directory and moves
  iii.exe over the existing binary only after the staged copy exists,
  so a failed or partial extraction never destroys a working iii.exe.
- Install commands (proxied curl download, tar.exe, Expand-Archive)
  run through an async spawn with a kill timeout instead of
  spawnSync, so the startup Ctrl+C handlers keep running during a
  stalled download.
- Archives and staging folders left by earlier failed installs are
  removed once they are older than 15 minutes.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): point the Windows setup steps at the private bin folder

After a failed install the warning said to extract iii.exe into
%USERPROFILE%\.agentmemory\bin, while the Setup required box below it
still said %USERPROFILE%\.local\bin. Both folders are searched; the
setup steps now name the one the installer itself uses.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): stop install children on exit and report staging errors

- A running curl, tar or PowerShell child is killed when the CLI
  exits, so cancelling a start with Ctrl+C no longer leaves it
  downloading or extracting in the background.
- A filesystem error while creating the staging folder or running an
  extractor now returns an extract failure, so the spinner stops and
  the manual install steps are printed.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): wait for a spawned install child to close

The error handler resolved as soon as any child error fired. When a
kill failed on a child that was still running, the installer moved on
and removed the staging folder while the extractor kept writing, and
the exit-time kill was dropped. The runner now resolves from error
only when the child never spawned; otherwise it waits for close.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(mcp): save the store before stderr on the crash path

The crash handler wrote to stderr with a synchronous write on fd 2
before it saved the store. When the MCP host stops reading a full
stderr pipe, that write blocks, so the shim never saved its fallback
store or exited.

The fatal path now runs in this order:
1. Append the crash line to mcp-crash.log.
2. Save the store (persist).
3. Write the fatal line and notices to stderr as a best-effort async
   process.stderr.write. A blocked pipe can lose the line, but it can
   no longer stop the save or the exit.
4. Exit 1.

The crash log is also bounded and private before it is written:
- A log at or above 1 MiB is moved to mcp-crash.log.1 first.
- An existing log is set to 0600 before the append. If that fails, the
  line is not appended and stderr says why.

installCrashHandlers now takes { persist, exit, write, logPath } hooks,
and handleFatal exposes the ordered path for tests. Generated docs
counts are synced.

* fix(mcp): skip stderr on a Windows pipe and keep rotated crash logs private

- Node writes to a stderr pipe synchronously on Windows, so a host that
  stops reading a full pipe blocks the write and the event loop with
  it. A timer cannot fire during that block, so the fatal path skips
  stderr when stderr is a pipe on Windows. The crash line is already in
  mcp-crash.log and the store is already saved; exit(1) follows. On
  POSIX the pipe write is asynchronous and stays best effort.
- A crash log rotated to mcp-crash.log.1 is set to 0600.
- The source-text check for writeSync is replaced with behavior tests:
  a blocking-capable stderr is never written and exit still runs, and
  only a Windows stderr pipe counts as able to block.

* fix(mcp): keep a crash record when the log and stderr both fail

- When stderr can block (a Windows pipe) and mcp-crash.log cannot be
  written, the fatal path writes the line and the failure reason to a
  fallback file in the temp directory, so a crash still leaves a record.
- A rotation rename that finds the log already gone (ENOENT, another
  process rotated it) no longer skips the append.
- A failed chmod of the rotated log is reported instead of ignored, and
  the new crash line is still appended.

* fix(mcp): bound crash records and restrict the log before writing

- Each crash line is capped at 64 KiB (an oversized reason is cut and
  marked), and the log rotates when its size plus the new line would
  pass 1 MiB, so one large reason cannot overshoot the cap.
- The log is opened with mode 0600 and fchmod runs on the open
  descriptor before the write. If that fails, nothing is written and a
  notice says why.
- The temp-directory fallback goes through the same writer, so it is
  bounded, rotated, and made owner-only before each write.

* fix(mcp): write the whole crash record or fall back

- writeAll loops until the whole record is on disk. A write that stops
  making progress (disk full, file size limit) throws, so the record
  counts as not written and the fallback path can run.
- boundCrashLine stays within the byte budget even when the budget is
  smaller than the truncation marker.
…comments (rohitg00#1675)

- The header and section 1 name AGENTMEMORY_ALLOW_AGENT_SDK=true as the
  second way session content can reach an LLM.
- FALLBACK_PROVIDERS is ignored when zero-LLM is active, which includes
  the Agent SDK case the old wording got wrong.
- MAX_OBS_PER_SESSION is a hard per-session cap; later observations are
  refused, and only capture-worker refusals are parked as dead letters.
Mike-Animal-Counseling and others added 27 commits November 8, 2026 21:37
Signed-off-by: March <183773531+Mike-Animal-Counseling@users.noreply.github.com>
…e LLM provider (rohitg00#1588)

* fix(config): treat placeholder provider keys as unset when picking the LLM provider

Doctor reports keys such as sk-ant-... or your-key-here as missing, but
the daemon accepted any non-empty value. It picked a provider for a
placeholder and sent that string with every request, and a placeholder
GEMINI_API_KEY shadowed a real GOOGLE_API_KEY.

Move the placeholder rule from doctor into config, widen it to any value
ending in "..." as .env.example ships them, and apply it both to
provider detection and to the key each provider sends. OPENAI_API_KEY
keeps any non-empty value while OPENAI_BASE_URL is a plain-http address,
because local servers ignore it and the README tells users to put any
string there.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

* refactor(doctor): drop the placeholder strip now that provider detection skips placeholders

detectLlmProviderKind already treats placeholder keys as unset, so deleting them before the check changed nothing. The test title claimed the daemon disagrees, which is no longer true.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

* fix(doctor): pass OPENAI_BASE_URL to the per-key provider check

The plain-http exception for OPENAI_API_KEY depends on OPENAI_BASE_URL, so without it a local-server key like xxx was dropped and doctor reported the agent-sdk fallback while the daemon picked openai.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

* test(config): pin the empty key behind a plain-http base URL, both real Gemini keys and blank keys

The plain-http rule counts only a non-empty OPENAI_API_KEY, the Gemini provider prefers GEMINI_API_KEY without a warning when both keys are real, and a blank or space-padded key is not real; each had a surviving mutant.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

* test(config): pin an empty OpenAI key behind a plain-http base URL and a real key starting with x

An empty or blank OPENAI_API_KEY next to a plain-http base URL is not a key, and a real key such as xai-... is not taken for the xxxx placeholder; both had a surviving mutant.

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>

---------

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…itg00#1220)

* fix(hooks): scope pre-tool-use enrichment to the current project

Claude Code's PreToolUse payload carries no `project` field — only
session_id, cwd, tool_name and tool_input — but the hook read `data.project`
and nothing else, so it always POSTed /agentmemory/enrich unscoped and
mem::enrich searched the entire corpus.

On a machine with several active projects that injects the wrong project's
observations into this project's tool turns. Reproduced against a live
0.9.29 server: enriching src/functions/summarize.ts in the agentmemory repo
returned daily-momentum-rebalancer content (lib/engine/main.ts,
ReallocationDecisionSnapshot); the same request with a project scope
returned agentmemory content and zero cross-project matches.

pre-tool-use.ts was the only project-aware hook not importing _project.js —
the other eleven already resolve via hookCwd(data) + resolveProject(cwd).
Do the same here, keeping an explicit data.project as an override for hosts
that do supply one.

* fix(hooks): skip pre-tool-use enrich when project resolves empty

A root cwd resolves to an empty project name. Return before the enrich
request so the hook never sends an unscoped or invalid call. Drop the
explanatory comments, merge duplicate imports, and add a root-cwd
regression test.

---------

Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…ohitg00#1350)

* fix(providers): clear the circuit breaker failure count on success

recordSuccess only reset the counter when leaving half-open. In the
closed state a success left it untouched, and recordFailure only cleared
it when two failures were more than failureWindowMs apart. Under steady
load a provider succeeding ~95 percent of the time still tripped,
because each scattered failure landed inside the window opened by the
previous one.

Observed on a hosted proxy that returns the occasional 502: a handful of
real upstream errors produced a stretch of 1,119 consecutive
circuit_breaker_open fast-fails, and mem::compress reached 22,400 calls
against 15,086 failures. Almost none of those failures were the provider
being down.

Counts failures since the last success instead, and moves the thresholds
into config so a deployment behind a flaky upstream can widen them
without a rebuild. Defaults go from 3 failures / 30s recovery to 10 /
15s: three scattered failures is not evidence that a hosted LLM proxy is
unavailable.

After the change, on the same install: 8 genuine upstream timeouts, 0
fast-fails.

Adds a regression test that 100 calls at a 5 percent failure rate keep
the breaker closed, and one that a genuinely failing provider still
opens it.

This is a different mechanism from rohitg00#1259 and rohitg00#1277, which filter which
errors are counted as failures in resilient.ts; this fixes the counter
never being reset by success in circuit-breaker.ts. The three compose.

Signed-off-by: reddeye1337 <reddeye1337@users.noreply.github.com>

* fix(providers): keep the recovery deadline when a success lands while open

A request already in flight when another request opened the breaker still
reaches recordSuccess. Clearing openedAt there left the breaker open with
no recovery deadline, so isAllowed could never promote it to half-open and
the provider stayed down permanently. Successes in the open state are now
ignored.

Also stops a non-positive env override from silently selecting the legacy
3 / 60s / 30s fallbacks: safeParseInt returns 0 and negatives verbatim,
which CircuitBreaker rejects in favour of its own defaults rather than the
configured ones.

Both from review feedback on this PR.

Signed-off-by: reddeye1337 <reddeye1337@users.noreply.github.com>

* fix(providers): reset circuit breaker failure count on success

A success in the closed state left the failure count in place, so a
mostly healthy provider with scattered failures inside the window
eventually opened the breaker. Clear the count on every success
outside the open state, and ignore successes that land while open so
the recovery deadline is kept.

Drop the default threshold change and the new circuit breaker env
vars to keep this a minimal bugfix.

---------

Signed-off-by: reddeye1337 <reddeye1337@users.noreply.github.com>
Co-authored-by: reddeye1337 <reddeye1337@users.noreply.github.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…reaker (rohitg00#1277)

* fix(resilient): content filter rejections must not open the circuit breaker

Azure OpenAI Prompt Shields rejects prompts whose content merely looks like a
jailbreak attempt. For a memory system that compresses arbitrary tool output
this fires on ordinary material — measured against a gpt-5.4-mini deployment,
a SECURITY.md that only *describes* prompt injection is enough:

  400 {"error":{"code":"content_filter", "innererror":
       {"code":"ResponsibleAIPolicyViolation",
        "content_filter_result":{"jailbreak":{"detected":true,"filtered":true}}}}}

ResilientProvider counted every throw as a provider failure, so three filtered
observations inside the 60s window opened the breaker and the next 30s of
compressions failed with `circuit_breaker_open` — including all the
unproblematic ones. A single awkward file took a whole batch down.

A content filter rejection is a property of that one payload, not a health
signal about the provider, so skip recordFailure() for it. The call still
fails; only the blast radius changes. Verified end to end: five filtered
observations followed by a harmless one now yield five failures and one
successful compression, with no circuit_breaker_open in between.

Kept deliberately narrow. Arguably no 4xx should count toward the breaker,
but that is a larger behavioural change and the filter case is the one with
evidence behind it.

Signed-off-by: David Kaulig <13939481+dKaulig@users.noreply.github.com>

* refactor(resilient): trim the rationale comment to the non-obvious part

Review feedback on rohitg00#1277. The block restated the failure chain, which the code
and the linked issue already carry. What is not derivable from the source is
why these rejections show up at all: Azure Prompt Shields fires on ordinary
documentation, so they are frequent rather than exceptional — and that is the
whole reason for treating them separately.

Three lines now, pointing at rohitg00#1276 for the measurements.

Signed-off-by: David Kaulig <13939481+dKaulig@users.noreply.github.com>

* fix(resilient): require the rejection status, not just the filter code

Review feedback on rohitg00#1277: isPayloadRejection matched on message text alone, so
any error quoting `content_filter` or `ResponsibleAIPolicyViolation` was
excused from the breaker regardless of what actually went wrong.

That is reachable. OpenAIProvider formats failures as

  OpenAI API error (${status}): ${body}

and gateways echo upstream bodies. A 502 whose body quotes a filter rejection
therefore matched, so repeated gateway failures left the breaker closed —
exactly the outage the breaker exists to catch.

The status now has to agree. `(400)` is matched before the JSON body starts,
so the provider's own status counts and an echoed one does not; the filter
code is still required alongside it.

One existing assertion changed rather than being added to: the bare
`new Error("ResponsibleAIPolicyViolation")` case asserted that the code alone
was sufficient, which is the contract this commit narrows. It now asserts the
opposite, and a 400-shaped message covers what it used to.

Signed-off-by: David Kaulig <13939481+dKaulig@users.noreply.github.com>

* refactor(providers): drop comments from content filter breaker change

Remove explanatory comments and the issue reference per repo rules,
drop the unused vi import, and cover the openrouter error format.

---------

Signed-off-by: David Kaulig <13939481+dKaulig@users.noreply.github.com>
Co-authored-by: David Kaulig <13939481+dKaulig@users.noreply.github.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…0#1286)

* fix(health): report CPU as machine-relative, not single-core (rohitg00#1235)

process.cpuUsage() deltas are single-core time, so 2.44 cores of work
read as 244% while thresholds.ts treated 90 as 90% of the machine. Every
multi-core host tripped cpu_critical and /health returned 503. Divide by
os.cpus().length at the producer and record the divisor on the snapshot.

* fix(health): record the clamped cpu.cores divisor and cover the producer (rohitg00#1235)

Round-1 review findings: cpu.cores was storing the raw os.cpus().length
instead of the clamped divisor actually used, so an empty cpus() array
recorded cores:0 while still (correctly) dividing by 1 -- self-
contradicting telemetry in exactly the edge case the clamp exists for.
Clamp before assigning to coreCount in collectHealth so the stored value
and the divisor are provably the same number.

Also add a test that drives registerHealthMonitor/collectHealth end to
end with mocked process.cpuUsage()/Date.now()/os.cpus(), reads the
persisted snapshot back out of a mock KV, and asserts the normalized
percent -- verified to fail (500 vs 62.5) if the normalizeCpuPercent
call is bypassed, so removing the fix trips this test even though the
full suite would otherwise stay green.

* chore(docs): restore docs-sync source file count

The previous sync ran while the merge index still held conflict stages,
so it counted src files that were not real. Restore the count from main.

---------

Co-authored-by: Daniel Carmingham <15822947+DanielCarmingham@users.noreply.github.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(cli): preserve newlines in generated Compose values

Signed-off-by: zhichao-poper <zhichao.zhu@poper.co>

* test(cli): verify Compose C1 values with the pinned engine

Add an optional isolated integration test that delivers an unchanged generated
C1 scalar through iii 0.25.1 into a real worker. Clarify that hook timeout
settings belong in the hook process environment rather than the server file.

Signed-off-by: zhichao-poper <zhichao.zhu@poper.co>

* ci: run the Compose C1 regression in the release gate

Add the C1 worker round-trip suite to the existing Linux live-test command.
Require a pinned engine when live tests are mandatory, and fail clearly if
it is unavailable or live tests are explicitly disabled.

Validation includes an actual pinned-engine run and a missing-engine negative
control, plus the full build, generation, documentation and unit checks.

Signed-off-by: zhichao-poper <zhichao.zhu@poper.co>

* test(cli): harden Compose probe setup and dependency resolution

Resolve the public SDK package entrypoint instead of a checkout-local path.
Clean the temporary root even when setup fails before the child is spawned.
Clarify the hook timeout restriction in the env example as well as README.

Signed-off-by: zhichao-poper <zhichao.zhu@poper.co>

* fix(cli): escape line separators and publish the Compose probe snapshot atomically

Route U+2028 and U+2029 through the double-quoted Compose scalar path with
explicit escapes, so YAML 1.1 parsers cannot fold them into line breaks.

The live probe now writes its snapshot to a temporary file and renames it,
so the poll loop never reads a partially written JSON file.

Remove the code comments added in the yamlString helper and the live test.

---------

Signed-off-by: zhichao-poper <zhichao.zhu@poper.co>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(clip): use CLIP text tower for text embeddings

The generic "feature-extraction" pipeline instantiates the full CLIPModel
dual-encoder, whose forward pass requires both input_ids and pixel_values.
Text-only calls therefore fail with "Missing the following inputs:
pixel_values", which breaks every text entry point into the provider:
vision-search with queryText returns a 400 while image-to-image search on
the same store works fine.

Load the text tower with its projection head instead. That is the encoder
whose 512-d output shares the contrastive space with the image embeddings
already written by mem::vision-embed, so stored vectors stay comparable and
no re-embedding is needed.

Note that pooling: "mean" over the last hidden state would not have been
equivalent even if it ran: CLIP's joint space is defined by the projection
head, so mean-pooled hidden states would embed into a different space and
return meaningless cosine scores against image vectors.

Verified against Xenova/clip-vit-base-patch32 (dtype q8): text embeddings
come back 512-d and L2-normalized, and a red-square fixture scores 0.3229
against "a red square" vs 0.2539 for "a blue circle".

Fixes rohitg00#1249

Signed-off-by: anhtahaylove <everest.kill1@gmail.com>

* refactor(clip): tighten text-tower comment to the why

Address review: repo guidance bans comments explaining what code does.
Keep the rationale (dual-encoder demands pixel_values, projection head
shares the image space) and drop the mechanical description.

Signed-off-by: anhtahaylove <everest.kill1@gmail.com>

* test(clip): pin the text tower's caching, padding and shared space

The existing tests cover the load path. These cover what the fix has to
keep true afterwards: the tower is built once rather than per call, a
batch is padded into one tensor, and text and image vectors come back
the same length and normalized — the property cross-modal search needs.

Also asserts a non-ERR_MODULE_NOT_FOUND failure keeps its own message
instead of being reported as a missing package.

Reverting to the feature-extraction pipeline fails six of the nine.

Signed-off-by: anhtahaylove <everest.kill1@gmail.com>

---------

Signed-off-by: anhtahaylove <everest.kill1@gmail.com>
* fix(connect): honor CLAUDE_CONFIG_DIR for Claude Code

Resolve detection, user MCP configuration and hook settings from Claude Code's configured directory. Preserve the legacy locations when the override is unset or empty.\n\nValidated custom-path regressions and native MCP/hook execution with Claude Code 2.1.319. Full suite: 4497 passed, 6 skipped.

Signed-off-by: mothieras <feigan47743@163.com>

* fix(connect): resolve Claude paths after env hydration

Read Claude Code paths when the adapter detects or installs a profile,
after the CLI hydrates AgentMemory's env file. Use the same resolver
for hook installation.

Add regression coverage for late overrides, default and custom env
files, and shell-over-file precedence through the built CLI. Include
the generated test-count updates required by docs:sync.

Validation: build, skills and docs checks pass; 4501 tests pass with
6 skipped. Native Claude Code 2.1.319 connects through MCP and runs
the lifecycle hooks with the connector profile supplied only by .env.

Signed-off-by: mothieras <feigan47743@163.com>

* docs(connect): clarify Claude hook paths in all READMEs

Document the custom settings path selected by a non-empty CLAUDE_CONFIG_DIR and the default-path fallback in the English README and all 32 translations.

Validation: build, skills generation and check, docs sync and check, and the full test suite (4,501 passed, six skipped).
Signed-off-by: mothieras <feigan47743@163.com>

* docs(connect): clarify Claude Code profile configuration

Document default and custom MCP and hook paths together in the English README and all 32 translations. Explain that Claude Code needs the same CLAUDE_CONFIG_DIR in its launch environment even when the connector reads it from AgentMemory's .env.

Validation: build, skills generation and check, docs sync and check, and the full test suite (4,501 passed, six skipped).
Signed-off-by: mothieras <feigan47743@163.com>

* fix(connect): warn for Claude profiles loaded from env files

Warn before connecting when CLAUDE_CONFIG_DIR was hydrated only from AgentMemory's env file, so users launch Claude Code with the same profile. Values already present in the shell, including identical values, do not trigger the warning.

Trim surrounding whitespace before resolving detection, MCP and hook paths; whitespace-only values retain the legacy defaults. Document whitespace handling and the existing directory prerequisite in all 33 READMEs.

Validation: seven new regression cases; 62 affected tests pass. Build, skills generation and check, docs sync and check, and the full test suite pass (4,508 passed, six skipped).
Signed-off-by: mothieras <feigan47743@163.com>

* fix(connect): preserve Claude profile path semantics

Preserve nonblank CLAUDE_CONFIG_DIR values verbatim so the connector
and Claude Code use the same profile. Keep the whitespace-only
fallback and warn when the shell override must be unset for Claude.

Warn for relative paths, skip non-directory profile paths, and isolate
CLAUDE_CONFIG_DIR in adapter tests. Update the README translations.

Validation: build, skills generation/check, docs sync/check, and eval
typecheck passed; 4,515 tests passed and 6 skipped with Node 26.12.1,
npm 11.20.0, and Python 3.14.5. The two affected suites passed all
55 tests with an inherited profile override and left that profile
unchanged. Native Claude Code 2.1.319 found the generated MCP entry
across eight configuration scenarios.

Signed-off-by: mothieras <feigan47743@163.com>

* fix(connect): warn on padded paths and skip inaccessible profiles

Warn before installing into a Claude profile whose path contains leading
or trailing whitespace, while preserving the literal path. Keep the
separate whitespace-only fallback warning.

Catch EACCES and EPERM during profile detection so inaccessible parents
produce an actionable warning and skip the adapter. Other filesystem
errors remain visible.

Validate the built CLI against a real inaccessible parent and existing
padded-profile cases. Four regression cases fail before the fix.
Build, skills generation/check, docs sync/check, and eval typecheck pass;
4,516 tests pass and 6 skip with Node 26.12.1, npm 11.20.0, and Python 3.14.5.

Signed-off-by: mothieras <feigan47743@163.com>

* fix(connect): align Claude profile detection with config paths

Normalize custom profile paths before detection and directory creation,
matching MCP and hook file paths and native Claude Code behavior for a
symlink followed by .. . Preserve the original value for warnings.

Cover both mismatched directory-existence cases with real symlinks and
the built CLI. Both regressions fail before the fix. Native Claude Code
2.1.319 also reads the resulting MCP entry in isolated profiles.

Build, skills generation/check, docs sync/check, and eval typecheck pass;
4,518 tests pass and 6 skip.

Signed-off-by: mothieras <feigan47743@163.com>

---------

Signed-off-by: mothieras <feigan47743@163.com>
…uery fails (rohitg00#1711)

The leftover process query returned an empty list when PowerShell failed,
so the demo and stop cleanup assertions passed without inspecting anything.
Stop on the first PowerShell error and throw when the query exits non-zero.

Remove the code comment in the demo Compose teardown.
…tg00#1712)

Remove the explanatory comments in the CLIP provider and its tests.
Assert the text model receives the tokenizer output, pin both towers to
512 dimensions, and cover a failed transformers import being rethrown
instead of turned into the install hint.
…rohitg00#1715)

Add a developer experience section with a terminal session of the real
CLI commands and the Worker Compose stack the first command starts, and
a performance section that shows the paged state read path against the
old single-frame read, plus sourced gains from 0.9.31 to 0.9.33. The
API key FAQ now says a provider must be named, as it is since 0.9.32,
and llms-full.txt carries both sections.
* chore: prepare 0.9.33

Bump the version to 0.9.33 across the package, plugin manifests,
integrations, the MCP shim and its runtime pin, the export version
union and supported import versions. Add the 0.9.33 CHANGELOG section
and README highlights, and sync documented counts with docs:sync.

* docs(changelog): add the fixes merged after the 0.9.33 draft

Adds rohitg00#1703 to Fixed and rohitg00#1711 and rohitg00#1712 to Infrastructure.

* docs(changelog): correct the MCP shim timeout to 190 s

* docs(changelog): say which setting turns on LLM features for Docker installs
…hitg00#1716)

* ci(release-gate): run the packed gate on arm64 and Intel machines

The packed-artifact gate ran on Linux x64 and macOS arm64 only, and the
Windows smoke on x64 only. It now also runs on Linux arm64
(ubuntu-24.04-arm), Intel macOS (macos-15-intel) and Windows arm64
(windows-11-arm), so every engine asset the CLI installs is exercised
before a release. The Linux live-worker step picks the cached engine for
the runner architecture instead of assuming x64.

* ci(release-gate): retry the graph-only recall before failing

Search gives graph enrichment a fixed 500 ms budget and returns keyword
and vector results without it when the budget runs out. On the slower
Intel macOS runner the first graph-only recall after a mesh update can
exceed that budget, so the gate now retries the recall for up to ten
seconds and still fails if the captured memory never appears.

* ci(release-gate): send the startup cancel only after the CLI is running

The external-startup cancel scenario sent SIGTERM one second after
launching the CLI. On the slower Intel macOS runner the CLI had not
loaded and installed its SIGTERM handler yet, so it died from the
default signal instead of exiting 143. The scenario now waits for the
CLI to print its first output, up to five seconds, before the same
one-second pause.

* ci(release-gate): wait for the readiness phase and retry every graph recall

The external-startup cancel scenario now runs the CLI with
AGENTMEMORY_VERBOSE=1 and sends SIGTERM only after it prints the
--no-engine readiness line, which follows the signal handler setup; the
splash alone printed before it. The graph-only recall checks after the
restart and the index rebuild use the same bounded retry as the first.

* ci(release-gate): retry failed recall requests and stop on an early CLI exit

The bounded graph-only recall retry also retries a failed /search
request and reports the last error if every attempt fails. The startup
cancel scenario stops waiting for the readiness line as soon as the CLI
exits and reports its exit status and output.

* ci(release-gate): hold the external worker until cancel and keep recall errors

The external-startup cancel scenario delays its Compose worker for 120
seconds, so the worker cannot become ready before the CLI reaches its
readiness wait on a slow runner. The graph recall retry keeps the last
request error for the failure report even when a later attempt succeeds
without a match.

* ci(release-gate): keep each run attempt's artifacts

Artifact names now include the run attempt. A rerun of a failed job used
the same name as the first attempt, so its upload was rejected and the
failing logs were lost.
…1719)

* fix(install): retry transient iii engine download failures

The iii engine download made a single attempt, so one GitHub 504, 503 or
dropped connection failed a fresh install. On 2026-11-09 the release
files for Linux and Windows returned 504 for hours.

curl downloads (macOS, Linux, Windows behind a proxy, and the printed
manual command) now pass --retry 3 --retry-delay 2 --retry-max-time 120;
--retry covers timeouts and HTTP 408, 429, 500, 502, 503 and 504 and is
accepted by every curl since 7.12. The Windows fetch download retries the
same statuses and network errors up to three times inside the same
120-second window. A 404 or other client error still fails at once. The
install spawn timeout grows by the retry window.

* docs(changelog): add the engine download retry

* fix(install): bound download retries by the retry window

Recheck the two-minute window after each failed download and before the
next one, retry a response body that drops mid-read, honor Retry-After on
408, 429 and 5xx, and release unread error bodies before retrying.

Leave CHANGELOG to the release PR.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…g00#1720)

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(index): unindex superseded and wiped memories

Signed-off-by: dimitri <dimitri.chrysafis@gmail.com>

* ci: retrigger workflows

* fix(index): guard delayed memory indexing and refill stale search windows

Signed-off-by: dimitri <dimitri.chrysafis@gmail.com>

---------

Signed-off-by: dimitri <dimitri.chrysafis@gmail.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…#1754)

* fix(connect): support native Windows in agentmemory connect

Remove the blanket refusal that stopped every connect on Windows except
copilot-cli.

On Windows the MCP server is now written as cmd /c npx -y @agentmemory/mcp,
because hosts cannot spawn npx without a shell. This applies to the JSON
adapters, Claude Code, Codex TOML, OpenCode and DeepSeek Harness. An old
bare npx entry is replaced instead of being reported as already wired.

Hook script paths use forward slashes on Windows and stay quoted or passed
as separate arguments, so a home folder with spaces works.

Antigravity runs hook commands without a shell and cannot take quoted
paths. When the plugin path has spaces, connect now uses the Windows short
path. If no short path exists, it prints the exact hook JSON to paste and
still wires MCP.

Zed and the legacy Antigravity user folder now resolve under APPDATA on
Windows. README and INSTALL_FOR_AGENTS no longer say connect is limited to
copilot-cli on Windows.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(connect): mark the short-path variable as internal

The generated config reference lists every AGENTMEMORY_ variable in
src. The Antigravity short-path lookup passes its path through an
internal variable, so it now ends in two underscores and stays out of
the user-facing list.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(connect): migrate bare npx entries and align Zed guideline on Windows

OpenCode, Continue, Codex and DSH now replace a legacy bare npx
agentmemory entry on Windows instead of reporting already wired.
Custom commands are still preserved unless --force is passed.

The Zed guideline now uses the same config directory as the Zed
adapter, so on Windows it lands in %APPDATA%\Zed.

Tests compare hook paths in forward-slash form, the DSH args check is
platform aware, and the runbook no longer limits native Windows
connect to copilot-cli.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(connect): migrate only agentmemory npx launchers and keep their settings

Treat an entry as legacy only when it is a bare npx command whose
arguments run @agentmemory/mcp. Custom npx packages stay untouched
unless --force is given.

The Windows migration now changes only the command and args. Existing
env values such as AGENTMEMORY_URL and AGENTMEMORY_SECRET and other
options stay in place for Codex, Continue, OpenCode and DSH. Codex also
accepts a trailing TOML comment after the command value.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(connect): scan Codex args safely and collapse duplicate DSH rows

Find the end of the Codex args array with a scanner that skips quoted
strings and comments, so brackets inside them do not cut the array
short. The migrated block is checked before it is written; on failure
connect stops and asks for --force.

DSH migration now keeps the first agentmemory row and removes the
duplicates, the same as a normal install.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(connect): keep custom DSH rows during launcher migration

DSH migration now converts the first legacy npx row and removes only
other legacy rows. Custom agentmemory rows stay as they are, whatever
their order.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…ohitg00#1755)

* fix(search): retry failed keyword index sessions in the background

When the boot keyword rebuild could not list some sessions, the index
stayed incomplete until the next restart. On large stores a single
state::list call for a big session can time out or exceed the frame
limit, so most observations stayed invisible to search.

The rebuild now records which sessions failed, and whether the memories
or session listings failed. A background timer retries only those, with
exponential backoff from 30 s up to 30 min. Retries read each session in
pages through the key iterator when the store supports it. Only one retry
runs at a time. The incomplete flag clears when every pending load
succeeds. A new full rebuild or shutdown cancels the pending retry, and
the timer is unref'd.

The status payload now reports the failed session count and the next
retry time next to the incomplete flag.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(search): page the session list retry and scope retry ownership

The background retry now reads the session list through collectAll, so a
store that returns an oversized list uses paged reads like the boot path.

The retry page size halves with plain division, so it stays at the
minimum after 32 attempts instead of wrapping back to 200.

A retry now records the generation it runs for. A new rebuild can
schedule its own retry while an older retry is still in flight, and the
older retry no longer clears the running state of a newer one.

The status message for an incomplete keyword index now covers memories
as well as session observations. Docs stats are synced.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
* fix(cli): say when an agent is connected with MCP only

An agent connected with MCP only and no hooks captures nothing on its
own. Observations are stored only when the agent calls memory_save.
connect and status never said so, so users expected automatic capture.

connect now prints one line after an MCP-only setup. It names
--with-hooks only for adapters that can install hooks, points
plugin-based agents at their plugin, and otherwise says the agent
must call memory_save. Each adapter declares its capture mode in a
new autoCapture field; JSON MCP adapters with a hook installer get
"with-hooks" automatically.

The status report and the status command warn when the server has
no sessions and no capture activity, which means no hook has reached
it yet. Sessions come from hooks or imports, never from MCP calls,
so the existing session count is the signal. No new storage is added.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* docs: sync generated stats

Run npm run docs:sync after the MCP-only capture notice change.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): base the MCP-only notice on hooks that were installed

Adapters now report whether their hooks were installed. The connect
notice stays quiet only when hooks are confirmed, and it warns when
--with-hooks was passed but the hook install was skipped. DSH reports
hook rows it keeps in place.

connect codex --with-hooks on an already-wired config now installs the
hooks before it returns.

The no-hook warning in status needs a known capture state. A capture
check that timed out no longer triggers it, and the CLI reads the
capture endpoint so accepted, queued or spooled captures suppress it.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): tighten the no-hook capture checks

A DSH hook row whose plugin file is gone no longer counts as installed.
The plugin-or-with-hooks notice keeps the plugin option when hooks fail.
The status check skips the diagnosis when the capture inbox is unreadable
and says capture was not observed yet instead of claiming it is off.
The CLI counts sessions across all agents and types the capture response.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(status): treat unreadable capture state as unknown

An unreadable capture inbox now reports capture-check-unavailable.
The spool summary flags read errors other than a missing file, and the
no-hook diagnosis is skipped while the spool cannot be read.
A legacy DSH bridge row counts as installed only while its manifest exists.
The no-hook message separates memories from observations and only offers
hooks or a plugin for agents that support them.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(status): report an unreadable spool as an unchecked capture

An unreadable spool now adds capture-check-unavailable, so status cannot
report that every check passed. The spool summary reads the primary file
directly, so an access error is not taken for an empty spool.
A legacy DSH bridge row no longer counts as installed hooks; the notice
points those users at the bundled plugin through --with-hooks.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(status): name the unreadable spool path in the capture check fix

When a spool cannot be read, the capture-check-unavailable fix now names
each spool path and asks the user to check that agentmemory can read it.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…hitg00#1757)

* fix(graph): report graphify import truncation and index readiness

The graphify import kept the first 5000 nodes and 20000 edges and only
returned a nested truncated object, so large graphs looked complete.
The response now has truncated, limits, droppedNodes and droppedEdges,
plus warnings, and the server logs a warning. Edges lost because an
endpoint was over the node limit count as dropped, not as dangling.

AGENTMEMORY_GRAPH_IMPORT_MAX_NODES and AGENTMEMORY_GRAPH_IMPORT_MAX_EDGES
set the limits.

The viewer reads the graph through the retrieval index. On a store
without a ready index the import wrote rows that the viewer could not
show, and the response did not say so. The response now has a graphIndex
status and a warning with the migrate command. mergedNodes and
mergedEdges explain a re-import that reports newNodes 0.

Tests cover truncation reporting, tilde expansion of
AGENTMEMORY_IMPORT_ROOT and cwd with confinement kept, and index
visibility.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* chore(skills): regenerate config reference for graph import limits

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(graph): address review on graphify import limits

Drop the CHANGELOG entry; release PRs own it. The docs now point to
graphIndex.action instead of always prescribing a migration, and note
that higher limits make the import request take longer. Tests isolate
the limit variables from the environment and the config file, and the
import helper uses typed results instead of any.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* docs(graph): say which edges the graphify import examines

The edge limit caps the edges the parser examines, not the edges it keeps.
Describe how droppedEdges and skippedEdges count the examined edges that
are left out.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…00#1759)

* fix(hermes): declare no plugin hooks in the provider manifest

Hermes reads the manifest hooks list as provides_hooks and checks each
name against its plugin hook registry. The list held memory provider
method names such as prefetch and sync_turn, so hermes plugins doctor
reported them as unknown hooks.

The provider registers no plugin hooks, so the manifest now declares
provides_hooks: [] and requires_hermes: ">=0.21.6", which matches the
Hermes catalog entry for agentmemory.

The Hermes guide states the version requirement and explains that the
lifecycle names are provider methods. The translated READMEs now link
https://github.com/rohitg00/agentmemory instead of "the agentmemory repo".

The manifest test checks declared hooks against a fixed copy of the
Hermes hook registry and checks the provider methods against the Hermes
memory provider interface.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* test(hermes): fail on provider methods outside the known contract

The lifecycle check filtered provider methods through the known Hermes
set, so a new public method absent from that set passed unchecked. Add a
test that lists every public AgentMemoryProvider method and fails when
one is neither a known lifecycle method nor a core provider method.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…ohitg00#1758)

* fix(cli): explain an engine that runs without the agentmemory worker

When only the iii engine runs on the REST port, the agentmemory routes
return 404. Status printed version v? and Health unknown, and the viewer
returned 404, with no hint about the cause. Old Docker images from the
legacy CLI Docker mode ran only the engine and showed this state.

Status now probes /agentmemory/livez and /agentmemory/health. When both
return 404, it says that the engine runs without the worker, how to start
agentmemory, and where the Docker migration guide is.

Doctor has a new worker-not-connected check with the same fix text.
Every failing doctor check now prints its message and a fix hint, not
only its id. The iii-on-path-not-local-bin check now says which iii is
used, its version, and the command to run.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): leave managed Compose status to the Compose failure report

When a supervised worker in the managed Compose project exhausts its
restarts, the agentmemory routes can return 404. The engine-only probe
then exited before status printed the Compose failure. Skip the probe
for managed Compose state in status and doctor; it is meant for engines
agentmemory does not manage.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): confirm the iii engine and keep the target in worker probes

Two 404 responses from the agentmemory routes no longer prove an iii
engine. The probe now also checks the engine port. If that port does
not answer, status and doctor report an unrecognized service and do not
tell the user to stop it.

Status and doctor now probe the selected target also when managed
Compose state exists. Status prints the Compose failure report first
when there is one. Doctor reports a managed Compose engine without its
worker and no longer passes for a remote URL or another port.

The recovery command keeps --instance, --port and --data-dir. The
iii-on-path-not-local-bin message no longer says that startup uses the
PATH iii.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): show the Compose failure report when routes are missing

When a managed Compose worker exhausted its restarts, the agentmemory
routes answer 404 and status exited with the engine-only message. Status
now continues to the normal report, which lists the Compose failure,
as it did before.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): keep the target in recovery hints and tighten worker probes

Status and doctor recovery commands now keep --instance, --port and a
shell-quoted --data-dir for status, stop and start. A route that fails
next to a 404 no longer counts as a connected worker. Status exits 1
when the worker routes do not respond. The engine bus probe honors
III_URL when III_ENGINE_URL is unset. The doctor message no longer
claims an engine is running, and the unrecognized-service hint points
old Docker images at the migration guide.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): quote Windows data directories for PowerShell

On Windows the recovery hint now puts --data-dir in PowerShell single
quotes, so dollar signs and apostrophes stay literal. Trailing path
separators are dropped, so no backslash comes before a closing quote.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): keep drive roots and use double quotes for Windows paths

A drive root such as C:/ keeps its separator in recovery hints. Windows
paths that need quoting use double quotes, which Command Prompt and
PowerShell both read literally. Paths with a dollar sign keep PowerShell
single quotes.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…hitg00#1760)

* fix(cli): make demo wait until seeded observations are searchable

The demo searched right after seeding. The observe endpoint can accept a
capture with 202 and store it later, so on a half-started setup the
queries ran before the seeded observations were in the index and showed
0 hits with no explanation.

The demo now polls a project-scoped keyword search for each demo
session, every 500 ms for up to 18 s, before it runs its queries.

When a query still returns no hits, the demo reads /agentmemory/status
and prints the reasons in plain words: observations not accepted, the
wait timed out, the worker is not connected to the engine, captures
still queued or dead-lettered, the keyword index rebuilding or
incomplete, observations missing from the index, or no embedding
provider. It then points to the status and doctor commands.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): scope demo readiness to the current run and fail on timeout

The demo readiness probes and the displayed searches now use the demo
project and count only hits from the sessions seeded in this run, so
records from an earlier demo run or another project cannot confirm
readiness. A timed-out readiness check now always prints the diagnosis
and skips the success message. Search request failures are kept as
errors and reported as a reason instead of being shown as zero hits.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(cli): give each demo run its own project

The demo used one fixed project for every run. Earlier runs seed the same
text, so their observations could fill the result limit and the current
run could report zero hits. Smart search filters by project before it
applies the limit, so a project per run keeps the probes scoped to the
sessions this run seeded.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
…fusing writes (rohitg00#1174)

* fix: evict lowest-value observations at the session cap instead of refusing writes

MAX_OBS_PER_SESSION currently makes mem::observe return
"Session observation limit reached" once a session holds its cap, so every
later observation in that session is dropped. The observations lost are the
NEWEST ones in the LONGEST sessions, which is the part a memory system is
least able to afford losing, and nothing is logged server-side, so a capped
session looks identical to a quiet one.

Evict instead: at the cap, drop the least valuable rows (lowest importance
first, oldest breaking ties) to make room, clear them from the BM25 and vector
indexes so search cannot return dead ids, and warn with the session id and the
number evicted. The bound on how much a session stores is unchanged; only the
choice of which observation is sacrificed changes.

Three sessions in a real install had been silently pinned at exactly 500 rows
for days before this was noticed.

Signed-off-by: sbynode-ux <sby.node@gmail.com>

* fix(observe): make session cap eviction complete and safe

Eviction now removes each victim the same way mem::evict removes an
observation. It marks the capture event deleted, deletes the KV row,
removes the BM25 and vector entries, drops the obs-session index entry
and releases image refs. One audit entry lists the evicted ids.

A failed delete moves on to the next candidate. If eviction cannot free
enough slots, the write is refused with a returned error, so the capture
inbox does not retry it and the cap still holds. Nothing in the eviction
path throws.

The incoming observation is never a candidate. Rows without an
importance score sort as 5, which matches the synthetic compression
default and the other eviction paths.

The status hint for cap dead letters now points at eviction failure.
Tests cover failed deletes, an above-cap session, image refs, the audit
entry, the obs-session index and concurrent writes at the cap.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* docs: sync stats

Output of npm run docs:sync after the new session cap tests.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(observe): evict only after the incoming observation is stored

Eviction ran before the new observation was written, so a failed write
lost the evicted rows and their image files. The write now happens
first, under the same session lock, and eviction runs only after it
succeeds. If eviction frees too few slots, the write is kept and the
next write evicts again.

The session observation count now drops by the number of evicted rows,
so the unindexed-observation scan can skip fully indexed capped
sessions again. Rows that are really missing from the index still
make the count exceed the indexed count.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(observe): budget a capped write's source against the retained rows

At the session cap, the incoming observation source was budgeted
against every existing row, including the rows that eviction removes
right after the write. Near the session source limit, this truncated
or dropped the new source even when eviction freed enough space.

The eviction victims are now selected before budgeting, and the source
is budgeted against the rows that remain. Victims are still deleted
only after the write succeeds. If a planned victim cannot be deleted,
the source is budgeted again against the rows that really remain and
the stored row is rewritten.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: sbynode-ux <sby.node@gmail.com>
Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
Co-authored-by: Rohit Ghumare <ghumare64@gmail.com>
…session cap (rohitg00#1766)

* fix(release-gate): force the dead-letter capture failure without the session cap

The deadletter scenario made the third capture fail by starting with
MAX_OBS_PER_SESSION=2. Since rohitg00#1174 the cap evicts the lowest-value
observation instead of refusing the write, so the capture succeeded, no
dead letter appeared and the scenario timed out on every platform.

mem::observe now rejects a capture whose data contains the value of
AGENTMEMORY_RELEASE_GATE_FAIL_OBSERVE. The variable is unset in normal
use, so nothing changes for users. The gate sets it to the third marker,
restarts without it, and the retry recovers the capture as before.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

* fix(release-gate): mark the dead-letter switch as internal and sync docs

The switch is for the release gate only, so it now ends in two
underscores like AGENTMEMORY_MCP_STDIO__. The skill reference generator
skips such internal markers, so the variable does not appear as a user
setting and skills:check passes. Documented counts are re-synced.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>

---------

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
The 37 conflicts were all generated documentation (the test-count badge, "4,100+" here and "4,900+" upstream, in the READMEs, AGENTS.md, two SVGs
and docs-sync.state.json); upstream's side taken, and `npm run docs:sync` then changes nothing. The fork's two fixes (compression deadline, queued
commands in replay) merge without conflict.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@GaryGTan-T2

Copy link
Copy Markdown
Collaborator Author

Superseded: Gary chose a rebase. The fork's main now mirrors upstream, and our two fixes sit on top of it in develop (old main tagged main-before-rebase-2026-11-13).

@GaryGTan-T2
GaryGTan-T2 deleted the merge-upstream-20261113 branch November 13, 2026 00:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.