Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

Merge pull request #1827 from M4ster3001/up/mcp-read-limits

AkitaOnRailse664c8486117
diff --cc CHANGELOG.md
index 1923694d,cbd0f578..c277f2a3
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -13,543 -13,24 +13,561 @@@ version in [`docs/changelog/`](docs/cha
### Added
+- Added `--project-id` to managed launches and checkout-local discovery to
+ recover populated legacy name collisions without moving or merging history.
+ An interactive launch offers authorized project choices and remembers the
+ selection for that server and checkout. Resumes reuse the binding, and
+ ID-selected runs keep startup context and hook capture in the selected scope
+ after checking current access, run ownership and native session identity.
+ Existing name selectors and legacy runs retain their behavior (#1833).
+
+- Added `ai-memory run --no-exit-prompt`, `[run] exit_prompt = false`, and
+ `AI_MEMORY_RUN_EXIT_PROMPT=false` to skip the switch/rerun menu after a
+ successful interactive session. The menu remains enabled by default (#1776).
+
+- `ai-memory merge-project --workspace <w> --from <source> --into <target>`
+ losslessly joins two project identities inside one workspace. Its default is
+ an exact dry run; `--confirm` re-stamps page history, sessions, observations,
+ handoffs, embeddings and managed workstreams in one writer transaction, then
+ removes the source project. Same-path pages get a new target version that
+ appends the source body behind an `ai-memory:merged-from` marker while both
+ prior histories remain restorable. The target frontmatter wins, a one-sided
+ expiry is removed, and the combined page is flagged stale for consolidation.
+ `restore-page --page-id <uuid>` restores either retained history even after
+ the source identity is removed. Open sessions and live managed runs refuse
+ the merge (#1645).
+- `audit-contamination` now reports projects in one workspace whose names
+ collide after Unicode compatibility decomposition, case folding, and
+ removal of non-spacing marks. Findings distinguish case from accent
+ differences and include page/session counts plus last activity (#1645).
+
+- Cross-project messages can carry an optional epistemic `nature` (`unknown`,
+ `measured`, `reported`, or `inferred`) and bounded supporting `evidence`.
+ The server refuses a `measured` send without non-empty evidence; existing
+ messages and callers remain `unknown` by default (#1428).
+
+- Added `memory_patch_page` for atomic, heading-anchored edits to an existing
+ Markdown page without re-emitting its body or metadata. It requires the
+ page's current `page_id`; section replacement additionally requires the
+ bounded SHA-256 token returned by `memory_read_page`. Missing, duplicate or
+ fenced-code headings, stale tokens, conflicting edits, failed admission and
+ concurrent writes leave the page unchanged. The typed TypeScript client
+ exposes the same contract as `pages.patch` (#1697).
+
+- Added an offline `ai-memory-eval abstention` benchmark with versioned
+ clean-room answerable, hard-negative, conflicting, partial and
+ missing-channel fixtures; raw lexical/score/density/belief signals;
+ FSR/FAR/coverage threshold sweeps with undefined denominators preserved;
+ optional reuse of pinned LongMemEval `*_abs` cases; and optional structured
+ LLM answerability through the existing QA provider path. Conflicting and
+ partial cases remain separate from binary ground truth, no threshold is
+ presented as calibrated, and production runtime behavior is unchanged.
+ The retrieval evaluator now also parses production's structured
+ `{text,citations}` answer shape instead of a stale string (#1717).
+
+- Added `[briefing] inject_on_subagent_start` to `.ai-memory.toml`. A project
+ that sets it hands each `claude-code` subagent the project brief when the
+ subagent starts: the same pinned, `_rules/` and `_slots/` brief that
+ `inject_on_session_start` adds at session start, kept within `max_chars` and
+ within the 10,000-character limit of that agent's hook context. The hook
+ reads it from a new read-only `GET /brief`, which resolves and authorizes the
+ project as `/handoff` does but never reads or claims a handoff, so a subagent
+ cannot take its parent session's baton. A server without the route answers
+ 404 and the subagent starts as before. The native hook and the
+ `hooks/claude-code` shell and PowerShell scripts deliver it, and every marker
+ parser treats the key as a settings boundary. It is off by default (#1715).
+
+- Added an optional `[query_answer] max_context_tokens` admission budget for
+ answer synthesis. It preserves retrieval hits, reports omitted or clipped
+ evidence, prioritizes known newer corrections, prefers whole snippets and
+ clips only complete trailing sentences or statements into leftover space. It
+ skips the model when no meaningful evidence fits. The default
+ remains disabled (#1684).
+
+- `GET /admin/status` and `ai-memory status --json` now carry a
+ `consolidation` block: the queue counts plus up to 20 `failed_sessions`
+ (`session_id`, `attempts`, `failed_at_us`, scrubbed `last_error`), newest
+ first. A consolidation run that gives up after its retries now has a
+ machine-readable record with the session ids needed to re-run it, instead of
+ only a journal line and the `/health` panel's count — which also resets with
+ the process. The web health panel's own view stays counts-only, and an older
+ server's status shape is unchanged (#1692).
+
+- Added the bundled `coding-v1` retrieval-evaluation corpus for offline checks
+ of decision rationale, resolved-error causes, correction evidence, and late
+ session details. It reuses the existing scorer and A/B reports; it measures
+ evidence retrieval, not semantic answer correctness or handoff behavior (#1686).
+
+- `[auto_improve.eval] builtin = "structure"` runs the eval gate's structural
+ checks in process, so the gate needs no interpreter, no scorer script inside
+ the container and no timeout to hit. It checks an H1, an upper-case
+ `TODO`/`TBD` placeholder (a hard failure), a `##` section and a list of steps
+ for `procedures/`, and text beyond the heading within 2,400 characters for
+ `_rules/` — never a section name or a wording, so the wiki's language does
+ not matter. `eval_results` records `checker_name = "builtin:structure"`.
+ `builtin` and `command` are mutually exclusive; `command` is unchanged for
+ project-specific scorers (#1638).
+
+- `ai-memory llm-test --server` probes the server's own configured provider
+ instead of building one from the caller's environment, through a new
+ root-only `POST /admin/llm-test`. The retry hint that `status` and the health
+ panel print now names it: with the server in a container or on another host
+ its keys exist only there, so the old client-side hint failed with "no API
+ key" or a provider `400` while the server was healthy. The probe runs one
+ fixed short prompt, reports provider, model, latency and the error class, and
+ scrubs the provider's message before printing it (#1639).
+
+- Added `[handoff] deliver_on_session_start = false` to `.ai-memory.toml`. A
+ project that sets it no longer gets its handoff, or the continuity notice, at
+ session start; the handoff is still created when the session ends and stays
+ open for `memory_handoff_accept`. The native hook, the shell and PowerShell
+ scripts and the generated TypeScript integrations send `handoff=0` only when
+ the value is explicitly falsy (#1621).
+
+- Added first-party Qoder CLI/IDE lifecycle and MCP support. Both installers
+ merge into `~/.qoder/settings.json`: `install-mcp --client qoder` writes a
+ sessionless stdio bridge, while `install-hooks --agent qoder` registers the
+ eight documented memory-bearing events as native commands. Session start
+ delivers a pending handoff through `hookSpecificOutput.additionalContext`,
+ prompt/tool capture uses Qoder's Claude-shaped payloads, and a missing hook
+ `cwd` falls back only to `QODER_PROJECT_DIR`. Setup detects `~/.qoder`,
+ uninstall removes both entries, and agent backups include its settings and
+ shared AGENTS-compatible skills/instructions (#1611).
+
+- Profile writes now return `digest_warning` when the selected summary,
+ abstract, or prose statement exceeds the 240-byte session-start digest
+ limit. The write still succeeds, but its author can shorten the summary
+ instead of discovering the truncation only in a later session (#1609).
+
+- Added project routing for the named profiles of a multiplexing Hermes
+ gateway. The gateway exports only the default profile's `terminal.cwd`, so
+ every other profile's events used to fall back to the gateway's own working
+ directory and all its bots landed in one project. A gateway event of a named
+ profile now routes by an `.ai-memory.toml` placed in that profile's Hermes
+ home (`~/.hermes/profiles/<name>`, or under the gateway's `HERMES_HOME`), and
+ that marker's capture exclusions and server profile apply. A profile without
+ such a marker keeps the old behavior. The profile name is checked against
+ Hermes' profile-id pattern before it is used as a path (#1597).
+
+- Added Hermes Agent hook consent to `ai-memory doctor`. Hermes runs a shell
+ hook only when that exact command is approved in the home's
+ `shell-hooks-allowlist.json`, and each profile under
+ `~/.hermes/profiles/<name>` keeps its own allowlist. A profile with the
+ ai-memory hooks in `config.yaml` but no approvals captured nothing, and its
+ gateway only logged `not allowlisted — skipped` for each event. `doctor` now
+ reads the root home and every profile, reports which ai-memory hook events
+ each one wires, and warns about every profile whose events are not
+ allowlisted (unless `hooks_auto_accept` is on), with the `hermes -p <name>
+ --accept-hooks` command that approves them. The JSON output gains a `hermes`
+ array. It never writes either file and never prints the hook commands,
+ which can embed a bearer token (#1598).
+
+- Added `AI_MEMORY_RERANK_TIMEOUT_SECS` (`rerank_timeout_secs` in
+ `config.toml`) to set the `memory_query` reranker budget, which was fixed at
+ 20 seconds. The default stays 20 and zero is rejected at startup. A hosted
+ provider behind an LLM fallback chain can spend the whole fixed budget on one
+ slow 503 before the next candidate answers, and every such query then keeps
+ its pre-rerank order. ([#1614](https://github.com/akitaonrails/ai-memory/issues/1614))
+
+- `ai-memory status` now shows the client's version next to the server's: a
+ `ai-memory X (client)` line under `ai-memory X (server)`, and `version` in
+ the JSON `client` object. In a split install (native client and hooks, the
+ server in a container or on another host) the two drift apart when only one
+ side is upgraded, and nothing showed it. When they differ in major version,
+ the text report adds a warning to upgrade the older side (#1644).
+
+### Changed
+
+- `memory_lint` now reports embedding-band pairs as
+ `similarity_candidate` instead of `contradiction`, and no longer infers that
+ a newer page supersedes an older one from timestamps alone. Explicit
+ `contradicts` edges remain `contradiction` findings (#1685).
+
+- `move-project` now refuses the **copy+purge merge** — the path taken when the
+ destination workspace already holds a project of the same name — unless
+ `--allow-lossy-merge` is passed as well as `--confirm`. That path keeps only
+ the source's latest pages and deletes the project with its sessions,
+ observations, handoffs and older page versions, which `--confirm` written for
+ "move this project" did not say; the refusal answers `409` with the counts it
+ would discard. A true-move (fresh destination, everything preserved) is
+ unchanged, and `merge-workspace`, whose command already says merge, keeps
+ working without the extra flag (#1713).
+
+- `memory_install_self_routing(compact: true)` and `ai-memory
+ install-instructions --compact` now return a block that is actually compact:
+ 2.1 KB instead of 5.9 KB, close to the 7.9 KB full block it was supposed to
+ replace. It keeps the rules a session needs without reading anything else
+ (scope selection for session-aware and static clients, managed-run resume,
+ capture, the untrusted-memory trust rule, and where rules belong) and points
+ at the installed `ai-memory-*` Agent Skills for the rest, which it already
+ required to be installed (#1672).
+
+- When the native session linked to a workstream is missing from its store,
+ an interactive `ai-memory run <harness>` now also names the newest session
+ this checkout still holds for that harness and the native selector that
+ resumes it, such as `resume <id>` for Codex. The launch still starts fresh
+ as before; running the same command again with that selector right after
+ the harness name links that session instead (#1654).
+
+- Managed-workstream startup packets now render completed tool calls and
+ results as compact provenance stubs instead of spending the 30,000-character
+ resume budget on raw command output or generated file content. Conversation,
+ checkpoints, compactions, and annotations remain inline; the complete
+ sanitized tool evidence stays searchable in the ledger (#1607).
+
+- The LLM fallback chain now logs its own events. A transient candidate
+ failure logs a warning with that candidate's provider, model, chain
+ position, error class, HTTP status and cooldown, and an info line records
+ each change of the answering candidate. Before, the chain logged nothing,
+ and callers such as the reranker named only the first candidate, so a log
+ could blame the primary for a timeout another candidate caused. Response
+ bodies are never logged (#1628).
+
+### Changed
+
+- Documented the settings that `config.default.toml` had left out, and added
+ `docs/config-properties.md`, a reference table of every key `config.toml`
+ accepts with its default, environment variable and purpose. The template now
+ describes the `llm_*` keys (including `llm_compat_strict` and
+ `[[llm_fallbacks]]`), the embedding endpoint and prefix keys,
+ `tcp_keepalive_secs`, `base_path`, `release_base_url`, `cors_allow_origins`,
+ `consolidate_on_session_end`, `backfill_on_start`, `run_autowire`,
+ `claude_true_yolo`, the `contradiction_band_*` keys, and the `[run]`,
+ `[hook_spool]`, `[handoff]`, `[maintenance]`, `[dream]`, `[retrieval]`,
+ `[search.fts]`, `[profile]` and `[[admission_webhooks]]` sections. It also
+ lists the remaining keys of `[decay]` (including `[decay.half_life_days]`),
+ `[consolidation]`, `[auto_improve]`, `[auto_scope]` and `[auth]`, and the
+ `[auto_improve.scheduler.experience_entropy_filter]` table. The new entries
+ are all commented examples, and keys with a built-in default show that
+ default. `AGENTS.md` now requires a new config key to land in both files.
+
+### Added
+
+- Added editing for queued messages in the web inbox. Edit takes a message that
+ is still waiting out of the queue, so no agent can collect it, and opens an
+ inline editor. Saving puts the new text back at the message's original place
+ in the queue, after the usual sanitizer, size caps and `message_send`
+ admission. Discarding returns it unchanged. A held message shows as Editing,
+ with a count above the list and a way back into the editor. Editing needs
+ write access to the mailbox project and to the project the message came from,
+ and a message an agent already collected cannot be edited. Held messages use a
+ new `editing` state (migration V95) that no claim path selects (#1832).
+
+- Added server-side response investigation to the project dashboard. Responses
+ can be filtered by UTC period, exact model, harness, session, turn and tool,
+ with complete pagination, filtered token totals and bounded native turn and
+ tool provenance. The context lives in extra `token_calls` columns and a
+ `token_call_tools` table (migration V94). A response from an older hook keeps
+ its provenance unknown instead of guessed. Filters apply after project
+ authorization and the session-owner check and before counting, ranking and
+ pagination (#1830).
+
+- Added version-specific knowledge evidence to the page and project views:
+ readable source links, declared contradictions, expiration context and an
+ on-page recall recomputation that reuses the original search filters (#1830).
+
+- Added caller-aware installation states and next steps to feature guides and
+ the authenticated `/api/v1/docs/features/status` reference. They
+ separate effective settings from client facts the server cannot know, and
+ administrative settings are masked for callers without admin rights (#1830).
+
+- Replaced the static Inbox label with live, access-filtered pending counts and
+ project links throughout the web navigation. Counts are grouped by workspace
+ and project, hide restricted projects, never consume mail, and link to the
+ pending-only mailbox of the project that has mail. Received inboxes open on
+ pending messages, with older queued requests behind collected history, and the
+ composer shows the current project explicitly (#1830).
+
+- Added bundled product documentation to the web UI and the API. The guides and
+ release notes are compiled into the binary and served at `/web/docs`,
+ `/web/docs/changelog` and `/web/docs/{id}` (a `.md` suffix returns the
+ Markdown). They include searchable feature activation guides, per-release
+ changelogs, and authenticated `/api/v1/docs` JSON and Markdown references for
+ agents. No network access or LLM is needed, and the pages describe shipped
+ capabilities without exposing the running server's configuration or
+ credentials. The source-built Docker image now copies `CHANGELOG.md` for this
+ (#1829).
+
+- Organized project pages into accessible tabs showing one section at a time: Overview,
+ Agents, Token usage, Sessions and Knowledge. The selected tab is kept in the
+ URL (`?tab=agents`), which keeps reload, shared links and browser history in
+ sync, and the tabs support Left, Right, Home and End. Existing
+ `#agents`-style section bookmarks still open the matching tab (#1829).
+
+- Updated the browser inbox composer to default To project to the source
+ project and list only harnesses with captured sessions in the destination
+ workspace and project. It resets a stale recipient when a project changes,
+ and it disables sending, with an explanation, for a project that has no
+ registered agent (#1829).
+
+- Redesigned the responsive web dashboard. It has persistent workspace
+ navigation, searchable project cards, per-agent consumption and coverage, and
+ session drilldowns that show the token totals recorded for each agent (#1828).
+
+- Added a browser inbox at `/web/inbox`. It lists received and sent mail
+ without consuming it. A caller with write access to both the source and the
+ destination project can also queue a message for a registered harness of that
+ project. The text goes through the configured sanitizer and admission before
+ the single writer, and the browser never claims mail or starts an agent.
+ Messages can now be addressed to one harness (`to_agent`, migration V93).
+ `memory_message_pop` and `ai-memory message pop` take an optional `agent`,
+ and only that harness can claim the message, even by id. Existing shared mail
+ (`to_agent = NULL`) behaves as before. A claim from a session-aware client
+ whose routing metadata arrives before its session start was persisted is no
+ longer refused. A browser session opened with the legacy read-only login can
+ send with an explicit write token supplied for that one request and cleared
+ right after, with no browser persistence (#1828).
+
+- Added live, deduplicated response token accounting for Claude Code and Codex.
+ Updated native hooks to send measured response usage on `post-tool-use`,
+ `stop`, `pre-compact` and `session-end`, keeping open-session totals current
+ rather than waiting for session end. Each response is stored once by its
+ native identity in a new `token_calls` ledger (V92). A partial or replayed
+ delivery raises the stored counters column by column and never adds the same
+ response twice. Live extraction reads a bounded 4 MiB transcript tail and
+ reports at most 256 responses per event. Fresh input excludes cache reads, so
+ Codex, whose reports included cached input, is normalized once during the
+ upgrade. The project page has a Token usage panel listing the fifty largest
+ captured responses. It flags contexts of at least 100,000 tokens, outputs of
+ at least 20,000 tokens and responses above three times the project average.
+ Only counters, response identities and model names are kept, and project
+ authorization and session-owner filters apply before ranking or aggregation
+ (#1811).
+
+- Added Light, Dark and System theme controls to the web UI. The choice is
+ stored in the browser and System follows the operating system. Tailwind's
+ dark variant now uses the `dark` class instead of the media query, so a
+ manual choice overrides the system setting (#1811).
+
+- Added a memory dashboard to the read-only web home, using sanitized data:
+ projects, sessions, sanitized capture events, compiled pages, open-session
+ continuity signals and last activity. Project cards separate captured work
+ from compiled pages, so an active hook no longer looks empty just because
+ its sessions have not ended (#1803).
+
+- Added dashboard hook-health counters for accepted, policy-dropped,
+ capacity-shed and rate-limited events. They count events since the process
+ started, and prompt, command, path and payload data is neither persisted nor
+ rendered (#1803).
+
+- Added agent CLI attribution to the project overview to show which harnesses
+ produced a project's memory. The stats card has an "Agents" badge row with session counts per
+ harness, and each Recent Activity entry shows the harness whose session last
+ contributed evidence to that page version. Both are best effort: a page or
+ project with no session evidence shows no badge (#1803).
+
+- Added per-session token accounting. At `session-end` the native hook (Claude Code
+ and Codex) reads the harness's own transcript and reports cumulative input,
+ output, cache-write and cache-read totals. It scans Claude Code's JSONL in
+ full and reads only the tail of Codex's rollout file, since both can reach
+ hundreds of MB. The server stores the totals with a `MAX(existing, reported)`
+ upsert, so a replayed or out-of-order delivery never lowers a total. The
+ project overview page shows a "Tokens" total in the stats card and a Sessions
+ table (agent, start, duration, events, tokens) with the 20 most recent
+ sessions. A session whose harness never reported usage, an unsupported
+ harness or an older client shows no number, never a zero (#1803).
+
+- Added recovery of usage and closure for sessions missing a graceful
+ `session-end`, which previously stayed open without tokens. This usually
+ happens when a paid quota runs out mid-task and the operator switches agents. When a new session
+ starts in the same scope and finds one quiet for at least 15 minutes, the
+ client looks for the old session's own transcript (Claude Code and Codex),
+ reports its usage and closes it with a normal synthetic `session-end`. That
+ is safe if the old session turns out to be live, because a later real
+ `session-end` with more work runs the full end path again. A second, more
+ conservative scheduled sweep closes sessions nobody continues anywhere,
+ after 48 hours without activity in any scope, so `open_session_count` stops
+ growing. It attaches no usage and starts no consolidation, because the
+ server cannot read a client's transcript outside a live hook request (#1803).
+
++### Added
++
+ - Added optional `max_chars` to `memory_read_page` (default 12000,
+ minimum 500, maximum 64000). It caps the returned body with the same visible
+ truncation marker as `memory_read_session_observations`. The response always
+ includes `truncated` and `total_chars`, which report whether the body was cut
+ and its full size (#1827).
+
+ ### Changed
+
+ - Reduced the default output of `memory_read_session_observations`: `limit`
+ from 50 to 20 and `body_max_chars` from 4000 to 1000. Callers can still raise
+ them to the unchanged ceilings of 200 and 16384. The smaller response reduces
+ token costs for routine "what did this session do" lookups. Updated the
+ retrieval skill with an `order="desc"` recipe using a narrow `kinds` filter
+ and small `limit` and `body_max_chars` values to avoid reading the whole
+ session (#1827).
+
### Fixed
+- Updated `libz-sys` to 1.1.31 so its build probe no longer records the build
+ environment, including possible secrets, in Cargo target artifacts
+ (RUSTSEC-2026-0418).
+- Imported every Claude transcript left behind by `/clear`, oldest first,
+ before finalizing the managed run on the newest session. Pre-clear turns now
+ retain their native-session provenance instead of disappearing from the
+ workstream ledger (#1797).
+- Kept purge-session tombstones out of automatic hollow-project cleanup, so
+ an old otherwise-empty project cannot lose replay protection immediately
+ after its session is purged (GHSA-pphw-hm98-3wh4).
+- Made Crush transcript cursors revision-aware within their one-second native
+ timestamp bucket. Same-second inserts and edits are now imported exactly
+ once, while captured recovery endpoints still exclude later revisions
+ (#1813).
+- Made TypeScript SDK capability initialization client-owned with independently
+ cancellable waits, so one caller cannot abort another caller's shared probe
+ and a later caller observes its own cancellation promptly (#1815).
+- Initialized MCP sessions in the document and agentmemory importer routes,
+ retaining validated session IDs and sending `notifications/initialized`, so
+ conditional imports work with both stateless and `--http-stateful` servers
+ (#1836).
+- Explicit `ai-memory run --fresh claude` launches now expose the previously
+ linked Claude session through `AI_MEMORY_PREVIOUS_SESSION_HISTORY`, including
+ when the two sessions live under different Claude config homes (#1789).
+- Replaced the misleading hook-refresh-only warning after a linked Codex run
+ fails to acknowledge context with a `/new`-specific ownership warning. The
+ wrapper does not adopt the unlinked thread because Codex supplies no trusted
+ parent relationship (#1788).
+
+- Sorted recent page lists by timestamp rather than RFC3339 text, so updates
+ with different fractional-second precision appear in chronological order
+ in the legacy recent API, project activity, folder previews and namespace
+ listings. Kept title-sort and equal-timestamp path tie-breaks (#1247).
+
+- Fixed `restore` replacing live data when a backup without `config.toml`
+ contains API keys that the configured pepper cannot verify. It now refuses
+ before the swap, preserving the live wiki, database and config, and names
+ the original configuration as the remedy (#1495).
+
+- Preserved explicit DOCX/PPTX line breaks and DOCX tabs in document imports
+ when XML uses paired tags, including formatted PowerPoint breaks in slides
+ and speaker notes. DOCX carriage returns now also keep adjacent text runs
+ on separate lines instead of joining their words. Paragraph tab-stop
+ definitions no longer insert spurious tabs into the extracted text (#1786).
+
+- Kept a wiki-sync server page when its repository file was recreated after
+ the sync planned a deletion. `sync --propagate-deletes --apply` now rechecks
+ local absence before sending the delete, preserves the page's baseline and
+ reports the changed file for the next sync, including with `--prefer repo`
+ (#1787).
+- Transcript imports (`backfill`, the `run` ledger, `recover`) now drop Codex
+ memory-writing agent runs by the same signals the live hook uses: the
+ checkout cwd, an event's recorded cwd, or a Codex user prompt that opens
+ with `## Memory Writing Agent`. A custom `CODEX_HOME` whose last path
+ component is not `.codex` previously reimported those sessions (#1790).
+- Admission webhook HTTP requests now follow redirects only within the
+ configured `scheme://host:port` origin (up to 10 hops) and fail on
+ cross-origin redirects without forwarding page payloads or applying foreign
+ response mutations, surfacing the redirect refusal cause in logs and
+ `reject`-policy errors (#1794).
+- `ai-memory project access` and `ai-memory project grants` now refuse empty
+ or whitespace-only `--workspace`, `--project`, and (for access) `--mode`
+ values before sending any request to the server. These commands take
+ required names and never call `resolve_scope`, so the #1774 choke point
+ did not cover them (#1791).
+- `ai-memory user grant` and `ai-memory user revoke` now refuse empty or
+ whitespace-only `--user`, `--workspace`, `--project`, and (for grant)
+ `--level` values before sending any request to the server. These commands
+ take required names and never call `resolve_scope`, so the #1774 choke
+ point did not cover them (#1792).
+- Stopped the lifecycle relay from treating an oversized HTTP response as a
+ transport failure and immediately resending its batch. A response beyond the
+ 64 KiB acknowledgement cap now retains its HTTP status, stops the flush, and
+ keeps unacknowledged events pending, including on HTTP 429 backpressure (#1799).
+- Decoded WebVTT cue character references before document-import sanitization,
+ preserving literal escaped tags and applying the existing text-size limit
+ to the decoded text. SRT extraction is unchanged (#1800).
+- Preserved native OIDC hook-spool entries when the POSIX or PowerShell script
+ bundle drained the shared queue. Scripts now leave those entries for native
+ credential resolution instead of posting them anonymously and retiring them
+ on a 2xx or 401 response; static, anonymous and legacy entries still drain
+ normally (#1801).
+- Refused backup restores with a missing or invalid gzip trailer before
+ replacing live data, even when all tar entries were readable (#1805).
+- Kept separate pre-migration archives when installations share a backup
+ destination and start in the same second, instead of overwriting an
+ existing installation's snapshot (#1806).
+- Restored the previous wiki file when `restore-page` could not commit its
+ SQLite update, including a rejected case-colliding historical path. Restores
+ now share the page writer's lock through conformance, file replacement and
+ indexing so a concurrent write to that same path cannot leave disk and
+ SQLite disagreeing (#1807).
+- Kept concurrent page edits current during opt-in cold-cluster dedup and dream
+ merges. Each write batch now skips if a selected source version changed,
+ preserving the newer body, tier and pin along with unchanged peers (#1808).
+- Dropping the final store writer handle now finishes when its command queue
+ is full. Accepted writes still drain before the writer thread exits, including
+ when callers have cancelled their waits (#1809).
+
+- Scheduled empty-project cleanup now preserves projects that have sent or
+ received agent messages, including claimed/cancelled history, so it cannot
+ silently delete their inbox/outbox through a project cascade (#1810).
+
+- Fixed `server add` rejecting valid inline tables in `servers.toml`, including
+ token rotations and URL changes. Updates now accept the same table forms as
+ reads and removal, preserving registered roots and other profiles (#1812).
+- Kept OpenCode V1 failed tool results in the managed workstream ledger,
+ including their visible error text and error status, instead of importing
+ only the call and silently dropping the failure reason (#1814).
+- Initialized the TypeScript SDK's MCP session before the first `callTool`,
+ fixing HTTP 422 responses with `--http-stateful`. Raw calls still skip
+ schema checks, and later wrapped calls reuse the session (#1816).
+- Preserved literal reasoning tags and their contents inside structured JSON
+ strings when parsing OpenAI-compatible tolerant replies and Anthropic text
+ replies. Reasoning blocks outside the JSON are still removed, including
+ when a strict OpenAI-compatible request falls back to tolerant parsing (#1817).
+- Disabled HTTP redirect following on the native hook client (`build_client`)
+ so 3xx responses from SSO gateways, captive portals, or proxies fail closed
+ instead of following to a 200 OK login page, which dropped spooled hook events
+ and injected login HTML into agent handoff context (#1818).
+- Supported singular units (`day`, `week`, `month`) and weeks in
+ `parse_since_to_epoch` for git commit filtering during consolidation
+ bootstrapping, trimmed surrounding whitespace, rejected negative intervals,
+ and used checked arithmetic to prevent integer overflow panics (#1820).
+- Kept OpenCode 2 failed tool results in the managed workstream ledger,
+ including their visible error text and error status, instead of importing
+ only the call and recording a status-error loss (#1823).
+- Imported OpenCode 2 compaction session messages into the managed workstream
+ ledger (`summary`, or `error.message` on a failed compaction) instead of
+ dropping them with no event and no loss (#1824).
+- `memory_query(global=false)` now overrides a project's
+ `[recall] default_global` marker and uses the resolved project's normal
+ search. Previously the explicit opt-out still returned cross-project
+ `global_hits` and disabled project-only query options (#1835).
+- Honored `base_path` from `config.toml` when mounting the HTTP server, so
+ thin clients and the web UI use the same prefix. Explicit flag and environment
+ overrides, including an empty value to serve at the root, kept their precedence (#1837).
+- Fixed live response capture after transcript gaps. Bounded batches now resume
+ from durable enqueue checkpoints, including across hook processes and
+ transcript read windows (#1830).
+
+- Fixed response search, signal filtering and recent ordering so they query all
+ authorized calls before pagination. Response pages are independent, and
+ session detail pages refresh usage live (#1830).
+
+- Updated scoped session reads to treat substantive work after an old end as a
+ resumed session, matching the activity feed while preserving persisted
+ lifecycle watermarks. Completed-only listings exclude those resumed sessions (#1830).
+
+- Moved token model label sanitization before truncation to prevent the size
+ limit from exposing a prefix of private text (#1830).
+
+- Updated release selection on the changelog page to load notes immediately
+ and keep the URL, outline and Markdown reference in sync. The form still submits
+ without JavaScript (#1830).
+
+- Added a read-only recovery snapshot at agent startup when the previous
+ substantive session in the project ended without a `SessionEnd` (quota
+ exhaustion, a killed process, a machine restart). The snapshot is built on
+ demand from at most 64 sanitized observations and capped at 6,000
+ characters, so no rolling copy of the transcript exists. It is scoped to the
+ project and owner, leaves out the receiving session, keeps the
+ untrusted-memory boundary, and never closes or claims the source, which may
+ be a legitimate parallel agent. It skips work a handoff already covers and
+ never mixes another live session's transcript into a delivered handoff.
+ Normal single-use handoffs and managed workstream packets are unchanged
+ (#1803).
+
- Refused empty and whitespace-only `--workspace` and `--project` flags at the
shared CLI scope-resolution choke point (`resolve_scope`,
`resolve_scope_noting_marker_project`, `resolve_scope_with_marker`, and
diff --cc companions/ai-memory-ts/CHANGELOG.md
index d6b0574c,f504151a..d959ccbd
--- a/companions/ai-memory-ts/CHANGELOG.md
+++ b/companions/ai-memory-ts/CHANGELOG.md
@@@ -25,10 -13,11 +25,15 @@@ and this project adheres to [Semantic V
- `query` takes the server's `memory_query` page filters: `kind`, `tier`,
`pathPrefix` and `tag`, in every search mode.
+- `messages.pop` takes `agent`, the harness claiming harness-addressed mail,
+ and `Message` carries `toAgent` (`null` for shared project mail), matching
+ the server's new `to_agent` addressing.
+
+ - `pages.read` takes `maxChars`, and `Page` carries `truncated` and
+ `totalChars`, matching the server's new `memory_read_page` size cap. Both are
+ `undefined` against a server that predates it. The documented `observations`
+ defaults are now 20 rows of 1000 characters.
+
## [0.1.0]
### Added
diff --cc companions/ai-memory-ts/src/types.ts
index e07a26a2,d38ce65b..ed7fbba2
--- a/companions/ai-memory-ts/src/types.ts
+++ b/companions/ai-memory-ts/src/types.ts
@@@ -217,14 -155,14 +219,18 @@@ export interface Page
readonly path: string;
/** Page title. */
readonly title: UntrustedText;
- /** Markdown body. */
+ /** Markdown body, cut at `maxChars` with a visible marker when `truncated`. */
readonly body: UntrustedText;
+ /** Whether the server cut the body at `maxChars`. */
+ readonly truncated: boolean | undefined;
+ /** Length in characters of the untruncated body. */
+ readonly totalChars: number | undefined;
/** Parsed frontmatter (tags, tier, pinned and other metadata). Untrusted. */
readonly frontmatter: Readonly<Record<string, unknown>>;
+ /** Bounded heading hashes for anchored patches. */
+ readonly sections: readonly PageSection[];
+ /** True when the page has more sections than the response cap. */
+ readonly sectionsTruncated: boolean;
/** Pages reachable through links, present only with `includeRelated`. */
readonly related: readonly RelatedPage[] | undefined;
/** The server's decoded JSON. */
diff --cc companions/ai-memory-ts/test/unit/client.test.ts
index 751c298d,326dd252..3b7cf589
--- a/companions/ai-memory-ts/test/unit/client.test.ts
+++ b/companions/ai-memory-ts/test/unit/client.test.ts
@@@ -661,17 -545,7 +679,17 @@@ describe("wire names", () =>
expectedPageId: "v",
}),
memory.pages.write({ path: "p", body: "b", createOnly: true }),
+ memory.pages.patch({
+ path: "p",
+ expectedPageId: "v",
+ edits: [
+ { op: "append", target: "section", anchor: "A", content: "a" },
+ { op: "append", target: "end_of_page", content: "b" },
+ { op: "add_section", anchor: "## B", content: "c" },
+ { op: "replace_section", anchor: "C", sectionSha256: "h", content: "d" },
+ ],
+ }),
- memory.pages.read({ path: "p", includeRelated: true, relatedDepth: 2 }),
+ memory.pages.read({ path: "p", includeRelated: true, relatedDepth: 2, maxChars: 500 }),
memory.pages.read({ query: "q" }),
memory.pages.delete({ path: "p", expectedPageId: "v" }),
memory.query({
diff --cc crates/ai-memory-mcp/src/server.rs
index e4805ea5,451d9074..4cd1e4a6
--- a/crates/ai-memory-mcp/src/server.rs
+++ b/crates/ai-memory-mcp/src/server.rs
@@@ -1733,36 -1705,31 +1735,53 @@@ struct ReadPageArgs
/// Ignored when `include_related` is false.
#[serde(default)]
related_depth: Option<u8>,
+ /// Cap the returned body at this many characters (default 12000, min
+ /// 500, max 64000). Longer bodies end with a visible truncation marker
+ /// and the response adds `truncated: true` and `total_chars`. Raise
+ /// this only when you actually need the whole page; most callers should
+ /// keep the default.
+ #[serde(default)]
+ max_chars: Option<usize>,
}
+#[derive(Debug, Deserialize, schemars::JsonSchema)]
+struct PatchPageArgs {
+ /// Existing page path to patch.
+ path: String,
+ /// Required latest page version from `memory_read_page`. The entire batch
+ /// fails if another writer changed or deleted the page.
+ expected_page_id: String,
+ /// Anchored edits, all resolved against the same captured base body.
+ edits: Vec<crate::page_patch::PagePatchEdit>,
+ /// Project containing the existing page. Session-aware clients may omit it
+ /// for the current project. Static MCP clients must pass it together with
+ /// `workspace` for every project-scoped call; partial explicit scope fails
+ /// closed.
+ #[serde(default)]
+ project: Option<String>,
+ /// Workspace containing the existing page, together with `project`.
+ /// Session-aware clients may omit both for the current project; static MCP
+ /// clients must pass both.
+ #[serde(default)]
+ workspace: Option<String>,
+}
+
+ /// Bounds for `memory_read_page`'s `max_chars`. The default keeps a typical
+ /// page read well under a context window while staying large enough that
+ /// most pages never truncate; the ceiling still lets a caller read a long
+ /// page whole by raising it explicitly.
+ const READ_PAGE_DEFAULT_MAX_CHARS: usize = 12_000;
+ const READ_PAGE_MIN_MAX_CHARS: usize = 500;
+ const READ_PAGE_MAX_MAX_CHARS: usize = 64_000;
+
/// Bounds for `memory_read_session_observations`. The defaults keep one call
- /// well under a context window; the ceilings match what the store keeps per
- /// body (16 KiB) so a caller can always read a whole observation in one go.
- const SESSION_OBSERVATIONS_DEFAULT_LIMIT: usize = 50;
+ /// cheap — a "what did this session do" lookup should cost low thousands of
+ /// tokens, not tens of thousands — while the ceilings still match what the
+ /// store keeps per body (16 KiB) so a caller can always read a whole
+ /// observation in one go by raising `limit`/`body_max_chars` explicitly.
+ const SESSION_OBSERVATIONS_DEFAULT_LIMIT: usize = 20;
const SESSION_OBSERVATIONS_MAX_LIMIT: usize = 200;
- const SESSION_OBSERVATIONS_DEFAULT_BODY_CHARS: usize = 4_000;
+ const SESSION_OBSERVATIONS_DEFAULT_BODY_CHARS: usize = 1_000;
const SESSION_OBSERVATIONS_MIN_BODY_CHARS: usize = 200;
const SESSION_OBSERVATIONS_MAX_BODY_CHARS: usize = 16_384;
/// Sessions with recent work the default read scans for one in the caller's
@@@ -5317,15 -5082,17 +5346,20 @@@ impl AiMemoryServer
// frontmatter title was never filled otherwise read back
// titleless despite a proper `# Heading` (#599).
let title = ai_memory_wiki::derive_title(&md.frontmatter, &md.body, &page_path);
+ let (sections, sections_truncated) = crate::page_patch::section_hashes(&md.body);
+ let total_chars = md.body.chars().count();
+ let truncated = total_chars > max_chars;
+ let body = cap_text_with_marker(&md.body, max_chars, "body");
ok_json(&annotate(serde_json::json!({
"path": page_path.to_string(),
"page_id": page_id.map(|id| id.to_string()),
"title": title,
- "body": md.body,
+ "body": body,
"frontmatter": md.frontmatter,
+ "sections": sections,
+ "sections_truncated": sections_truncated,
+ "truncated": truncated,
+ "total_chars": total_chars,
})))
}
Err(disk_err) if is_missing_wiki_file(&disk_err) => {
@@@ -5344,17 -5111,18 +5378,22 @@@
.and_then(|v| v.as_str())
.map(str::to_string)
.or(Some(stored.title));
+ let (sections, sections_truncated) =
+ crate::page_patch::section_hashes(&stored.body);
+ let total_chars = stored.body.chars().count();
+ let truncated = total_chars > max_chars;
+ let body = cap_text_with_marker(&stored.body, max_chars, "body");
ok_json(&annotate(serde_json::json!({
"path": page_path.to_string(),
"page_id": page_id.map(|id| id.to_string()),
"title": title,
- "body": stored.body,
+ "body": body,
"frontmatter": frontmatter,
+ "sections": sections,
+ "sections_truncated": sections_truncated,
"served_from": "db-fallback",
+ "truncated": truncated,
+ "total_chars": total_chars,
})))
}
None => {
@@@ -10507,57 -9071,6 +10546,59 @@@ mod tests
);
}
+ #[tokio::test]
+ async fn operations_addressed_mail_uses_the_declared_receiving_agent() {
+ let (_tmp, store, server, ws, project) = setup_server().await;
+ store
+ .writer
+ .insert_message(ai_memory_core::NewAgentMessage {
+ from_workspace_id: ws,
+ from_project_id: project,
+ from_agent: AgentKind::Other,
+ from_session_id: None,
+ from_owner_user: None,
+ to_workspace_id: ws,
+ to_project_id: project,
+ to_agent: Some(AgentKind::Codex),
+ subject: Some("Browser request".into()),
+ body: "Inspect this project".into(),
++ nature: ai_memory_core::MessageNature::Unknown,
++ evidence: None,
+ })
+ .await
+ .unwrap();
+ for (agent, delivered) in [
+ (None, false),
+ (Some("claude-code"), false),
+ (Some("codex"), true),
+ ] {
+ let result = call_tool_json(
+ server
+ .memory_message_pop(
+ Parameters(MessagePopArgs {
+ agent: agent.map(str::to_owned),
+ message_id: None,
+ project: Some("scratch".into()),
+ workspace: Some("default".into()),
+ }),
+ test_optional_parts(),
+ )
+ .await
+ .unwrap(),
+ );
+ assert_eq!(!result["message"].is_null(), delivered);
+ if delivered {
+ assert_eq!(result["message"]["to_agent"], "codex");
+ assert!(
+ result["security_notice"]
+ .as_str()
+ .unwrap()
+ .contains("UNTRUSTED")
+ );
+ }
+ }
+ }
+
#[tokio::test]
async fn message_send_then_pop_round_trips_across_projects() {
let (_tmp, store, server, ws, _scratch) = setup_server().await;
@@@ -15373,6 -13879,6 +15415,7 @@@
workspace: None,
include_related: false,
related_depth: None,
++ max_chars: None,
}),
OptionalParts(test_parts_default()),
)
@@@ -18622,240 -17244,6 +18779,241 @@@
}
}
+ #[tokio::test]
+ async fn memory_patch_page_preserves_metadata_and_enforces_both_preconditions() {
+ let (tmp, store, server, ws, proj) = setup_server().await;
+ let server = server.with_wiki(Wiki::new(tmp.path(), store.writer.clone()).unwrap());
+ let write = server
+ .memory_write_page(
+ Parameters(WritePageArgs {
+ metadata: serde_json::from_value(serde_json::json!({
+ "kind": "fact",
+ "abstract": "preserve me"
+ }))
+ .unwrap(),
+ path: "notes/status.md".into(),
+ body: "# Status\n## Log\nold\n".into(),
+ title: None,
+ tier: Some("procedural".into()),
+ tags: vec!["customer".into()],
+ pinned: true,
+ project: None,
+ workspace: None,
+ scope: None,
+ expires_at: None,
+ session_id: None,
+ create_only: false,
+ expected_page_id: None,
+ }),
+ OptionalParts(test_parts_default()),
+ )
+ .await
+ .unwrap();
+ let first = call_tool_json(write);
+ let page_id = first["page_id"].as_str().unwrap().to_owned();
+ let page = server
+ .memory_read_page(
+ Parameters(ReadPageArgs {
+ path: Some("notes/status.md".into()),
+ query: None,
+ project: None,
+ workspace: None,
+ include_related: false,
+ related_depth: None,
++ max_chars: None,
+ }),
+ OptionalParts(test_parts_default()),
+ )
+ .await
+ .unwrap();
+ let page = call_tool_json(page);
+ let section_sha256 = page["sections"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .find(|section| section["anchor"] == "Log")
+ .unwrap()["sha256"]
+ .as_str()
+ .unwrap()
+ .to_owned();
+
+ let patch = |page_id: String, section_sha256: String, content: &str| PatchPageArgs {
+ path: "notes/status.md".into(),
+ expected_page_id: page_id,
+ edits: vec![crate::page_patch::PagePatchEdit::ReplaceSection {
+ anchor: "Log".into(),
+ section_sha256,
+ content: content.into(),
+ }],
+ project: None,
+ workspace: None,
+ };
+ let patched = server
+ .memory_patch_page(
+ Parameters(patch(page_id.clone(), section_sha256.clone(), "new")),
+ OptionalParts(test_parts_default()),
+ )
+ .await
+ .unwrap();
+ let patched = call_tool_json(patched);
+ assert_ne!(patched["page_id"], page_id);
+ let stored = server
+ .wiki
+ .as_ref()
+ .unwrap()
+ .read_page(ws, proj, &PagePath::new("notes/status.md").unwrap())
+ .unwrap();
+ assert_eq!(stored.body, "# Status\n## Log\nnew\n");
+ assert_eq!(stored.frontmatter["kind"], "fact");
+ assert_eq!(stored.frontmatter["abstract"], "preserve me");
+ assert_eq!(stored.frontmatter["tier"], "procedural");
+ assert_eq!(stored.frontmatter["pinned"], true);
+ assert_eq!(stored.frontmatter["tags"], serde_json::json!(["customer"]));
+
+ let stale_page = server
+ .memory_patch_page(
+ Parameters(patch(page_id, section_sha256.clone(), "lost")),
+ OptionalParts(test_parts_default()),
+ )
+ .await
+ .unwrap_err();
+ assert_eq!(stale_page.data.unwrap()["reason"], "precondition_failed");
+ let fresh_id = patched["page_id"].as_str().unwrap().to_owned();
+ let stale_section = server
+ .memory_patch_page(
+ Parameters(patch(fresh_id, section_sha256, "lost")),
+ OptionalParts(test_parts_default()),
+ )
+ .await
+ .unwrap_err();
+ assert_eq!(
+ stale_section.data.unwrap()["reason"],
+ "section_precondition_failed"
+ );
+ let stored = server
+ .wiki
+ .as_ref()
+ .unwrap()
+ .read_page(ws, proj, &PagePath::new("notes/status.md").unwrap())
+ .unwrap();
+ assert!(!stored.body.contains("lost"));
+ }
+
+ #[tokio::test]
+ async fn memory_patch_page_requires_write_access_and_one_concurrent_writer_wins() {
+ let (tmp, store, server, _ws, proj) = setup_server().await;
+ let server = server.with_wiki(Wiki::new(tmp.path(), store.writer.clone()).unwrap());
+ store
+ .writer
+ .set_access_mode(proj, ai_memory_store::AccessMode::Restricted)
+ .await
+ .unwrap();
+ let user = store
+ .writer
+ .create_human_user(
+ NewUser {
+ username: "patcher".into(),
+ name: None,
+ email: None,
+ },
+ ai_memory_core::UserRole::User,
+ None,
+ false,
+ )
+ .await
+ .unwrap();
+ let write = server
+ .memory_write_page(
+ Parameters(WritePageArgs {
+ metadata: Default::default(),
+ path: "notes/shared.md".into(),
+ body: "# Shared\n".into(),
+ title: None,
+ tier: None,
+ tags: vec![],
+ pinned: false,
+ project: None,
+ workspace: None,
+ scope: None,
+ expires_at: None,
+ session_id: None,
+ create_only: false,
+ expected_page_id: None,
+ }),
+ OptionalParts(test_parts_default()),
+ )
+ .await
+ .unwrap();
+ let page_id = call_tool_json(write)["page_id"]
+ .as_str()
+ .unwrap()
+ .to_owned();
+ let args = |content: &str| PatchPageArgs {
+ path: "notes/shared.md".into(),
+ expected_page_id: page_id.clone(),
+ edits: vec![crate::page_patch::PagePatchEdit::Append {
+ target: crate::page_patch::AppendTarget::EndOfPage,
+ anchor: None,
+ content: content.into(),
+ }],
+ project: Some("scratch".into()),
+ workspace: Some("default".into()),
+ };
+ let mut user_parts = test_parts_default();
+ user_parts.extensions.insert(AuthLevel::User);
+ user_parts.extensions.insert(user);
+ user_parts
+ .extensions
+ .insert(ai_memory_core::AuthorizedViewer(user));
+ let denied = server
+ .memory_patch_page(Parameters(args("denied")), OptionalParts(user_parts))
+ .await;
+ assert!(denied.is_err());
+
+ grant_writer(store.db_path(), user, proj);
+ let mut granted_parts = test_parts_default();
+ granted_parts.extensions.insert(AuthLevel::User);
+ granted_parts.extensions.insert(user);
+ granted_parts
+ .extensions
+ .insert(ai_memory_core::AuthorizedViewer(user));
+ server
+ .memory_patch_page(Parameters(args("granted")), OptionalParts(granted_parts))
+ .await
+ .unwrap();
+
+ let current = server
+ .reader
+ .latest_page_id_by_ids(
+ _ws,
+ proj,
+ PagePath::new("notes/shared.md").unwrap().to_string(),
+ )
+ .await
+ .unwrap()
+ .unwrap()
+ .to_string();
+ let concurrent = |content: &str| PatchPageArgs {
+ expected_page_id: current.clone(),
+ ..args(content)
+ };
+ let (left, right) = tokio::join!(
+ server.memory_patch_page(
+ Parameters(concurrent("left")),
+ OptionalParts(test_parts_default())
+ ),
+ server.memory_patch_page(
+ Parameters(concurrent("right")),
+ OptionalParts(test_parts_default())
+ )
+ );
+ assert_ne!(
+ left.is_ok(),
+ right.is_ok(),
+ "exactly one CAS writer must win"
+ );
+ }
+
/// A malformed path, tier or scope is the caller's mistake, so the page
/// tools answer `invalid params` like their siblings, not an internal
/// error a client would read as "the server broke, retry".
diff --cc crates/ai-memory-mcp/tests/suite/access_reinforcement.rs
index ed173bc7,57ed5ab0..51159f51
--- a/crates/ai-memory-mcp/tests/suite/access_reinforcement.rs
+++ b/crates/ai-memory-mcp/tests/suite/access_reinforcement.rs
@@@ -290,9 -290,9 +290,11 @@@ async fn read_page_response_payload_unc
"frontmatter",
"page_id",
"path",
+ "sections",
+ "sections_truncated",
"title",
+ "total_chars",
- "truncated"
++ "truncated",
],
"reinforcement must not add fields to the read_page payload: {resp}"
);
diff --cc docs/ARCHITECTURE.md
index f3e7840e,3e865c30..bb8694f4
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@@ -781,10 -734,9 +781,10 @@@ does not need to ride on the public pro
| Tool | Hint | Purpose |
|---|---|---|
-| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`. Citation paths must identify exactly one supplied page version, including supplemental preferences. Repeated citations are deduplicated in model order. An unknown path or a path shared by distinct page IDs withholds the whole answer and returns `answer_unavailable` with the unchanged retrieval hits; this includes same-path historical versions. Empty citations remain valid for abstention. This validates source identity, not the truth of generated claims. With no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
+| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`. Citation paths must identify exactly one supplied page version, including supplemental preferences. Repeated citations are deduplicated in model order. An unknown path or a path shared by distinct page IDs withholds the whole answer and returns `answer_unavailable` with the unchanged retrieval hits; this includes same-path historical versions. Empty citations remain valid for abstention. This validates source identity, not the truth of generated claims. With no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Optional `[query_answer] max_context_tokens` bounds synthesis admission while preserving all retrieval hits. Each UTF-8 input byte counts as one estimated token; serialized schema bytes and a fixed 1024-unit provider-envelope allowance also count, and the reasoning tier's output allowance is reserved separately. This is a conservative admission contract, not a guarantee for every provider's tokenizer or framing. Answer admission gives known supersession successors priority over predecessors, and newer evidence priority within the same workspace/project and normalized exact title. A bounded metadata query reads only already-authorized hit IDs; canonical session pages use session start time rather than ingestion time. Unrelated evidence retains retrieval order. Whole snippets are admitted before any clipping. Otherwise-unused space may hold one final complete trailing sentence or statement, with ellipses marking removed text; a fragment with no complete boundary is omitted. The boundary rule recognizes sentence punctuation and code statement terminators and does not perform semantic inference. Empty and punctuation-only snippets are omitted. `answer_context` reports `admitted`, `omitted`, `clipped`, `estimated_input_tokens`, `reserved_output_tokens` and `max_context_tokens`; it appears only when admission runs. If fixed content or evidence cannot fit, the provider is not called and `answer_unavailable` accompanies the full hits. The question is never silently clipped. Citation validation uses only admitted sources. Superseded status is explicit in budgeted prompts. Clipping can remove a qualification or correction; callers should inspect the receipt and original hits. An explicit zero or undersized limit prevents synthesis; only omission disables admission. Omitted configuration preserves existing wire request and response bytes. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). Optional `kind`, `tag`, `tier` and `path_prefix` filters narrow candidates before ranking, on every stream including the CJK substring search. |
| `memory_recent` | read-only | Most-recently-updated `is_latest=1` pages. |
- | `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). The response carries the page's current version as `page_id`, the value compare-and-write calls pass back, plus at most 100 parsed Markdown headings with exact section SHA-256 tokens for `memory_patch_page` (`sections_truncated` reports overflow). Fenced-code headings are excluded. A page whose `expires_at` TTL has passed is still returned and carries `expired: true`; a live page's response has no such field. |
-| `memory_read_page` | read-only | Fetch the body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. The body is capped by `max_chars` (default 12000, max 64000); responses include `truncated` and `total_chars`. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). The response carries the page's current version as `page_id`, the value compare-and-write calls pass back. A page whose `expires_at` TTL has passed is still returned and carries `expired: true`; a live page's response has no such field. |
++| `memory_read_page` | read-only | Fetch the body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. The body is capped by `max_chars` (default 12000, max 64000); responses include `truncated` and `total_chars`. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off adds no `related` field. The response carries the page's current version as `page_id`, the value compare-and-write calls pass back, plus at most 100 parsed Markdown headings with exact section SHA-256 tokens for `memory_patch_page` (`sections_truncated` reports overflow). Section hashes always cover the full body even when the returned body is truncated. Fenced-code headings are excluded. A page whose `expires_at` TTL has passed is still returned and carries `expired: true`; a live page's response has no such field. |
+| `memory_patch_page` | destructive | Atomically append inside a parsed Markdown section or at EOF, add a unique level 2-6 section, or replace a section. It requires the current page id; replacement also requires the read-returned exact section hash. All edits resolve against one captured body, ambiguity/conflicts fail before writing, and the resulting full page goes through `Wiki::write_page_if`, preserving frontmatter and the normal sanitizer, admission, attribution, supersession, index, rollback and git-checkpoint boundaries. Existing-scope write authorization is fail-closed and cannot create a target. |
| `memory_read_session_observations` | read-only | Page through ONE session's raw hook observations (`ObservationRecord` with full sanitized body, capped per row by `body_max_chars`), restricted to the rows that landed in the resolved scope and to sessions the caller may see; `total` and `elided_other_scope` report the in-scope count and the rows the session left in another project. `session_id` omitted reads the visible session with the newest captured work other than the caller's own, ended or cut off (`ReaderPool::recent_session_activity` over 30 days, preferring the caller session's cwd), else the latest completed visible session. |
| `memory_status` | read-only | Counts, paths, version, plus the `scope` that answered: `workspace`, `project`, and `resolved_by` (`explicit`, `session`, `shared_slot`, `startup_seed`, `default`, `default_after_mismatch`). Unscoped reads resolved by `startup_seed` or `default_after_mismatch` also log a server warning. |
| `memory_briefing` | read-only | Structured counts/activity/rules/slots/recent snapshot. Project-scoped snapshots also carry a bounded `pinned` list (up to 10) of the project's pinned latest pages (`pinned = 1`, newest first) as standing SessionStart hot-context, distinct from `slots`, which is keyed by the `_slots/` path prefix; empty and omitted from JSON when the project has no pins, so the default shape is unchanged. Opt-in `settled_first: true` leads with up to 8 of the project's highest-standing `rule`/`decision` pages, ordered by evidence count then recency; off by default. `scope` names the workspace/project briefed and `resolved_by` how it was chosen. |