@botbotgo/agent-harness 0.0.63 → 0.0.65

package/README.md

@@ -68,6 +68,8 @@ Boundary documents live in:
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/feature-checklist.md`
+- `docs/long-term-memory.md`
+- `docs/app-task-pattern.md`
 
 ## Why This Exists
 
@@ -109,6 +111,7 @@ your-workspace/
     embedding-models.yaml
     vector-stores.yaml
     stores.yaml
+    runtime-memory.yaml
     backends.yaml
     tools.yaml
     mcp.yaml
@@ -330,6 +333,7 @@ Core workspace files:
 - `config/embedding-models.yaml`
 - `config/vector-stores.yaml`
 - `config/stores.yaml`
+- `config/runtime-memory.yaml`
 - `config/backends.yaml`
 - `config/tools.yaml`
 - `config/mcp.yaml`
@@ -437,6 +441,12 @@ spec:
     path: checkpoints.sqlite
 ```
 
+### `config/runtime-memory.yaml`
+
+Use this singleton file for runtime-owned durable long-term memory defaults.
+
+Keep bootstrap context in `config/agent-context.md`. Keep resumable execution state in the checkpointer. Use `RuntimeMemory` for durable memory policy and retrieval defaults.
+
 ### `config/backends.yaml`
 
 Use reusable DeepAgents backend presets so filesystem and `/memories/*` topology stays in YAML:
@@ -551,6 +561,7 @@ For backend-specific options, prefer the upstream concept directly inside `spec.
 - upstream LangChain v1 and DeepAgents concepts should be expressed as directly as possible in YAML
 - when a feature can be expressed in YAML, prefer YAML over expanding the public API
 - recovery, approvals, threads, runs, and events are runtime concepts, not backend escape hatches
+- application task centers should be built on the existing store plus runtime ids instead of expanding the public runtime contract
 - new LangChain v1 or DeepAgents config should land in YAML mapping and tests before adding public runtime APIs
 
 In short, the product model stays stable while the execution semantics remain upstream-owned.

package/README.zh.md

@@ -68,6 +68,8 @@
 - `docs/upstream-feature-matrix.md`
 - `docs/product-boundary.md`
 - `docs/feature-checklist.md`
+- `docs/long-term-memory.md`
+- `docs/app-task-pattern.md`
 
 ## 为何需要它
 
@@ -551,6 +553,7 @@ spec:
 - 应尽量在 YAML 中直接表达 LangChain v1 与 DeepAgents 的概念
 - 能用 YAML 表达的能力，优先 YAML 而非扩张公共 API
 - 恢复、审批、线程、运行与事件是运行时概念，不是后端逃生舱
+- 应用里的 task center 应基于现有 store 与 runtime id 建模，而不是把 task 扩成公共运行时契约
 - 新的 LangChain v1 或 DeepAgents 配置应先落在 YAML 映射与测试中，再考虑公共运行时 API
 
 简言之：产品模型稳定，执行语义仍归上游。

package/dist/config/agents/direct.yaml

@@ -44,6 +44,9 @@ spec:
       # The default direct host keeps this enabled so middleware can use the same durable store surface as other hosts.
       store:
         ref: store/default
+      # agent-harness feature: workspace-level durable long-term memory defaults for this host profile.
+      runtimeMemory:
+        ref: runtime-memory/default
       # Upstream execution feature: no declarative HITL tool routing by default.
       interruptOn: {}
       # Upstream execution feature: filesystem middleware settings for LangChain v1 agents.

package/dist/config/agents/orchestra.yaml

@@ -54,6 +54,9 @@ spec:
       # Other store kinds should flow through a custom runtime resolver instead of being claimed as built in.
       store:
         ref: store/default
+      # agent-harness feature: workspace-level durable long-term memory defaults for this host profile.
+      runtimeMemory:
+        ref: runtime-memory/default
       # Upstream execution feature: backend config passed into the selected backend adapter.
       # Prefer a reusable backend preset via `ref` so backend topology stays declarative and reusable in YAML.
       # The default preset keeps DeepAgent execution semantics upstream-owned:

package/dist/config/runtime-memory.yaml

@@ -0,0 +1,65 @@
+# agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+# agent-harness feature: workspace-global durable long-term memory defaults.
+# This object is harness-owned and defines the stable memory policy/config contract for the workspace.
+# It is loaded automatically as a singleton and can also be referenced from agent execution config.
+kind: RuntimeMemory
+metadata:
+  # agent-harness feature: stable singleton name for the default runtime memory object.
+  name: default
+spec:
+  # ======================
+  # agent-harness Features
+  # ======================
+  # agent-harness feature: enable or disable runtime-owned durable long-term memory for the workspace.
+  enabled: true
+
+  # agent-harness feature: primary durable store used for structured long-term memory records.
+  store:
+    ref: store/default
+
+  # agent-harness feature: optional semantic retrieval substrate for long-term memory recall.
+  vectorStore:
+    ref: vector-store/default
+
+  # agent-harness feature: default embedding model used with the configured vector store.
+  embeddingModel:
+    ref: embedding-model/default
+
+  # agent-harness feature: stable namespace roots used by the runtime memory policy layer.
+  namespaces:
+    users: memories/users
+    projects: memories/projects
+    threads: memories/threads
+
+  # agent-harness feature: retrieval defaults for selecting a bounded number of relevant memories per turn.
+  retrieval:
+    defaultTopK: 5
+    maxPromptMemories: 8
+
+  # agent-harness feature: selective write policy for durable long-term memory.
+  writePolicy:
+    mode: selective
+    allow:
+      - user_preferences
+      - project_facts
+      - confirmed_decisions
+      - reusable_summaries
+    deny:
+      - scratchpad
+      - transient_reasoning
+      - intermediate_results
+
+  # agent-harness feature: background consolidation and retention defaults for stored memories.
+  consolidation:
+    dedupe: true
+    mergeStrategy: replace_or_merge
+    decay:
+      enabled: true
+      maxAgeDays: 180
+
+  # agent-harness feature: lifecycle events that can trigger runtime memory digestion.
+  ingestion:
+    backgroundConsolidation: true
+    writeOnApprovalResolution: true
+    writeOnRunCompletion: true

package/dist/contracts/types.d.ts

@@ -204,6 +204,7 @@ export type CompiledAgentBinding = {
         capabilities?: RuntimeCapabilities;
         checkpointer?: Record<string, unknown> | boolean;
         store?: Record<string, unknown>;
+        runtimeMemory?: Record<string, unknown>;
     };
 };
 export type WorkspaceBundle = {

package/dist/init-project.js

@@ -131,6 +131,33 @@ spec:
         kind: StoreBackend
 `;
 }
+function renderRuntimeMemoryYaml() {
+    return `apiVersion: agent-harness/v1alpha1
+kind: RuntimeMemory
+metadata:
+  name: default
+spec:
+  enabled: true
+  namespaces:
+    users: memories/users
+    projects: memories/projects
+    threads: memories/threads
+  retrieval:
+    defaultTopK: 5
+    maxPromptMemories: 8
+  writePolicy:
+    mode: selective
+    allow:
+      - user_preferences
+      - project_facts
+      - confirmed_decisions
+      - reusable_summaries
+    deny:
+      - scratchpad
+      - transient_reasoning
+      - intermediate_results
+`;
+}
 function renderToolsYaml(options) {
     if (!options.withWebSearch) {
         return `apiVersion: agent-harness/v1alpha1
@@ -175,6 +202,8 @@ ${toolsBlock}    skills:
 ${subagentsBlock}    config:
       backend:
         ref: backend/default
+      runtimeMemory:
+        ref: runtime-memory/default
       systemPrompt: ${prompt}${delegationLine}
 `;
 }
@@ -197,6 +226,8 @@ ${toolsBlock}    skills:
     config:
       backend:
         ref: backend/default
+      runtimeMemory:
+        ref: runtime-memory/default
       systemPrompt: ${prompt}
 `;
 }
@@ -270,6 +301,7 @@ export async function initProject(projectRoot, projectName, options = {}) {
         ["config/workspace.yaml", renderWorkspaceYaml()],
         ["config/agent-context.md", renderAgentContext(resolved)],
         ["config/models.yaml", renderModelsYaml(resolved)],
+        ["config/runtime-memory.yaml", renderRuntimeMemoryYaml()],
         ["config/backends.yaml", renderBackendsYaml()],
         ["config/tools.yaml", renderToolsYaml(resolved)],
         ["config/agents/research.yaml", renderResearchAgentYaml(resolved)],

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.62";
+export declare const AGENT_HARNESS_VERSION = "0.0.64";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.62";
+export const AGENT_HARNESS_VERSION = "0.0.64";

package/dist/runtime/harness.d.ts

@@ -14,6 +14,7 @@ export declare class AgentHarnessRuntime {
     private readonly embeddingModels;
     private readonly vectorStores;
     private readonly defaultStore;
+    private readonly runtimeMemoryStore;
     private readonly routingSystemPrompt?;
     private readonly routingRules;
     private readonly routingDefaultAgentId?;
@@ -35,6 +36,7 @@ export declare class AgentHarnessRuntime {
     private buildRoutingInput;
     private resolveSelectedAgentId;
     private resolveStore;
+    private resolveStoreFromConfig;
     private resolveEmbeddingModel;
     private resolveVectorStore;
     constructor(workspace: WorkspaceBundle, runtimeAdapterOptions?: RuntimeAdapterOptions);

package/dist/runtime/harness.js

@@ -29,6 +29,7 @@ export class AgentHarnessRuntime {
     embeddingModels = new Map();
     vectorStores = new Map();
     defaultStore;
+    runtimeMemoryStore;
     routingSystemPrompt;
     routingRules;
     routingDefaultAgentId;
@@ -98,18 +99,18 @@ export class AgentHarnessRuntime {
     }
     resolveStore(binding) {
         const storeConfig = binding ? getBindingStoreConfig(binding) : undefined;
+        return this.resolveStoreFromConfig(storeConfig, binding?.harnessRuntime.runRoot ?? this.defaultRunRoot()) ?? this.defaultStore;
+    }
+    resolveStoreFromConfig(storeConfig, runRoot) {
         const cacheKey = storeConfig ? JSON.stringify(storeConfig) : undefined;
-        if (!storeConfig) {
-            return this.defaultStore;
-        }
-        if (!cacheKey) {
-            return this.defaultStore;
+        if (!storeConfig || !cacheKey) {
+            return undefined;
         }
         const existing = this.stores.get(cacheKey);
         if (existing) {
             return existing;
         }
-        const created = createStoreForConfig(storeConfig, binding?.harnessRuntime.runRoot ?? this.defaultRunRoot());
+        const created = createStoreForConfig(storeConfig, runRoot);
         this.stores.set(cacheKey, created);
         return created;
     }
@@ -142,7 +143,12 @@ export class AgentHarnessRuntime {
         const runRoot = this.defaultRunRoot();
         this.persistence = new FilePersistence(runRoot);
         const defaultStoreConfig = this.listHostBindings()[0]?.harnessRuntime.store;
-        this.defaultStore = defaultStoreConfig ? createStoreForConfig(defaultStoreConfig, runRoot) : new FileBackedStore(`${runRoot}/store.json`);
+        this.defaultStore = this.resolveStoreFromConfig(defaultStoreConfig, runRoot) ?? new FileBackedStore(`${runRoot}/store.json`);
+        const runtimeMemoryStoreConfig = typeof this.listHostBindings()[0]?.harnessRuntime.runtimeMemory?.store === "object" &&
+            this.listHostBindings()[0]?.harnessRuntime.runtimeMemory?.store
+            ? this.listHostBindings()[0]?.harnessRuntime.runtimeMemory?.store
+            : undefined;
+        this.runtimeMemoryStore = this.resolveStoreFromConfig(runtimeMemoryStoreConfig, runRoot) ?? this.defaultStore;
         this.resolvedRuntimeAdapterOptions = {
             ...runtimeAdapterOptions,
             toolResolver: runtimeAdapterOptions.toolResolver ??
@@ -177,7 +183,7 @@ export class AgentHarnessRuntime {
         this.routingRules = getRoutingRules(workspace.refs);
         this.routingDefaultAgentId = getRoutingDefaultAgentId(workspace.refs);
         this.modelRoutingEnabled = isModelRoutingEnabled(workspace.refs);
-        this.threadMemorySync = new ThreadMemorySync(this.persistence, this.defaultStore);
+        this.threadMemorySync = new ThreadMemorySync(this.persistence, this.runtimeMemoryStore);
         this.unregisterThreadMemorySync = this.eventBus.registerProjection(this.threadMemorySync);
         const checkpointMaintenanceConfig = readCheckpointMaintenanceConfig(workspace);
         this.checkpointMaintenance = checkpointMaintenanceConfig

package/dist/workspace/agent-binding-compiler.js

@@ -3,7 +3,7 @@ import { getSkillInheritancePolicy, resolveToolTargets } from "../extensions.js"
 import { compileModel, compileTool } from "./resource-compilers.js";
 import { inferAgentCapabilities } from "./support/agent-capabilities.js";
 import { discoverSkillPaths } from "./support/discovery.js";
-import { compileAgentMemories, getRuntimeDefaults, getWorkspaceObject, resolvePromptValue, resolveRefId } from "./support/workspace-ref-utils.js";
+import { compileAgentMemories, getRuntimeDefaults, getRuntimeMemoryDefaults, getWorkspaceObject, resolvePromptValue, resolveRefId } from "./support/workspace-ref-utils.js";
 const WORKSPACE_BOUNDARY_GUIDANCE = "Keep repository and file exploration bounded to the current workspace root unless the user explicitly asks for broader host or filesystem access. " +
     "Do not inspect absolute paths outside the workspace, system directories, or unrelated repos by default. " +
     "Prefer workspace-local tools, relative paths, and the current repository checkout when analyzing code.";
@@ -215,6 +215,23 @@ function resolveCheckpointerConfig(agent, refs) {
     }
     return { config: inlineAgentCheckpointer };
 }
+function resolveRuntimeMemoryConfig(agent, refs) {
+    const inlineRuntimeMemory = typeof agent.deepAgentConfig?.runtimeMemory === "object" && agent.deepAgentConfig.runtimeMemory
+        ? agent.deepAgentConfig.runtimeMemory
+        : typeof agent.langchainAgentConfig?.runtimeMemory === "object" && agent.langchainAgentConfig.runtimeMemory
+            ? agent.langchainAgentConfig.runtimeMemory
+            : undefined;
+    if (inlineRuntimeMemory) {
+        if (isRefConfig(inlineRuntimeMemory)) {
+            return {
+                config: materializeWorkspaceObjectConfig(refs, inlineRuntimeMemory.ref, ["runtime-memory"], `Agent ${agent.id} runtimeMemory`),
+            };
+        }
+        return { config: inlineRuntimeMemory };
+    }
+    const runtimeMemoryDefaults = getRuntimeMemoryDefaults(refs);
+    return runtimeMemoryDefaults ? { config: runtimeMemoryDefaults } : undefined;
+}
 export function compileBinding(workspaceRoot, agent, agents, referencedSubagentIds, refs, models, tools) {
     const internalSubagent = referencedSubagentIds.has(agent.id);
     const runtimeDefaults = getRuntimeDefaults(refs);
@@ -224,6 +241,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
     const backend = resolveBackendConfig(agent, refs);
     const store = resolveStoreConfig(agent, refs);
     const checkpointer = resolveCheckpointerConfig(agent, refs);
+    const runtimeMemory = resolveRuntimeMemoryConfig(agent, refs);
     const runRoot = typeof agent.runRoot === "string" && agent.runRoot.trim().length > 0
         ? path.resolve(workspaceRoot, agent.runRoot)
         : typeof runtimeDefaults?.runRoot === "string" && runtimeDefaults.runRoot.trim().length > 0
@@ -248,6 +266,7 @@ export function compileBinding(workspaceRoot, agent, agents, referencedSubagentI
             capabilities: inferAgentCapabilities(agent),
             ...(checkpointer ? { checkpointer: checkpointer.config } : {}),
             ...(store ? { store: store.config } : {}),
+            ...(runtimeMemory ? { runtimeMemory: runtimeMemory.config } : {}),
         },
     };
     if (agent.executionMode !== "deepagent") {

package/dist/workspace/object-loader.js

@@ -130,6 +130,8 @@ function normalizeKind(kind) {
             return "skill";
         case "Runtime":
             return "runtime";
+        case "RuntimeMemory":
+            return "runtime-memory";
         case "Prompt":
             return "prompt";
         case "McpServer":
@@ -303,6 +305,7 @@ function readLangchainAgentConfig(item) {
         "middleware",
         "backend",
         "store",
+        "runtimeMemory",
         "taskDescription",
         "generalPurposeAgent",
         "filesystem",
@@ -310,6 +313,7 @@ function readLangchainAgentConfig(item) {
     return {
         ...readSharedAgentConfig(config),
         ...(typeof config.store === "object" && config.store ? { store: config.store } : {}),
+        ...(typeof config.runtimeMemory === "object" && config.runtimeMemory ? { runtimeMemory: config.runtimeMemory } : {}),
         ...(typeof config.taskDescription === "string" && config.taskDescription.trim() ? { taskDescription: config.taskDescription } : {}),
         ...(typeof config.generalPurposeAgent === "boolean" ? { generalPurposeAgent: config.generalPurposeAgent } : {}),
         ...(passthrough ? { passthrough } : {}),
@@ -329,6 +333,7 @@ function readDeepAgentConfig(item) {
         "middleware",
         "backend",
         "store",
+        "runtimeMemory",
         "taskDescription",
         "generalPurposeAgent",
         "filesystem",
@@ -337,6 +342,7 @@ function readDeepAgentConfig(item) {
         ...readSharedAgentConfig(config),
         ...(typeof config.backend === "object" && config.backend ? { backend: config.backend } : {}),
         ...(typeof config.store === "object" && config.store ? { store: config.store } : {}),
+        ...(typeof config.runtimeMemory === "object" && config.runtimeMemory ? { runtimeMemory: config.runtimeMemory } : {}),
         ...(typeof config.taskDescription === "string" && config.taskDescription.trim() ? { taskDescription: config.taskDescription } : {}),
         ...(typeof config.generalPurposeAgent === "boolean" ? { generalPurposeAgent: config.generalPurposeAgent } : {}),
         ...(passthrough ? { passthrough } : {}),

package/dist/workspace/support/index.d.ts

@@ -1,2 +1,2 @@
 export { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./source-collectors.js";
-export { compileAgentMemories, getRuntimeDefaults, getWorkspaceObject, resolvePathList, resolvePromptValue, resolveRefId, } from "./workspace-ref-utils.js";
+export { compileAgentMemories, getRuntimeDefaults, getRuntimeMemoryDefaults, getWorkspaceObject, resolvePathList, resolvePromptValue, resolveRefId, } from "./workspace-ref-utils.js";

package/dist/workspace/support/index.js

@@ -1,2 +1,2 @@
 export { collectAgentDiscoverySourceRefs, collectToolSourceRefs } from "./source-collectors.js";
-export { compileAgentMemories, getRuntimeDefaults, getWorkspaceObject, resolvePathList, resolvePromptValue, resolveRefId, } from "./workspace-ref-utils.js";
+export { compileAgentMemories, getRuntimeDefaults, getRuntimeMemoryDefaults, getWorkspaceObject, resolvePathList, resolvePromptValue, resolveRefId, } from "./workspace-ref-utils.js";

package/dist/workspace/support/workspace-ref-utils.d.ts

@@ -22,6 +22,7 @@ export type ConcurrencyConfig = {
 };
 export declare function getWorkspaceObject(refs: Map<string, WorkspaceObject | ParsedAgentObject>, ref: string | undefined): WorkspaceObject | undefined;
 export declare function getRuntimeDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
+export declare function getRuntimeMemoryDefaults(refs: Map<string, WorkspaceObject | ParsedAgentObject>): Record<string, unknown> | undefined;
 export declare function getRecoveryConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): RecoveryConfig;
 export declare function getConcurrencyConfig(refs: Map<string, WorkspaceObject | ParsedAgentObject>): ConcurrencyConfig;
 export declare function getRoutingSystemPrompt(refs: Map<string, WorkspaceObject | ParsedAgentObject>): string | undefined;

package/dist/workspace/support/workspace-ref-utils.js

@@ -25,6 +25,16 @@ export function getRuntimeDefaults(refs) {
     }
     return runtimes[0].value;
 }
+export function getRuntimeMemoryDefaults(refs) {
+    const runtimeMemories = Array.from(refs.values()).filter((object) => !("executionMode" in object) && object.kind === "runtime-memory");
+    if (runtimeMemories.length === 0) {
+        return undefined;
+    }
+    if (runtimeMemories.length > 1) {
+        throw new Error(`Expected at most one RuntimeMemory object, found ${runtimeMemories.length}`);
+    }
+    return runtimeMemories[0].value;
+}
 export function getRecoveryConfig(refs) {
     const runtimeDefaults = getRuntimeDefaults(refs);
     const recovery = typeof runtimeDefaults?.recovery === "object" && runtimeDefaults.recovery
@@ -169,7 +179,7 @@ export function resolveRefId(ref) {
     if (rest.length === 0) {
         return ref;
     }
-    if (["agent", "embedding-model", "mcp", "model", "object", "prompt", "runtime", "tool", "vector-store"].includes(namespace)) {
+    if (["agent", "embedding-model", "mcp", "model", "object", "prompt", "runtime", "runtime-memory", "tool", "vector-store"].includes(namespace)) {
         return rest.join("/");
     }
     return ref;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.63",
+  "version": "0.0.65",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -53,7 +53,7 @@
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json && cp -R config dist/",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts test/config-secrets.test.ts test/init-command.test.ts",
+    "test": "vitest run test/hello-file.test.ts test/public-api.test.ts test/resource-optional-provider.test.ts test/resource-isolation.test.ts test/stock-research-app-load-harness.test.ts test/stock-research-app-run.test.ts test/stock-research-app-config.test.ts test/release-workflow.test.ts test/release-version.test.ts test/gitignore.test.ts test/package-lock.test.ts test/readme.test.ts test/product-boundary-docs.test.ts test/long-term-memory-docs.test.ts test/docs-site.test.ts test/runtime-adapter-regressions.test.ts test/runtime-capabilities.test.ts test/runtime-recovery.test.ts test/tool-extension-gaps.test.ts test/checkpoint-maintenance.test.ts test/llamaindex-dependency-compat.test.ts test/skill-standard.test.ts test/routing-config.test.ts test/workspace-compat-regressions.test.ts test/upstream-compat-regressions.test.ts test/yaml-format.test.ts test/config-secrets.test.ts test/init-command.test.ts",
     "test:real-providers": "vitest run test/real-provider-harness.test.ts",
     "release:prepare": "npm version patch --no-git-tag-version && node ./scripts/sync-example-version.mjs",
     "release:pack": "npm pack --dry-run",