Web, Headless, Tools, Commands, and RPC

This page is an integration reference. For daily use, start with the Sidebar and conversation UI guide.

#Memory space naming and compatibility

The product term is memory space (Chinese: 记忆空间). The Source exports MemorySpace, MemorySpaceView, MemorySpaceCatalog, and corresponding request and metadata types. Previously published MemoryBody* types remain deprecated aliases with the same shapes.

Existing v0.5.x identifiers such as mnemon_memory_bodies, mnemon_memory_body_create, body-directory, and memoryBodyId / memoryBodyIds still refer to memory spaces. They remain stable for installed tools, Source pages, Provider adapters, and persisted Document/Pack lineage. The .dsh-memory-bodies.json filename and its bodies field are also retained. Renaming the product does not rename user-created spaces, change their IDs, move databases, or alter access grants.

#User-facing entry points

displayMode selects sidebar (default) or builtin, the conversation tab; tabEnabled controls whether the selected entry appears. The conversation tab does not show the Sidebar's scope controls. The two conversation shortcuts are switched independently under Interface, stored through the mnemon-ui settings scope.

#Profile surfaces

Headless receives the full model-tool surface. Its task argument is submitted as an ordinary user message, so it does not provide an interactive slash-command dispatcher. Explicit and model-guided writes that finish before the Agent becomes idle are durable.

Model tools, lifecycle hooks, and system scheduling use an automatic trigger. User-initiated data-plane operations over Web/RPC use manual. Setting a Source to manual therefore preserves direct management while denying model tools and automatic projection. memory-system and status are control-plane observations and remain readable even when a Source is disabled.

#Model tools

#Read-only tools

“Read only” means managed bodies and durable semantics do not change. mnemon_document_search still updates lastAccessedAt for LRU ordering, so feature read-only is not disk read-only.

#Tools available with writeEnabled=true

When a worker invokes the same tool name, it reaches the service directly and is not delegated recursively.

Autonomous write workers — distillation and supervised writeback runs — decide content on their own, so the host excludes mnemon_forget from their hard tool allowlist: a duplicate or conflict is resolved by skipping or storing a corrected entry, never by deleting the existing one. Operations whose request names an exact target supplied by the user or a user-facing flow (/mnemon forget, mnemon_link, and Memory Space management) keep the full write toolset.

Idle review can search Documents and call mnemon_document_create, but cannot call mnemon_document_manage or mnemon_view_action. It skips covered candidates or creates one separate document referencing existing document ids. The Source's create Action accepts title, content, optional description, sourcePaths, and sessionIds; it rejects action, id, and other unknown fields. Capacity exhaustion rejects creation without archiving an existing document. This protection applies to existing user- and Agent-created documents. Explicit editing continues through the existing management paths.

mnemon_runtime_memory accepts an optional branches array (git branch names) for target=memory writes. Branch-scoped entries are projected into the per-turn Runtime snapshot only when the session's workspace is checked out on a listed branch; untagged entries are always projected. On replace, providing branches changes the scope, an empty array clears it, and omitting it keeps the current scope. The parameter is rejected for target=user.

#Tool admission

• Runtime: explicit preferences, stable project conventions, environment facts, and high-frequency lessons.
• Documents: designs, investigations, procedures, postmortems, or handoffs with complete structure and rationale.
• Memory Spaces: stable facts, decisions, and insights that must survive across tasks or benefit from graph relationships.
• Skip: questions, guesses, temporary progress, completion logs, raw output, secrets, and ordinary repository facts that are easy to rediscover.

mnemon_forget is a destructive semantic action. Use it only on explicit request or after confirming that content is wrong or obsolete. The host enforces this for autonomous workers by excluding the tool from their allowlist; the main agent can still call it when the user explicitly asks.

#/mnemon commands

/mnemon
/mnemon status
/mnemon recall <query>
/mnemon related <full memory ID>
/mnemon remember <content>
/mnemon forget <exact ID>

• Empty /mnemon equals status.
• status is deterministic and starts no model.
• recall and related read through the live Agent's scoped Source route without spawning a worker. remember and forget use that Agent as the write worker's parent.
• Command recall returns at most 10 results.
• forget requires one exact ID without spaces.
• forget reports deletion only for a forgotten receipt; skipped, failed, or unconfirmed results are reported as errors with the worker summary.

#UI contributions

Everything Mnemon shows inside DSH is registered into DSH's own UI regions. The conversation contributions are additive and replace no official DSH rendering.

Mnemon declares two keyed regions of its own, both keyed by a component's package name: mnemon.component.settings, rendered on that component's page, and mnemon.component.status, its card on the Status page. Official and third-party components contribute through the same regions; see Plugin development.

The assistant-message candidate is editable and long replies are bounded by the UI preview limit. Confirmation starts an independent task Agent, and persistence is complete only after its settled receipt.

#Workspace routing

Web workbench requests carry sessionId and an optional workspaceId. The Host accepts only IDs registered in workspaceRegistry:

• deterministic reads and manual maintenance may route to the inspected root selected by workspaceId;
• Agents, tools, commands, and lifecycle hooks still route by the Agent cwd associated with sessionId;
• status.workspaceContext returns selected / effective roots and aligned;
• independent task Agents started from the workbench use the inspected workspace; they do not require the main conversation to match. Conversation tools continue to use their own session cwd and pinned View, not the workbench inspection scope.

Profiles without a Web workspace registry, including Headless, have no arbitrary inspection target. Agent execution still routes workspace scope directly from the session cwd.

#RPC channels

RPC is an internal Host-to-client bridge, not a stable external HTTP API. Pages and component plugins should use the scoped clients from dsh-mnemon/client; see Plugin development.

Loopback pages call these channels directly, authenticated by the DSH browser session. Remote pages reach the same handlers through DSH's API Gateway: channel /api, endpoints dshMnemon/read, dshMnemon/activation, dshMnemon/write, dshMnemon/pack, dshMnemon/settings, dshMnemon/view and dshMnemon/viewWrite. The Gateway owns Host/Origin validation, browser pairing and the response envelope; Mnemon adds only the remoteAccess grant shown above, captured at startup. See Remote management.

#Read channel

#Activation channel

/dsh-mnemon-activation has a narrower request schema than the write channel. Its body endpoint accepts only memoryBodyId, a Boolean active, and the normal session/workspace routing fields; source-assistance accepts the same two fields as a confirmed activation operation on a Memory Spaces instance. Both control participation in DSH reads and routing without accepting metadata, Provider connection, credential, deletion, or durable-memory mutations. Read-only mode rejects them at the Host boundary.

#Write channel

provider-services returns a redacted catalog through the read channel. The settings editor knows which credential fields are configured; it can replace or explicitly clear them without reading saved values back.

With writeEnabled=false, the activation and write channels stay registered but mutations are rejected at the Host boundary. The browser also disables mutation controls from the Host's settings snapshot before transport.

#Backup channel

Backups contain private memory, so callers must treat the authenticated DSH browser session as a full Host authority and protect exported archives separately.

#Settings channel

/dsh-mnemon-settings offers get and mutate for two namespaces: mnemon owns Host and storage settings, and mnemon-ui owns turnBar and saveAction, saved as conversationInteraction. Mutations carry settings revisions so concurrent edits are not overwritten. dsh-mnemon's page under Plugins (plugins.bundle.config) reads and writes through this channel on loopback and remote pages alike. On loopback pages it also follows DSH's ctx.configForms revision of the mnemon entry and re-reads the channel when another page or a profile reload changes it.

#Memory composition channels

apply stores the strategy and each component's options in the mnemon-view scope, saved as memoryView; DSH's plugin manager records the component switches in the profile patch. See Configuration.

#npm exports and extension service

Core publishes ctx.mnemonMemory: MnemonMemoryService; the actual service exposes only installContributions. Source/Strategy authors use inject = ['mnemonMemory'] and installMemory, without receiving an engine, controller or registry. Public subpaths are defined by each package's package.json#exports; Sources may provide their own ./contracts and optional ./client.

Generic model tools mnemon_view_route and mnemon_view_action execute only routes/offers present in the current View. Existing named tools preserve the default workflow. Browser management uses source-management-catalog, source-management-read, source-management-mutate and optional source-assistance; instance identity, confirmation, revision and current authority are checked by the Host/Source. Internal RPC names are not the plugin SDK: use the scoped page client. See Plugin development.

#Internationalization

The main Sidebar workbench, the configuration page under Plugins, and conversation entries support Chinese and English and follow DSH locale live. Brand names, tool names, and configuration keys are not translated. /mnemon commands, model-tool cards, some Host errors, and compatibility metadata remain partially untranslated.