Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(agent): add P10 memory lifecycle calibration
Rahman25f74e692fe3
diff --git a/README.md b/README.mdindex 007037b5..c9febc56 100644--- a/README.md+++ b/README.md@@ -79,7 +79,7 @@ For a real deployment, put MSO behind **Tailscale, a VPN, or a TLS reverse proxy- **Message live local sessions by a short name** — every durable same-principal MSO session gets a unique familiar handle such as `@milo`, `@luna`, or `@nara`, independent from its longer auto-generated session title. `/rename <name>` changes that handle, while `/title <text>` changes the session description. `@milo …` resolves only agents with a current lease **and** a live receiver subscription, then creates an explicitly correlated request; replies relay deterministically into the originating conversation while notify-only events remain passive. Presence lease (`idle`/`busy`/`offline`) and receiver subscription (`consumerConnected`) are reported separately so an idle-but-unsubscribed target is diagnosable. For ChatGPT/MCP sessions, `local_agent_inbox(wait_ms=...)` temporarily turns the foreground MCP call into that live receiver for up to 20 seconds, enabling direct two-way session messaging without a worker, DB, webhook, or broker. See [Local Agents](./docs/LOCAL-AGENTS.md).- **Spawn focused same-session subagents** — `/spawn` and `agent_subagent_run` create bounded foreground workers with isolated context, explicit delegated scope, turn/timeout caps, no recursive spawn, and final-result-only return. They are not Local Agent peers and do not run autonomously after the parent call returns. See [Subagents](./docs/SUBAGENTS.md).- **Delegate between remote agents with standard A2A v1** — register public HTTPS peers, attach private API-key/Bearer/OAuth access-token profiles, stream remote tasks over SSE, or expose MSO's authenticated inbound Agent Card when a public HTTPS origin is configured. Inbound credentials are owner-minted `read | write | exec` capabilities and run in a memory-isolated task context. See [A2A](./docs/A2A.md).-- **Keep agents efficient independently of the model provider** — the MCP-first [Cognitive Runtime](./docs/COGNITIVE-RUNTIME.md) isolates conversations from OAuth identity, budgets model context/tool output, uses the RASMIC catalog-first router to select a tiny per-turn capability pack without weakening scopes, compacts durable sessions with sanitized 30-day backup archives, learns only verified workflow recipes, promotes repeated procedures only through the eval-gated Tool Forge, and batches/filter/aggregates independent reads through `read_pipeline` before raw data reaches the model. `bun run bench:cognitive`, `bun run bench:memory:calibration`, `bun run bench:pipeline`, isolated scratch-fixture `bun run bench:corpus`, deterministic repeated `bun run bench:corpus:repeat`, and observation-only `bun run bench:cache-calibration` guard routing, memory correction/privacy semantics, correctness, policy compliance, repeat coverage/spread, latency, context savings, cache telemetry, and proof-gated normalized provider usage so cache/reasoning details are never double-counted or guessed.+- **Keep agents efficient independently of the model provider** — the MCP-first [Cognitive Runtime](./docs/COGNITIVE-RUNTIME.md) isolates conversations from OAuth identity, budgets model context/tool output, uses the RASMIC catalog-first router to select a tiny per-turn capability pack without weakening scopes, compacts durable sessions with sanitized 30-day backup archives, learns only verified workflow recipes, promotes repeated procedures only through the eval-gated Tool Forge, and batches/filter/aggregates independent reads through `read_pipeline` before raw data reaches the model. `bun run bench:cognitive`, `bun run bench:memory:calibration`, `bun run bench:memory:lifecycle`, `bun run bench:memory:retrieval-calibration`, `bun run bench:pipeline`, isolated scratch-fixture `bun run bench:corpus`, deterministic repeated `bun run bench:corpus:repeat`, and observation-only `bun run bench:cache-calibration` guard routing, memory correction/privacy/retention semantics, frozen-session behavior, lexical/relationship retrieval evidence gates, correctness, policy compliance, repeat coverage/spread, latency, context savings, cache telemetry, and proof-gated normalized provider usage so cache/reasoning details are never double-counted or guessed.- **Make orchestration risk-aware and self-improving** — [RASMIC](./docs/RASMIC.md) classifies task risk/contention, retrieves compact repo-local memory, records manual user tests and Evidence Receipts, detects path/shared-resource collisions before merge conflicts, and promotes repeated safe routes from observed traces → recipes → tested bounded scripts.- **Add app slices** — features are modular under `frontend/slices/<slug>/`.- **Personalize the interface** — macOS, Windows, iOS, and Android shell layouts are UI preferences, not the core product.diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex d4e0d94c..8885abd0 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,6 +8,7 @@ this is the *what*, and it is what Settings → About shows as “What's new”.**Added**+- `agent` add P10 memory lifecycle calibration- `mcp` complete Fresh 3 plugin contracts- `mcp` maximize Fresh 3 operator capabilities- `mcp` harden ChatGPT profile and project bridgediff --git a/docs/COGNITIVE-RUNTIME.md b/docs/COGNITIVE-RUNTIME.mdindex 6d400f4c..4ac71ad3 100644--- a/docs/COGNITIVE-RUNTIME.md+++ b/docs/COGNITIVE-RUNTIME.md@@ -91,8 +91,10 @@ recovery is a narrower read/search/grep/tail, not silently increasing the contexP1 keeps the two proven planes but upgrades stable agent memory from untyped Markdown into a structured, backward-compatible ledger:-- **Agent memory ledger** — private `records-v1.json` claims keyed by client principal, with semantic/episodic/procedural kind, confidence, sensitivity, temporal validity, provenance authority/channel, supersession/retraction and conflict evidence.+- **Agent memory live ledger** — private `records-v1.json` claims keyed by client principal, with semantic/episodic/procedural kind, confidence, sensitivity, temporal validity, provenance authority/channel, supersession/retraction and conflict evidence. Hard safety limits remain 2,000 live records / 2 MiB.+- **Cold finished-history archive** — P10 moves only records that can no longer become effective now or in the future into owner-only content-addressed `archive-v1/segment-<sha>.json` files before the live-ledger swap. Normal resolved reads never load archive content. Explicit history or explicit temporal retrieval can read it, preserving provenance and historical resolution without inflating model-active context.- **Markdown compatibility projection** — `USER.md` / `MEMORY.md` remain the resolved materialized view consumed by older CLI/session code. Existing installations are read unchanged; the first structured mutation seeds the ledger from legacy `## key` sections instead of deleting or rewriting history.+- **Privacy-safe memory telemetry** — aggregate-only lifecycle diagnostics count live/archived/resolved/superseded/retracted/future/conflict records, correction-depth buckets, bytes and archive segments. They never emit memory values, raw keys, raw conversation ids, bearer data or secrets.- **Experience memory** — verified workflow trajectories remain client-scoped and now accumulate P1 quality telemetry: completed/failed/denied/rate-limited/invalid-argument steps, retries, rollback/restore evidence and timed-step latency.Resolution is deterministic at a requested timestamp: only effective claims participate, then authority (`explicit > observed > inferred > migration`), confidence, observation recency, creation recency and stable id break ties. `mode=replace` supersedes the currently resolved claim from its `valid_from`; `mode=claim` keeps parallel evidence so disagreement remains inspectable. A future replacement therefore does **not** erase the fact that is still valid today. `agent_memory_forget` retracts every matching claim that can still become effective now or later, so a scheduled future value cannot resurrect after a forget request; already-finished historical evidence is left unchanged and remains visible only through explicit history retrieval.@@ -107,6 +109,8 @@ Run:bun run bench:cognitive # routing/schema + typed-memory gatesbun run bench:memory # deterministic retrieval/temporal/conflict suitebun run bench:memory:calibration -- --corrections 200 # repeated-correction/privacy/context calibration in isolated temp memory+bun run bench:memory:lifecycle # retention/archive/telemetry/frozen-session calibration in isolated temp memory+bun run bench:memory:retrieval-calibration # paraphrase/synonym/bilingual + two-hop graph evidence gatebun run bench:quality -- --live # learned workflow success + P1 telemetry coveragebun run bench:agents -- --provider openai-codex --model gpt-5.6-terra # one-task smoke planbun run bench:corpus -- --provider openai-codex --model gpt-5.6-terra # nine-task dry plan@@ -367,6 +371,22 @@ That result does **not** prove that graph memory is never useful. It does show t4. **Preserve frozen-session semantics** — new sessions capture the latest resolved snapshot; an active session must not silently change because persistent memory changed elsewhere.5. **Benchmark semantic recall only if lexical retrieval becomes the bottleneck** — do not add embedding/vector infrastructure merely because it is available.+## P10 memory retention and lifecycle calibration++P10 completes that handoff without introducing a graph database, vector database or external memory service. Retention is deterministic and threshold-driven: at **1,400 live records or ~1.4 MiB**, MSO attempts to archive the oldest finished records until the live ledger is at or below **1,000 records and ~1 MiB**. The existing **2,000-record / 2 MiB hard caps remain fail-closed**. If the ledger is large because records are still current or future-effective, retention refuses to archive them and the hard guard remains authoritative.++Archive segments are bounded (up to 400 records / 768 KiB), owner-only (`0700` directory, `0600` files), content-addressed and written atomically through temp-file + rename. The archive write happens before the atomic live-ledger replacement so a crash cannot lose cold history. If a crash leaves the same record id in both places, explicit retrieval deduplicates with the persisted live ledger winning; the P10 crash fixture verifies that a stale archive copy cannot manufacture a retraction or replace live authority. Because archived rows are immutable, a later backdated replacement records the old id in its forward `supersedes` edge; temporal resolution treats that edge as the replacement boundary without rewriting cold history. This preserves `replace` semantics even when the archived claim had stronger authority.++`bun run bench:memory:lifecycle` uses only temporary memory/session roots. Its threshold fixture starts with 1,400 sequential corrections and ends at **1,000 live + 401 archived records in two segments** while the resolved projection remains **56 bytes**. The current suite is **8/8 deterministic**: retention before the hard cap, archived-history retrieval, archived temporal resolution, aggregate-only telemetry, owner-only permissions, archive-before-ledger crash recovery semantics, backdated replacement over immutable archive, and frozen-session behavior. Session A keeps its old snapshot after persistent memory changes; a newly created session B gets the new snapshot; resuming A returns A's frozen snapshot rather than silently live-refreshing it.++The lifecycle fixture also closed one deterministic lexical defect. A history search for `Runtime-1` could previously be crowded out by substring matches such as `Runtime-10` through `Runtime-19` before the result limit. Search scoring now prioritizes exact phrase/token matches and only uses bounded alphabetic-prefix matching for ordinary word stems. The existing 8-scenario `bench:memory` suite remains 100%.++`bun run bench:memory:retrieval-calibration` deliberately probes cases that literal lexical retrieval may not solve. The bounded fixture currently passes **4/6 lexical cases**: paraphrase-with-overlap, long-value tail retrieval, similar-key disambiguation and exact domain phrase pass; `IDE`↔`editor` synonym and Indonesian `kantor`↔English `office` remain objective misses. That is evidence of a semantic gap, but **not yet evidence for vector infrastructure**: no local embedding approach has demonstrated a measured recall benefit with acceptable privacy, latency and context cost. Vector/embedding storage therefore remains blocked rather than being added speculatively.++The same calibration passes **3/3 two-hop relationship fixtures** by retrieving the first edge and then the intermediate-node edge with the existing keyed records. This proves only that the tested relationship chains are reachable without graph storage; it is not a universal graph-reasoning claim. Graph memory remains blocked until a reproduced task cannot be solved with bounded keyed retrieval and a smaller relationship layer measurably fixes it.++P9's future-forget privacy rule remains unchanged and revalidated at **6/6** with 200 repeated corrections. Cache remains observation-only until request envelopes are equivalent, cost remains withheld until both runners expose comparable attributable USD semantics, OpenClaw remains unranked without a legitimate matched provider/model path, and five-run reliability remains descriptive rather than inferential.+## Security notes- Session archives are private backups, not secret vaults; recursive redaction happens before compression.diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex ec5eeda1..1917b3a1 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1,4 +1,15 @@# mso — Progress Log++## 2026-09-03 — Cognitive Runtime P10 memory retention & lifecycle++- **Cold-history retention before hard caps:** typed agent memory now starts deterministic retention at 1,400 live records or ~1.4 MiB and targets <=1,000 records / ~1 MiB by archiving only records whose effective interval has already ended. Current or future-effective facts are never selected; the existing 2,000-record / 2 MiB live-ledger limits remain fail-closed.+- **Crash-safe owner-only archive:** finished history moves into content-addressed `archive-v1/segment-<sha>.json` files (<=400 records / 768 KiB each) under `0700` directories / `0600` files. Archive segments are written before the atomic live-ledger swap; duplicate ids after an interrupted commit are deduped with the persisted live ledger winning. Backdated replacements use forward `supersedes` edges as temporal boundaries, so immutable archived rows never need in-place mutation. Explicit history/time-travel reads include cold records, while normal resolved memory stays archive-free.+- **Privacy-safe lifecycle telemetry:** aggregate diagnostics report live/archive/total counts, resolved keys, superseded/retracted/future/conflict counts, correction-depth buckets, max corrections per key, ledger/projection/archive bytes and segment count. No memory values, raw keys, raw conversation ids, bearer/client data or secrets are emitted. The telemetry is kept out of the default MCP memory-read payload to avoid permanent tool/context overhead.+- **Frozen sessions now have explicit regression coverage:** the isolated lifecycle fixture proves session A retains its captured old memory after persistent memory changes, session B captures the new value, and resuming A returns A's frozen snapshot. No hidden mutable global memory context was added.+- **Threshold calibration:** `bench:memory:lifecycle` is **8/8 deterministic**. A synthetic 1,400-correction ledger compacts to **1,000 live + 401 archived records / two segments**, with a 56-byte resolved projection. The same fixture verifies archived-history retrieval, historical temporal resolution, archive permissions, archive-before-ledger crash semantics, backdated replacement over immutable cold records, and frozen sessions without touching real operator memory.+- **Retrieval evidence gate found and fixed exact-match crowding:** history query `Runtime-1` could be displaced by substring matches like `Runtime-10` before the result limit. Deterministic scoring now prioritizes exact phrases/tokens and keeps bounded alphabetic-prefix stemming. Existing `bench:memory` stays 8/8 / 100%.+- **Vector and graph complexity remain evidence-blocked:** realistic retrieval calibration is **4/6 lexical**, with objective misses only for `IDE`↔`editor` synonym and Indonesian `kantor`↔English `office`; no embedding layer is added because no candidate has yet proven better recall with acceptable privacy/latency/context cost. Relationship calibration is **3/3 two-hop**, so current keyed retrieval does not justify graph storage.+- **P9 privacy semantics preserved:** 200-correction `bench:memory:calibration` remains 6/6 and future-scheduled claims still cannot resurrect after `forget`. Cache remains observation-only, cost remains attribution-blocked, OpenClaw remains unranked without a legitimate matched provider/model path, and five-run reliability remains descriptive.- **MCP Apps navigation hardening (2026-09-03):** server `1.8.2` / toolset `2026.09.03.7` bumps all four UI resources to v2 and makes `Open in MSO` self-diagnosing: official `openExternal` + `setOpenInAppUrl`, visible success/failure feedback, and a user-clickable direct-link fallback. No tool count or security-scope changes.## 2026-09-03 — Cognitive Runtime P9 memory calibrationdiff --git a/docs/TESTING-HANDOFF.md b/docs/TESTING-HANDOFF.mdindex 5e34c48c..ef7107a9 100644--- a/docs/TESTING-HANDOFF.md+++ b/docs/TESTING-HANDOFF.md@@ -8,6 +8,7 @@ The current release target is **MSO CLI 1.12.0**, MCP server `1.8.2`, toolset `2Current verified behavior:- Fresh 3 current MCP contract: server `1.8.2` / toolset `2026.09.03.7`; ChatGPT receives **62 transport tools = 61 model/operator actions (32 read / 17 write / 12 exec) + app-only `workflow_status`**, while the full transport catalog is 86 tools / 85 model tools. Every ChatGPT action advertises `outputSchema`, the dedicated MCP Apps widget origin is `https://mso-ui.rahmanef.com`, and five official digest-verified Skills are exposed through the MCP Skills/resource extension. The four MCP Apps use v2 resource URIs and `Open in MSO` now has visible bridge status, `setOpenInAppUrl`, and a direct-link fallback for host navigation failures.+- P10 memory retention/lifecycle: isolated fixtures now archive only cold finished claims before the hard 2,000-record / 2 MiB live-ledger limits. Trigger/target are 1,400 -> <=1,000 live records (or ~1.4 MiB -> ~1 MiB); archive segments are content-addressed, owner-only and archive-before-ledger atomic. `bench:memory:lifecycle` is **8/8 deterministic** with a 1,400-correction seed ending at **1,000 live + 401 archived / two segments** and a 56-byte resolved projection. It verifies explicit archived-history retrieval, historical temporal resolution, aggregate-only no-content telemetry, `0700/0600` permissions, interrupted-commit live-wins semantics, backdated replacement over immutable archive, and frozen session A / fresh session B / resume-copy behavior. The P10 retrieval gate is **4/6 lexical** (synonym + Indonesian/English misses remain explicit), vector storage stays blocked without measured embedding benefit, and **3/3 two-hop relationship fixtures** keep graph storage blocked. The exact-history crowding bug (`Runtime-1` vs `Runtime-10...`) is fixed by exact phrase/token scoring; legacy `bench:memory` remains 100%.- P9 memory calibration: isolated temporary-memory fixtures now cover repeated corrections, explicit-vs-observed authority, confidence/recency, future validity, forget, and history integrity. P9 fixed a real temporal privacy bug where `forget` could leave a future-scheduled claim that resurrected later; forget now closes all current/future-capable intervals while preserving already-ended history. Final 200-correction stress from source `d249da4`: **6/6 calibration scenarios**, existing memory benchmark **100%**, Cognitive Runtime memory gates **100%**; 200 ledger rows / 135,180 bytes resolve to 1 row / 58-byte compatibility projection (**99.96% smaller**) and history retrieval remains capped at 100. No calibrated case requires graph memory.- P8 calibration: repeat aggregation now reports descriptive per-run spread without inferential claims; three new complete nine-scenario runs from source `51ae31f` were **27/27 task + 27/27 scenario-policy and 3/3 perfect runs for both agents**, with 54/54 row identity/provider/model/token-arithmetic checks passing. Combined with P7, both agents are **5/5 perfect**; five-run means are MSO vs Hermes 16,907.6 vs 66,791.1 normalized tokens/attempt (~74.7% lower for MSO), 18,985.9 vs 21,779.8 ms average latency, and 14,130.8 vs 21,457.2 ms per-run p50. New `bench:cache-calibration` final 4-round/12K-prefix run was 8/8 success; MSO cache-read was zero on 4/4 while Hermes naturally reported positive cache reads on 2/4 (9,728 + 19,968), but cache frequency is unranked because request envelopes differ. P8 also fixes false token non-comparability when independently valid normalized proof shapes vary across cache/no-cache rows. Cost remains non-comparable because attribution is asymmetric.- P7 repeatability gate: `bench:corpus:repeat` adds explicit/deterministic seeds, alternating starting-agent order, and strict per-run/per-agent scenario + provider/model identity checks before any cross-run ranking. The first two complete 9-scenario runs from source `5bd5788` on `openai-codex/gpt-5.6-terra` were 18/18 task + 18/18 scenario-policy for both agents and 2/2 perfect runs each. Aggregate MSO vs Hermes: 17,271.3 vs 65,073.3 normalized tokens/attempt (~73.5% lower for MSO), 18,922.6 vs 21,077.4 ms average latency, and 13,761 vs 20,513.5 ms p50. All 36 token-proof arithmetic checks passed. This is a bounded two-run baseline, not statistical reliability proof; cost remains non-comparable.diff --git a/lib/agent/memory-archive.ts b/lib/agent/memory-archive.tsnew file mode 100644index 00000000..05208868--- /dev/null+++ b/lib/agent/memory-archive.ts@@ -0,0 +1,109 @@+import { createHash, randomUUID } from "node:crypto";+import { constants as fsConstants, promises as fs } from "node:fs";+import path from "node:path";+import type { AgentMemoryRecord } from "./memory-types";++const ARCHIVE_DIR_NAME = "archive-v1";+const SEGMENT_RE = /^segment-[a-f0-9]{32}\.json$/;+const MAX_ARCHIVE_SEGMENT_BYTES = 768 * 1024;+const MAX_ARCHIVE_SEGMENT_RECORDS = 400;+const MAX_ARCHIVE_RECORDS_READ = 100_000;++interface AgentMemoryArchiveSegment {+ schemaVersion: 1;+ records: AgentMemoryRecord[];+}++export interface AgentMemoryArchiveRead {+ records: AgentMemoryRecord[];+ segmentCount: number;+ bytes: number;+}++export function memoryArchiveDir(dir: string): string {+ return path.join(dir, ARCHIVE_DIR_NAME);+}++function bodyFor(records: AgentMemoryRecord[]): string {+ return JSON.stringify({ schemaVersion: 1, records } satisfies AgentMemoryArchiveSegment, null, 2);+}++async function readArchiveSegment(file: string): Promise<{ segment: AgentMemoryArchiveSegment; bytes: number }> {+ let handle: Awaited<ReturnType<typeof fs.open>> | null = null;+ try {+ handle = await fs.open(file, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);+ const stat = await handle.stat();+ if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_ARCHIVE_SEGMENT_BYTES) throw new Error("agent memory archive segment has an invalid file shape");+ if ((stat.mode & 0o077) !== 0) throw new Error("agent memory archive permissions are too broad; expected 0600");+ if (typeof process.getuid === "function" && stat.uid !== process.getuid()) throw new Error("agent memory archive is not owned by the MSO user");+ const parsed = JSON.parse(await handle.readFile("utf8")) as AgentMemoryArchiveSegment;+ if (parsed?.schemaVersion !== 1 || !Array.isArray(parsed.records)) throw new Error("agent memory archive segment has an invalid schema");+ return { segment: parsed, bytes: stat.size };+ } finally {+ await handle?.close().catch(() => undefined);+ }+}++function chunkRecords(records: AgentMemoryRecord[]): AgentMemoryRecord[][] {+ const chunks: AgentMemoryRecord[][] = [];+ let current: AgentMemoryRecord[] = [];+ for (const record of records) {+ const candidate = [...current, record];+ if (current.length && (candidate.length > MAX_ARCHIVE_SEGMENT_RECORDS || Buffer.byteLength(bodyFor(candidate), "utf8") > MAX_ARCHIVE_SEGMENT_BYTES)) {+ chunks.push(current);+ current = [record];+ } else {+ current = candidate;+ }+ if (Buffer.byteLength(bodyFor(current), "utf8") > MAX_ARCHIVE_SEGMENT_BYTES) throw new Error("single agent memory archive record exceeds segment limit");+ }+ if (current.length) chunks.push(current);+ return chunks;+}++export async function archiveMemoryRecords(dir: string, records: AgentMemoryRecord[]): Promise<{ records: number; segments: number }> {+ if (!records.length) return { records: 0, segments: 0 };+ const archiveDir = memoryArchiveDir(dir);+ await fs.mkdir(archiveDir, { recursive: true, mode: 0o700 });+ await fs.chmod(archiveDir, 0o700).catch(() => undefined);+ let segments = 0;+ for (const chunk of chunkRecords(records)) {+ const body = bodyFor(chunk);+ const digest = createHash("sha256").update(body).digest("hex").slice(0, 32);+ const file = path.join(archiveDir, `segment-${digest}.json`);+ try {+ const existing = await readArchiveSegment(file);+ if (bodyFor(existing.segment.records) !== body) throw new Error("agent memory archive segment hash collision");+ continue;+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;+ }+ const tmp = `${file}.${randomUUID()}.tmp`;+ await fs.writeFile(tmp, body, { encoding: "utf8", mode: 0o600, flag: "wx" });+ await fs.chmod(tmp, 0o600);+ await fs.rename(tmp, file);+ await fs.chmod(file, 0o600);+ segments += 1;+ }+ return { records: records.length, segments };+}++export async function readMemoryArchive(dir: string): Promise<AgentMemoryArchiveRead> {+ const archiveDir = memoryArchiveDir(dir);+ let names: string[];+ try {+ names = (await fs.readdir(archiveDir)).filter((name) => SEGMENT_RE.test(name)).sort();+ } catch (error) {+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return { records: [], segmentCount: 0, bytes: 0 };+ throw error;+ }+ const records: AgentMemoryRecord[] = [];+ let bytes = 0;+ for (const name of names) {+ const { segment, bytes: segmentBytes } = await readArchiveSegment(path.join(archiveDir, name));+ records.push(...segment.records);+ bytes += segmentBytes;+ if (records.length > MAX_ARCHIVE_RECORDS_READ) throw new Error(`agent memory archive exceeds explicit retrieval limit of ${MAX_ARCHIVE_RECORDS_READ} records`);+ }+ return { records, segmentCount: names.length, bytes };+}diff --git a/lib/agent/memory-query.ts b/lib/agent/memory-query.tsindex 723fc087..16f84cce 100644--- a/lib/agent/memory-query.ts+++ b/lib/agent/memory-query.ts@@ -7,11 +7,27 @@ export function memoryQueryTime(value = new Date().toISOString()): string {return new Date(parsed).toISOString();}+function words(value: string): string[] {+ return value.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+(?:[-_][\p{L}\p{N}]+)*/gu) ?? [];+}++function fieldScore(field: string, query: string, queryWords: string[], weight: number): number {+ const normalized = field.normalize("NFKC").toLowerCase();+ const fieldWords = words(normalized);+ let score = normalized === query ? weight * 20 : normalized.includes(query) ? weight * 5 : 0;+ for (const token of queryWords) {+ if (fieldWords.includes(token)) { score += weight * 4; continue; }+ if (/^\p{L}{4,}$/u.test(token) && fieldWords.some((word) => word.startsWith(token))) score += weight;+ }+ return score;+}+function searchScore(record: AgentMemoryRecord, query: string): number {if (!query) return 1;- const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);- const key = record.key.toLowerCase(), value = record.value.toLowerCase();- return tokens.reduce((score, token) => score + (key.includes(token) ? 4 : 0) + (value.includes(token) ? 1 : 0), 0);+ const normalized = query.normalize("NFKC").toLowerCase().trim();+ const tokens = words(normalized);+ if (!tokens.length) return 0;+ return fieldScore(record.key, normalized, tokens, 4) + fieldScore(record.value, normalized, tokens, 1);}export function queryMemoryLedger(ledger: AgentMemoryLedger, query: AgentMemoryQuery = {}) {diff --git a/lib/agent/memory-resolution.ts b/lib/agent/memory-resolution.tsindex 9377ffee..f02232b4 100644--- a/lib/agent/memory-resolution.ts+++ b/lib/agent/memory-resolution.ts@@ -37,14 +37,31 @@ function compare(a: AgentMemoryRecord, b: AgentMemoryRecord): number {return a.id.localeCompare(b.id);}+function forwardSupersessionBoundaries(records: AgentMemoryRecord[]): Map<string, number> {+ const boundaries = new Map<string, number>();+ for (const replacement of records) {+ const boundary = Date.parse(replacement.validFrom);+ if (!Number.isFinite(boundary)) continue;+ for (const supersededId of replacement.supersedes ?? []) {+ const existing = boundaries.get(supersededId);+ if (existing === undefined || boundary < existing) boundaries.set(supersededId, boundary);+ }+ }+ return boundaries;+}+export function resolveMemoryKey(ledger: AgentMemoryLedger,document: AgentMemoryRecord["document"],key: string,at = new Date().toISOString(),): AgentMemoryResolvedRecord | null {- const candidates = ledger.records- .filter((record) => record.document === document && record.key === key && recordEffectiveAt(record, at))+ const target = Date.parse(at);+ if (!Number.isFinite(target)) throw new Error("memory query time must be ISO-8601");+ const records = ledger.records.filter((record) => record.document === document && record.key === key);+ const forwardSupersededAt = forwardSupersessionBoundaries(records);+ const candidates = records+ .filter((record) => recordEffectiveAt(record, at) && target < (forwardSupersededAt.get(record.id) ?? Number.POSITIVE_INFINITY)).sort(compare);const winner = candidates[0];if (!winner) return null;diff --git a/lib/agent/memory-retention.test.ts b/lib/agent/memory-retention.test.tsnew file mode 100644index 00000000..0811d34f--- /dev/null+++ b/lib/agent/memory-retention.test.ts@@ -0,0 +1,59 @@+import { describe, expect, it } from "vitest";+import { planMemoryRetention, MEMORY_RETENTION_TARGET_RECORDS } from "./memory-retention";+import { recordCanBeEffectiveAtOrAfter } from "./memory-resolution";+import type { AgentMemoryLedger, AgentMemoryRecord } from "./memory-types";++const BASE = Date.parse("2026-01-01T00:00:00.000Z");++function record(i: number, total: number): AgentMemoryRecord {+ const validFrom = new Date(BASE + i * 1000).toISOString();+ const next = i + 1 < total ? new Date(BASE + (i + 1) * 1000).toISOString() : undefined;+ return {+ id: `ret_${i}`,+ document: "MEMORY.md",+ key: "Runtime",+ value: `Runtime-${i}`,+ kind: "semantic",+ confidence: 1,+ sensitivity: "normal",+ validFrom,+ createdAt: validFrom,+ provenance: { authority: "explicit", channel: "system", observedAt: validFrom },+ ...(next ? { supersededAt: next, supersededBy: `ret_${i + 1}` } : {}),+ };+}++function ledger(records: AgentMemoryRecord[]): AgentMemoryLedger {+ return { schemaVersion: 1, updatedAt: "2026-09-03T00:00:00.000Z", records };+}++describe("agent memory retention planner", () => {+ it("archives only finished history and keeps the effective record live", () => {+ const records = Array.from({ length: 1400 }, (_, i) => record(i, 1400));+ const at = "2026-09-03T00:00:00.000Z";+ const plan = planMemoryRetention(ledger(records), at);+ expect(plan.triggered).toBe(true);+ expect(plan.targetReached).toBe(true);+ expect(plan.ledger.records.length).toBeLessThanOrEqual(MEMORY_RETENTION_TARGET_RECORDS);+ expect(plan.archiveRecords.length).toBeGreaterThan(0);+ expect(plan.ledger.records.some((row) => row.id === "ret_1399")).toBe(true);+ expect(plan.archiveRecords.every((row) => !recordCanBeEffectiveAtOrAfter(row, at))).toBe(true);+ });++ it("fails closed instead of archiving current or future-effective claims", () => {+ const at = "2026-09-03T00:00:00.000Z";+ const records = Array.from({ length: 1400 }, (_, i) => ({+ ...record(i, 1),+ id: `active_${i}`,+ key: `Key ${i}`,+ validFrom: i % 2 ? at : "2026-09-04T00:00:00.000Z",+ supersededAt: undefined,+ supersededBy: undefined,+ }));+ const plan = planMemoryRetention(ledger(records), at);+ expect(plan.triggered).toBe(true);+ expect(plan.archiveRecords).toHaveLength(0);+ expect(plan.targetReached).toBe(false);+ expect(plan.ledger.records).toHaveLength(records.length);+ });+});diff --git a/lib/agent/memory-retention.ts b/lib/agent/memory-retention.tsnew file mode 100644index 00000000..6250f102--- /dev/null+++ b/lib/agent/memory-retention.ts@@ -0,0 +1,84 @@+import { recordCanBeEffectiveAtOrAfter } from "./memory-resolution";+import type { AgentMemoryLedger, AgentMemoryRecord } from "./memory-types";++export const MEMORY_RETENTION_TRIGGER_RECORDS = 1400;+export const MEMORY_RETENTION_TARGET_RECORDS = 1000;+export const MEMORY_RETENTION_TRIGGER_BYTES = 1400 * 1024;+export const MEMORY_RETENTION_TARGET_BYTES = 1024 * 1024;+const RECENT_FINISHED_RESERVE = 100;++export function memoryLedgerBytes(ledger: AgentMemoryLedger): number {+ return Buffer.byteLength(JSON.stringify(ledger, null, 2), "utf8");+}++function endedAt(record: AgentMemoryRecord): number | null {+ const values = [record.validUntil, record.retractedAt, record.supersededAt]+ .filter((value): value is string => Boolean(value))+ .map((value) => Date.parse(value))+ .filter(Number.isFinite);+ return values.length ? Math.min(...values) : null;+}++function archiveCandidates(ledger: AgentMemoryLedger, at: string): AgentMemoryRecord[] {+ const target = Date.parse(at);+ if (!Number.isFinite(target)) throw new Error("memory retention time must be ISO-8601");+ return ledger.records+ .filter((record) => {+ const end = endedAt(record);+ return end !== null && end <= target && !recordCanBeEffectiveAtOrAfter(record, at);+ })+ .sort((a, b) => (endedAt(a) ?? 0) - (endedAt(b) ?? 0) || Date.parse(a.createdAt) - Date.parse(b.createdAt) || a.id.localeCompare(b.id));+}++export interface AgentMemoryRetentionPlan {+ ledger: AgentMemoryLedger;+ archiveRecords: AgentMemoryRecord[];+ triggered: boolean;+ targetReached: boolean;+ beforeRecords: number;+ afterRecords: number;+ beforeBytes: number;+ afterBytes: number;+}++export function planMemoryRetention(ledger: AgentMemoryLedger, at = new Date().toISOString()): AgentMemoryRetentionPlan {+ const beforeBytes = memoryLedgerBytes(ledger);+ const triggered = ledger.records.length >= MEMORY_RETENTION_TRIGGER_RECORDS || beforeBytes >= MEMORY_RETENTION_TRIGGER_BYTES;+ if (!triggered) {+ return { ledger, archiveRecords: [], triggered: false, targetReached: true, beforeRecords: ledger.records.length, afterRecords: ledger.records.length, beforeBytes, afterBytes: beforeBytes };+ }++ const candidates = archiveCandidates(ledger, at);+ if (!candidates.length) {+ return { ledger, archiveRecords: [], triggered: true, targetReached: false, beforeRecords: ledger.records.length, afterRecords: ledger.records.length, beforeBytes, afterBytes: beforeBytes };+ }++ const preferredCount = Math.max(0, candidates.length - RECENT_FINISHED_RESERVE);+ const ordered = [...candidates.slice(0, preferredCount), ...candidates.slice(preferredCount)];+ const selected = new Set<string>();+ const minimumByCount = Math.max(0, ledger.records.length - MEMORY_RETENTION_TARGET_RECORDS);+ for (let i = 0; i < Math.min(minimumByCount, ordered.length); i += 1) selected.add(ordered[i].id);++ let retainedRecords = ledger.records.filter((record) => !selected.has(record.id));+ let retained: AgentMemoryLedger = { ...ledger, records: retainedRecords };+ let selectedCount = selected.size;+ while (memoryLedgerBytes(retained) > MEMORY_RETENTION_TARGET_BYTES && selectedCount < ordered.length) {+ selected.add(ordered[selectedCount].id);+ selectedCount += 1;+ retainedRecords = ledger.records.filter((record) => !selected.has(record.id));+ retained = { ...ledger, records: retainedRecords };+ }++ const afterBytes = memoryLedgerBytes(retained);+ const targetReached = retained.records.length <= MEMORY_RETENTION_TARGET_RECORDS && afterBytes <= MEMORY_RETENTION_TARGET_BYTES;+ return {+ ledger: retained,+ archiveRecords: ordered.filter((record) => selected.has(record.id)),+ triggered: true,+ targetReached,+ beforeRecords: ledger.records.length,+ afterRecords: retained.records.length,+ beforeBytes,+ afterBytes,+ };+}diff --git a/lib/agent/memory-store.ts b/lib/agent/memory-store.tsindex f2e58960..b4bd570e 100644--- a/lib/agent/memory-store.ts+++ b/lib/agent/memory-store.ts@@ -3,12 +3,16 @@ import { constants as fsConstants, promises as fs } from "node:fs";import os from "node:os";import path from "node:path";import { withSecurityStoreLock } from "@/lib/security-store-lock";+import { archiveMemoryRecords, readMemoryArchive } from "./memory-archive";import { ledgerFile, materializeDocuments, readMemoryLedger, seedLedger, writeMemoryLedger } from "./memory-ledger";import { queryMemoryLedger } from "./memory-query";+import { planMemoryRetention } from "./memory-retention";import { recordCanBeEffectiveAtOrAfter, recordEffectiveAt } from "./memory-resolution";+import { collectMemoryTelemetry, type AgentMemoryTelemetry } from "./memory-telemetry";import type { AgentMemoryDocument, AgentMemoryLedger, AgentMemoryQuery, AgentMemoryRecord, AgentMemoryWriteOptions } from "./memory-types";export type { AgentMemoryDocument, AgentMemoryKind, AgentMemoryQuery, AgentMemoryRecord, AgentMemorySensitivity, AgentMemoryWriteOptions } from "./memory-types";+export type { AgentMemoryTelemetry } from "./memory-telemetry";export interface AgentMemorySnapshot { capturedAt: string; user: string; memory: string; schemaVersion?: 1; recordCount?: number; }const ROOT = path.resolve(process.env.OS_AGENT_MEMORY_DIR || path.join(os.homedir(), ".mso", "agent-memory"));@@ -67,6 +71,12 @@ function confidence(value: number | undefined): number {if (!Number.isFinite(n) || n < 0 || n > 1) throw new Error("memory confidence must be between 0 and 1");return Math.round(n * 1000) / 1000;}+function dedupeRecords(archived: AgentMemoryRecord[], live: AgentMemoryRecord[]): AgentMemoryRecord[] {+ const byId = new Map<string, AgentMemoryRecord>();+ for (const record of archived) byId.set(record.id, record);+ for (const record of live) byId.set(record.id, record); // live ledger wins after an interrupted archive-before-ledger commit.+ return [...byId.values()];+}async function legacyDocs(principal: string) { const [user, memory] = await Promise.all([readDocument(principal, "USER.md"), readDocument(principal, "MEMORY.md")]); return { user, memory }; }async function ledgerForRead(principal: string): Promise<AgentMemoryLedger> {@@ -74,6 +84,13 @@ async function ledgerForRead(principal: string): Promise<AgentMemoryLedger> {if (ledger) return ledger;const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory);}+async function ledgerForQuery(principal: string, query: AgentMemoryQuery): Promise<AgentMemoryLedger> {+ const live = await ledgerForRead(principal);+ if (!query.includeHistory && !query.at) return live;+ const archived = await readMemoryArchive(dirFor(principal));+ if (!archived.records.length) return live;+ return { ...live, records: dedupeRecords(archived.records, live.records) };+}function snapshotFromLedger(ledger: AgentMemoryLedger, capturedAt = new Date().toISOString()): AgentMemorySnapshot {const docs = materializeDocuments(ledger, capturedAt);return { capturedAt, user: docs["USER.md"], memory: docs["MEMORY.md"], schemaVersion: 1, recordCount: ledger.records.length };@@ -82,6 +99,13 @@ async function persistProjection(principal: string, ledger: AgentMemoryLedger, aconst docs = materializeDocuments(ledger, at);await writeDocument(principal, "USER.md", docs["USER.md"]); await writeDocument(principal, "MEMORY.md", docs["MEMORY.md"]);}+async function persistLedgerMutation(principal: string, ledger: AgentMemoryLedger, at: string): Promise<AgentMemoryLedger> {+ const retention = planMemoryRetention(ledger, at);+ if (retention.archiveRecords.length) await archiveMemoryRecords(dirFor(principal), retention.archiveRecords);+ await writeMemoryLedger(dirFor(principal), retention.ledger);+ await persistProjection(principal, retention.ledger, at);+ return retention.ledger;+}export async function snapshotAgentMemory(principal: string): Promise<AgentMemorySnapshot> {const stored = await readMemoryLedger(dirFor(principal));@@ -104,11 +128,19 @@ export async function rememberAgentMemory(principal: string, document: AgentMemoawait withSecurityStoreLock(ledgerFile(dirFor(principal)), async () => {const current = await readMemoryLedger(dirFor(principal)) ?? await (async () => { const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory, now); })();if ((options.mode ?? "replace") === "replace") {- const superseded = current.records.filter((row) => row.document === document && row.key === safeKey && recordEffectiveAt(row, validFrom));+ let searchable = current.records;+ if (Date.parse(validFrom) < Date.parse(now)) {+ const archived = await readMemoryArchive(dirFor(principal));+ searchable = dedupeRecords(archived.records, current.records);+ }+ const superseded = searchable.filter((row) => row.document === document && row.key === safeKey && recordEffectiveAt(row, validFrom));if (superseded.length) record.supersedes = superseded.map((row) => row.id);- for (const row of superseded) { row.supersededAt = validFrom; row.supersededBy = record.id; }+ const supersededIds = new Set(superseded.map((row) => row.id));+ for (const row of current.records) {+ if (supersededIds.has(row.id)) { row.supersededAt = validFrom; row.supersededBy = record.id; }+ }}- current.records.push(record); current.updatedAt = now; await writeMemoryLedger(dirFor(principal), current); await persistProjection(principal, current, now); result = current;+ current.records.push(record); current.updatedAt = now; result = await persistLedgerMutation(principal, current, now);});return snapshotFromLedger(result, now);}@@ -120,11 +152,17 @@ export async function forgetAgentMemory(principal: string, document: AgentMemoryfor (const row of current.records) {if (row.document === document && row.key === safeKey && recordCanBeEffectiveAtOrAfter(row, now)) row.retractedAt = now;}- current.updatedAt = now; await writeMemoryLedger(dirFor(principal), current); await persistProjection(principal, current, now); result = current;+ current.updatedAt = now; result = await persistLedgerMutation(principal, current, now);});return snapshotFromLedger(result, now);}export async function queryAgentMemory(principal: string, query: AgentMemoryQuery = {}) {- return queryMemoryLedger(await ledgerForRead(principal), query);+ return queryMemoryLedger(await ledgerForQuery(principal, query), query);+}++export async function agentMemoryTelemetry(principal: string): Promise<AgentMemoryTelemetry> {+ const live = await ledgerForRead(principal);+ const archived = await readMemoryArchive(dirFor(principal));+ return collectMemoryTelemetry(live, archived.records, { segmentCount: archived.segmentCount, bytes: archived.bytes });}diff --git a/lib/agent/memory-telemetry.ts b/lib/agent/memory-telemetry.tsnew file mode 100644index 00000000..0e157e1d--- /dev/null+++ b/lib/agent/memory-telemetry.ts@@ -0,0 +1,81 @@+import { materializeDocuments } from "./memory-ledger";+import { memoryLedgerBytes } from "./memory-retention";+import { recordCanBeEffectiveAtOrAfter, resolveMemoryLedger } from "./memory-resolution";+import type { AgentMemoryLedger, AgentMemoryRecord } from "./memory-types";++export interface AgentMemoryTelemetry {+ schemaVersion: 1;+ liveRecords: number;+ archivedRecords: number;+ totalStructuredRecords: number;+ resolvedKeyCount: number;+ supersededCount: number;+ retractedCount: number;+ futureScheduledCount: number;+ conflictCount: number;+ correctionDepthDistribution: {+ zero: number;+ one: number;+ twoToFive: number;+ sixToTwenty: number;+ twentyOneToHundred: number;+ overHundred: number;+ };+ maxCorrectionsPerKey: number;+ ledgerBytes: number;+ projectionBytes: number;+ archiveSegments: number;+ archiveBytes: number;+}++function dedupeRecords(archived: AgentMemoryRecord[], live: AgentMemoryRecord[]): AgentMemoryRecord[] {+ const byId = new Map<string, AgentMemoryRecord>();+ for (const record of archived) byId.set(record.id, record);+ for (const record of live) byId.set(record.id, record);+ return [...byId.values()];+}++export function collectMemoryTelemetry(+ ledger: AgentMemoryLedger,+ archived: AgentMemoryRecord[] = [],+ archiveMeta: { segmentCount?: number; bytes?: number } = {},+ at = new Date().toISOString(),+): AgentMemoryTelemetry {+ const all = dedupeRecords(archived, ledger.records);+ const grouped = new Map<string, number>();+ for (const record of all) {+ const group = `${record.document}\u0000${record.key}`;+ grouped.set(group, (grouped.get(group) ?? 0) + 1);+ }+ const distribution = { zero: 0, one: 0, twoToFive: 0, sixToTwenty: 0, twentyOneToHundred: 0, overHundred: 0 };+ let maxCorrectionsPerKey = 0;+ for (const count of grouped.values()) {+ const corrections = Math.max(0, count - 1);+ maxCorrectionsPerKey = Math.max(maxCorrectionsPerKey, corrections);+ if (corrections === 0) distribution.zero += 1;+ else if (corrections === 1) distribution.one += 1;+ else if (corrections <= 5) distribution.twoToFive += 1;+ else if (corrections <= 20) distribution.sixToTwenty += 1;+ else if (corrections <= 100) distribution.twentyOneToHundred += 1;+ else distribution.overHundred += 1;+ }+ const resolved = resolveMemoryLedger(ledger, at);+ const docs = materializeDocuments(ledger, at);+ return {+ schemaVersion: 1,+ liveRecords: ledger.records.length,+ archivedRecords: all.length - ledger.records.length,+ totalStructuredRecords: all.length,+ resolvedKeyCount: resolved.length,+ supersededCount: all.filter((record) => Boolean(record.supersededAt || record.supersededBy)).length,+ retractedCount: all.filter((record) => Boolean(record.retractedAt)).length,+ futureScheduledCount: ledger.records.filter((record) => Date.parse(record.validFrom) > Date.parse(at) && recordCanBeEffectiveAtOrAfter(record, at)).length,+ conflictCount: resolved.reduce((sum, row) => sum + row.conflicts.length, 0),+ correctionDepthDistribution: distribution,+ maxCorrectionsPerKey,+ ledgerBytes: memoryLedgerBytes(ledger),+ projectionBytes: Buffer.byteLength(JSON.stringify({ user: docs["USER.md"], memory: docs["MEMORY.md"] }), "utf8"),+ archiveSegments: archiveMeta.segmentCount ?? 0,+ archiveBytes: archiveMeta.bytes ?? 0,+ };+}diff --git a/package.json b/package.jsonindex 38d65803..e103f6c6 100644--- a/package.json+++ b/package.json@@ -29,6 +29,8 @@"bench:cognitive": "bun scripts/bench-cognitive-runtime.mjs","bench:memory": "bun scripts/bench-memory-retrieval.mjs","bench:memory:calibration": "bun scripts/bench-memory-calibration.mjs",+ "bench:memory:lifecycle": "bun scripts/bench-memory-lifecycle.mjs",+ "bench:memory:retrieval-calibration": "bun scripts/bench-memory-retrieval-calibration.mjs","bench:quality": "bun scripts/bench-task-quality.mjs","bench:agents": "bun scripts/bench-agent-comparison.mjs","forge:sandbox": "bash scripts/provision-forge-sandbox.sh",diff --git a/scripts/bench-memory-lifecycle.mjs b/scripts/bench-memory-lifecycle.mjsnew file mode 100644index 00000000..092a4202--- /dev/null+++ b/scripts/bench-memory-lifecycle.mjs@@ -0,0 +1,157 @@+#!/usr/bin/env bun+import { createHash } from "node:crypto";+import { mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";+import os from "node:os";+import path from "node:path";++function principalDir(root, principal) { return path.join(root, createHash("sha256").update(principal).digest("hex").slice(0, 32)); }+function pct(n, d) { return d ? Math.round(n / d * 1000) / 10 : 0; }+function row(i, base, count) {+ const validFrom = new Date(base + i * 1000).toISOString();+ const next = i + 1 < count ? new Date(base + (i + 1) * 1000).toISOString() : undefined;+ return {+ id: `p10_mem_${String(i + 1).padStart(4, "0")}`,+ document: "MEMORY.md",+ key: "Preferred runtime",+ value: `Runtime-${i + 1}`,+ kind: "semantic",+ confidence: 1,+ sensitivity: "normal",+ validFrom,+ createdAt: validFrom,+ provenance: { authority: "explicit", channel: "system", observedAt: validFrom },+ ...(i ? { supersedes: [`p10_mem_${String(i).padStart(4, "0")}`] } : {}),+ ...(next ? { supersededAt: next, supersededBy: `p10_mem_${String(i + 2).padStart(4, "0")}` } : {}),+ };+}++export async function runMemoryLifecycleCalibration() {+ const root = await mkdtemp(path.join(os.tmpdir(), "mso-memory-p10-"));+ const memoryRoot = path.join(root, "memory"), sessionRoot = path.join(root, "sessions"), sessionArchiveRoot = path.join(root, "session-archives");+ const previous = Object.fromEntries(["OS_AGENT_MEMORY_DIR", "OS_AGENT_SESSIONS_DIR", "OS_AGENT_SESSION_ARCHIVE_DIR"].map((key) => [key, process.env[key]]));+ process.env.OS_AGENT_MEMORY_DIR = memoryRoot;+ process.env.OS_AGENT_SESSIONS_DIR = sessionRoot;+ process.env.OS_AGENT_SESSION_ARCHIVE_DIR = sessionArchiveRoot;+ try {+ const store = await import("../lib/agent/memory-store.ts");+ const ledgerLib = await import("../lib/agent/memory-ledger.ts");+ const archiveLib = await import("../lib/agent/memory-archive.ts");+ const session = await import("../lib/agent/session-store.ts");+ const scenarios = [];++ const principal = "p10:lifecycle";+ const dir = principalDir(memoryRoot, principal);+ const count = 1400;+ const base = Date.now() - (count + 20) * 1000;+ const seed = { schemaVersion: 1, updatedAt: new Date(base + (count - 1) * 1000).toISOString(), records: Array.from({ length: count }, (_, i) => row(i, base, count)) };+ await ledgerLib.writeMemoryLedger(dir, seed);+ await store.rememberAgentMemory(principal, "MEMORY.md", "Preferred runtime", "P10-Final");++ const liveRaw = JSON.parse(await readFile(path.join(dir, "records-v1.json"), "utf8"));+ const archived = await archiveLib.readMemoryArchive(dir);+ const current = await store.queryAgentMemory(principal, { query: "preferred runtime" });+ scenarios.push({+ id: "retention-before-hard-cap",+ pass: liveRaw.records.length <= 1000 && archived.records.length >= 400 && current.records.length === 1 && current.records[0]?.record.value === "P10-Final",+ evidence: { liveRecords: liveRaw.records.length, archivedRecords: archived.records.length },+ });++ const oldHistory = await store.queryAgentMemory(principal, { query: "Runtime-1", includeHistory: true, limit: 10 });+ scenarios.push({ id: "explicit-archived-history", pass: oldHistory.records.some((item) => item.record.value === "Runtime-1"), evidence: { returned: oldHistory.records.length } });++ const historicalAt = new Date(base + 250).toISOString();+ const historical = await store.queryAgentMemory(principal, { query: "preferred runtime", at: historicalAt });+ scenarios.push({ id: "archived-temporal-resolution", pass: historical.records[0]?.record.value === "Runtime-1", evidence: { value: historical.records[0]?.record.value ?? null } });++ const telemetry = await store.agentMemoryTelemetry(principal);+ const telemetryText = JSON.stringify(telemetry);+ scenarios.push({+ id: "privacy-safe-aggregate-telemetry",+ pass: telemetry.liveRecords === liveRaw.records.length && telemetry.archivedRecords === archived.records.length && telemetry.totalStructuredRecords === count + 1 && telemetry.maxCorrectionsPerKey === count+ && !telemetryText.includes("Preferred runtime") && !telemetryText.includes("P10-Final") && !telemetryText.includes(principal),+ evidence: telemetry,+ });++ const archiveDirStat = await stat(path.join(dir, "archive-v1"));+ const [segmentName] = (await readdir(path.join(dir, "archive-v1"))).filter((name) => name.endsWith(".json"));+ const archiveFileStat = await stat(path.join(dir, "archive-v1", segmentName));+ scenarios.push({ id: "owner-only-archive-permissions", pass: (archiveDirStat.mode & 0o777) === 0o700 && (archiveFileStat.mode & 0o777) === 0o600, evidence: { dirMode: (archiveDirStat.mode & 0o777).toString(8), fileMode: (archiveFileStat.mode & 0o777).toString(8) } });++ const orphanPrincipal = "p10:archive-before-ledger-crash";+ const orphanDir = principalDir(memoryRoot, orphanPrincipal);+ const orphanNow = new Date(Date.now() - 60_000).toISOString();+ const liveOrphanRecord = {+ id: "p10_orphan_1", document: "MEMORY.md", key: "Crash marker", value: "Live authority", kind: "semantic", confidence: 1, sensitivity: "normal",+ validFrom: orphanNow, createdAt: orphanNow, provenance: { authority: "explicit", channel: "system", observedAt: orphanNow },+ };+ await ledgerLib.writeMemoryLedger(orphanDir, { schemaVersion: 1, updatedAt: orphanNow, records: [liveOrphanRecord] });+ await archiveLib.archiveMemoryRecords(orphanDir, [{ ...liveOrphanRecord, value: "Stale archive copy", retractedAt: new Date().toISOString() }]);+ const orphanHistory = await store.queryAgentMemory(orphanPrincipal, { query: "crash marker", includeHistory: true, limit: 10 });+ scenarios.push({+ id: "archive-before-ledger-crash-live-wins",+ pass: orphanHistory.records.length === 1 && orphanHistory.records[0]?.record.value === "Live authority" && !orphanHistory.records[0]?.record.retractedAt,+ evidence: { returned: orphanHistory.records.length, liveWins: orphanHistory.records[0]?.record.value === "Live authority" },+ });++ const backdatedPrincipal = "p10:backdated-archived-replace";+ const backdatedDir = principalDir(memoryRoot, backdatedPrincipal);+ const archivedOld = {+ id: "p10_archived_old", document: "MEMORY.md", key: "Historical region", value: "Jakarta", kind: "semantic", confidence: 1, sensitivity: "normal",+ validFrom: "2026-01-01T00:00:00.000Z", supersededAt: "2026-06-01T00:00:00.000Z", supersededBy: "historical-successor",+ createdAt: "2026-01-01T00:00:00.000Z", provenance: { authority: "explicit", channel: "system", observedAt: "2026-01-01T00:00:00.000Z" },+ };+ await archiveLib.archiveMemoryRecords(backdatedDir, [archivedOld]);+ await ledgerLib.writeMemoryLedger(backdatedDir, { schemaVersion: 1, updatedAt: "2026-09-03T00:00:00.000Z", records: [] });+ await store.rememberAgentMemory(backdatedPrincipal, "MEMORY.md", "Historical region", "Singapore", {+ mode: "replace", confidence: 0.1, validFrom: "2026-03-01T00:00:00.000Z", provenance: { authority: "observed", channel: "system", observedAt: "2026-09-03T00:00:00.000Z" },+ });+ const backdated = await store.queryAgentMemory(backdatedPrincipal, { query: "historical region", at: "2026-04-01T00:00:00.000Z" });+ scenarios.push({+ id: "backdated-replace-over-immutable-archive",+ pass: backdated.records.length === 1 && backdated.records[0]?.record.value === "Singapore" && backdated.records[0]?.conflicts.length === 0,+ evidence: { value: backdated.records[0]?.record.value ?? null, conflicts: backdated.records[0]?.conflicts.length ?? 0 },+ });++ const frozenPrincipal = "p10:frozen-session";+ await store.rememberAgentMemory(frozenPrincipal, "MEMORY.md", "Session setting", "Old value");+ const sessionA = await session.createAgentSession(frozenPrincipal, "cli", { title: "Frozen A" });+ await store.rememberAgentMemory(frozenPrincipal, "MEMORY.md", "Session setting", "New value");+ const reloadedA = await session.getAgentSession(frozenPrincipal, sessionA.id);+ const sessionB = await session.createAgentSession(frozenPrincipal, "cli", { title: "Fresh B" });+ const resumedA = await session.resumeAgentSession(frozenPrincipal, sessionA.id);+ scenarios.push({+ id: "frozen-session-snapshot",+ pass: Boolean(reloadedA?.memorySnapshot.memory.includes("Old value")) && !reloadedA?.memorySnapshot.memory.includes("New value")+ && sessionB.memorySnapshot.memory.includes("New value") && resumedA.memorySnapshot.memory.includes("Old value") && !resumedA.memorySnapshot.memory.includes("New value"),+ evidence: { sessionAOld: Boolean(reloadedA?.memorySnapshot.memory.includes("Old value")), sessionBNew: sessionB.memorySnapshot.memory.includes("New value"), resumeCopiesFrozenSnapshot: resumedA.memorySnapshot.memory.includes("Old value") },+ });++ const passed = scenarios.filter((item) => item.pass).length;+ return {+ calibrationVersion: "mso-memory-lifecycle-v1",+ scenarioCount: scenarios.length,+ passed,+ accuracyPct: pct(passed, scenarios.length),+ deterministic: true,+ scenarios,+ retention: { triggerSeedRecords: count, finalLiveRecords: liveRaw.records.length, archivedRecords: archived.records.length, archiveSegments: archived.segmentCount, ledgerBytes: telemetry.ledgerBytes, archiveBytes: telemetry.archiveBytes, projectionBytes: telemetry.projectionBytes },+ note: "Runs only in isolated temporary memory/session roots. Cold finished records are archived before the live ledger is replaced; normal resolved reads do not load archive content, while explicit history/time-travel retrieval does.",+ };+ } finally {+ for (const [key, value] of Object.entries(previous)) {+ if (value === undefined) delete process.env[key]; else process.env[key] = value;+ }+ await rm(root, { recursive: true, force: true });+ }+}++if (import.meta.main) {+ const result = await runMemoryLifecycleCalibration();+ if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2));+ else {+ console.log(`MSO memory lifecycle calibration · ${result.passed}/${result.scenarioCount} pass · deterministic=${result.deterministic}`);+ for (const scenario of result.scenarios) console.log(` ${scenario.pass ? "PASS" : "FAIL"} ${scenario.id}`);+ console.log(` retention ${result.retention.triggerSeedRecords} seed → ${result.retention.finalLiveRecords} live + ${result.retention.archivedRecords} archived (${result.retention.archiveSegments} segments)`);+ }+ if (result.accuracyPct !== 100 || !result.deterministic) process.exitCode = 1;+}diff --git a/scripts/bench-memory-lifecycle.test.ts b/scripts/bench-memory-lifecycle.test.tsnew file mode 100644index 00000000..2ab49b2d--- /dev/null+++ b/scripts/bench-memory-lifecycle.test.ts@@ -0,0 +1,16 @@+import { describe, expect, it } from "vitest";+import { runMemoryLifecycleCalibration } from "./bench-memory-lifecycle.mjs";++describe("P10 memory lifecycle calibration", () => {+ it("keeps retention, archival history, telemetry, permissions, and frozen-session semantics deterministic", async () => {+ const result = await runMemoryLifecycleCalibration();+ expect(result.accuracyPct).toBe(100);+ expect(result.deterministic).toBe(true);+ expect(result.scenarios.find((row) => row.id === "retention-before-hard-cap")?.pass).toBe(true);+ expect(result.scenarios.find((row) => row.id === "archived-temporal-resolution")?.pass).toBe(true);+ expect(result.scenarios.find((row) => row.id === "privacy-safe-aggregate-telemetry")?.pass).toBe(true);+ expect(result.scenarios.find((row) => row.id === "frozen-session-snapshot")?.pass).toBe(true);+ expect(result.retention.finalLiveRecords).toBeLessThanOrEqual(1000);+ expect(result.retention.archivedRecords).toBeGreaterThan(0);+ });+});diff --git a/scripts/bench-memory-retrieval-calibration.mjs b/scripts/bench-memory-retrieval-calibration.mjsnew file mode 100644index 00000000..197360fd--- /dev/null+++ b/scripts/bench-memory-retrieval-calibration.mjs@@ -0,0 +1,111 @@+#!/usr/bin/env bun+import { queryMemoryLedger } from "../lib/agent/memory-query.ts";++const AT = "2026-09-03T00:00:00.000Z";+let seq = 0;+function rec(key, value) {+ seq += 1;+ return {+ id: `p10_retrieval_${seq}`,+ document: "MEMORY.md",+ key,+ value,+ kind: "semantic",+ confidence: 1,+ sensitivity: "normal",+ validFrom: "2026-01-01T00:00:00.000Z",+ createdAt: "2026-01-01T00:00:00.000Z",+ provenance: { authority: "explicit", channel: "system", observedAt: "2026-01-01T00:00:00.000Z" },+ };+}+function ledger(records) { return { schemaVersion: 1, updatedAt: AT, records }; }+function topKey(records, query) { return queryMemoryLedger(ledger(records), { query, at: AT }).records[0]?.record.key ?? null; }++const retrievalCases = [+ {+ id: "paraphrase-same-concept",+ class: "paraphrase",+ records: [rec("Deployment rollback policy", "Verify service health before rolling back a release"), rec("Frontend convention", "Use Svelte 5 runes")],+ query: "undo release safely",+ expected: "Deployment rollback policy",+ },+ {+ id: "synonym-ide-editor",+ class: "synonym",+ records: [rec("Primary editor", "VS Code"), rec("Primary shell", "zsh")],+ query: "IDE preference",+ expected: "Primary editor",+ },+ {+ id: "bilingual-office-kantor",+ class: "bilingual",+ records: [rec("Office location", "Jakarta"), rec("Release region", "Singapore")],+ query: "kantor utama",+ expected: "Office location",+ },+ {+ id: "long-value-tail",+ class: "long-value",+ records: [rec("Release handbook", `${"Operational notes. ".repeat(80)}Before rollback always verify service health and preserve evidence.`), rec("Design handbook", "Use compact mobile navigation")],+ query: "verify service health",+ expected: "Release handbook",+ },+ {+ id: "similar-keys-disambiguation",+ class: "similar-keys",+ records: [rec("Primary database", "PostgreSQL"), rec("Analytics database", "ClickHouse"), rec("Archive database", "SQLite")],+ query: "analytics database",+ expected: "Analytics database",+ },+ {+ id: "exact-domain-phrase",+ class: "lexical-control",+ records: [rec("Deployment rollback policy", "Verify service health"), rec("Deployment region", "Jakarta")],+ query: "deployment rollback",+ expected: "Deployment rollback policy",+ },+];++const retrieval = retrievalCases.map((row) => {+ const first = topKey(row.records, row.query), second = topKey(row.records, row.query);+ return { id: row.id, class: row.class, pass: first === row.expected, deterministic: first === second, topKey: first };+});++const graphCases = [+ { id: "ownership-dependency", first: "Atlas", intermediate: "Beacon", second: "Core", records: [rec("Atlas ownership", "Atlas owns Beacon"), rec("Beacon dependency", "Beacon depends on Core"), rec("Unrelated preference", "Compact UI")] },+ { id: "service-team", first: "Orchid", intermediate: "Platform", second: "Infra", records: [rec("Orchid owner", "Orchid is owned by Platform"), rec("Platform dependency", "Platform depends on Infra"), rec("Theme", "Dark") ] },+ { id: "module-package", first: "Renderer", intermediate: "Scene", second: "Assets", records: [rec("Renderer relation", "Renderer uses Scene"), rec("Scene relation", "Scene consumes Assets"), rec("Editor", "VS Code") ] },+];++const graph = graphCases.map((row) => {+ const firstHop = queryMemoryLedger(ledger(row.records), { query: row.first, at: AT }).records.map((item) => `${item.record.key} ${item.record.value}`);+ const secondHop = queryMemoryLedger(ledger(row.records), { query: row.intermediate, at: AT }).records.map((item) => `${item.record.key} ${item.record.value}`);+ const pass = firstHop.some((text) => text.includes(row.intermediate)) && secondHop.some((text) => text.includes(row.second));+ return { id: row.id, pass, hops: 2, firstHopRows: firstHop.length, secondHopRows: secondHop.length };+});++const retrievalPassed = retrieval.filter((row) => row.pass && row.deterministic).length;+const semanticMisses = retrieval.filter((row) => !row.pass).map((row) => row.id);+const graphPassed = graph.filter((row) => row.pass).length;+const result = {+ calibrationVersion: "mso-memory-retrieval-calibration-v1",+ retrieval: { passed: retrievalPassed, total: retrieval.length, accuracyPct: Math.round(retrievalPassed / retrieval.length * 1000) / 10, deterministic: retrieval.every((row) => row.deterministic), rows: retrieval },+ semanticEvidenceGate: {+ objectiveMisses: semanticMisses,+ vectorLayerRequired: false,+ reason: semanticMisses.length+ ? "The fixture exposes semantic gaps, but no embedding approach has yet proven a measurable benefit with acceptable privacy/token/latency cost. Keep vector infrastructure blocked until that comparison exists."+ : "The deterministic lexical fixture is adequate; no vector layer is justified.",+ },+ graph: { passed: graphPassed, total: graph.length, rows: graph, graphStorageRequired: graphPassed !== graph.length },+ note: "This is a bounded synthetic evidence gate. Graph rows prove whether small relationship chains remain reachable through explicit two-step retrieval; they do not claim general graph reasoning reliability.",+};++if (process.argv.includes("--json")) console.log(JSON.stringify(result, null, 2));+else {+ console.log(`MSO memory retrieval calibration · lexical ${result.retrieval.passed}/${result.retrieval.total} · deterministic=${result.retrieval.deterministic}`);+ for (const row of result.retrieval.rows) console.log(` ${row.pass && row.deterministic ? "PASS" : "MISS"} ${row.id}`);+ console.log(` semantic gate: ${result.semanticEvidenceGate.vectorLayerRequired ? "vector candidate" : "vector blocked"}`);+ console.log(` graph gate: ${result.graph.passed}/${result.graph.total} two-hop fixtures · graph storage ${result.graph.graphStorageRequired ? "candidate" : "blocked"}`);+}+if (!result.retrieval.deterministic || result.graph.passed !== result.graph.total) process.exitCode = 1;