Skip to content

armgit / mso

Public Imported from GitHub
0

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.

feat(agent): add P10 memory lifecycle calibration

Rahman25f74e692fe3
diff --git a/README.md b/README.md
index 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.md
index 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 bridge
diff --git a/docs/COGNITIVE-RUNTIME.md b/docs/COGNITIVE-RUNTIME.md
index 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 contex
P1 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 gates
bun run bench:memory # deterministic retrieval/temporal/conflict suite
bun 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 gate
bun run bench:quality -- --live # learned workflow success + P1 telemetry coverage
bun run bench:agents -- --provider openai-codex --model gpt-5.6-terra # one-task smoke plan
bun 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 t
4. **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.md
index 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 calibration
diff --git a/docs/TESTING-HANDOFF.md b/docs/TESTING-HANDOFF.md
index 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 `2
Current 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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, a
const 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: AgentMemo
await 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: AgentMemory
for (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.ts
new file mode 100644
index 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.json
index 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.mjs
new file mode 100644
index 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.ts
new file mode 100644
index 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.mjs
new file mode 100644
index 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;