v0.3.0.md

v0.3.0: Composable Memory Kernel

简体中文 | English | Extension guide

v0.3.0 lifts the existing three-tier system into a composable memory kernel while preserving one-package installation, default behavior, public tools, and existing data formats. Runtime, Documents, and Memory Spaces are independently switchable Layers. The existing routing behavior is expressed by the default-three-tier Strategy, and Provider construction is decoupled through a Registry/Factory seam.

What you need to do

Reader	Action
Existing user	Back up, update, restart, and verify the three default Layers. No data migration or new View interaction is required
New user	Keep all three default Layers enabled for the first workflow
Operator	Review the saved Layer switches and Status generations after changing scope, Layers, or extensions
Extension author	Import only public dsh-mnemon/* subpaths and register contributions through mnemonMemory / MemoryBoot

Delivered

• Wire-safe Contracts, MemoryCatalog, atomic MemoryTopologyManager, MemoryKernel, Guards, MemoryPlan, and MemoryReceipt.
• Separate Catalog, Topology, and Guard generation boundaries. A component or Guard change rejects an old Plan before execution and requires re-planning; accepted Plans are atomically claim-once, so sequential or concurrent replay cannot repeat a data-plane step.
• The ordinary Settings surface gives each Layer one master switch. Enabled means the default strategy may use it on demand; it never forces Recall. Disabled stops context, model tools, background processing, and data-plane Web/RPC together.
• The Kernel still distinguishes capabilities and trigger sources and enforces Guards authoritatively. Those constraints are control-plane internals, not fine-grained ordinary-user settings in v0.3.
• MemoryBoot and the Cordis mnemonMemory service (MemoryExtensionHost remains a v0.3 pre-release alias). Extensions may contribute Layers, Adapters, Strategies, Guards, and MemorySources before Host mount or while it is live; unloading advances generations and Source readiness is transactional.
• A descriptor-driven Settings UI backed by the memory-system RPC endpoint. A discovered Layer needs no fixed frontend enum and starts disabled; Save writes only changed Layer enabled Booleans.
• Strategy manifests, permission boundaries, and deterministic replay primitives as the artifact interface for future model-generated shadow/canary/rollback workflows.
• Multiple private source workspaces while npm still publishes one dsh-mnemon package, with new contracts, kernel, extension-sdk, provider-sdk, strategy-sdk, default Layer, and default Strategy subpaths.
• Every root-Agent user turn pins one immutable, lightweight MemoryTurnView. Its bounded Wake preserves the complete Runtime projection and count-only covers for Documents and Memory Spaces; Source revisions and digests are stable across every model step in the turn. The complete Document and Memory Space ID sets remain Host-only and are not truncated to the Wake budget.
• Recall and related reads derive the root turn (including through a child agent's parentSession), validate optional Memory Space IDs against that pinned Host state, and call MnemonService directly. There is no model-facing View/node ID, Zoom tool, View capability, full catalog or selected-ID echo, or second recall LLM. Recall remains LLM-driven: an ordinary turn performs zero Provider queries. After one initial query, the LLM may explicitly issue one materially different refinement only when evidence is insufficient; same-query calls replay, a third query cannot reach a Provider, and no child Agent is created. Both attempts share one envelope of at most six results, 1,200 characters each and 4,800 content characters total; the initial admission reserves recovery capacity. One separately bounded Related traversal may follow. Brittle model-selected semantic filters are not exposed, low relevance is dropped, and medium/unknown evidence remains bounded.
• An authorized Mnemon Native smart search that loses exact structured anchors or sufficient focused-query lexical coverage after quality selection performs one bounded local keyword recovery. Recovered rows are threshold-validated, deduplicated, prioritized ahead of generic rows, and pass through the same quality and output envelopes; remote Providers, Recall scheduling, and model-call counts are unchanged. Each of the two LLM-chosen queries retains one bounded medium/unknown admission slot so refinement remains useful without broadening the shared six-result/4,800-character envelope.
• Model-facing Document search, Memory Space catalog, and status output now have separate hard envelopes. One root turn has one shared Documents search slot across root, child, and parallel calls; later calls return a compact no-I/O notice. Document search uses bounded Han bigrams so natural Chinese queries can reach relevant passages instead of becoming one unmatchable token, while focused queries require minimum token coverage to reject incidental partial overlaps. Complete records, provider settings, filesystem paths, detailed statistics, and inactive provider rows remain on Web/RPC control-plane surfaces instead of accumulating in conversation history.
• Runtime writes remain available for newly supplied facts and explicit save or correction requests, but a read-only question does not copy, promote, or summarize evidence returned by Documents, Recall, or Related into hot memory unless the user explicitly requests that promotion.
• Successful compatibility-Controller and Provider Authority mutations produce the standard MemoryReceipt. Receipts coalesce at the turn boundary so the next turn snapshots a fresh TurnView, while the current turn stays immutable.
• MEMORY.md capacity maintenance uses a no-tool planner only for routing and compaction candidates. The Host restricts routes to existing active writable Spaces, writes each original entry exactly, verifies committed receipts or exact Recall evidence, then applies compaction and the pending add/replace/remove in one revision-bound local commit. The pending or replaced/removed entry is never archived as an old source; invalid coverage, byte overflow, or a stale revision fails closed with Runtime retained.
• Background review first passes deterministic dirty-candidate and current-turn no-memory admission. Ordinary eligible activity with no persistence signal starts no child model; the short recall/writeback cue is emitted at most once per session.

Benchmark and behavioral verification

These results are pinned to the 2026-08-24 product candidate 6066aa796326a98575e142d68883b11b09d38f13, whose file tree is identical to the pre-identity-rewrite commit 95a4a450e62098614cbb443d12f6d675f5e75402 that actually ran the evaluation. The formal baseline is dsh-mnemon@0.2.16 / e5aae00797772bee34f414820b545d21391b84c7, running on DSH 0.1.1-rc.2 with the real deepseek-v4-flash model. Behavioral gates are release evidence; token and latency deltas from a real Provider are observations in this environment, not an SLA across models, networks, or hardware.

• All 27 final v0.3 full-suite runs completed. Two additional stable Recall gates each ran 20 fresh isolated sessions and passed semantics plus tool policy 40/40, with no Runtime, Documents, or Memory Space mutation, no Memory Space Catalog prefetch for Recall, and no child Agent.
• Recall remains an LLM choice: the no-durable-history steady state passed 16/16 with zero memory-tool calls. Only 1/20 misleading-wording runs used the one materially different refinement chosen by the LLM; the Host still prevented a third query.

Scenario	Correctness	v0.2.16 → v0.3 median tokens	Median user wall	Scheduling change
Autonomous Recall	10/10 → 10/10	279,077 → 99,736 (-64.26%)	86.95s → 14.87s (-82.90%)	child 13 → 0
Isolated Recall	5/5 → 5/5	119,352 → 22,609 (-81.06%)	47.68s → 8.59s (-81.99%)	child 9 → 0
Capacity maintenance	baseline completed 2/2; v0.3 3/3	137,879 → 37,275 (-72.97%)	58.88s → 28.27s (-51.98%)	child 5 → 1
Steady state	16/16 → 16/16	85,650 → 84,741 (-1.06%)	8.39s → 8.38s	zero memory tools in both

Context and retrieval	v0.2.16	v0.3.0	Interpretation
Realistic-corpus first request	10,198 tokens	10,167 tokens	No new fixed-context token tax
80 Documents + 80 Spaces first request	10,200 tokens	10,169 tokens; 4,158-character Wake	Titles, IDs, descriptions, and content do not enter the Prompt as the catalog grows
Direct retrieval hit@1	41/60	60/60	Better long-tail coverage
Direct retrieval hit@6	45/60	60/60	All 60 current-version expected-bearing queries hit
Median result body	304 characters	304 characters	Recall quality did not come from expanding result bodies
Local retrieval P95	43.22ms	62.73ms	A 19.51ms explicit cost for bounded local recovery

Bidirectional canonical-data verification passed 4/4 with no migration. Another 20 absent queries could return candidates in both versions, so a non-empty result is not proof that a fact exists.

The tables above are the public frozen release record. The public evaluation harness guide documents the scenarios, methodology, safety boundaries, and rerun commands; each run writes machine-readable metrics into its selected output directory. Raw Provider traces, request/session events, and local paths are intentionally not committed. No private engineering archive is required to understand the published claims or rerun the harness.

Upgrade and data compatibility

Upgrading from v0.2.16 requires no data migration. Runtime JSON/Markdown, Documents, the Memory Space registry, Provider service registry, Mnemon Native Stores, and remote Provider data formats are unchanged.

TurnViews, Source authority, turn pins, and pending Receipts are Host runtime state and are not written into those user data formats. Existing settings, commands, RPC, WebUI, and user workflows require no View management. Recall uses the pinned Source state automatically and exposes no new interaction.

Without memoryTopology configuration, resolution produces a topology equivalent to the old behavior: all three Layers are enabled under the fixed compatibility policy. Existing storageScope, dataDir, Provider, recall-quality, lifecycle, tool, and UI settings continue to apply.

Recommended upgrade sequence:

1. Back up the current Mnemon root or export a Mnemon Pack using the existing procedure.
2. Update dsh-mnemon and restart every DSH profile that uses it.
3. Confirm the three default Layers under Settings → Memory System → Memory layers.
4. Inspect Catalog/Topology generations and Providers on Status.
5. Open each Sidebar tab, then use one conversation turn to verify Runtime projection and on-demand Recall.

enabled=false stops participation without deleting or moving data. The Sidebar tab remains visible with an Off badge; re-enabling uses the same directories. Before downgrading to v0.2.16, back up and remove v0.3-only Layer switches from YAML. No persistent format changed, so package rollback needs no reverse data migration. v0.2.x ignores these switches and restores the older hard-coded participation behavior even though canonical data remains readable.

Extension-author migration

• Import only public dsh-mnemon/* subpaths, never repository-internal src/ or packages/ paths.
• Let the disposer returned by mnemonMemory.register() own component lifetime; do not maintain a second process-global Catalog.
• Contribute a MemorySource for each extension Layer that participates in automatic projection. Use eager only for bounded text that must enter every Wake; use routed for a bounded cover plus Host-only routing state.
• Keep Strategies to JSON-safe step proposals with no data-plane handles. Wrap permissions in a manifest and replay disabled-Layer, automatic/manual, budget, and escape cases.
• Honor AbortSignal in executors and let the Kernel produce succeeded, partial, failed, or cancelled Receipts.
• Re-plan after a stale-plan error instead of replaying old steps.

The repository's old src/memory-system/* files are source-compatibility facades only. Third parties should use npm subpaths.

Security boundaries and current limits

• Guards may only deny. A Strategy cannot broaden Host or participation authority, and a changed Guard set invalidates old Plans.
• A Cordis isolate owns scope and unloading; it does not sandbox malicious JavaScript. Layer executors, Provider Adapters, and Strategies must come from trusted packages.
• This release does not automatically execute newly model-generated code. It delivers manifests, permission wrapping, replay, and authoritative Kernel validation.
• Any new engine can integrate today as an independent Layer/Adapter. Fully dynamic Memory Space Provider settings cards, connection schemas, and persistent-registry registration are not generalized yet; the nine current Providers remain in the built-in Catalog.
• Existing controller data planes remain compatible and uniformly subject to Layer participation gates. Compatibility paths that do not yet execute a persisted MemoryPlan bridge committed Authority changes into the same MemoryReceipt contract instead of creating a second receipt type.

Verification scope

Release verification covers TypeScript, the complete Vitest suite, reproducible double builds, imports of every public subpath, declaration resolution, real isolated Headless-profile activation, package contents, publint, and attw. New regressions focus on Catalog/Topology generations, live registration and unloading, Guard changes, stale Plans, partial Receipts, all eight three-Layer switch combinations, descriptor-driven Settings, and Sidebar disabled states.

• The complete local suite passes 472 tests. One Windows-only smoke test is skipped only in the current non-Windows environment.
• The double build compares 103 generated files with identical hashes. All 10 Node-compatible public entries import directly; the Client entry is validated as a browser wrapper.
• An isolated Headless profile activates successfully and exposes 35 total tools to the model request, including all five representative Mnemon tools.
• The package contains 110 files; publint strict and the attw ESM profile pass. DSH 0.1.1-rc.2 UI primitives still emit only the upstream development-time missing-source-map warning.

See the v0.2.16 release notes for the previous release.