liuyu/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-06 05:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: document memory runtime contracts

Browse Source
This commit is contained in:
Peter Steinberger
2026-06-04 22:44:01 -04:00
parent 5613a0fb6e
commit 9448f91e6f
2 changed files with 25 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
src/plugin-sdk/memory-core-bundled-runtime.ts
View File

@@ -181,27 +181,32 @@ function loadRuntimeFacadeModule(): RuntimeFacadeModule {
});
}
/** Create a memory embedding provider with built-in fallback metadata. */
export const createEmbeddingProvider: RuntimeFacadeModule["createEmbeddingProvider"] = ((...args) =>
loadRuntimeFacadeModule().createEmbeddingProvider(
...args,
)) as RuntimeFacadeModule["createEmbeddingProvider"];
/** Register all built-in memory embedding provider adapters with a host registry. */
export const registerBuiltInMemoryEmbeddingProviders: RuntimeFacadeModule["registerBuiltInMemoryEmbeddingProviders"] =
((...args) =>
loadRuntimeFacadeModule().registerBuiltInMemoryEmbeddingProviders(
...args,
)) as RuntimeFacadeModule["registerBuiltInMemoryEmbeddingProviders"];
/** Remove short-term recall candidates already grounded into durable memory. */
export const removeGroundedShortTermCandidates: RuntimeFacadeModule["removeGroundedShortTermCandidates"] =
((...args) =>
loadRuntimeFacadeModule().removeGroundedShortTermCandidates(
...args,
)) as RuntimeFacadeModule["removeGroundedShortTermCandidates"];
/** Repair or archive problematic dreaming artifacts through the bundled runtime facade. */
export const repairDreamingArtifacts: RuntimeFacadeModule["repairDreamingArtifacts"] = ((...args) =>
loadRuntimeFacadeModule().repairDreamingArtifacts(
...args,
)) as RuntimeFacadeModule["repairDreamingArtifacts"];
/** Preview grounded REM markdown facts and candidates for selected input files. */
export const previewGroundedRemMarkdown: ApiFacadeModule["previewGroundedRemMarkdown"] = ((
...args
) =>
@@ -209,16 +214,19 @@ export const previewGroundedRemMarkdown: ApiFacadeModule["previewGroundedRemMark
...args,
)) as ApiFacadeModule["previewGroundedRemMarkdown"];
/** Remove duplicate dreaming diary entries while preserving canonical records. */
export const dedupeDreamDiaryEntries: ApiFacadeModule["dedupeDreamDiaryEntries"] = ((...args) =>
loadApiFacadeModule().dedupeDreamDiaryEntries(
...args,
)) as ApiFacadeModule["dedupeDreamDiaryEntries"];
/** Write synthetic/backfill dreaming diary entries for harness or migration use. */
export const writeBackfillDiaryEntries: ApiFacadeModule["writeBackfillDiaryEntries"] = ((...args) =>
loadApiFacadeModule().writeBackfillDiaryEntries(
...args,
)) as ApiFacadeModule["writeBackfillDiaryEntries"];
/** Remove dreaming diary entries previously written by the backfill helper. */
export const removeBackfillDiaryEntries: ApiFacadeModule["removeBackfillDiaryEntries"] = ((
...args
) =>
@@ -226,11 +234,13 @@ export const removeBackfillDiaryEntries: ApiFacadeModule["removeBackfillDiaryEnt
...args,
)) as ApiFacadeModule["removeBackfillDiaryEntries"];
/** Filter recall entries to the configured REM lookback window. */
export const filterRecallEntriesWithinLookback: ApiFacadeModule["filterRecallEntriesWithinLookback"] =
((...args) =>
loadApiFacadeModule().filterRecallEntriesWithinLookback(
...args,
)) as ApiFacadeModule["filterRecallEntriesWithinLookback"];
/** Preview REM harness output across dreaming, grounded, and deep promotion candidates. */
export const previewRemHarness: ApiFacadeModule["previewRemHarness"] = ((...args) =>
loadApiFacadeModule().previewRemHarness(...args)) as ApiFacadeModule["previewRemHarness"];

15
src/plugin-sdk/memory-core-engine-runtime.ts
View File

@@ -9,6 +9,7 @@ import {
} from "./facade-runtime.js";
import type { MemorySearchManager } from "./memory-core-host-engine-storage.js";
/** Doctor metadata for a built-in memory embedding provider. */
export type BuiltinMemoryEmbeddingProviderDoctorMetadata = {
providerId: string;
authProviderId: string;
@@ -17,6 +18,7 @@ export type BuiltinMemoryEmbeddingProviderDoctorMetadata = {
autoSelectPriority?: number;
};
/** One issue found while auditing dreaming/session-corpus artifacts. */
export type DreamingArtifactsAuditIssue = {
severity: "warn" | "error";
code:
@@ -28,6 +30,7 @@ export type DreamingArtifactsAuditIssue = {
fixable: boolean;
};
/** Summary of dreaming diary and session-corpus artifact health. */
export type DreamingArtifactsAuditSummary = {
dreamsPath?: string;
sessionCorpusDir: string;
@@ -39,6 +42,7 @@ export type DreamingArtifactsAuditSummary = {
issues: DreamingArtifactsAuditIssue[];
};
/** Result from archiving or repairing problematic dreaming artifacts. */
export type RepairDreamingArtifactsResult = {
changed: boolean;
archiveDir?: string;
@@ -49,6 +53,7 @@ export type RepairDreamingArtifactsResult = {
warnings: string[];
};
/** One issue found while auditing short-term promotion artifacts. */
export type ShortTermAuditIssue = {
severity: "warn" | "error";
code:
@@ -65,6 +70,7 @@ export type ShortTermAuditIssue = {
fixable: boolean;
};
/** Summary of recall-store and qmd state used by short-term promotion. */
export type ShortTermAuditSummary = {
storePath: string;
lockPath: string;
@@ -86,6 +92,7 @@ export type ShortTermAuditSummary = {
| undefined;
};
/** Result from repairing invalid recall-store entries or stale short-term locks. */
export type RepairShortTermPromotionArtifactsResult = {
changed: boolean;
removedInvalidEntries: number;
@@ -142,34 +149,42 @@ function loadFacadeModule(): FacadeModule {
artifactBasename: "runtime-api.js",
});
}
/** Audit short-term promotion artifacts in an agent workspace. */
export const auditShortTermPromotionArtifacts: FacadeModule["auditShortTermPromotionArtifacts"] = ((
...args
) =>
loadFacadeModule()["auditShortTermPromotionArtifacts"](
...args,
)) as FacadeModule["auditShortTermPromotionArtifacts"];
/** Audit dreaming diary and session-corpus artifacts in an agent workspace. */
export const auditDreamingArtifacts: FacadeModule["auditDreamingArtifacts"] = ((...args) =>
loadFacadeModule()["auditDreamingArtifacts"](...args)) as FacadeModule["auditDreamingArtifacts"];
/** Resolve doctor metadata for one built-in memory embedding provider. */
export const getBuiltinMemoryEmbeddingProviderDoctorMetadata: FacadeModule["getBuiltinMemoryEmbeddingProviderDoctorMetadata"] =
((...args) =>
loadFacadeModule()["getBuiltinMemoryEmbeddingProviderDoctorMetadata"](
...args,
)) as FacadeModule["getBuiltinMemoryEmbeddingProviderDoctorMetadata"];
/** Resolve the active memory search manager and any runtime availability error. */
export const getMemorySearchManager: FacadeModule["getMemorySearchManager"] = ((...args) =>
loadFacadeModule()["getMemorySearchManager"](...args)) as FacadeModule["getMemorySearchManager"];
/** List built-in memory embedding providers eligible for automatic selection. */
export const listBuiltinAutoSelectMemoryEmbeddingProviderDoctorMetadata: FacadeModule["listBuiltinAutoSelectMemoryEmbeddingProviderDoctorMetadata"] =
((...args) =>
loadFacadeModule()["listBuiltinAutoSelectMemoryEmbeddingProviderDoctorMetadata"](
...args,
)) as FacadeModule["listBuiltinAutoSelectMemoryEmbeddingProviderDoctorMetadata"];
/** Lazy memory index manager facade used by status and runtime callers. */
export const MemoryIndexManager: FacadeModule["MemoryIndexManager"] = createLazyFacadeObjectValue(
() => loadFacadeModule()["MemoryIndexManager"] as object,
) as FacadeModule["MemoryIndexManager"];
/** Repair invalid recall-store entries and stale short-term promotion locks. */
export const repairShortTermPromotionArtifacts: FacadeModule["repairShortTermPromotionArtifacts"] =
((...args) =>
loadFacadeModule()["repairShortTermPromotionArtifacts"](
...args,
)) as FacadeModule["repairShortTermPromotionArtifacts"];
/** Repair or archive problematic dreaming artifacts. */
export const repairDreamingArtifacts: FacadeModule["repairDreamingArtifacts"] = ((...args) =>
loadFacadeModule()["repairDreamingArtifacts"](
...args,