Skip to content

Merge upstream v0.9.33 while keeping the JTT scoped gateway - #462

Merged
ShintaroKawakami merged 214 commits into
mainfrom
jtt/upstream-0.9.33
Nov 10, 2026
Merged

ShintaroKawakami merged 214 commits into
mainfrom
jtt/upstream-0.9.33

Conversation

@ShintaroKawakami

@ShintaroKawakami ShintaroKawakami commented Nov 10, 2026 •

Copy link
Copy Markdown
Owner

Do not merge this PR and do not deploy. This is the JTT-preserving import of upstream v0.9.33 (28ffc538) onto fork main.

Why

Production today is fork main at 538ac1f (upstream 0.9.28). This branch brings 0.9.33 search/paging/status/iii-sdk 0.25.1 while keeping the JTT gateway that upstream still lacks.

Head

  • Branch: jtt/upstream-0.9.33
  • Merge commit: cb9f97716975a6d23e28a67fabe1e710dfc28bf3
  • Follow-up: 2d50dcbb9c72b09c7f084c30690003ce22a648e2 (npm run skills:gen — CI skills:check drift)

Conflicts (12) and how they were resolved

File Resolution
src/functions/search.ts Take 0.9.33 hybrid ranking loop (fixes saved memories capped at 3). Keep JTT project/cwd fail-closed filtering already applied in authorizeGraph and the load pass.
src/triggers/api.ts Keep selectLatestProjectHandoff and GET /memories?handoffProject= { handoff } body. Take upstream status/unindexed/list-query imports.
src/types.ts Keep JTT project on CompressedObservation and upstream origin / captureKey / compressedAt / compression.
src/state/memory-utils.ts Carry both project and agentId through memoryToObservation.
tsdown.config.ts Keep JTT src/jtt/scoped-gateway.ts entry and upstream pi / omp / dsh entries.
package.json iii-sdk / @iii-dev/helpers 0.25.1, upstream dotenv. Keep @modelcontextprotocol/sdk for the JTT gateway.
src/index.ts Upstream REST count (147). Handoff is a query on existing /memories, not a new route.
AGENTS.md Upstream 0.9.33 stats; keep JTT CARD / harness inheritance.
README.md Upstream API/auth text (147 endpoints, secret-on-by-default).
.gitignore Both JTT harness ignores and upstream generated-plugin ignores.
plugin skill REFERENCE files Regenerated AUTOGEN:env (88 variables, including JTT AGENTMEMORY_GATEWAY_*). REST stays 147.

Unconflicted JTT pieces kept as-is: src/jtt/scoped-gateway.ts, src/jtt/stored-envelope.ts, deploy/macos/run-jtt-*.sh, token→project mapping / implementation_handoff, tests under test/jtt-*.ts and test/handoff-boundary.test.ts.

Tests

  • npm run build — pass, including dist/jtt/scoped-gateway.mjs
  • Local unit tests: 4798 passed, 7 skipped, 1 failed (test/startup-gate-pack.test.ts, Cloud PATH spawn npm ENOENT; new upstream gate test)
  • Targeted JTT/search/paging tests passed
  • First CI on cb9f977: all 8 test matrix jobs failed at skills:check (stale AUTOGEN:env count). packed artifact passed on ubuntu, ubuntu-arm, macos-latest; macos-15-intel failed later at Graph-only memory recall must survive a restart (release-gate graph-index, after restart). Windows smoke passed.

Production switch (env / config) — do not apply until this PR is approved

Keep keyword/BM25-only. 0.9.33 does not require an LLM to start.

Leave unset:

  • AGENTMEMORY_LLM_PROVIDER
  • AGENTMEMORY_ALLOW_AGENT_SDK
  • EMBEDDING_PROVIDER

Must keep / verify:

  • Existing AGENTMEMORY_SECRET / gateway secret / token→project (0.9.33 mints a file secret if REST secret is missing)
  • run-jtt-core.sh --tools core
  • First start after iii-sdk@0.25.1 downloads the pinned engine
  • Hermes must keep GET /memories?handoffProject= (unpaged /memories can 413)

Not in this PR: merge to main, Mac mini deploy.

Open in Web Open in Cursor 

ErikBPF and others added 30 commits July 19, 2026 19:43
Signed-off-by: Erik Bogado <erikbogado@gmail.com>
)

* feat(cli): native hooks adapter for Antigravity CLI (agy)

Antigravity ships two products with unrelated configuration: the IDE,
already wired by `connect antigravity`, and the `agy` CLI, which reads
its customizations out of ~/.gemini/ and until now was not wired at all.
This adds `connect antigravity-cli` for the latter — MCP via
~/.gemini/config/mcp_config.json, plus optional native auto-capture hooks
behind --with-hooks.

Unlike Droid (rohitg00#1130), the Codex merge engine could not be reused. The
Antigravity hooks contract differs in three ways:

  * hooks.json is a map of *named* hook bundles at the root, not the
    `{ hooks: { <Event>: [...] } }` envelope, so antigravity-hooks.ts
    implements a merge that owns top-level keys instead of per-event
    entries. User-authored bundles are preserved; a re-install replaces
    only the bundle whose commands point under the bundled plugin dir.
  * only five events exist (PreToolUse, PostToolUse, PreInvocation,
    PostInvocation, Stop) — no SessionStart/SessionEnd/UserPromptSubmit,
    so the session lifecycle is synthesized from the first PreInvocation
    and from Stop. PostInvocation is left unwired to avoid double-capture.
  * the stdin payload is camelCase and nested (`toolCall.args` with
    PascalCase keys, `conversationId`, `workspacePaths`), and stdout must
    be a JSON object — `pre-tool-use.mjs` writes raw prose when context
    injection is on.

plugin/scripts/antigravity-bridge.mjs bridges all three: it normalizes the
payload onto the shape the bundled hooks already accept, maps Cascade tool
names (view_file, replace_file_content, …) onto the read/edit/write/grep
vocabulary the capture heuristics use, pipes to the right script, discards
child stdout and always answers `{}` so Antigravity's own permission
decisions are never overridden.

Event names, tool names and arg keys were verified against the shipped
agy binary rather than docs alone (docs disagree on the global hooks
path); the customization dir is ~/.gemini/config/, matching where agy
already keeps mcp_config.json and plugins/.

Signed-off-by: Bertho Joris <bertho_joris@yahoo.co.id>

* fix(cli): keep $-bearing plugin paths literal when resolving hook commands

resolveBundle() expanded ${CLAUDE_PLUGIN_ROOT} via
String.prototype.replace with a string argument, so a plugin root
containing `$$`, `$&`, "$`" or `$'` was read as a replacement pattern
and rewritten:

  C:/plug$&in  ->  C:/plug${CLAUDE_PLUGIN_ROOT}in/scripts/...
  C:/plug$$in  ->  C:/plug$in/scripts/...

`$1` and `$<name>` are unaffected — the regex has no capture groups.

Switching to a replacer function keeps the path verbatim. The failure
mode this closes is silent: the hook installs with a broken command and
auto-capture simply never fires.

Regression test builds the manifest against a temp plugin root named
`plug$&$$in` and asserts the resolved command contains it literally.

Reported by CodeRabbit on rohitg00#1146.

Signed-off-by: Bertho Joris <bertho_joris@yahoo.co.id>

* fix(antigravity): emit an explicit allow decision from the PreToolUse hook

Antigravity documents `decision` as a required field of PreToolUse hook
output, and agy treats a response that omits it as a denial: the bare `{}`
the bridge used to write made the agent refuse every matched tool call
(reported against agy 1.0.5 in cmux#5358) instead of passively capturing
it. `responseFor` now answers PreToolUse with `{"decision":"allow"}` and
leaves every other event on `{}`, so no event that carries no permission
decision starts overriding the user's own settings.

The response is written from the `finally` block, so a failed capture or an
unparseable payload still produces the contract rather than empty stdout,
which PreToolUse would read the same way as `{}`.

Tests cover both the pure contract and the built bundled script running
end to end with no server listening. Also extends the ARG_KEY_MAP test to
every mapped key and pins that an explicit canonical key wins over a
PascalCase alias.

* fix(antigravity): match agy's real hooks.json schema, verified against 1.0.15

Three defects found by probing a live agy 1.0.15 with an instrumented hook,
each of which stopped the adapter from capturing anything at all.

Lifecycle events take a flat handler list, not the tool-event wrapper. agy
parses `PreToolUse`/`PostToolUse` as `[{matcher, hooks: [...]}]` but
`PreInvocation`/`PostInvocation`/`Stop` as a bare `[{type, command}]`, since
there is no tool name to match on. Wrapping a lifecycle event makes agy read
the wrapper itself as a handler and reject the *whole file* with
`invalid hook "agentmemory": command hook must specify 'command'` — so the
mis-shaped Stop entry disabled every hook in the bundle, and would have
disabled hooks other tools had written to the same file.

`command` is not run through a shell and quotes are not stripped, so the
quoted path resolved to a module name that literally began with a double
quote: `Cannot find module 'C:\Users\…\.gemini\config\"C:\…\bridge.mjs"'`.
Commands are now bare. That also means a path containing spaces cannot be
expressed at all — quoted and unquoted both fail — so the installer refuses
with an explanation instead of writing hooks that can only fail at tool time.

The merge engine reads both shapes when deciding which bundles agentmemory
owns, so a re-install over the old wrapped layout still replaces it rather
than leaving a second copy behind.

Tests pin both event shapes, the absence of quotes, the space check, and
normalization of a payload captured verbatim from the live run — which also
confirms `conversationId`, PascalCase `toolCall.args`, and that agy sends no
`cwd` key at all.

* refactor(antigravity): cut comment volume to match the sibling adapters

The bundled script carried 24 comment lines where every other script in
plugin/scripts has three. The bundler strips `//` comments but preserves
JSDoc blocks, so the fix is to document the bridge's exported helpers with
line comments: the explanations stay in source and the generated artifact
comes out as clean as its siblings.

The connect adapter and merge engine restated the same facts in a file
header and again in a per-function block. Kept one statement of each,
dropped the repetition, and left the verified agy behaviour in place since
that is the part not derivable from the code.

---------

Signed-off-by: Bertho Joris <bertho_joris@yahoo.co.id>
…aces (rohitg00#1141)

* chore(release): v0.9.29 with project-scope parity across surfaces

Version trio + plugin manifests + supportedVersions + ExportData union
bumped to 0.9.29; CHANGELOG entry covering everything since v0.9.28 with
upgrade notes for the four visible behavior changes.

Fixes the endpoint-count drift on main (130 registered routes vs docs
saying 129 after rohitg00#1132 landed in parallel with rohitg00#1136).

Project-scope parity: OpenCode plugin, Hermes plugin, Pi extension, and
JSONL replay now resolve project the same way the hooks do (env
override, git toplevel basename, cwd basename) instead of sending raw
filesystem paths, closing rohitg00#903 and rohitg00#1135 and pre-empting the same bug
in pi. The filesystem watcher accepts AGENTMEMORY_PROJECT_NAME with the
old AGENTMEMORY_PROJECT kept as a deprecated alias, replay handles
Windows-recorded paths, and OpenCode file enrichment matches the
agent's lowercase tool names (the capitalized set never matched).

Tests: opencode fallback expectations updated to basenames per the
canonicalization, git-toplevel resolution covered with a fixture repo,
new project-scope-parity suite for replay and fs-watcher.

* fix(release): review findings, git-toplevel parity, doc counts

- skills generator dedupes routes on method plus path, so the REST
  reference lists all 130 registered routes instead of hiding the second
  method on ten dual-method paths (header said 119)
- fs-watcher trims AGENTMEMORY_PROJECT_NAME and the deprecated alias,
  treating whitespace as unset, and derives the git toplevel basename
  when watching a subdirectory
- replay resolves the git toplevel basename when the recorded cwd still
  exists locally (memoized per cwd), keeping the basename fallback for
  historical or cross-platform paths; no env override here since a bulk
  import spans many projects
- parity tests for replay git-root resolution, watcher git-root and
  trim behavior
- stat-tests badge updated from 1428+ to 1550+ passing

* fix(cli): refuse second-instance boot over a live daemon

Closes the class behind issue 1140: agentmemory consolidate (or any
unrecognized word) fell through the command table into the full server
boot, registering a duplicate worker on the running engine; on iii
0.11.2 the second instance's shutdown tears down the daemon's HTTP
trigger routing until a full engine restart. Unknown subcommands now
error with the supported list, and main() probes livez on the resolved
port and refuses to boot over a live daemon, so multi-instance setups
on other ports are unaffected. Verified behaviorally against the built
CLI: both paths refuse with exit 1.

Also from review: the watcher stamps each event with its own root's
project via a per-root map (an explicit config.project still overrides
for every root), and replay only accepts a non-empty string cwd from
parsed JSONL so malformed entries cannot reach the filesystem probe.

* test(watcher): two-repository flush events scope to their own project

* chore(release): bump packages/mcp, guard it, refresh CONTRIBUTING

packages/mcp was still 0.9.28 after the release bump because nothing
guarded it; a consistency test now pins it to package.json. CONTRIBUTING
release list corrected to the files a bump actually touches (no tracked
lockfile, the two extra plugin manifests, the export test derives from
VERSION now), and the subsystems table gains src/cli, integrations/pi,
and the generated-manifest note.

* fix(export): refuse over-frame export instead of dropping the worker

Closes the availability bug in issue 1142: GET /agentmemory/export
assembles the full store and returns it through sdk.trigger, so a store
whose serialized export passes the engine's 16 MiB WebSocket frame
(tungstenite max_frame_size, not raisable under the 0.11.2 pin) dies on
the worker->engine hop, drops the worker, and 404s every endpoint for
~1s. The session collections page on maxSessions/offset but ~18 others
do not, so a large store hits this at any parameter combination.

A shared frame-guard measures the serialized size before returning:
mem::export returns a small oversized error instead of the giant
object, and api::mesh-export returns 413 (same dead-end as rohitg00#890). Either
way the over-frame payload never crosses the boundary, so the daemon
stays up and the failure is one clean request with a hint to narrow the
range. Full pagination of the non-session collections is a follow-up.

Layer 1 of the fix; verified with a synthetic oversized export returning
the error object (tiny) rather than the payload.

* ci: collapse to a single npm install to fix Node 24/26 CI

The two-step install (npm install --package-lock-only then npm ci) failed
only on the Node 24/26 matrix rows: their stricter npm rejects rolldown's
optional platform bindings (@rolldown/binding-android-arm64) that a
--package-lock-only pass does not fully enumerate. Lockfiles are gitignored,
so npm ci re-validation buys no reproducibility here. A single lenient
npm install resolves and installs in one pass.

* fix(mesh): scope exported memories by project like actions

api::mesh-export filtered actions by ?project but returned every project's
memories. On a mesh instance federating one project to a peer, the peer
pulled other projects' memories (cross-project leak), and those extras could
push the payload past the 16 MiB transport frame into a 413 even when the
requested project's own slice fit. Memories carry the same optional project
field as actions, so filter both before the frame-size guard runs.

Adds a regression test asserting a project-scoped export excludes other
projects' memories and that an oversized memory in another project no longer
413s the scoped request.

* chore(release): credit the Antigravity native hooks adapter in 0.9.29 notes

* chore(release): sweep stale 0.9.28 refs for 0.9.29

Deploy Dockerfiles/compose/render pins, AGENTS.md stats header, opencode
plugin manifest, website meta snapshot, test-count claims (1,428 -> 1,596)
in README/AGENTS/stat SVGs, and the missing 0.9.29 CHANGELOG compare link.

* chore(release): sync stat-tests badge to 1596+ and commit bridge exec bit

* refactor: trim frame-guard comments and drop issue refs from code
The six drafts covered vulnerabilities fixed in 0.8.2 and were staging
material for filing through the repository Security tab. GitHub reads
advisories only from the Security tab, so the folder carries no function
in the repo.
…rohitg00#1205)

* fix: prompt dedup, double summarize, docker-mode stop, hermetic tests

- observe: hash the hook payload when tool_input is absent so prompt_submit,
  notification, and lifecycle events dedup on content instead of collapsing
  onto one shared key that silently dropped every prompt after the first in
  a TTL window (rohitg00#1173)
- stop hook: drop the direct /agentmemory/summarize POST; /session/end
  already fans out event::session::stopped which runs mem::summarize, so
  every Stop dispatched two full summarizes (rohitg00#1203)
- cli: refuse to adopt or signal Docker/VM port holders (com.docker.backend,
  vpnkit, colima, ...) as the native engine unless --force; scope Docker-mode
  teardown to agentmemory's own compose services via rm -s -f instead of an
  unscoped down; reap the native worker before Docker teardown instead of
  deleting worker.pid with the process still running (rohitg00#1151)
- tests: isolate HOME/USERPROFILE for the whole vitest run so suites stop
  reading the developer's real ~/.agentmemory/.env (rohitg00#1178)

* fix(viewer): live stream port discovery, fresh tab data, honest states

- resolve the stream WebSocket target from /agentmemory/livez (new
  streamsPort field) instead of viewerPort-1 arithmetic, which pointed at
  the wrong server whenever the viewer bound a fallback port and silently
  degraded live updates to 10s polling — verified reaching 'live' on the
  fallback-port case
- refetch tab data on every tab entry; the loaded-once cache meant a
  memory saved by the agent never appeared until a hard browser reload
  (loading placeholders now render only on first load, so background
  refreshes don't flash)
- memories: rows expand on click/Enter to the full stored record —
  content, id, project, created, supersedes, files — plus a collapsible
  raw JSON view
- graph: a 503 with the structured disabled body renders 'Knowledge
  graph is off' with the enableHow text and docs link instead of a
  'query failed / Retry' error that sends users to server logs
- sessions: cards get role=button, tabindex, Enter/Space activation, and
  the detail panel scrolls into view on select; session ids truncate
  head…tail so the distinguishing suffix stays visible
- style search inputs and toolbar buttons on lessons/actions/crystals/
  replay (previously bare native controls); horizontal scroll containment
  for narrow viewports
- demo: only print the semantic-recall success notice when the search
  actually hit; on 0 hits explain the missing embedding key instead

* fix: thread agentId/project through save paths, per-session OpenCode scope

- REST /agentmemory/remember accepts and forwards agentId to mem::remember;
  it previously dropped the field so per-request multi-agent scoping was
  impossible over REST (rohitg00#1159)
- memoryToObservation() carries the memory's agentId into the search-index
  shape; dropping it made every memory invisible to agent-scoped search
  (rohitg00#1160)
- MCP memory_save path: the tool schema now exposes agentId, the in-worker
  MCP server forwards it, and the standalone stdio package parses and
  forwards both agentId and project — the stdio pipeline previously dropped
  project even though its schema advertised it (rohitg00#1197)
- opencode plugin: project/cwd attribution is per-session (resolved from
  the session's own directory at session.created, pruned on session end)
  instead of module-level state that recorded every session in a
  multi-directory OpenCode process under whichever repo loaded the plugin
  first (rohitg00#1188)

Live-verified: memory saved with agentId=agent-alpha is returned by
smart-search for agent-alpha and hidden from agent-beta.

* feat: hybrid recall everywhere, indexed lessons, provenance, recall hygiene

- mem::search ranks through the full BM25+vector+graph fusion when the
  vector index is populated (injected post-boot via setHybridRanker);
  the primary recall surface was keyword-only while only smart-search
  got hybrid ranking
- fusion weights normalize per item over the streams that actually
  ranked it, with a small explicit cross-stream agreement bonus; the
  old every-enabled-stream denominator permanently penalized
  single-stream hits (the graph stream is empty on default installs).
  Result order is now deterministic (score, best rank, id)
- lessons get a dedicated in-memory BM25 index built lazily from one KV
  list and maintained incrementally on save/delete/decay; recall
  previously listed and substring-scanned the whole corpus per query.
  Confidence x recency composite scoring is unchanged
- mem::remember finds supersession candidates through the search index
  (top-50) instead of walking every memory per save, with a full-scan
  fallback while the index is cold; near-miss similarity (0.4-0.7)
  is reported back as an advisory similarTo hint
- superseded memory versions leave the BM25 and vector indexes; the
  version chain stays in KV for history, but recall no longer returns
  an outdated fact as if current
- every observation and memory now carries an immutable origin block
  (channel: user|agent|tool|import|shared, detail, capturedAt) stamped
  at capture, save, and import, and inherited through both compression
  paths — the base for trust-aware retrieval and ingest screening
- regression tests: supersede index removal, similarTo hint,
  index-backed candidate discovery, lesson index recall/lazy
  rebuild/delete

* feat(viewer): two-pane sessions, navigable dashboard, motion and copy polish

- sessions: list + sticky detail panel side by side above 1100px (the
  detail previously rendered below the whole list, off-screen on any
  real corpus); selected/hover/active states with reserved left border
  so selection doesn't shift layout
- dashboard stat cards for sessions/memories/lessons/crystals/graph
  navigate to their tabs (click or Enter), with hover affordance
- observation subtitles that are raw serialized tool input now display
  the meaningful field (file path, command, pattern, url) instead of a
  JSON blob
- expanded memory rows show the new origin provenance (channel + detail)
- motion: 160ms view entrance, live-badge pulse, both gated behind
  prefers-reduced-motion; tabular numerals in tables
- mobile: header stops wrapping the dateline into the badge row
- lessons/crystals empty-state copy aligned with the header definitions
  (each concept was described two conflicting ways)

* refactor: cleanup pass over the branch diff

- shared test mocks: the three new test files use test/helpers/mocks
  (extended with update, store access, and an opt-in loose trigger)
  instead of three diverging inline copies
- lessons: record cache beside the index takes recall to zero KV
  round-trips (was up to 50 gets per call); the observation adapter
  moved next to memoryToObservation so both record kinds thread new
  fields in one place; dead reset export removed
- mem::search hybrid path carries the observations the ranker already
  loaded instead of refetching every result (halves KV I/O on the
  primary recall path); remember's candidate lookup skips ids that
  cannot resolve as memories and fails open to a full scan
- fusion: derived tiebreak field no longer rides along past the sort;
  comment trimmed to the non-obvious history
- cli: engine identity is a positive check (only the iii binary may be
  adopted or signaled; unknown port holders are refused, not just known
  VM names); worker reap extracted to one helper; demo notice picks its
  branch from a hoisted count
- api: livez and health share one instanceInfo source (health now
  reports streamsPort too) computed once at boot instead of rebuilding
  the merged env per request
- provenance: one importOrigin factory encodes the keep-or-mark rule at
  all three import sites
- opencode plugin: project resolution memoized per directory (was a
  blocking git subprocess per session event); session.created uses the
  entry it just built
- observe: origin channel derived from a named hook set, no nested
  ternary
- viewer: toolbar buttons merged into the .btn rules, one 720px media
  block, generic keyboard activation for role-carrying cards,
  scroll-into-view only on the stacked layout, 5s freshness gate on tab
  refetch (replay stays fetch-once, reason documented), subtitle
  humanizer covers the capture-side key variants

* feat(viewer): clarity pass and ambient refresh

- health notes/alerts translate their machine slugs into sentences
  (memory_heap_tight_93%_rss111mb reads as heap usage with context)
- lessons rows expand to full detail: rule, why-learned context, tags,
  learned/last-confirmed times, source sessions, raw record; column
  headers carry title hints for confidence and uses
- actions tab gets the same intro card as the other tabs (status flow
  and frontier explained on the populated view, not just when empty)
- timeline defaults to the session with the most observations instead
  of the newest, which was often a sparse just-started session
- consolidation status and top-concepts zero states explain what fills
  them and which flags gate it
- ambient background: the static dot grid becomes a slowly drifting
  ordered-dither field (quarter-res canvas, ~12fps, static frame under
  prefers-reduced-motion, theme-aware)
- dark theme: layered near-black surfaces, hairline borders, softened
  accent — replaces the flat gray borders

* feat(website): reskin on the near-black token system

- neutral token foundation in globals.css: canvas/canvas-soft/card
  surfaces, hairline borders, ink/body/mute text scale, one warm accent
  used sparingly, 8px card radius + pill buttons, focus-visible rings
- Inter display at weight 400 with tight tracking; mono uppercase
  eyebrows and captions; sentence-case body (case normalization only,
  no copy changes)
- hero: two-tone lowercase wordmark, install command as a soft input
  card, ambient drifting dot field capped at 0.12 alpha with a static
  frame under prefers-reduced-motion
- sections rebuilt on the card recipe: quiet background-shift hovers,
  hairline data table for the comparison, segmented tabs with polarity
  flip, per-vendor accent colors stripped from agent cards
- fixed two latent token misuses that resolved to nothing
- build green: 5/5 static pages, TypeScript clean

* fix(viewer): make the graph tab legible without edges

- nodes anchor to per-type cluster centers (captioned on the canvas)
  whenever relations are sparse; a pure force layout with no edges was
  an unlabeled scatter. Edge springs take over as real relations arrive
- labels always render on graphs of 30 or fewer visible nodes instead
  of only past a zoom threshold
- sidebar explains the entities-without-relations state and what
  produces edges; static legend removed (the type filter already
  carries color and shape)

* fix(viewer): graph readability on sparse data

- hover focus-fade only engages when the graph has edges; with none it
  faded every other node and suppressed all labels
- cluster anchor pull reduced and initial scatter widened so type
  groups spread instead of collapsing into blobs
- minimum node radius raised for degree-zero nodes; cluster captions
  offset above their groups

* fix(viewer): graph fits the view; site copy grounded in the repo

viewer graph:
- container height leaves room for the footer instead of running under it
- one-shot auto-fit zooms and pans to the node bounds once the layout
  settles, so first paint is framed instead of adrift
- cluster captions and small-graph labels hide below readable zoom

website copy (full pass, technical register):
- every unverifiable number removed: benchmark percentages, latency
  claims, press strip, testimonials, invented terminal output; the
  comparison table usage dropped rather than shipping stale competitor
  figures
- remaining stats are build-derived (54 MCP tools, 130 REST endpoints,
  12 hooks, 1619 tests) or live from the GitHub API (stars)
- feature copy corrected against src behavior: consolidation, graph
  extraction, and LLM compression activate with a provider key;
  provider list completed; install step numbering fixed
- release-branch capabilities surfaced: agent-scoped save and recall,
  write-time provenance channels, hybrid ranking on the primary recall
  path, indexed lessons, near-duplicate save hints, superseded-version
  recall hygiene, JSONL import deriving crystals and lessons
- em-dashes and slop phrasing removed throughout

* fix: restore featured strip, label collision avoidance, optional no-think

- website: FeaturedIn strip returns to the hero (its claims are the
  project's own credentials); rest of the grounded-copy pass unchanged
- viewer graph: canvas cluster captions removed and labels place
  greedily into free space (selected/hovered always win), so zoomed-out
  views degrade to fewer labels instead of overlapping pills
- graph extraction: AGENTMEMORY_LLM_NOTHINK=1 opt-in asks local
  reasoning models to skip their hidden thinking pass (several times
  faster, slight quality tradeoff); documented in .env.example, default
  behavior unchanged

* feat(website): testimonials return, OpenCode joins the featured connectors

- Testimonials section restored after LiveTerminal (launch-thread
  quotes are the project's own record)
- OpenCode promoted from the marquee to the featured grid: it ships a
  native capture plugin with per-session project attribution; fills the
  empty eighth slot
- full connector roster verified against src/cli/connect (18 dedicated
  adapters all present: featured grid + marquee)

* fix(viewer): official icon as the favicon (was a text placeholder)

* test(viewer): favicon assertion checks the served SVG, not a hex value

* test(viewer): favicon checks assert served SVG shape, not old artwork

* docs: readme grounded in source, changelog entry, env example consistency

* revert(website): restore measured benchmark claims and comparison table

The retrieval recall and token reduction figures are the project's own
measurements and its adoption story; earlier scrubbing was over-strict.
Backing them with a published run of the eval harness stays on the
roadmap.

* fix(website): drop the orphaned pause control on the hero field

The old animated constellation earned a pause button; the subtle dither
field does not, and prefers-reduced-motion already renders it static.

* fix(website): official OpenCode brand mark on the featured card

* chore: bump provider default models to current generations

OpenAI gpt-4o-mini to gpt-5.6-luna, Anthropic claude-sonnet-4-20250514 to claude-sonnet-5, Gemini gemini-2.5-flash to gemini-3.7-flash, MiniMax M2.7 to M3, OpenRouter default to anthropic/claude-sonnet-5. Premium cost warning matches the Sol tier; cheap-model hints lead with deepseek/deepseek-v4-flash-0731. README local picks move to qwen3 / gpt-oss / deepseek-r1 with a NOTHINK callout; cost table refreshed with verified OpenRouter list prices. Embedding defaults unchanged.

* feat: keyless heuristic graph extraction with LLM enrichment optional

Entities and co-occurrence do not need a language model: files and concepts on compressed observations already name the nodes, and appearing in the same observation is an edge. mem::graph-extract now always runs this deterministic pass, so the graph populates for keyless installs; the LLM pass layers typed relations on top only when GRAPH_EXTRACTION_ENABLED is set and a real provider exists. Session end fires extraction unconditionally.

* feat: DeepSeek Harness connector via home-level cordis patch layer

agentmemory connect dsh appends an @deepseek-ai/dsh-mcp-client row to DSH_HOME/cordis.patch.yml (default ~/.dsh), the machine-local patch layer every Harness profile loads, so the MCP tools register as mcp__agentmemory__* before the first turn. Idempotent, --force replaces the row, dry-run supported. Config shape verified against the mcp-client README and publish docs in deepseek-ai/deepseek-harness. Website agents grid and README connector table updated.

* feat: dsh --with-hooks auto-capture via Harness Claude Code bridge

DeepSeek Harness ships a first-party @deepseek-ai/dsh-hooks-claude-code plugin that runs Claude Code shaped command hooks on the harness's own interception points. connect dsh --with-hooks writes the bundled hook manifest (absolute script paths, reusing the codex-hooks merge engine) to DSH_HOME/agentmemory.hooks.json and appends a second patch row pointing the bridge at it. Auto-capture on SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop; PreCompact is outside the bridge subset and skipped. Adapter recategorized native. MCP-only installs never touch the hooks row; --force replaces both.

* feat(pi): automated connect install into pi's auto-discovery dir

connect pi was a stub printing manual copy steps because integrations/ never shipped in the npm package. The extension source now ships (integrations/pi/ in files), and the adapter copies index.ts + security.ts into ~/.pi/agent/extensions/agentmemory/, which pi auto-discovers with no settings.json edit; /reload picks it up live. Idempotent by content compare, stale copies refresh with a backup, dry-run supported. integrations/pi is also a private local pi package (pi-package keyword, pi.extensions manifest limited to index.ts so security.ts is not loaded as its own extension, peer deps on the pi core packages) so pi install ./integrations/pi works from a checkout; never published to npm. Type import moved to @earendil-works/pi-coding-agent (upstream rename).

* fix(codex): warn that hooks need one-time TUI trust approval

Codex executes only hooks with a recorded trusted_hash in config.toml, and the Hooks-need-review approval prompt appears only in the interactive TUI. A codex exec-only workflow therefore never runs freshly installed hooks and gets no signal why. connect codex --with-hooks now warns to launch codex once and choose Trust all, and to re-approve after upgrades since the refreshed absolute paths change the hash. Verified live on codex 0.147.0: before trust, exec dispatched nothing for agentmemory hooks; after TUI approval, SessionStart and UserPromptSubmit fired and the observation landed in the daemon.

* feat(pi): capture parity for the pi extension

Session registration on session_start (ordered after the health check so it fires on the first session of a fresh process), prompt capture with client-side dedup and user-channel provenance, per-tool observations from tool_result with AGENTMEMORY_TOOL_OBSERVE=0 opt-out, turn slices raised to 8000, memory_save scoped to the current project, session end plus one consolidate run on real quit only (no client summarize: session/end already fans out the summary), health accepts status ok, and refreshStatus binds the status setter before awaiting so a session replacement mid-check cannot throw a stale-context error. Live-verified on pi 0.84.2 with a local model: prompt and turn observations landed and the session closed as completed on quit.

* chore: regenerate skill reference docs

npm run skills:gen after the adapter, env, and tool changes: 20 adapters including dsh, refreshed env defaults, tool listing.

* refactor: trim oversized comments to constraint one-liners

Connector and extension comments compressed to the constraints the code cannot show; narrative headers, source citations, and restated behavior removed.

* docs(changelog): fold unreleased into the 0.9.29 release section

This branch ships as 0.9.29 (npm latest is 0.9.28; the previous 0.9.29 section was prepped but never published). One section, dated 2026-08-15, upgrade notes preserved, all 44 bullets intact.

* docs(readme): interactive-first install, dedupe, refresh stale counts

Install leads with npx and the first-run wizard (agent multi-select, provider pick, global-install offer) instead of six manual commands; Windows, EACCES, npx-cache, and iii-pin notes collapse into details blocks. Quick Start drops the duplicated install prose for an everyday-commands list. Nav drops the redundant iii Console link. Gist badge updated to the live 1.6k stars / 230 forks; test count pill and alt text updated to 1,648.

* fix: apply review round — ranking, indexes, lifecycle, connectors

Hybrid scoring normalizes once per query by the best attainable weighted score over streams that produced results, so configured stream weights survive single-stream hits; expansion merge gets the same deterministic tie-break. Graph functions register unconditionally (keyless installs previously fired mem::graph-extract at an unregistered function every session end) and the trigger goes through fireVoid; heuristic edges accumulate observation provenance for repeated pairs instead of dropping it. Supersession candidate search waits for the memory index walk (new isMemoryIndexReady signal) instead of trusting idx.size, and mem::search falls back to keyword search when the hybrid ranker throws. Lesson recall over-fetches under project/confidence filters, refreshes the index entry when reinforcement changes indexed text, and resetLessonIndex clears the cache after import and replay write lessons directly. Observe preserves primitive payloads in the dedup key so distinct prompts never collapse (regression test added). pi extension dedups prompts per session and passes project on both smart-search calls. dsh reads a corrupt hooks manifest as absent via readJsonSafe; pi install returns skipped instead of throwing when the bundled source is missing; both use the shared writeTextAtomic. Docker-mode stop clears each pidfile/state only after its shutdown succeeded and matches compose services at any indentation. Viewer livez fetch gets a 5s timeout. opencode session.deleted prunes through pruneSessionMaps (was leaking sessionProjects). MiniMax MAX_TOKENS doc says the real 4096 default. README MCP catalog: base-tools table completed to the registry's 14, the 8-tool core mode and 7-tool standalone fallback distinguished, two missing resources listed. Tests restore env vars without writing the string undefined, similarTo assertions are unconditional, vitest test home is unique per run, website meta regenerated, deprecated word-break replaced.

* docs: competitors refreshed — TencentDB Agent Memory column, entrants

TencentDB Agent Memory (TencentCloud OSS, May 2026, 22K stars) gets a full column: team memory hub captured through an LLM proxy, four asset types, PersonaMem 76% self-reported, Docker Core+Hub+Proxy stack. Stale star counts refreshed against the live API (mem0 58K to 63K, Letta 24K, Khoj 36K, supermemory 29K). A newer-entrants table covers Zep/Graphiti, Cognee, LangMem, Cloudflare Agent Memory, and Memobase, with matching choose-if sections in benchmark/COMPARISON.md. Section badge subtitle updated.

* fix: lesson index build races, rebuild ready flag, pi file backups

* docs: drop competitor links from README

* Update README.md
…ohitg00#1211)

* fix: negotiate MCP protocolVersion instead of hardcoding 2024-11-05

* docs: sync 11 README translations with v0.9.29 English rework

* feat: memory-discipline and lesson skills for proactive memory use

* fix: bump remaining skill-count claims to 17

* fix: mobile install-box overflow and stale compare counts

* chore: regenerate website meta snapshot

* fix: honest compare benchmarks and scrollable mobile table

* docs: refine lesson skill wording and context block copy

* fix: compare table reads generated meta, focusable scroll region

* fix: render each lesson as a single context line
…#1213)

* feat: cursor marketplace plugin with native hooks and mcp config

* fix: cursor payload compat and transcript prompt backfill in hooks

* fix: plugin-root hook paths, backfill ordering, session-id fallbacks

* docs: cursor plugin rows in readme, translations, and changelog

* fix: cursor native-plugin card, broken agent logos

* chore: sync openclaw and hermes plugin manifest versions

* docs: openclaw hook permission and hermes tool count

* chore: clawhub compat metadata for openclaw plugin

* docs: tested openclaw and hermes install rows in readme
* feat: devin support replacing windsurf

* feat: devin cli adapter, plugin manifest, and hook payload compat

* fix: stale tool counts in translations and cwd validation
* fix(cli): anchor engine cwd and rewrite bundled config with absolute paths

The bundled iii-config.yaml uses cwd-relative paths and the engine was
spawned without a cwd, so on global and npx installs ./data/state_store.db
and ./data/stream_store landed in whatever directory the user ran the CLI
from, and the iii-exec supervision block (src/**/*.ts watch, node
dist/index.mjs exec) never resolved, meaning the engine never supervised a
worker and nothing respawned it after the in-process worker died. That
surfaced as all data gone reports against a live REST port.

startIiiBin now prepares the launch: when the resolved config is the
bundled one it writes ~/.agentmemory/iii-config.runtime.yaml (regenerated
each boot) with absolute data paths under ~/.agentmemory/data and an
absolute node exec line for the installed worker entry, copies any legacy
./data stores from the invocation directory on first run, and spawns the
engine with cwd anchored at ~/.agentmemory. Repo checkouts keep the cwd
config and repo-root cwd, so dev behavior is unchanged. User overrides
via env or ~/.agentmemory/iii-config.yaml are passed through verbatim.

agentmemory remove gains a plan item for the generated runtime config.

Covered by test/engine-launch.test.ts including a drift guard that
rewrites the repo's real iii-config.yaml and asserts no relative paths
remain.

* fix: make fresh installs portable and persistent

* docs: refresh generated config reference
* chore(engine): pin iii-sdk and engine at 0.19.7

Move the iii-sdk dependency and the pinned iii-engine from 0.11.2 to
0.19.7, the last engine before the 0.20 SDK reorganization. It carries
the upstream route-ownership fix, so /agentmemory/* no longer answers
404 after the engine reconnects (rohitg00#1013).

Engines from 0.19.4 persist each builtin worker's config block into
data/configuration on first boot and ignore the config file afterwards,
which made --port, --instance and data-dir changes silently ineffective.
The CLI now clears those persisted entries before every engine spawn so
the runtime config rendered from the environment is the seed each time.

Also: agentmemory upgrade pins the SDK to the same constant instead of
a hardcoded version, Dependabot ignores iii-sdk, and every pin mention
in docs, translations, deploy templates, the eval harness and
.env.example is updated.

* fix(cli): harden the engine pin follow-ups from review

agentmemory upgrade now pins iii-sdk to the version this package was
built against instead of whatever AGENTMEMORY_III_VERSION overrides the
engine to. A persisted builtin config entry that exists but cannot be
removed is surfaced as a warning naming the directory, rather than
silently leaving the engine on stale ports; a test covers it.

The bundled docker-compose.yml keeps the engine's persisted builtin
config on a tmpfs so every container start re-seeds from config.yaml
and the III_* env vars, matching the native CLI path.

The deploy templates go back to the engine pair of the published npm
package; they move together with AGENTMEMORY_VERSION at release time.

* fix(index): persist the search snapshot continuously and bound worker shutdown

The BM25/vector snapshot was written only by a graceful shutdown, after a
full rebuild, or by delete paths. Live observation, compression and memory
writes added to the in-memory index without ever scheduling the debounced
save, so a crash, SIGKILL or power loss booted the previous snapshot; the
rebuild was skipped because that snapshot was not empty, and every
observation captured since the last clean stop stayed invisible to search.
Every live add now schedules the 5 s debounced save, bulk indexing does the
same, and on boot the worker compares the loaded snapshot with each
session's observation count and re-indexes what is missing.

The SIGTERM handler awaited a state write that cannot land while the SDK
is reconnecting, so a worker whose engine had already gone never exited
and `agentmemory stop` fell through to SIGKILL. The final flush and the
SDK shutdown are now time-boxed at 4 s each with a hard exit at 8 s, open
viewer connections are closed instead of awaited, and the CLI's orphan
reap grace matches that budget.

Review follow-ups: the compose tmpfs now targets the engine image's real
working directory (/home/nonroot/data/configuration; the previous path
never received the persisted entries), a persisted builtin config entry
that cannot be removed aborts `agentmemory start` instead of launching an
engine that would ignore the requested ports, and the deploy Dockerfiles
refuse to build when III_VERSION and III_SDK_VERSION differ.

Verified against the containerized 0.19.7 engine: SIGKILL 1 s after an
observation is healed by the boot reconcile, SIGKILL 8 s after is covered
by the debounced save, SIGTERM with the engine stopped exits in about 5 s
instead of hanging, no persisted config survives a container restart, and
the Fly image builds with matching versions and fails with mismatched ones.

* fix(index): replace on re-add, widen the boot reconcile, surface SDK shutdown errors

SearchIndex.add on an id that is already indexed now removes the old
document first. Before, the entry was overwritten but the old postings
and the old term count stayed behind, which skewed BM25 scoring every
time compression replaced a synthetic observation under the same id, and
would have done the same for a reconcile racing a live write. The boot
reconcile also treats a session whose observationCount is 0 or missing
as unknown and reads it instead of skipping it, and re-checks membership
right before it indexes what it collected.

settleWithin no longer turns a rejected promise into a successful
settlement; the SDK shutdown call site logs the failure and still exits.

* fix(cli): clear persisted builtin config under a custom configuration directory

The engine's configuration worker accepts an fs adapter directory; a
custom engine config that sets it makes the engine persist the builtin
entries there instead of data/configuration, so the CLI's cleanup missed
them and the rendered ports were ignored on the next start. The cleanup
now reads the configuration worker block of the rendered runtime config
and clears that directory too, resolved against the engine working
directory the way the engine resolves it.

* fix: stop the viewer listener before dropping its connections on shutdown

closeAllConnections ran before close, so a request accepted in between
kept the shutdown waiting on a connection nothing was going to drain.
The listener now closes first and the open connections are dropped
while it winds down.
* chore(engine): move iii-sdk and the engine pin to 0.22.1

Stage 2 of the engine upgrade, on top of 0.19.7. The 0.20 SDK
reorganization renames the client handle (ISdk to IIIClient) and moves the
buffered HTTP request type to @iii-dev/helpers/http (ApiRequest to
HttpRequest); those are the only source changes the SDK needs, so helpers
becomes a pinned dependency next to iii-sdk and `agentmemory upgrade` pins
both.

Engine 0.22.1 persists each builtin worker's config under config/ in its
working directory instead of data/configuration/, so the pre-spawn cleanup
now covers the engine cwd, the directory of the runtime config file, and
the legacy location, for both the prefixed and the unprefixed entry names.
The bundled compose file keeps /app/config on a tmpfs for the same reason.

The bundled configs keep the iii- prefixed builtin names: on 0.22.1 an
unprefixed http/state/queue/pubsub/cron entry resolves to the standalone
registry worker and fails to boot without iii-worker, which is the 0.23
migration, not this one. The in-engine queue stays listed explicitly as
iii-queue so durable:subscriber triggers keep working.

Verified against engine 0.22.1: standalone worker (boot, observe, search,
engine restart with REST back in 1 s, clean SIGTERM), the real CLI on a
fresh HOME (engine download, port change across restarts through the
persisted-config cleanup), a copy of a real store, the Docker compose path,
and the crash-safety and shutdown probes from stage 1.

* docs: sweep the remaining engine references for 0.22.1

Full-repo pass after the pin: the contributor guide (AGENTS.md) now names
the 0.22 client and request types and where HttpRequest is imported from;
the Python examples pin iii-sdk to the same release as the engine; the
README and its eleven translations describe the shipped observability
sampling ratio (0.1, not 1.0).

Checked and left alone: every engine function id and trigger type the
worker uses is registered by 0.22.1 (state, stream, mcp, engine::workers,
http, durable:subscriber); no workflow, script, plugin or package other
than the root package.json references the SDK or the engine version; the
"Invalid function id format: publish" line in the engine log is the
engine's own pubsub builtin at shutdown and appears on 0.19.7 as well.

* feat(cli): agentmemory console through the pinned engine

Engine 0.22 ships the iii web console as a subcommand of the engine binary
and downloads the console on first use, so the separate install prompt on
start (an engine installer piped to sh) and the skipConsoleInstall
preference are gone. `agentmemory console` resolves the pinned iii (PATH
if it matches the pin, else the private install) and runs `iii console`
against the REST, streams and bridge ports agentmemory resolved, serving
one port above the viewer by default; --console-port overrides, --port and
--instance pick the instance, other flags pass through. The ready panel
points at the command instead of a binary path or an install hint.

Verified on an isolated HOME: the console serves with the engine ports
injected, registers its functions on the agentmemory engine, and warns but
still starts when no engine answers.

* chore(engine): start the pinned engine quiet and align the deploy configs

The CLI spawns the pinned engine with --no-update-check, so a pinned
release never looks up newer releases or advisories on GitHub at boot,
and with iii's anonymous usage telemetry off unless the user exported
III_TELEMETRY_ENABLED themselves; the bundled compose file passes the
same flag and variable.

The deploy entrypoints generated sampling_ratio 1.0 with console log
output on, the combination behind the log feedback loop the bundled
config already avoids; they now ship the bundled values.

README: the "extend with one command" section listed builtins that
already ship in iii-config.yaml and linked a registry page that no longer
exists (iii-database is database); it now names the running builtins,
the current registry names, where a custom config lives
(~/.agentmemory/iii-config.yaml) and how the worker runtime is installed.
The translations only get the link fix; their prose is resynced in the
usual batch.

* docs: pin .env.example to 0.22.1 and place the engine note under the port table

.env.example still named 0.19.7 in the engine pin block and lacked
III_TELEMETRY_ENABLED next to the pin. The README paragraph about the
quiet engine start had landed above the banner; it now follows the port
table where the engine flags are described.

* docs: describe trace spans as sampled in the observability paragraph

The README and the translations kept promising a trace span for every
memory operation next to sampling_ratio: 0.1; the sentence now says every
operation emits a structured log and one in ten also carries a span.

* fix(cli): only remove engine-written config entries, and let console find every pinned iii

With a custom engine config the engine's working directory is the
config file's directory, so the persisted-config cleanup looked for the
seeded builtin names under a project's own config/ folder and would
have removed files such as http.yaml or state.yaml that belong to the
project. Every entry the engine writes starts with an `id: <worker>`
line (0.19.7 and 0.22.1 both), so the cleanup now reads each candidate
and removes it only when that line matches the file name.

agentmemory console resolved iii from PATH or the private install only;
it now walks the same candidate list as engine start, so it finds a
compatible engine from the fallback locations as well.
…00#1408)

* feat(status): GET /agentmemory/status and a viewer Health tab

One report of what is wrong with an install and how to fix it: health
monitor state and alerts, LLM and embedding providers, the circuit
breaker, functions failing on at least 20% of 5+ calls (with a
provider-specific fix for summarize, compress and graph extraction),
observations missing from the search index, graph snapshot age, ports,
uptime, the pinned engine version and every feature flag.

The missing-observation check reuses the boot reconcile scan
(findUnindexedObservations, split out of reconcileIndex), so it counts
exactly what search cannot find instead of comparing approximate
session counters. Every probe is time-boxed at 5 s.

Browsers get an HTML page with no scripts behind a strict nonce CSP;
other clients get JSON, and ?format=json|html forces either. Same
bearer auth as the rest of the API. The flag list moves into
buildConfigFlags() so config/flags and status share it, and the engine
pin moves into src/version.ts so the CLI and the status report read the
same constant.

* chore(skills): regenerate the REST reference for the new endpoint

npm run skills:check fails CI when plugin/skills/agentmemory-rest-api/
REFERENCE.md does not list every registered REST route; regenerated
with npm run skills:gen.

* fix(status): report a missing health snapshot and share one index scan

A status report with no health snapshot (none yet, or the probe timed
out) added no problem and could read ok; it now adds an info-level
health-check-unavailable finding.

Every status request started its own findUnindexedObservations scan,
and the 5 s probe timeout only stopped waiting, so repeated requests
stacked full storage scans. singleFlight() shares one in-flight scan
between overlapping requests and reuses its result for 30 s; a failed
scan is dropped so the next request retries.
… failed refresh, correct dashboard numbers (rohitg00#1407)

* fix(viewer): coalesce live reloads, keep data on failed refresh, correct dashboard numbers

Every stream event and poll tick reloaded the whole dashboard (about ten
requests each), so a burst of observations fanned out hundreds of
requests and could exhaust the browser's connection pool. Reloads are
now coalesced into one per 2 s and never overlap; live buffers on the
Timeline and Activity tabs are capped.

A refresh that fails keeps the previous panel data behind a "could not
refresh" note instead of dropping to the new-install screen, and a first
load that cannot reach the API offers a retry.

Dashboard numbers: Memories uses the API total, token savings counts
only sessions with observations, and the Graph Nodes card shows the
snapshot time. Session summaries stored as objects render as text and
comma-separated tags are split instead of breaking a tab.

GET /agentmemory/memories now sorts newest first before paging. Rebuild
Graph asks for confirmation, ignores repeat clicks and reports its
result. The live stream reconnects when the tab becomes visible again.

* fix(viewer): drive the dashboard from the live stream instead of re-fetching

The dashboard blinked because it re-fetched everything and wiped itself
to "Loading dashboard..." on a 30 s timer and on every stream event,
even while the stream was connected: 73 rebuilds and 20 requests a
minute on an idle store, 200 requests for 21 live events.

The worker now pushes session.updated and session.deleted from the
sessions state trigger, and memory.updated and memory.deleted from a new
memories state trigger, on the mem-live viewer group. The viewer applies
those and the existing session.activity events (it used to drop them by
reading evt.data instead of evt.event) to the lists it already holds,
batches redraws to one per 250 ms, and skips a redraw when the HTML did
not change. The 30 s timer is gone and no refresh path resets a loaded
view. Polling stays as the fallback when the stream cannot connect.

The stream connects with the join mode engine 0.22 serves first and
flips to the direct URL only after two failures.

* feat(viewer): explain consolidation per layer and extract procedures from sessions

Consolidation Status was three bare counters and Procedural Memory
stayed empty on almost every install. Procedures only came from a
cross-session pass that needs two pattern memories each seen in two or
more sessions, and mem::skill-extract, which turns one finished session
into a procedure, had no caller.

The consolidation pipeline now stores each run's per-tier results under
consolidation:lastPipelineRun, and GET /agentmemory/consolidation/status
turns them plus the tier inputs (summaries, recurring patterns, counts,
flags) into one status per layer: off with the setting to change,
waiting with progress, ready, active with the last run's output, or
failed with the error. The dashboard replaces the Semantic, Procedural
and Consolidation Status cards with one Memory layers panel built from
it, previewing the first items of each layer.

mem::skill-extract runs for the stopping session inside the existing
consolidation cooldown, only when consolidation is on and an LLM
provider is configured.

* chore(skills): regenerate the REST reference for the new endpoint

npm run skills:check fails CI when plugin/skills/agentmemory-rest-api/
REFERENCE.md does not list every registered REST route; regenerated
with npm run skills:gen.

* fix(viewer): keep live session and memory views consistent

Engine 0.22 reports state deletes as "state:deleted" with a null
new_value; the session trigger compared against "delete", so deleted
sessions were pushed as updates. Both state triggers now share one
delete check, and with an isolated agent scope they drop records that
belong to another agent, matching the REST filters.

In the viewer:
- a reconnect re-fetches the views that were already loaded, so changes
  made while the stream was down show up;
- session events are sequenced and replayed onto any session list
  fetched while they arrived, so a delete is not undone by an older
  response;
- observation count updates reuse the cached session detail instead of
  blanking and re-fetching it; the detail refetches in place only when
  that session's record changes or another session is selected;
- memory events coalesce into at most one memory list reload in flight,
  and only the newest memory count response is applied;
- the direct/join failure count resets on the first delivered message
  instead of on open.

* fix(viewer): honor stale retries and keep counts and rebuild notes honest

- The consolidation status endpoint listed five full state scopes on
  every request. The store has no count primitive, so overlapping
  requests now share one scan through singleFlight and reuse its counts
  for 30 s, the same bound the status page uses for its index scan.
- The "Retrying automatically" banner had no retry behind it once the
  30 s dashboard timer was removed. A stale dashboard now schedules one
  retry on its own 15 s timer, separate from the 2 s reload coalescer.
- The dashboard's memory total is applied only when no newer count
  request started while it was loading.
- A graph rebuild whose follow-up refresh fails no longer reports
  success.
- The consolidation header shows the date of the last run, not only
  the time.
…0#1409)

The memory alert divided heapUsed by heapTotal. Node sizes heapTotal
just above heapUsed and grows it on demand, so a normal process reads
90% or more, and once RSS passed the 512 MB floor the health check
raised "Memory elevated" or "critically high" with nothing wrong.

The health snapshot now records v8 heap_size_limit and the thresholds
divide by it, falling back to heapTotal for snapshots written before
this change. The viewer's Heap gauge shows used against the limit, and
the alert wording says "of the heap limit".

Fixes rohitg00#1406
Bumps [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node) from 25.9.8 to 26.6.2.
- [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases)
- [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node)

---
updated-dependencies:
- dependency-name: "@types/node"
  dependency-version: 26.6.2
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Bumps [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node) from 25.9.8 to 26.6.2.
- [Release notes](https://github.com/DefinitelyTyped/DefinitelyTyped/releases)
- [Commits](https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node)

---
updated-dependencies:
- dependency-name: "@types/node"
  dependency-version: 26.6.2
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
* fix(audit): make index_persist audit entries opt-in

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

* test(audit): isolate the index_persist gate tests from the ambient env

AGENTMEMORY_* variables are documented as living in ~/.agentmemory/.env,
so the suite can inherit AGENTMEMORY_AUDIT_INDEX_PERSIST from a
configured machine. The default-off case then ran with auditing on and
failed, and afterEach deleted whatever value the developer had set.

Capture and restore around each case, and cover the whole vocabulary the
parser accepts — trimmed and case-insensitive 1/true — plus the values an
operator would reach for to turn it off.

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

---------

Signed-off-by: Dmitrii Zhukov <dmitry0983@gmail.com>
…ohitg00#1415)

* perf(index): throttle index saves and report each leg's save state

Every observation, compression and memory save scheduled a full index
save 5 s later, and each save re-serializes the whole BM25 and vector
index and rewrites every shard. On a busy store that is a full index
rewrite almost continuously.

Saves now run at most once per AGENTMEMORY_INDEX_SAVE_INTERVAL_MS
(default 10 minutes), measured from the start of the previous save.
Explicit saves (deletes, shutdown) still run immediately. Only one save
runs at a time; saves requested while one is running collapse into a
single follow-up save.

The BM25 and vector saves now fail independently. Before, a BM25
failure skipped the vector save in the same run and both were reported
as one warning. Each leg records when it last saved, its last error,
since when it has unsaved changes, and its serialized size.

/agentmemory/status reports a failing leg as an error, unsaved changes
older than twice the interval as a warning, and a vector index above
80% of the Node.js string limit (536,870,888 characters) as a warning,
since past that limit the index can no longer be saved or loaded. The
status page shows each leg's save state and the vector index size.

* chore: credit co-authors

The per-leg save failure handling and the single save queue build on
the fix in rohitg00#1256. The problem was measured and reported in discussion
rohitg00#1358.

Co-authored-by: Omar Gerardo <omargrard@gmail.com>
Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>

* fix(index-persistence): snapshot dirtyEpoch per leg before serializing

runSave() captured one dirtyEpoch before the BM25 leg's write and reused
it for the vector leg's dirty check. When scheduleSave() ran while the
BM25 write was in flight, the vector leg would serialize the current
(already up to date) state but still compare against the stale epoch,
leaving vector.dirtySince set even though the just-written snapshot
already reflected the change. status() would report the vector leg as
dirty until an unrelated follow-up save cleared it.

saveLeg() now snapshots dirtyEpoch itself, immediately before invoking
the leg's own serialize+write callback, so each leg judges its dirty
state against the epoch as of its own write rather than one captured
before an earlier leg ran.

Added a regression test that gates the BM25 manifest write, triggers a
scheduleSave() while it is held, and asserts the vector leg's
dirtySince clears once its own write completes.

---------

Co-authored-by: Omar Gerardo <omargrard@gmail.com>
Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>
…tent (rohitg00#1416)

* perf(index): throttle index saves and report each leg's save state

Every observation, compression and memory save scheduled a full index
save 5 s later, and each save re-serializes the whole BM25 and vector
index and rewrites every shard. On a busy store that is a full index
rewrite almost continuously.

Saves now run at most once per AGENTMEMORY_INDEX_SAVE_INTERVAL_MS
(default 10 minutes), measured from the start of the previous save.
Explicit saves (deletes, shutdown) still run immediately. Only one save
runs at a time; saves requested while one is running collapse into a
single follow-up save.

The BM25 and vector saves now fail independently. Before, a BM25
failure skipped the vector save in the same run and both were reported
as one warning. Each leg records when it last saved, its last error,
since when it has unsaved changes, and its serialized size.

/agentmemory/status reports a failing leg as an error, unsaved changes
older than twice the interval as a warning, and a vector index above
80% of the Node.js string limit (536,870,888 characters) as a warning,
since past that limit the index can no longer be saved or loaded. The
status page shows each leg's save state and the vector index size.

* perf(index): store vectors in fixed buckets and rebuild BM25 from content

The vector index was persisted by serializing every vector into one
JSON string, cutting that string into shards and writing a new
generation of all shards on every save. Node.js cannot hold a string
longer than 536,870,888 characters, which a 2,048-dimension index
reaches near 49,000 vectors; past it the index can no longer be saved
or loaded, silently. Each save also rewrote the whole index.

Vectors now live in a fixed set of state scopes (256 by default,
AGENTMEMORY_VECTOR_BUCKETS), chosen by a stable hash of the id, with
one key per vector holding its id, session and base64 embedding. The
index tracks which ids were added or removed since the last save, and a
save writes or deletes only those keys, then updates a small metadata
record. Loading lists the bucket scopes one at a time. Nothing builds a
string of the whole index, and scope names never change between saves.

One key per vector, rather than one packed value per bucket: the iii
file store rewrites a whole scope when any key in it changes, so both
layouts cost the same on disk per flush (one bucket scope, 1/256 of the
index). Per-key writes avoid re-encoding a whole bucket in the worker
for every changed vector, a single added vector is exactly one state
write, and a failed write retries only that vector.

BM25 is no longer persisted. It is rebuilt at boot from stored
observations and latest memories, the same documents the live paths
index. A 3,000-document rebuild takes about 120 ms in the unit test;
real boots add the engine round-trips for one list per session, and the
boot log now reports the rebuild time. The rebuild also drops entries
for content that no longer exists. Documents added after the last
vector save that have no vector are embedded in the background; when no
vector state was ever saved, every document without a vector is.

Existing installs migrate on first boot: the old sharded or monolithic
vector snapshot is read once, written into buckets, and only then are
the old vector and BM25 shards and manifests removed. If the old
snapshot cannot be read it is left untouched. If writing the buckets
fails, the old snapshot stays and the next save finishes the job. No
vector is lost and nothing is re-embedded. Changing the bucket count
moves vectors to their new buckets on the next boot.

The dimension-mismatch guard is unchanged; when
AGENTMEMORY_DROP_STALE_INDEX discards persisted vectors, the next save
now deletes them from storage too.

The status page drops the string-size warning, which no longer applies,
and shows the bucket count and unsaved vector changes.

* chore: credit co-authors

The per-leg save failure handling and the single save queue build on
the fix in rohitg00#1256. The problem was measured and reported in discussion
rohitg00#1358.

Co-authored-by: Omar Gerardo <omargrard@gmail.com>
Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>

* chore: credit co-authors

The string-limit and whole-generation rewrite analysis comes from
discussion rohitg00#1358; the reclaim work in rohitg00#1256 mapped the generation
lifecycle this replaces.

Co-authored-by: Omar Gerardo <omargrard@gmail.com>
Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>

* fix(index-persistence): snapshot dirtyEpoch per leg before serializing

runSave() captured one dirtyEpoch before the BM25 leg's write and reused
it for the vector leg's dirty check. When scheduleSave() ran while the
BM25 write was in flight, the vector leg would serialize the current
(already up to date) state but still compare against the stale epoch,
leaving vector.dirtySince set even though the just-written snapshot
already reflected the change. status() would report the vector leg as
dirty until an unrelated follow-up save cleared it.

saveLeg() now snapshots dirtyEpoch itself, immediately before invoking
the leg's own serialize+write callback, so each leg judges its dirty
state against the epoch as of its own write rather than one captured
before an earlier leg ran.

Added a regression test that gates the BM25 manifest write, triggers a
scheduleSave() while it is held, and asserts the vector leg's
dirtySince clears once its own write completes.

* fix(index): close vector-index safety gaps from PR review

Guard rebuildKeywordIndex's sessions listing with a retried helper instead
of a bare kv.list call; a failure now reports an incomplete BM25 rebuild
on status instead of throwing. mem::search's cold-start path now calls
rebuildKeywordIndex instead of rebuildIndex, so a query against an empty
index can never clear or re-embed the persisted vector index; only an
explicit dimension mismatch at boot still drops vectors.

Gate the vector backfill so a whole-store embed never starts silently:
AGENTMEMORY_VECTOR_BACKFILL=all is required when there is no prior save
to catch up from, backfills are capped per boot by
AGENTMEMORY_VECTOR_BACKFILL_MAX (default 500), the pending count is
reported on /agentmemory/status, and backfillVectors now saves progress
every few batches so a restart does not repeat finished embedding work.

On load, compare the vector count actually read against the count the
last save recorded; a shortfall is reported on status and falls back to
a bounded backfill for the missing ids instead of trusting the saved
timestamp. Meta is still written only after every bucket write of a
save succeeds.

Replace hash-mod-N vector bucketing with fill-and-roll: every vector's
bucket is tracked in memory, built by reading all known buckets at load;
new vectors fill the current open bucket up to
AGENTMEMORY_VECTOR_BUCKET_SIZE (default 500) before a new bucket opens,
and updates/deletes go straight to a vector's existing bucket. A save
under load now touches only the buckets it actually changed instead of
rewriting the whole store, and a bucket-size change no longer requires
moving existing data. Migration from the pre-PR sharded/monolithic
format is unchanged; the hash-bucket layout from this PR's earlier,
unreleased commit is dropped rather than migrated.

Tests: sessions-listing failure keeps vectors untouched and marks the
rebuild incomplete; whole-store backfill opt-in and per-boot cap;
partial bucket set detected against the saved count; a save spread over
several waves of adds touches only the open bucket; deletes touch only
the owning bucket; migration from the old sharded format still passes.

* fix(index): remove legacy BM25 shards when missing keys read back undefined

The engine SDK returns undefined for a missing key. The legacy cleanup
treated undefined as a failed read and returned early, so after
migration the old BM25 shards and manifest stayed in the store for
good. Both legacy cleanups now read through readIndexValue, which only
reports failure when the read throws.

---------

Co-authored-by: Omar Gerardo <omargrard@gmail.com>
Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>
)

* perf(consolidation-pipeline): skip decay writes for unchanged memories

The decay tier of mem::consolidate-pipeline listed every semantic and
procedural memory and wrote every row back on every run, even when
applyDecay left the strength untouched (the common case for anything
not yet due for decay). Each write is a full state::set RPC and marks
the whole scope dirty for the engine's next flush, so this scaled with
total memory count on every consolidation cycle regardless of how much
actually decayed.

Capture each item's strength before calling applyDecay and only call
kv.set for items whose strength changed by more than a small float
tolerance, mirroring the dirty-only pattern already used by
mem::lesson-decay-sweep. applyDecay itself is unchanged, so the decay
trajectory over time is identical to before; only the redundant no-op
writes for untouched rows are removed. results.decay now reports
scanned/written counts per tier instead of just the row count.

Added tests covering: unchanged rows are not written, changed rows are
written with correct scanned/written counts, and decay progression
across simulated time lands at the same strengths as the unconditional
write path did.

* perf(consolidation): write decayed rows one at a time

The first decay run after an upgrade can find most rows due at once.
Writing them all in parallel would fire that many state::set calls at
the engine together, where they queue behind its single store lock.
Sequential writes keep the load the same shape as before.

* test(consolidation-pipeline): assert persistence at each decay step

The simulated-time decay test only checked kv.list()[0].strength, but
mockKV.list returns live object references that applyDecay mutates in
place. That let the assertions pass even if a kv.set write were
skipped, since the in-memory object already reflected the mutation
regardless of persistence. Spy on kv.set and assert exactly one
semantic write after the 45-day step and a second after the 95-day
step, so a missed persistence write would actually fail the test.

* fix(consolidation): decay at most once per period

applyDecay recomputed daysSince from lastAccessedAt on every pipeline
run, and lastAccessedAt never advances, so each run re-applied the
0.9^periods factor to the already-decayed strength. With the default
consolidation cooldown this compounded a month-old fact down to the
0.1 floor within hours of active use instead of over months.

Track lastDecayedAt on semantic and procedural rows and anchor the
next decay check to max(lastAccessedAt, lastDecayedAt), only applying
another decay step once decayDays have passed since that anchor. Rows
without the field decay once, same as before, and get it set. Updated
the simulated-time test to assert once-per-period decay (including a
run inside the same period that must not write) instead of pinning
the old compounded value.
…payload (rohitg00#1422)

api::export always returned status_code 200, even when mem::export
detected the response would exceed the transport frame limit and
returned its {success:false, oversized:true, ...} refusal object
instead of the export data. A caller checking only the HTTP status
saw a normal successful export and could write out the tiny refusal
object as if it were a real backup.

Detect the refusal shape in the api::export trigger and return 413
with the refusal body, matching the pattern api::mesh-export already
uses for the same guard. mem::export itself is unchanged: it still
returns 200 for a real export and the refusal object for an oversized
one, the HTTP layer just now reports the right status.

The MCP standalone proxy's memory_export path called handle.call(),
which throws on any non-2xx response and let the generic proxy-error
handler in handleToolCall silently fall back to local in-memory KV
data, masking the refusal behind a small, unrelated response instead
of surfacing it. rest-proxy.ts now throws a ProxyCallError carrying
the parsed response body, and the memory_export case in standalone.ts
returns that body directly instead of letting it fall through to the
local-KV fallback. Every other proxied tool keeps its existing
fallback-on-error behavior unchanged.

The viewer does not call /agentmemory/export, so no viewer change is
needed. mcp/server.ts's in-process memory_export handler calls
mem::export directly and always wraps the result as MCP text content
regardless of shape, so it already surfaces the refusal and needed no
change.
…ohitg00#1423)

* perf(remember): move the embedding call out of the mem:remember lock

mem::remember wrapped its whole body in withKeyedLock("mem:remember", ...),
including the vectorIndexAddGuarded call, which makes a network round-trip
to the embedding provider. Every save serialized behind that network call,
so two unrelated saves that happened to land at the same time queued
behind each other's embedding latency even though they touch different
memory ids and do not conflict.

Split mem::remember so the locked callback covers only the read-dedup-write
critical section (candidate generation, Jaccard supersede check, the
memory's KV writes, and the BM25 index update) and returns the saved
memory. The embedding call, the mem::cascade-update fire-and-forget
trigger, and the final log line now run after the lock releases, using
the memory the locked section already wrote.

Dedup/supersede correctness is unchanged: two concurrent saves for
identical content still serialize on the read-dedup-write section (that
part is still inside the lock), so the second call's candidate scan still
sees the first call's already-written memory and correctly supersedes it.
Only the embedding network call, which never reads or writes the
supersede state, moved outside.

Added test/remember-lock-scope.test.ts: one test with a slow fake
embedder proves two concurrent saves' embed calls overlap in wall time
instead of serializing, and one test proves two concurrent saves of
identical content still dedup correctly (first becomes v1, second
supersedes it as v2) even with the slow embedder in place.

* fix(remember): keep superseded memories out of the vector index

The embedding call for a saved memory runs outside the mem:remember
lock so concurrent saves can overlap. If a second save supersedes the
first memory while its embedding is still pending, the pending vector
add could finish after the supersede's vectorIndexRemove call and put
the superseded memory back into the vector index.

Move the final vector-index write into the same mem:remember lock the
supersede path already uses, guarded by a fresh isLatest check read
right before the write. The embedding computation itself stays outside
the lock, so concurrent saves still overlap on the slow part; only the
cheap check-and-write is serialized against supersession.

Added a test that races two identical concurrent saves with a slow
embedder and asserts the superseded memory's id never lands in the
vector index.

* perf(remember): schedule an index save after the vector commit and split failure logging

The deferred vector-index add scheduled no index save after it landed,
so if the embedding call outlasted the 5s debounce window from the
earlier BM25 add, the just-added vector could sit unsaved until some
unrelated write happened to reschedule it. Call scheduleIndexSave()
right after the commit's vector-index add.

vectorIndexAddGuarded ran the deferred commit callback inside the same
try/catch as the embedding call, so a failure in the commit (for
example the KV read that rechecks isLatest) was logged as "embed
failed" with the embedding provider's name, which is misleading when
diagnosing a KV problem. The embed call and the commit callback now
have their own try/catch with distinct log messages.

Added a test for each: one confirms scheduleIndexSave is called again
after the vector commit resolves, the other confirms a throwing commit
callback is logged as a commit failure, not an embed failure.

Also addressed the review's flaky wall-clock assertion in
remember-lock-scope.test.ts: dropped the elapsed-time bound and kept
the start/end cross-check assertions, which already prove the two
embeds overlapped without depending on machine timing.
* perf(patterns): bound mem::patterns to the most recent sessions

mem::patterns listed every session in the store and then issued
kv.list(KV.observations(id)) once per session with no bound at all
when the caller omitted project (the MCP tool's default call shape).
On a large store this is the N+1 issue rohitg00#1226 measured directly: a walk
of 97,385 observations that killed the invocation after ~3s and took
the whole iii worker down with it.

Add an optional limit (default 50, max 500, clamped) and sort sessions
by startedAt before slicing, so the project filter (when given) narrows
the pool first and the recency limit then bounds it to the most recent
sessions instead of every session ever recorded. The batched kv.list
fan-out (already bounded to 10 concurrent sessions per batch) also now
tracks total observations scanned and stops issuing further batches
once MAX_OBSERVATIONS_SCANNED (5,000) is crossed, so one huge session
inside the session limit can't still blow the invocation timeout.

The response now reports sessionLimit, sessionsInScope, sessionsProcessed,
and observationsScanned so a caller can see when it was bounded.

MCP tool contract stays backward compatible: memory_patterns gets one
new optional limit property in tools-registry.ts (existing callers that
don't pass it get the same bounded-by-default behavior), the server.ts
handler passes args.limit through, and api::patterns's request type
picks up the same optional field (it already forwarded the whole POST
body, so no behavior change there beyond the new field being honored).
Regenerated plugin/skills/agentmemory-mcp-tools/REFERENCE.md via
npm run skills:gen to pick up the new tool parameter.

Added test/patterns-session-bound.test.ts: default-to-50, explicit
limit, clamp to 500, project filter applied before the recency limit,
recency direction (the most recent sessions are scanned, not the
oldest), and the MAX_OBSERVATIONS_SCANNED early stop within an
under-limit session count.

* chore(patterns): drop an inline comment

* fix(patterns): bound the session limit and per-session observation work

A positive fractional limit (e.g. 0.5) passed the finite/positive check
in resolveSessionLimit but then floored to zero, silently returning an
empty session slice. Clamp the floored value to at least 1. The MCP
tool schema for mem::patterns' limit now declares "integer" instead of
"number" so clients validate the input shape up front.

The observation budget was only checked between batches of 10 session
loads, so a single session with far more observations than
MAX_OBSERVATIONS_SCANNED still had its full observation list processed
before the next check could trip. The per-session loop now checks the
running budget before processing each loaded session and truncates a
session's observations to the remaining budget, so processing work
cannot exceed the configured cap even when one session is unusually
large. The parallel batch read itself is unaffected: kv.list/state::list
has no bounded-read primitive to limit the fetch size, so the initial
load for sessions already in flight in a batch is not shrunk; only the
downstream CPU work is capped.

* perf(patterns): skip oversized sessions before listing them

mem::patterns bounded per-session observation processing with
MAX_OBSERVATIONS_SCANNED, but still called kv.list on every session in
a batch before applying that bound. A single session that alone
exceeds the remaining budget was still pulled whole in one frame,
which is exactly the failure mode (a worker drop on an oversized
frame) the budget was meant to prevent for rohitg00#1226-sized stores.

Use the Session.observationCount already tracked on every observe to
skip a session's kv.list entirely when its count exceeds the batch's
remaining budget, and report the skipped session ids as
sessionsSkipped in the result instead of silently dropping them.

Also accept a missing payload on mem::patterns (data ?? {}) so callers
that omit project/limit do not throw.

* fix(api): whitelist the patterns request body

api::patterns forwarded req.body straight into sdk.trigger, against
the project rule that REST endpoints must whitelist fields instead of
passing the raw request body to sdk.trigger(). mem::patterns only
reads project and limit, so the exposure was latent, but a bodyless
POST also threw once mem::patterns started reading data.limit before
this fix, since req.body was undefined and nothing defaulted it.

Build the payload explicitly from req.body?.project and
req.body?.limit so unexpected fields never reach mem::trigger and a
missing body no longer errors.

* perf(patterns): fill each batch only up to the remaining observation budget

Each session was checked against the whole remaining budget on its own, so
a batch of ten sessions that each fit could still list up to ten times the
budget in parallel. A batch now takes sessions in recency order only while
their combined observationCount fits the remaining budget; the next batch
continues from there, and a session larger than the remaining budget is
still skipped without being listed.
…1421)

* fix(state): close the KV.sessions concurrent read-modify-write race

Every whole-object writer to KV.sessions (api::session::start,
event::session::started, api::session::commit, plus the bulk import
paths in migrate/snapshot/replay/export-import) read the session,
mutated a local copy, and wrote it back with no lock, or with a lock
under a different namespace than mem::observe's obs:${sessionId}.
A concurrent kv.update from observe (or from any other writer) landing
between the read and the write got silently reverted by the later
whole-object set.

Route every session mutation through the same obs:${sessionId} keyed
lock observe.ts already uses, so no two writers can interleave a
read against a write for the same session. api::session::commit keeps
its get-then-set shape (it needs the current commitShas to dedupe) but
now shares the lock namespace instead of its own session:${sessionId}
key, which also keeps it compatible with the pending session::end lock
in PR rohitg00#1252. session::end and event::session::ended already mutate via
kv.update path ops, which the engine applies atomically per call, so
they are left as-is.

Adds test/session-kv-races.test.ts, which reproduces the lost-update
race deterministically (a gated mock KV that pauses a read mid-flight
so a concurrent writer can land in between) and fails on main before
this change.

* fix(graph): serialize persistGraphDelta so concurrent extracts cannot duplicate nodes

persistGraphDelta read the graph snapshot once, resolved each node/edge
through the name/edge index with a get-then-set (no lock anywhere in
graph.ts), and wrote the accumulated snapshot back once at the end.
Two concurrent mem::graph-extract calls (routine when session-stops
land within seconds of each other) could both miss the same name-index
key and each create their own node for the same (type, name) pair, or
both merge into the same existing node from a stale copy and drop one
side's sourceObservationIds, or overwrite each other's snapshot stat
deltas.

The node/edge keys aren't known until the name/edge index lookup
resolves, and the snapshot is a single shared aggregate mutated
in-memory across the whole batch, so a per-key lock alone would still
let two batches race the aggregate snapshot write. Serialize the whole
function body behind one graph:persist keyed lock instead, matching
mesh.ts's existing per-item locking style for the parts that are
per-key. graph-import.ts's structural importer calls the same
function, so it gets the same protection for free.

Adds test/graph-extract-concurrency.test.ts: two concurrent
persistGraphDelta calls for the same (type, name) key must not create
duplicate nodes, and two concurrent merges into an existing node must
not lose either batch's sourceObservationIds. Both fail on main before
this change.

* fix(graph): serialize graph-row writers outside persistGraphDelta on graph:persist

persistGraphDelta already serializes mem::graph-extract under the
graph:persist keyed lock, but temporal extraction, mesh sync,
export/import, snapshot restore, and cascade-update all read and wrote
KV.graphNodes/KV.graphEdges without it. A concurrent call from any of
these paths could overlap persistGraphDelta's read-modify-write and
drop the loser's changes.

Route each of those write paths through the same graph:persist lock
(sibling acquisitions, never nested, since withKeyedLock is not
re-entrant): temporal-graph-extract's merge loop, mesh's
lwwMergeGraphNodes and a new lwwMergeGraphEdges (replacing the generic
per-item lock for graph edges), export/import's graph delete and
import loops, snapshot-restore's graph node writes, and
cascade-update's stale-flag writes (which now also re-read the latest
row inside the lock before writing, instead of writing back the
pre-lock in-memory copy).

Snapshot/index maintenance (name index, edge index, degree, the
graph:snapshot cache) is still only performed by persistGraphDelta and
the explicit rebuild/reset functions; that gap predates this change
and is out of scope here. This commit only closes the lost-update race
on the raw node/edge rows.

Added test/graph-cross-path-locks.test.ts, which races
persistGraphDelta against mem::cascade-update on the same node and
asserts both the merge and the stale flag survive.

* fix(state): close remaining session and graph lock gaps from review

Session end (api::session::end and event::session::ended) wrote
endedAt/status with an unlocked kv.update, so the locked commit linker
could still read-modify-write the session row around it and revert the
end. Both now take the obs:${sessionId} lock, the same key the commit
linker and observe use, so the two orderings serialize instead of
racing.

Session start (api::session::start and event::session::started) built
a fresh row and blind-set it under the lock, so if observe's implicit
create had already landed, start would reset observationCount to zero
and drop firstPrompt/summary/commitShas. Both now read the existing
row inside the lock and merge onto it, keeping observationCount,
commitShas, and firstPrompt/summary when the incoming request does not
explicitly supply them.

Graph import/delete (mem::import) took the graph:persist lock once per
item inside the 20-wide chunked loop, which serialized the four graph
node/edge import and delete loops down to one operation at a time.
Each of the four loops now takes graph:persist once for the whole
loop, restoring the chunk's intended concurrency.

mem::graph-reset and mem::graph-snapshot-rebuild wrote the graph
snapshot without the graph:persist lock, so a reset could race a
concurrent extract's read-modify-write of the same snapshot and lose
resetAt (breaking the post-reset orphan check) or a rebuilt count.
Both writes now take graph:persist.

The graph-cross-path-locks regression test gated the name-index read
inside persistGraphDelta, which lets cascade's write land and then be
silently re-merged back to the correct value, so the test passed even
without the fix it was meant to guard. Moved the gate to the node-row
read, the point the lost update actually depends on; verified it now
fails on origin/main and passes on this branch.

Added a session-kv-races test for api::session::commit racing
api::session::end, and a sequential test for api::session::start
running after mem::observe's implicit create, covering the merge
behavior above.

* fix(graph): hold graph:persist for the whole snapshot rebuild

mem::graph-snapshot-rebuild listed nodes and edges and backfilled the
name, edge-key and degree indexes outside the lock, and took
graph:persist only for the final snapshot write. A delta that committed
between the listing and that write was overwritten by a snapshot built
from the older lists, and the backfill could reset degree counters the
delta had just raised.

The listing, index backfill and snapshot write now run in one
graph:persist critical section, so an extract either lands before the
rebuild lists or waits until it finishes. Nothing inside the section
takes the lock again.

The new concurrency test pauses the rebuild's node listing, commits a
delta meanwhile, and checks that the final snapshot holds both nodes.
It fails without this change.
…p index (rohitg00#1418)

* perf(context): add per-project recent-sessions index

mem::context listed the entire mem:sessions scope on every session
start to find one project's 10 most recent sessions, then discarded
everything else. The iii file store rewrites and clones a whole scope
on every list, so this cost grows with total sessions across every
project, forever, on the highest-frequency path in the product.

Add a small per-project index (scope mem:idx:project-sessions, one key
per project) holding up to 50 recent session ids and startedAt
timestamps, capped and sorted newest-first. Maintain it wherever a new
session is written: event::session::started, api::session::start, the
implicit session create in mem::observe, and mem::import; remove
entries wherever a session is deleted: mem::evict, mem::forget, and
the bulk replace path in mem::import.

mem::context now reads the index and kv.get's only those sessions
instead of listing the whole scope. If a project has no index yet, it
falls back to the previous full-list behavior once and writes the
index from that result so subsequent calls stay bounded.

* perf(smart-search): add sharded obsId -> sessionId reverse index

findObservation's fallback path (used by memory_smart_search's
expandIds when no sessionIdHint is available, which is the common
case from the documented MCP call path) listed every session and
scanned each one's observation scope in batches of 5 until it found a
match. Worst case that is O(sessions) kv.get round-trips per id, times
up to 20 ids per call.

Add a reverse index from obsId to sessionId, sharded across 64 fixed
scopes (mem:idx:obs:<n>, bucket = hash(obsId) mod 64) so no single
scope grows with the corpus and the file store's whole-scope rewrite
on flush stays cheap. Maintain it wherever an observation is written
(mem::observe's per-observation hot path, mem::import) and remove it
wherever an observation is deleted (mem::evict, mem::forget,
mem::auto-forget, the bulk replace path in mem::import).

findObservation now tries the reverse index before falling back to the
session scan, and backfills the index when the fallback path finds a
match so the next lookup for that id is O(1).

* chore: credit co-authors

The memories-first observation lookup follows rohitg00#1091, and rohitg00#1230 traced
the expandIds path this index serves.

Co-authored-by: Erik Bogado <erikbogado@gmail.com>
Co-authored-by: cmondragon023 <cmondragon023@outlook.com>

* fix(session-index): close index consistency gaps from review

Three gaps in the new per-project session index and its context.ts
fallback could silently hide sessions from mem::context:

- addSessionToProjectIndex built a fresh index containing only the
  session being added when no index existed yet, discarding every
  other session already stored for that project. Cold start now
  seeds the index from the project's stored sessions before merging
  in the new entry.
- context.ts's fallback (full scan + write-back when the index is
  missing) ran outside any lock, so it could race a concurrent
  addSessionToProjectIndex call and overwrite its update. Both paths
  now go through ensureProjectSessionIndex, which rechecks under the
  same per-project lock before writing.
- The 50-entry cap picked the most recent sessions across all agents
  sharing a project, so an agent with less session volume than
  others could be pushed out of the index entirely and lose all
  context. The cap now reserves up to 10 slots per agent before
  filling the remainder by recency, and removeSessionFromProjectIndex
  replenishes from stored sessions when a removal drops the index
  below the cap instead of letting it shrink permanently.

ProjectSessionIndexEntry gained an optional agentId used only for
the fairness reservation; existing entries without it keep behaving
exactly as before (single implicit bucket).

Left the evict.ts observation reverse-index entries alone: that path
never deletes the observations themselves (mem::summarize creates a
summary for the recovered session first), matching the same
long-lived reverse-index behavior a normal event::session::stopped
leaves in place. Removing the mapping there would break expandIds
for observations mem::smart-search's own query path can still
legitimately return as hits.

* perf(session-index): refill only a full index after a removal

An index holding fewer than 50 entries already lists every session in
its project, so removing one needs no refill. Refilling only when the
index was full keeps deletions in small projects from listing the
whole sessions scope each time.

* fix(session-index): self-heal untracked writers and drop O(N^2) refill

Replay, migrate, and snapshot-restore wrote sessions directly to KV
without touching the per-project session index, so those sessions
were permanently invisible to mem::context. A failed sessions listing
during the index's cold-seed path was silently swallowed and replaced
with an empty array, so a transient state::list failure could wipe a
project's visible history. Session removal rescanned the full
sessions scope every time the index crossed the 50-entry cap, turning
bulk eviction or a replace-strategy import into an O(N^2) sweep over
the sessions scope.

Fix: replay, migrate, and snapshot-restore now call
addSessionToProjectIndex after writing each session row. The cold-seed
list no longer swallows a failed state::list, so a failure leaves the
index key absent instead of persisting an empty one. Session removal
now only drops the matching entry and never re-lists. A new
rebuildAllProjectSessionIndexes function lists every session once,
groups by project, and rewrites each project's index key; it runs
once at boot behind a KV.config generation marker and is registered as
mem::diagnostic::session-index-rebuild for use after bulk operations.

Tests exercise mem::forget, mem::evict, mem::import (replace),
mem::replay::import-jsonl, and mem::snapshot-restore through their
real registered functions, including an assertion that removing 100
sessions from one project performs at most one sessions listing.

* fix(session-index): unindex evicted observations and keep concurrent index changes across a rebuild

Evicting a stale session deleted the session record but left its
observations in the obsId to session reverse index, so expandIds could
still return an observation from the evicted session. The eviction now
removes those entries using the observations it already loaded.

The boot rebuild runs in the background and lists sessions once before
writing each project index. A session started or removed between that
listing and the write was overwritten by the older snapshot, and the
generation marker then stopped any later repair. Adds and removals made
while a rebuild is running are now recorded and applied to the rebuilt
index under the project lock.

* fix(session-index): drop the project index when an add cannot be written

A failed index write left the existing index in place without the new
session, and since the index was present no later read or boot rebuilt
it, so the session never reached mem::context. The add now deletes that
project index on a failed write, so the next read rebuilds it from the
session scan, and records the change first so a running rebuild keeps it.

---------

Co-authored-by: Erik Bogado <erikbogado@gmail.com>
Co-authored-by: cmondragon023 <cmondragon023@outlook.com>
…klog (rohitg00#1420)

* perf(stream): stop writing per-session mem-live groups, bound the viewer group

The engine's file-based stream store rewrites a whole (stream, group)
scope on every dirty flush tick, the same whole-scope-rewrite cost as
state. observe.ts and compress.ts wrote every raw and compressed
observation into a per-session mem-live group (group id = sessionId)
in addition to the shared viewer group, but grepping src/, plugin/,
integrations/, packages/ and the viewer for stream::get, stream::list,
stream::delete or any WS subscribe targeting a session-id group turned
up zero reads anywhere: the viewer only ever joins stream/mem-live/viewer.
That write was pure waste, doubling the persisted cost of every
observation for nothing, so this drops it and removes the now-dead
STREAM.group helper.

The remaining shared "viewer" group is written on every observation via
one persisted stream::set call (the synthetic/non-auto-compress path in
observe.ts; the stream::send calls elsewhere only publish to live
subscribers and never touch storage, confirmed against the engine's
stream::send handler) and was never pruned, so a long-running daemon
accumulates one entry per observation forever and every viewer
join/reconnect replays the whole backlog. src/state/viewer-stream.ts
tracks written item ids in memory and, every 50 writes, deletes the
oldest items beyond AGENTMEMORY_VIEWER_STREAM_MAX (default 500) via
stream::delete, batched rather than per-write. Delete failures are
logged and swallowed (Promise.allSettled) so pruning never blocks
observation ingestion.

Did not implement a one-time boot cleanup of pre-existing per-session
groups: the engine has stream::list_groups to enumerate groups cheaply,
but stream::list/get_group returns only stored values, never item ids,
and stream::delete requires an item id per call with no group-level or
bulk delete anywhere in the stream or state workers. Reconstructing ids
from nested value fields across every historical session group would be
fragile and, at the reported scale (600+ sessions, up to 500 items
each), not cheap - the opposite of what this fix is for. Per the task's
own conditional, reporting instead of building it.

* perf(stream): trim the stored viewer backlog after restarts

The prune tracker only knew about items written by the running
process, so every item stored before a restart stayed in the viewer
group for good, and that is the backlog existing stores already have.
At boot the tracker is now seeded from one listing of the viewer group,
oldest first, and anything beyond the cap is deleted in batches of 100
in the background.

Pruning no longer holds up the observation that triggered it.

* chore: credit co-authors

The persisted per-session stream groups were measured and reported in
discussion rohitg00#1358.

Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>

* fix(viewer-stream): retry failed prunes and reject malformed stream cap

Keep a failed stream::delete id tracked instead of dropping it, so the
next prune retries it rather than letting the backlog grow past the
limit forever. Recheck for overflow once an in-progress prune finishes
if writes arrived while it was busy, instead of losing that check when
the write counter resets. Seed and requeue large id lists in bounded
chunks instead of spreading them into function arguments, which could
throw once a stored backlog got large enough. Reject a non-empty
AGENTMEMORY_VIEWER_STREAM_MAX value with trailing junk (e.g.
"500000junk") and fall back to the documented default instead of
silently taking the numeric prefix.

* perf(viewer-stream): delete overflow newest-first, seed in listing order

The engine's stream store removes items with IndexMap::shift_remove, whose
cost is proportional to how many entries sit after the removed one. Pruning
took the oldest tracked ids first and deleted them front to back, so each
delete shifted almost the whole remaining store; a large boot backlog made
every stream::set queue behind a prune that ran quadratic in the store size.
Deleting the same oldest-ids selection but issuing the deletes newest-of-the-
overflow-first means each removal only shifts the retained tail, bounded by
the configured cap instead of the store size.

The boot seed sorted the listed backlog by the hook's client-supplied
timestamp before choosing what counts as oldest. An unparseable or skewed
timestamp could make the newest item look oldest and get pruned first. The
engine already returns the group in insertion order, so the seed now trusts
that order directly and never parses timestamps.

AGENTMEMORY_VIEWER_STREAM_MAX accepted any integer, including negative
values that emptied the tracker (and deleted every stored item) on the next
prune, and values under 200 that silently shrank the backlog below what the
viewer's join sync displays. The getter now rejects negative values (falls
back to the default) and floors any other value at 200.

The boot stream::list call had no timeout, so an oversized backlog — or a
list response that exceeds the SDK socket's payload limit and closes the
connection without rejecting the pending call — could hang the seed
indefinitely during startup. It now carries a 5s timeoutMs; a failure of any
kind is already treated as "skip seeding this boot".

trackViewerStreamItem and the seed now share one id set, so a write that
races the boot seed for the same id is tracked once instead of twice.

The PR description's claim that the old per-session groups "would need ids
the stored values do not carry reliably" is wrong: both writers set
item_id = obsId with observation.id === obsId, so the ids are reliable.
Leaving those groups alone is a scope decision, not an ids problem.

---------

Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>
* perf(stream): bound the viewer stream backlog (base from rohitg00#1420)

The stream group changes from rohitg00#1420, which the live viewer builds on.
This commit disappears from the diff once rohitg00#1420 merges.

* feat(api): stream every viewer scope and add viewer endpoints

State triggers and viewer events for memories, lessons, actions,
crystals, semantic facts, procedures, audit, graph deltas,
consolidation runs and health; one snapshot endpoint and a counts
endpoint; cursor pagination, filters and facets on the list endpoints;
graph node, observation locate and memories-by-session lookups; and the
backend fixes the viewer audit found (LLM detection, profile files,
status wording, mem::evolve, lesson sourceIds, audit filters).

* feat(viewer): rebuild the viewer on one streamed store

Every page renders from one store fed by the snapshot and stream events,
with no polling. Grouped navigation, glossary help, self-explaining empty
states, and rebuilt Memories, Sessions (with the timeline merged in),
Graph, Health with a consolidation explainer, Audit, Activity, Profile,
Replay, Lessons, Actions and Crystals.
* perf(audit): shard mem:audit into month scopes so writes stop paying for the whole log

The iii file store rewrites a whole scope on every flush when any key in it
changed, and the audit log lived in one scope (mem:audit) forever, so a
mature store paid O(log-size) disk I/O on every audited operation. One store
had 583k rows, 534k of them index_persist noise written before that kind of
row became opt-in.

recordAudit now writes into a UTC month scope (mem:audit:YYYY-MM) derived
from the entry timestamp, with a small index key (mem:audit:months)
tracking which month scopes exist so readers never have to list_groups.
queryAudit, and everything that goes through it (the memory_audit MCP tool,
GET /agentmemory/audit, the viewer audit tab, mem::heal, diagnostics),
reads month scopes newest-first and stops once it has the requested limit,
falling back to the legacy mem:audit scope only if it still needs more.

A background migration runs at boot, bounded to 200 rows per tick, moving
legacy rows into their month scopes and dropping legacy index_persist rows
outright (system noise, not deletion records); it records one summary audit
row for the purge and leaves every other row alone. It resumes on the next
boot if interrupted, since queryAudit's legacy fallback keeps unmigrated
rows readable in the meantime.

AGENTMEMORY_AUDIT_RETENTION_MONTHS (default 0, keep forever) adds a daily
sweep that drops whole month scopes older than N months; off by default so
no install loses audit history without asking for it.

* perf(audit): migrate the legacy audit log in two fast passes

Moving one row at a time kept the legacy scope large for the whole
migration, and the engine rewrites a changed scope in full on every
5 s flush, so a store with hundreds of thousands of rows would have
rewritten that file hundreds of times. The migration now copies the
rows it keeps into their month scopes, records each month in the index
once, and then deletes the legacy keys, both passes with bounded
concurrency and no pauses, so the legacy scope empties within a few
flushes. A migration that stops early leaves the legacy rows readable
and resumes on the next boot.

* chore: credit co-authors

The audit growth (583,035 rows, 534k index_persist) was measured and
reported in discussion rohitg00#1358.

Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>

* fix(audit): close the lost-update race on the month index

markAuditMonth and runAuditRetentionSweep each did a read, modify,
write round trip against the single mem:audit:months index key with
no coordination between callers. startAuditMigration runs unawaited
at boot alongside request-time recordAudit calls, and the retention
sweep reads the index once at the start of a run that can take a
while to delete rows. In every case, a second writer could read the
stale index before the first writer's write landed, and the later
write would silently drop the other writer's month from the index,
making its rows unreachable by queryAudit and the retention sweep.

Serialize index mutations through the existing keyed mutex (already
used elsewhere in this file's neighborhood for the same class of
read-modify-write race) and have the sweep re-read the index inside
the lock right before its final write, instead of writing back a
snapshot captured before the sweep started.

Also run the audit retention sweep once at startup, after audit
migration finishes, instead of only on a 24h interval. Deployments
that restart daily before the first interval fires never get a
sweep.

* perf(audit): gate the legacy audit migration on a local size probe

The migration used to unconditionally state::list the legacy mem:audit
scope on every boot, which can return a payload over the SDK socket's
100 MiB limit and hang boot for the invocation timeout, and it deleted
legacy keys in insertion order, which is quadratic against the engine's
IndexMap-backed store. queryAudit had the same unconditional list on
its legacy fallback path, with no de-duplication against rows already
copied into month scopes.

Replace the unconditional list with a local file-system probe of the
engine's own state store directory (mem%3Aaudit.bin) so a store's size
is known before ever asking the engine for it. Under
AGENTMEMORY_AUDIT_MIGRATE_MAX_BYTES (default 32 MiB) and locally
readable, the migration copies rows into their month scopes, waits at
least two engine save intervals so the copies are durable, then deletes
the legacy keys in reverse insertion order with lower concurrency.
Anything larger, or not locally readable (for example an engine on
another host), is left frozen and reported through
GET /agentmemory/status instead of migrated.

Progress is tracked in a migration marker (mem:audit:months/migration)
so a crash mid-pass resumes without re-deriving counts from a
shrinking legacy scope, and the completion summary is written exactly
once behind that marker. queryAudit only reads the legacy scope when
the marker says it is safe, de-duplicates by id, and reports a
legacyFrozen flag plus size when older rows are known to remain
frozen. The retention sweep also deletes in reverse insertion order.

Fixed a re-entrant deadlock this introduced: the migration's
summary-write step called safeAudit under the same keyed lock used by
markAuditMonth, which queued behind itself forever. It now uses its
own lock key.

AuditMonthIndex and the new migration/query types now live in
src/types.ts per the KV-scope convention. standalone MCP's memory_audit
handler now goes through queryAudit like every other reader instead of
listing the legacy scope directly.

* fix(audit): stop calling a copied legacy log frozen and export the deploy data dir

A migration in the copied state has already moved every legacy row into
the month scopes; only the delete pass is pending. queryAudit and the
status page treated any state other than done as frozen, so a failed
delete pass reported rows as missing from audit queries until the next
boot. Only too-large and unreadable now count as frozen.

The deploy entrypoints kept /data in a shell-only DATA_DIR variable while
the engine config writes state under /data. With AGENTMEMORY_DATA_DIR
unset, the CLI resolved a platform default directory instead, so the
legacy audit probe looked in the wrong place and left the migration
frozen. The entrypoints now export the directory they use.

---------

Co-authored-by: Vladimir <7998636+MarvinFS@users.noreply.github.com>
* feat(state): add opt-in redis backend for iii-state and iii-stream

The bundled file-based kv adapter rewrites a whole scope on every flush
and holds the entire store in the engine's heap, which does not scale
for a shared daemon with several concurrent writers. iii-engine 0.22.1
already ships a redis adapter for both iii-state and iii-stream that
writes per key (HSET) instead of rewriting a whole scope, so expose it
as an opt-in instead of building a new storage layer.

AGENTMEMORY_STATE_BACKEND=redis (plus AGENTMEMORY_REDIS_URL) switches
both iii-state and iii-stream to that adapter when agentmemory renders
its runtime iii-config. The file-based store stays the default; leaving
the variable unset renders byte-identical config to before this change.
Selecting redis without a URL fails fast with a clear error before the
engine is launched, both from renderEngineConfig directly and from the
CLI's startEngine() check.

rewriteBundledConfig (src/cli/engine-launch.ts) is the path a real npm
install actually takes; it previously rebuilt its own options object
for renderEngineConfig and silently dropped anything beyond dataDir and
ports, so a live redis: false-negative was live-verified via docker
(iii-state/iii-stream kept rendering to the file adapter under the
bundled config until this was fixed) before landing.

README documents the switch plus the export/import commands for moving
data between backends, since switching starts from an empty store.

* fix(state): fail loudly on unswitchable redis config, harden migration docs and test isolation

renderEngineConfig silently left a worker on its default file/kv adapter
when a custom iii-config.yaml was missing the iii-state/iii-stream worker
block or its adapter block, even though AGENTMEMORY_STATE_BACKEND=redis
had been requested. It now throws so the mismatch surfaces instead of the
engine starting on a different backend than the user selected.

The README migration commands for export/import omitted the bearer token
required when AGENTMEMORY_SECRET is set, used curl -s (which can write an
HTTP error body to backup.json without failing), and never checked that
backup.json was a usable export before telling the user to switch backends
and restart. All three are fixed.

test/state-backend-config.test.ts imported src/config.ts at module scope,
so DATA_DIR/ENV_FILE were computed from the real HOME before beforeEach
sandboxed it, letting a developer's real ~/.agentmemory/.env leak into the
test. It now sandboxes HOME before a fresh dynamic import of the module,
matching the pattern already used in test/env-loader.test.ts.

* fix(state): make a failed redis launch fatal and stop leaking the URL to disk

A failed redis config rewrite in prepareEngineLaunch was caught and
silently discarded, so the CLI would start the engine on the file (or
in-memory) store while the user believed it was on Redis. The catch
now runs resolveLaunchRenderFailure and exits loudly when the state
backend is redis, while the file backend keeps its existing silent
fallback to the bundled config.

The rendered runtime config no longer embeds the literal Redis URL.
iii 0.22.1 expands ${VAR} references in config values at boot (see
engine/src/workers/config.rs expand_env_vars, called from
config_file), so the adapter block now renders
redis_url: '${AGENTMEMORY_REDIS_URL}' and the CLI already forwards
process.env (hydrated from ~/.agentmemory/.env) to the spawned engine
process, so the reference resolves the same way the literal used to.
The engine's own configuration worker still persists the expanded
value under ~/.agentmemory/config/*.yaml (fs.rs writes the resolved
struct, not the source text), so the README documents that residual
exposure and recommends chmod 700 on shared hosts. Every engine
stderr surface the CLI prints (captured startup stderr, docker logs)
now runs through redactCredentialUrls first.

getStateBackend() now throws on an unrecognized AGENTMEMORY_STATE_BACKEND
value instead of silently defaulting to file; startEngine validates it
before touching the engine and exits with the same clear error style
already used for a missing AGENTMEMORY_REDIS_URL. Both Docker paths
(resuming a persisted docker-owned engine, and the AGENTMEMORY_USE_DOCKER
compose path) now warn when redis was requested, since neither renders
iii-config.docker.yaml. /agentmemory/status reports the active
stateBackend so an operator can confirm which store is live without
reading the URL.

README: replaced the AUTH=(...) migration snippet, which produces a
different (and wrong) curl argv under zsh than under bash, with an
if/else that is not shell-dependent; documented plain redis:// only
(the pinned engine has no TLS), one Redis DB per --instance, the
appendonly/noeviction recommendation, and corrected the claim that
only a native start renders the two variables (the one-click deploy
templates overwrite the bundled config and start natively too, so
they render it as well; only this repo's own Docker Compose path
does not). deploy/README.md documents the same two variables.

* fix(redis): reject unloadable URLs and close the file-store fallback

The engine expands ${AGENTMEMORY_REDIS_URL} into the YAML text before it
parses the config, so a single quote or a control character in the URL
breaks the single-quoted scalar and the engine does not start. The render
now rejects those characters with a message to percent-encode them.

A failure to create the engine working directory returned the original
file-backed config before the Redis render ran, so a Redis selection
could silently start on the file store. That path now uses the same
fatal handling as a failed Redis render.

Docker Compose forwards AGENTMEMORY_REDIS_URL to the engine container,
so a hand-edited iii-config.docker.yaml can reference it instead of
holding a literal URL. The README and deploy notes say plain redis://
is unencrypted and must stay on a trusted network or behind an
encrypted tunnel.

* docs(redis): drop em-dashes from the state backend section

* fix(redis): make every state and stream path behave the same on redis

The engine's redis adapter differs from the file store in ways that
broke or degraded agentmemory beyond basic writes:

- state::list is HGETALL collected into a HashMap, so records came back
  in arbitrary order (export paging, viewer stream seeding, anything
  that slices a list). StateKV now sorts redis listings oldest first by
  the creation time in generated ids, then timestamps, then id.
- state::update runs a Lua script whose cjson round trip turns empty
  arrays into empty objects (session tags, commitShas). On redis StateKV
  applies set/remove/merge itself under a per-key lock and writes with
  state::set, which fires the same created/updated triggers.
- The legacy audit migration probed the file store's scope file on disk,
  so a fresh redis store was marked unreadable and the audit log showed
  as frozen. On redis it sizes the legacy scope from the hash itself and
  skips the file flush wait.
- After a redis restart the engine's pub/sub pump ends and live viewer
  events stop until restart. The health monitor now sends a probe event
  through the stream every 30 seconds on redis and raises
  stream_relay_down with a restart fix.
- /status probes the state store and reports state-store-unreachable
  with a backend specific fix; the Health page shows the backend in the
  State store row and the relay state.

* docs(redis): document redis behaviour, one server per instance and the restart caveat

Redis pub/sub ignores the database index, so separate DB numbers keep
data apart but still cross-feed live viewer events between instances.
List what works unchanged, what agentmemory handles for the engine's
redis differences, and what to do after Redis restarts.
rohitg00 and others added 29 commits November 8, 2026 12:53
* fix(hooks): send PreToolUse context in the hook envelope

The PreToolUse hook wrote enrich context to stdout as plain text.
Claude Code and Codex only show plain stdout to the model for a few
events, and PreToolUse is not one of them, so the context never
reached the model. The hook also gave /agentmemory/enrich a fixed
2 s, with no way to raise it.

When the payload names the PreToolUse event, the hook now writes
hookSpecificOutput.additionalContext. Hosts that send another shape,
and the Factory droid host, still get plain text.
AGENTMEMORY_ENRICH_TIMEOUT_MS sets the enrich wait (default 2000 ms).

* fix(hooks): reject malformed enrich timeouts

AGENTMEMORY_ENRICH_TIMEOUT_MS now accepts only whole milliseconds from
1 to the Node timer limit. A fractional, suffixed or oversized value
falls back to the 2000 ms default instead of aborting enrich at once.

* fix(hooks): skip PreToolUse enrichment for Cursor

Cursor's preToolUse response carries only a permission decision, so
the context text the hook wrote could not reach the model there. The
hook now returns before calling enrich for Cursor payloads. The timeout
tests also tell a malformed value apart from the default.
…tg00#1692)

* fix(hooks): give the Claude Code SessionEnd hook time to finish

Claude Code allows a SessionEnd hook 1.5 s unless the hook sets a
timeout. The agentmemory SessionEnd hook back-fills transcript prompts
with a 3 s client budget and then waits up to 1.5 s for the session end
request, so Claude Code cancelled it and printed "Hook cancelled" on
exit.

The SessionEnd entry in the Claude Code hook manifest now sets a 10 s
timeout. connect claude-code --with-hooks copies the field through.

* fix(hooks): finish SessionEnd work in a detached worker

Claude Code does not let a plugin hook timeout raise its shared 1.5 s
SessionEnd budget, so the timeout added to the manifest only helps
hooks installed into settings. For a Claude Code SessionEnd payload
the hook now passes its input to a detached copy of itself and exits
at once. The worker back-fills transcript prompts and then ends the
session, in the same order as before. Other hosts keep running inline.

* fix(hooks): run SessionEnd inline when the worker cannot start

Node reports a failed spawn through an asynchronous error event, so the
hand-off could report success for a worker that never started and the
session would not be ended. The hook now waits for the worker to spawn
and receive its input, and runs inline when either step fails. The
hand-off test also keeps the slow observe reply until the worker posts.
…0#1696)

* fix(search): stop capping saved memories at three per search

Saved memories with no session share the synthetic session id
"memory", so per-session diversification let only three of them into
the first pass, and observations from real sessions ranked ahead of
the fourth best memory. Saved memories now skip the per-session cap.

BM25 and vector search also return at least 40 candidates before
fusion, so a small limit no longer drops a record that ranks well in
only one stream.

* fix(search): fill result slots that stale index entries leave empty

Enrichment read only the first ranked candidates. When some of them were
stale index entries with no stored record, they used up slots and hid
valid lower-ranked records. Enrichment now keeps reading ranked
candidates until it has enough records or runs out of candidates.

The candidate-pool test now checks a search result. It shows that a
record ranked well in both keyword and vector search comes first in a
one-result search.

* perf(search): keep enrichment batches full when entries are stale

Each refill batch only asked for the number of missing slots, so many
stale candidates meant many small sequential batches. Every batch now
reads a full limit of candidates, and the result is trimmed to the limit
in rank order.
Bumps [actions/upload-artifact](https://github.com/actions/upload-artifact) from 4 to 7.
- [Release notes](https://github.com/actions/upload-artifact/releases)
- [Commits](actions/upload-artifact@v4...v7)

---
updated-dependencies:
- dependency-name: actions/upload-artifact
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Bumps [actions/checkout](https://github.com/actions/checkout) from 6 to 7.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@v6...v7)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '7'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
…ohitg00#1698)

* fix(diagnostics): find and heal facets that point at deleted targets

Facets left behind by deletions from before cascade cleanup had no
repair path: memory_diagnose and memory_heal had no facets category, so
heal reported success while the orphans stayed and still answered facet
queries. A new facets category reports facets whose memory, observation
or action no longer exists, and heal removes them, with a dry run and an
audit record per removal. Facets whose target cannot be checked are
left in place.

* fix(diagnostics): keep facets of live observations that the index misses

The session index for observations is written best-effort, and older
observations may have no entry. An index miss alone made a live
observation look deleted, so heal could remove its facets. An
observation facet is now an orphan only when a scan of every session
also does not find the observation. If the scan fails, the facet stays.

Heal also checks each facet again right before it deletes it, and skips
the facet if the facet is already gone or its target is back.

* perf(diagnostics): read session observations in parallel for the facet check

The fallback scan for observations missing from the session index read
each session one after another. It now reads them concurrently. The scan
still runs at most once per diagnose or heal call, and only when an
observation facet misses the index.

* perf(diagnostics): scan session observations in bounded batches

The fallback scan read every session at once and held every full
observation until all reads finished. It now reads 16 sessions at a time
and keeps only the observation ids.

* fix(diagnostics): keep facets on migrated observations without a session

Migration writes observations without a session id to the migrated scope
without a session record or an index entry, so the orphan scan missed
them and heal could delete their facets. Migration now indexes each
observation, the scan includes the migrated scope, and the heal recheck
looks there before deleting.

* fix(diagnostics): check observation facets by target type, not only by id prefix

Migration can create observation ids with a mig_ prefix. Orphan discovery,
the heal recheck and facet cleanup now look up the observation for any
facet whose target type is observation.
Signed-off-by: dimitri <dimitri.chrysafis@gmail.com>
* feat(sessions): filter by startedAt and endedAt

GET /agentmemory/sessions accepts startedAfter, startedBefore,
endedAfter and endedBefore (ISO 8601). After is inclusive, before is
exclusive; sessions without the field are excluded and a bad timestamp
returns 400.

Signed-off-by: yxtay <5795122+yxtay@users.noreply.github.com>

* fix(sessions): parse time filters as strict ISO 8601

Date.parse accepted values like "5" or "2026" and read zone-less
strings in the server's timezone. Require an ISO 8601 shape, read
zone-less values as UTC, and accept an offset whose plus was decoded to
a space by the query string.

Signed-off-by: yxtay <5795122+yxtay@users.noreply.github.com>

* fix(sessions): reject impossible dates and empty time bounds

Date.parse normalises 2026-02-30 to March 2, and an empty value was
treated as absent, so both returned 200 with wrong results instead of
400. Validate the calendar day before parsing and treat any supplied
time param as present. Add a route-level test for bounds combined with
cursor paging, and drop the CHANGELOG entry (release PRs own it).

Signed-off-by: yxtay <5795122+yxtay@users.noreply.github.com>

* fix(sessions): accept space-separated date-time bounds

A bound like "2026-10-09 12:00" had its time read as a "+12:00" offset,
producing an invalid date and a 400 for supported input. Replace the
date/time separator before detecting an offset.

Signed-off-by: yxtay <5795122+yxtay@users.noreply.github.com>

---------

Signed-off-by: yxtay <5795122+yxtay@users.noreply.github.com>
Four merged PRs each added variables, so the generated count in the
config skill reference drifted from .env.example and skills:check fails
on main.
* fix(reflection): bound evidence and insight responses

* fix(reflect): page lesson and crystal reads

Read lessons and crystals through collectAll like semantic memories, and
describe that in the reflection evidence doc.

* fix(reflect): keep other projects' crystals out of a scoped reflection

A project-scoped reflection filtered lessons by project but not
crystals, so another project's crystal narrative could reach the model
and be cited in an insight stored under the requesting project.
* fix: serialize and recover consolidation publication

* fix(consolidate): compare evidence, not bookkeeping, and adopt legacy heads

The pre-publication source check now compares the same evidence fields
the key hashes, so a compression retry that only updates bookkeeping
during generation no longer discards the result. A legacy head that
matches by source and session ids is stamped with the current key once
instead of blocking every later run, so a later evidence change
publishes a new version.

* fix(consolidate): audit legacy memory adoption

* fix(consolidate): record legacy adoption after releasing the publication locks
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>
Take 0.9.33 search ranking (uncap saved-memory results) and re-apply
JTT project fail-closed filtering. Keep GET /memories?handoffProject=
plus selectLatestProjectHandoff, scoped-gateway, and iii-sdk 0.25.1.

Co-authored-by: ShintaroKawakami <ShintaroKawakami@users.noreply.github.com>
skills:check failed on every CI test matrix because AUTOGEN:env still
said 81 variables after JTT gateway vars were kept. Regenerated only.

Co-authored-by: ShintaroKawakami <ShintaroKawakami@users.noreply.github.com>
@ShintaroKawakami
ShintaroKawakami merged commit 6cffd9a into main Nov 10, 2026
14 checks passed
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.