The registrars that allow only one active implementation at a time, and the memory adapter contracts that sit on top of them. Part of the Plugin SDK overview.

Exclusive slots

To participate in durable admitted turns, context engines must declare currentTurnFence: "before-current-turn-entry-v1" and turnAdvancementIdempotency: "atomic-idempotent-v1" under info.transcriptSemantics, then implement commitTurn(...) as an atomic, idempotent write keyed by advancementKey. Apus supplies only the inclusive accepted turn, from its admitted user entry through its terminal entry; use the readSessionTranscriptVisibleMessageDelta(...) cursor API to bootstrap or rebuild earlier history. Without the full contract, Apus uses the legacy context path for the whole logical turn and its retries, leaves the configured engine unchanged, and tries that engine again on the next logical turn.

Memory embedding adapters

• registerMemoryCapability is the exclusive memory-plugin API.
• A selected memory plugin may omit capability.runtime, including when it handles memory through its own hooks. The Memory settings page reports absent host search support neutrally; this does not assess other memory integrations. Plugin loading and search-runtime failures remain errors.
• registerMemoryCapability may also expose publicArtifacts.listArtifacts(...) for host-managed exports. Companion plugins that enumerate those declared artifacts still use listActiveMemoryPublicArtifacts(...) from the retained apus/plugin-sdk/memory-host-core facade until a focused public consumer API exists; they must not reach into another plugin's private layout.
• A memory runtime that can return session-transcript hits should implement runtime.authorizeSearchHits(...). The host calls this hook before raw search hits reach caller-visible surfaces and supplies the requesting agent, session key, and sandbox state. Return only hits the requester may observe. For a host or operator caller without a session, the host sets trustedAgentScope; return that agent's own session hits and no other agent's. When a session caller carries a host-granted conversation recall pass, the host forwards it as conversationRecall; admit only the hits that pass allows. If the hook is absent, Apus fails closed by withholding session-source hits while retaining ordinary memory hits. Keep transcript identity and visibility policy in the owning memory plugin; callers must not infer authorization from paths or duplicate plugin-specific rules.
• Embedding providers use api.registerEmbeddingProvider(...) and contracts.embeddingProviders; there is no separate memory-only registry.

Pre-compaction memory flush

Register a flush resolver on MemoryPluginCapability to supply the silent turn that saves durable context before compaction. Apus resolves flush timing first from agents.defaults.compaction.memoryFlush and the active context window. When enabled is false, the host does not invoke the resolver. Return null to skip the flush for provider-specific reasons.

There are two resolver fields:

• flushPlanResolver returns a complete MemoryFlushPlan or null. Its contract is unchanged from earlier releases. Memory Core uses it.
• providerFlushPlanResolver returns a plan the host completes: a MemoryFlushFilePlanDraft (a complete MemoryFlushPlan is one such draft) or a MemoryFlushToolsPlan. When a plugin registers both, the host uses providerFlushPlanResolver.

Each plan has prompt, systemPrompt, and one persistence arm. In plans from providerFlushPlanResolver, the softThresholdTokens, forceFlushTranscriptBytes, reserveTokensFloor, and model fields are deliberate provider overrides. The host fills omitted timing fields from its resolved timing, and fills an omitted model from memoryFlush.model for the tools arm only; a file plan without model keeps the session's model. A model override pins the turn to an exact provider/model reference, such as ollama/qwen3:8b, without inheriting the active fallback chain.

Choose exactly one persistence arm:

Only the selected memory slot owner may supply a tools-arm plan, through providerFlushPlanResolver. The host tracks which plugin supplied the effective resolver, including when sidecar capability fields are merged; an owner's resolver of either kind wins over a sidecar's. A tools-arm plan from a non-owner is skipped with a warning naming that plugin.

For the tools arm, ownership comes from registered tool metadata. A same-named tool from another plugin is excluded. Normal message, model, sandbox, allowlist, and authorization policies still apply after this projection. Persistence and lookup tool names must not overlap; the host skips an overlapping plan and warns with the plugin name. If none of the declared persistence tools survives, the host skips inference and logs a warning naming the missing tools. If policy removes any lookup tools, the flush still runs with its surviving persistence tools and logs one warning naming the unavailable lookup tools. Compaction can continue after a skipped flush.

Audience and flush identity

The flush runs in a detached internal session so its maintenance transcript does not enter later user turns. For a tools-arm turn, the host resolves the source turn's memoryAudience from its trusted session entry, session key, session ID, and the source turn's sender ownership, including for a flush scheduled after the turn completes. It delegates that audience to the detached session key, retaining the source lineage and revocation checks. Persistence and lookup tools receive this delegated audience and the source sandbox state. If the source has no valid audience, the host skips the tools-arm flush with a debug log. The maintenance copy still has senderIsOwner: false; providers authorize memory access through the supplied audience and its current-authority check.

Only tools-arm flush contexts include memoryFlush: { flushId: string } on ApusPluginToolContext. The host derives flushId deterministically from the source session incarnation (its sessionId and lifecycle revision) and its pre-compaction compactionCount (zero when absent). The count advances after a completed compaction, so model fallback attempts and later retries within the same cycle share an ID; a later cycle or a new session incarnation, including a reset that keeps the session ID, gets a different ID. Providers can combine this ID with their mutation's identity to deduplicate retries. The ID does not grant authority.

Completion evidence

A tools-arm flush succeeds only when at least one declared persistence tool completes without error, or the assistant's final output is the silent token NO_REPLY. A successful lookup call is not persistence evidence. Without either valid completion signal, the host records a failed flush with the reason no persistence tool call succeeded. Run errors still fail the flush. The file arm retains its file-writing and completion behavior.

Provider-neutral memory runtime

The provider-neutral runtime lets a record-based provider own the memory slot without impersonating workspace files. The legacy file-shaped MemoryPluginRuntime contract remains intact. Success means:

• existing legacy providers continue to work without changes;
• a record-only provider can serve every reader whose declared needs it supports;
• unsupported operations are declared as capabilities, not discovered by calling the provider and handling failure.

The integration has three layers:

1. The host selects one provider, supplies trusted caller authority, owns the caller-bound lifecycle, and routes requests.
2. providerRuntime supplies neutral search, retrieval, and health through provider-scoped references and declared capabilities.
3. Provider-owned tools, skills, and UI retain rich workflows such as mutation, organization, and maintenance. The neutral runtime does not replace them.

External plugins derive provider types from the already-public MemoryPluginCapability; memory-host-search remains a private-local facade for bundled consumers.

import type { MemoryPluginCapability } from "apus/plugin-sdk/memory-host-core";

type MemoryProviderRuntime = NonNullable<MemoryPluginCapability["providerRuntime"]>;
type MemoryProviderOpenResult = Awaited<ReturnType<MemoryProviderRuntime["open"]>>;
type MemoryProviderHandle = NonNullable<MemoryProviderOpenResult["provider"]>;

const providerRuntime: MemoryProviderRuntime = {
  async open({ agentId, context }) {
    // Reuse the plugin's service. Routing facts and record IDs do not grant access.
    const provider: MemoryProviderHandle = await service.openMemoryReader({ agentId, context });
    return { provider };
  },
};

api.registerMemoryCapability({ providerRuntime });

service.openMemoryReader is provider-owned code. It returns a caller-bound MemoryProviderHandle with these members:

Capabilities are enforced before provider code runs:

The selected memory slot owner can also declare recallToolNames. These are the concrete agent tools Active Memory uses for deep recall. A valid explicit Active Memory toolsAllow list takes precedence, followed by the selected provider's recallToolNames, then the built-in fallback. Unselected sidecars cannot contribute this field. For a native provider, recallToolNames also gates provider-direct trigger recall: Active Memory runs it only when the declaration is non-empty and the turn's tool policy allows every declared tool. Otherwise it skips the provider lookup and injects nothing.

Host consumers

The required MemoryCallerContext carries an assertCurrent() callback, an optional abort signal, and MemoryCallerAuthority:

• operator: authenticated operator scopes and optional connection identity;
• session: the actual session key, optional session ID, sandbox state, and an optional host-resolved memory audience. conversationRecall carries the bounded recall pass the host granted that session's tool context, such as an Active Memory recall run; copy it only from that trusted context, never from model input;
• host: a named host operation, not an operator or private-session grant.

The host rechecks caller and plugin lifetime before and after asynchronous operations. Providers apply visibility policy from the supplied authority and revalidate before releasing data. A session authority without an audience has no private or conversation grant. A host authority also grants neither private nor conversation access.

Memory audience

Apus resolves memory audience once from trusted turn facts and durable session lineage. Providers and plugin tools consume the resulting host-minted value:

type MemoryAudience =
  | { kind: "owner-private"; agentId: string }
  | { kind: "conversation"; agentId: string; sessionKey: string; sessionId: string };

• A direct turn from the trusted agent owner has owner-private audience.
• A direct turn from another sender, or a group, channel, or thread turn, has conversation audience for the durable root session.
• A spawned child inherits its root audience only after the host validates each recorded parent key, session ID, and lifecycle revision.
• Missing, malformed, cross-agent, cyclic, or stale lineage produces no audience. Unknown or missing durable chat type also produces no audience.

Audience is separate from sandbox policy. A provider can deny sandboxed callers even when they have a valid audience. Operator authority is also separate and explicit; it does not become owner-private session authority.

Providers must not reconstruct audience from session lookups, session-key patterns, record IDs, or cached fingerprints. They must also reject an audience for another agent. The host binds each audience to its invocation session and rejects it when presented for another session. Host-mediated child runs receive a new audience bound to the child session's current session ID and lifecycle revision (or, for a detached child run, to the absence of a row for its key), sharing the parent's lineage and revocation state; a child reset or reassignment rejects it as well. The host rejects audience objects that it did not mint and invalidates a captured audience when any session in its lineage changes incarnation or lifecycle, or when the run that owns it ends. The host checks audience currency before and after opening a provider and around every provider call. The context.assertCurrent() passed to open() includes audience currency, so a provider that calls it immediately before I/O, including after its own awaited work, is refused instead of acting under stale authority. Session writes that keep the session ID and lifecycle revision, such as a turn's own activity and usage bookkeeping, do not interrupt these checks while they publish; a pending reset, replacement, or deletion still reports currency as unavailable until it settles, then revokes the audience. Audience revocation does not abort context.signal; call assertCurrent() before each effect.

Compatibility and host integration

• Consumers prefer providerRuntime. Only its absence selects the host-owned legacy adapter. Failure, denial, or an invalid provider runtime never retries against legacy storage.
• Existing plugin registration, MemoryPluginRuntime, manager types, and getActiveMemorySearchManager remain available. Existing plugins need no source or storage migration.
• The legacy adapter declares memory and session search, no pagination, project filtering, and no automatic-recall candidates. It preserves manager receivers, virtual paths, read bounds, visibility filtering, and cleanup. Its health details omit host paths such as the database and workspace locations.
• Provider references include providerId; another selected provider's reference is rejected. Providers own revision behavior and must not substitute unrelated content for a stale reference.
• The Gateway exposes neutral search with memory.search and version: 2, retrieval with memory.get, and health with memory.status. Any authenticated operator connection with operator.read can call them, the same callers as unversioned memory.search, including token-authenticated CLI connections. In-process agent-tool and agent-runtime callers use their admitted run's operator authority instead. Request abort, connection close, and revoked client authority are rechecked before and after every provider call. Omitting the search version, or sending version: 1, retains the old file-shaped response for legacy providers. A native provider returns an error naming the selected plugin and directs the client to retry with version: 2.
• Voice fast context, project recall, Active Memory trigger recall, and Memory Wiki use the neutral interface when the selected slot owner registers providerRuntime and declares their required capabilities. With a legacy runtime, they keep their manager calls, results, and citation labels.
• A record-only provider keeps its own tools, skills, and UI; selection does not create a fake file browser. Older hosts ignore providerRuntime, so plugins that require it must declare a compatible host version.

This is the shared read runtime. Memory Core tools and CLI, file-index diagnostics, startup workspace files, pre-compaction saving, reset capture, and maintenance keep their existing ownership. Native provider workflows continue alongside it.

Dreaming remains separate

Dreaming is not a provider runtime capability. Selecting another memory plugin can still activate Memory Core as a dreaming sidecar under the existing loader policy. Explicitly disabling Memory Core prevents that sidecar. The Dreams UI and file-backed maintenance methods do not imply that the selected provider implements dreaming.

Bundled Memory Core workers

Memory Core uses the shared process-runtime worker pool for lexical retrieval, cosine fallback, and immutable chunk preparation. Retrieval retains the search generation until its readers close; publication, source-hash validation, and forget operations remain with their existing database owners.

Bundled workers use the private memory-core-host-engine-knn facade for read-only database access, the shared SQLite idle lifetime, and vector primitives, and memory-core-host-engine-indexing for pure chunking, annotations, hashes, and embedding input limits. These facades avoid loading provider registries or writable-store initialization into worker threads. They are bundled runtime contracts, not third-party typed SDK entrypoints.