@botbotgo/agent-harness 0.0.155 → 0.0.156

package/README.md

@@ -118,7 +118,7 @@ That means:
 
 The runtime provides:
 
-- `createAgentHarness(workspaceRoot)`, `run(...)`, `memorize(...)`, `recall(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- `createAgentHarness(workspaceRoot)`, `run(...)`, `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, `removeMemory(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
 - local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
@@ -414,10 +414,13 @@ const recalled = await recall(runtime, {
 });
 ```
 
-Use `memorize(...)` and `recall(...)` when an application needs a stable public runtime memory surface without importing internal `runtime/harness/system/*` modules.
+Use `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, and `removeMemory(...)` when an application needs a stable public runtime memory surface without importing internal `runtime/harness/system/*` modules.
 
 - `memorize(...)` returns stable `MemoryRecord` and `MemoryDecision` results while leaving merge, review, archive, and storage layout runtime-managed
 - `recall(...)` returns ranked `MemoryRecord` items filtered by runtime memory scope and kind
+- `listMemories(...)` returns stable `MemoryRecord` items for inspection and admin workflows, defaulting to `active` records unless status filters are provided
+- `updateMemory(...)` edits one durable memory record by `memoryId` without exposing internal store namespaces
+- `removeMemory(...)` deletes one durable memory record by `memoryId` and rebuilds runtime-managed projections
 - app-specific knowledge taxonomy, review UI, and admin surfaces still belong in the application layer
 
 ### Let The Runtime Route
@@ -467,6 +470,7 @@ The runtime event stream includes:
 
 ```ts
 import {
+  deleteSession,
   getSession,
   getApproval,
   listSessions,
@@ -485,6 +489,10 @@ if (approval) {
     decision: "approve",
   });
 }
+
+if (session && session.currentState === "completed") {
+  await deleteSession(runtime, session.sessionId);
+}
 ```
 
 These methods return runtime-facing records, not raw checkpoint or backend objects.
@@ -548,6 +556,13 @@ Core workspace files:
 - `resources/tools/`
 - `resources/skills/`
 
+Discovery rules:
+
+- every YAML document under `config/**` is discovered recursively; filenames and subfolders are organizational only
+- YAML object semantics come from `kind`, `metadata.name` or `id`, and object content rather than the file path
+- local tools are auto-discovered from `resources/tools/**/*.js|*.mjs|*.cjs` when they export `tool({...})`
+- skills are auto-discovered from `resources/skills/**/SKILL.md`
+
 Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
 Any other local module shape is not supported, and unsupported shapes are rejected at load time.
 
@@ -563,7 +578,7 @@ There are three main configuration layers:
 
 - runtime policy in `config/runtime/workspace.yaml`
 - reusable object catalogs in `config/catalogs/*.yaml`
-- agent assembly in `config/agents/*.yaml`
+- agent assembly in `config/**/*.yaml`
 
 ### Backend Guidance
 
@@ -633,7 +648,7 @@ Use this file for shared bootstrap memory loaded at agent construction time.
 
 Keep stable project context here. Treat it as startup context, not mutable long-term memory.
 
-### `config/catalogs/models.yaml`
+### Models Catalogs In `config/**`
 
 Use named chat-model presets:
 
@@ -649,7 +664,9 @@ spec:
 
 These load as `model/default`.
 
-### `config/catalogs/embedding-models.yaml`
+You can place `kind: Models` catalogs anywhere under `config/`; `config/catalogs/models.yaml` is only the recommended layout.
+
+### Embedding Model Catalogs In `config/**`
 
 Use named embedding-model presets for retrieval-oriented tools.
 
@@ -740,10 +757,12 @@ spec:
 
 `spec[].kind` can be omitted here; catalog entries default to `McpServer`.
 
-### `config/agents/*.yaml`
+### Agents In `config/**`
 
 Agents always use `kind: Agent` plus `spec.backend`.
 
+Agent YAML can live anywhere under `config/`; `config/agents/*.yaml` is the recommended layout, not a loader requirement.
+
 Use two sections:
 
 - `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runRoot`

package/README.zh.md

@@ -118,7 +118,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 运行时提供：
 
-- `createAgentHarness(workspaceRoot)`、`run(...)`、`memorize(...)`、`recall(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
+- `createAgentHarness(workspaceRoot)`、`run(...)`、`memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)`、`removeMemory(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
 - 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
 - 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
 - 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
@@ -386,10 +386,13 @@ const recalled = await recall(runtime, {
 });
 ```
 
-当应用需要稳定的公开 runtime memory 接口，而不想依赖内部 `runtime/harness/system/*` 模块时，使用 `memorize(...)` 与 `recall(...)`。
+当应用需要稳定的公开 runtime memory 接口，而不想依赖内部 `runtime/harness/system/*` 模块时，使用 `memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)` 与 `removeMemory(...)`。
 
 - `memorize(...)` 返回稳定的 `MemoryRecord` 与 `MemoryDecision` 结果，而 merge、review、archive 与存储布局仍由 runtime 内部托管
 - `recall(...)` 返回按相关性排序、并按 scope / kind 过滤后的 `MemoryRecord`
+- `listMemories(...)` 返回稳定的 `MemoryRecord`，用于 inspection / admin 场景；如果不传 status 过滤器，默认只返回 `active`
+- `updateMemory(...)` 通过 `memoryId` 更新单条 durable memory，而不暴露内部 store namespace
+- `removeMemory(...)` 通过 `memoryId` 删除单条 durable memory，并重建运行时托管的 projection
 - 业务知识分类、review UI 与管理后台仍应留在应用层
 
 ### 由运行时路由
@@ -439,6 +442,7 @@ const result = await run(runtime, {
 
 ```ts
 import {
+  deleteSession,
   getApproval,
   getSession,
   listApprovals,
@@ -457,6 +461,10 @@ if (approval) {
     decision: "approve",
   });
 }
+
+if (session && session.currentState === "completed") {
+  await deleteSession(runtime, session.sessionId);
+}
 ```
 
 这些方法返回面向运行时的记录，而非原始 checkpoint 或后端对象。
@@ -520,6 +528,13 @@ await stop(runtime);
 - `resources/tools/`
 - `resources/skills/`
 
+发现规则：
+
+- `config/**` 下的所有 YAML 文档都会被递归发现；文件名与子目录只用于组织，不参与语义
+- YAML 对象语义由 `kind`、`metadata.name` 或 `id` 以及对象内容决定，而不是由文件路径决定
+- 本地工具会从 `resources/tools/**/*.js|*.mjs|*.cjs` 中自动发现，前提是模块导出 `tool({...})`
+- skills 会从 `resources/skills/**/SKILL.md` 自动发现
+
 `resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
 不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
 
@@ -529,7 +544,7 @@ await stop(runtime);
 - agent 再按名字白名单选择 tools 与 skills
 - `config/runtime/workspace.yaml` 中的运行时策略
 - `config/catalogs/*.yaml` 中的可复用对象目录
-- `config/agents/*.yaml` 中的 agent 装配
+- `config/**/*.yaml` 中的 agent 装配
 
 ### Backend 选择建议
 
@@ -602,7 +617,7 @@ spec:
 
 在此放置稳定的项目上下文；视为启动上下文，而非可变长期记忆。
 
-### `config/catalogs/models.yaml`
+### `config/**` 下的 Models Catalog
 
 命名聊天模型预设：
 
@@ -618,7 +633,9 @@ spec:
 
 加载为 `model/default`。
 
-### `config/catalogs/embedding-models.yaml`
+`kind: Models` catalog 可以放在 `config/` 下任意位置；`config/catalogs/models.yaml` 只是推荐布局。
+
+### `config/**` 下的 Embedding Model Catalog
 
 面向检索类工具的命名嵌入模型预设。
 
@@ -707,10 +724,12 @@ spec:
 
 这里可以省略 `spec[].kind`；catalog 项会默认按 `McpServer` 处理。
 
-### `config/agents/*.yaml`
+### `config/**` 下的 Agent YAML
 
 Agent 始终使用 `kind: Agent` 以及 `spec.backend`。
 
+Agent YAML 可以放在 `config/` 下任意位置；`config/agents/*.yaml` 是推荐布局，不是 loader 的硬性要求。
+
 两个区块：
 
 - `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runRoot`

package/dist/api.d.ts

@@ -1,11 +1,11 @@
-import type { CancelOptions, InvocationEnvelope, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { CancelOptions, InvocationEnvelope, ListMemoriesInput, ListMemoriesResult, MemoryRecord, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RemoveMemoryInput, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, UpdateMemoryInput, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
-export type { MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, } from "./contracts/types.js";
+export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, UpdateMemoryInput, } from "./contracts/types.js";
 type PublicApprovalRecord = {
     approvalId: string;
     pendingActionId: string;
@@ -57,6 +57,9 @@ export declare function normalizeUserChatInput(input: UserChatInput, options?: N
 export declare function run(runtime: AgentHarnessRuntime, options: PublicRunOptions): Promise<PublicRunResult>;
 export declare function memorize(runtime: AgentHarnessRuntime, input: MemorizeInput): Promise<MemorizeResult>;
 export declare function recall(runtime: AgentHarnessRuntime, input: RecallInput): Promise<RecallResult>;
+export declare function listMemories(runtime: AgentHarnessRuntime, input?: ListMemoriesInput): Promise<ListMemoriesResult>;
+export declare function updateMemory(runtime: AgentHarnessRuntime, input: UpdateMemoryInput): Promise<MemoryRecord>;
+export declare function removeMemory(runtime: AgentHarnessRuntime, input: RemoveMemoryInput): Promise<MemoryRecord>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listSessions(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<SessionSummary[]>;
 export declare function listRequests(runtime: AgentHarnessRuntime, filter?: {

package/dist/api.js

@@ -134,6 +134,15 @@ export async function memorize(runtime, input) {
 export async function recall(runtime, input) {
     return runtime.recall(input);
 }
+export async function listMemories(runtime, input = {}) {
+    return runtime.listMemories(input);
+}
+export async function updateMemory(runtime, input) {
+    return runtime.updateMemory(input);
+}
+export async function removeMemory(runtime, input) {
+    return runtime.removeMemory(input);
+}
 export function subscribe(runtime, listener) {
     return runtime.subscribe(listener);
 }

package/dist/contracts/runtime.d.ts

@@ -195,6 +195,37 @@ export type RecallInput = {
 export type RecallResult = {
     items: MemoryRecord[];
 };
+export type ListMemoriesInput = {
+    scopes?: MemoryScope[];
+    kinds?: MemoryKind[];
+    status?: MemoryRecordStatus[];
+    threadId?: string;
+    agentId?: string;
+    workspaceId?: string;
+    userId?: string;
+    projectId?: string;
+    limit?: number;
+};
+export type ListMemoriesResult = {
+    items: MemoryRecord[];
+};
+export type UpdateMemoryInput = {
+    memoryId: string;
+    content?: string;
+    summary?: string;
+    status?: MemoryRecordStatus;
+    confidence?: number;
+    expiresAt?: string | null;
+    sourceType?: string;
+    sourceRefs?: string[];
+    tags?: string[];
+    observedAt?: string;
+    lastConfirmedAt?: string;
+    provenance?: Record<string, unknown>;
+};
+export type RemoveMemoryInput = {
+    memoryId: string;
+};
 /**
  * Operator-facing projection of tool execution policy already compiled into a binding.
  * This summarizes existing timeout, retry, validation, and retry-safety hints without

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
-export type { MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, UserChatInput, UserChatMessage, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.154";
+export declare const AGENT_HARNESS_VERSION = "0.0.155";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.154";
+export const AGENT_HARNESS_VERSION = "0.0.155";

package/dist/runtime/harness/system/runtime-memory-records.d.ts

@@ -15,6 +15,9 @@ export declare function renderMemoryRecordsMarkdown(title: string, records: Memo
 export declare function rebuildStructuredMemoryProjections(store: StoreLike, namespace: string[], title: string, scope: MemoryScope, maxEntries: number): Promise<void>;
 export declare function listMemoryRecordsForScopes(store: StoreLike, scopes: MemoryScope[]): Promise<MemoryRecord[]>;
 export declare function getMemoryRecord(store: StoreLike, scope: MemoryScope, recordId: string): Promise<MemoryRecord | null>;
+export declare function findMemoryRecordById(store: StoreLike, recordId: string): Promise<MemoryRecord | null>;
+export declare function updateMemoryRecord(store: StoreLike, record: MemoryRecord, updatedAt: string): Promise<MemoryRecord>;
+export declare function removeMemoryRecord(store: StoreLike, scope: MemoryScope, recordId: string): Promise<MemoryRecord | null>;
 export declare function persistStructuredMemoryRecords(options: PersistMemoryRecordsOptions): Promise<{
     records: MemoryRecord[];
     decisions: MemoryDecision[];

package/dist/runtime/harness/system/runtime-memory-records.js

@@ -34,6 +34,12 @@ function createCanonicalKey(candidate, kind, scope) {
 function buildScopeNamespace(scope) {
     return ["memories", "records", scope];
 }
+function buildCanonicalIndexNamespace(scope) {
+    return ["memories", "indexes", "canonical", scope];
+}
+function buildSourceRefIndexNamespace(scope) {
+    return ["memories", "indexes", "source-ref", scope];
+}
 function normalizeTextForCompare(value) {
     return value.toLowerCase().replace(/\s+/g, " ").trim();
 }
@@ -312,7 +318,7 @@ function evaluateDecision(existing, incoming, recordedAt) {
 async function putRecordWithIndexes(store, record, updatedAt) {
     const canonicalKeyId = createFingerprint(record.canonicalKey);
     await store.put(buildScopeNamespace(record.scope), `${record.id}.json`, record);
-    await store.put(["memories", "indexes", "canonical", record.scope], `${canonicalKeyId}-${record.id}.json`, {
+    await store.put(buildCanonicalIndexNamespace(record.scope), `${canonicalKeyId}-${record.id}.json`, {
         canonicalKey: record.canonicalKey,
         recordId: record.id,
         scope: record.scope,
@@ -321,7 +327,7 @@ async function putRecordWithIndexes(store, record, updatedAt) {
     });
     await Promise.all(record.sourceRefs.map((sourceRef) => {
         const sourceRefId = createFingerprint(sourceRef);
-        return store.put(["memories", "indexes", "source-ref", record.scope], `${sourceRefId}-${record.id}.json`, {
+        return store.put(buildSourceRefIndexNamespace(record.scope), `${sourceRefId}-${record.id}.json`, {
             sourceRef,
             recordId: record.id,
             scope: record.scope,
@@ -384,6 +390,46 @@ export async function getMemoryRecord(store, scope, recordId) {
     const candidate = record;
     return typeof candidate.id === "string" && typeof candidate.content === "string" ? candidate : null;
 }
+export async function findMemoryRecordById(store, recordId) {
+    for (const scope of MEMORY_SCOPES) {
+        const record = await getMemoryRecord(store, scope, recordId);
+        if (record) {
+            return record;
+        }
+    }
+    return null;
+}
+async function deleteRecordIndexes(store, record) {
+    const [canonicalEntries, sourceRefEntries] = await Promise.all([
+        store.search(buildCanonicalIndexNamespace(record.scope)),
+        store.search(buildSourceRefIndexNamespace(record.scope)),
+    ]);
+    await Promise.all([
+        ...canonicalEntries
+            .filter((entry) => entry.value?.recordId === record.id)
+            .map((entry) => store.delete(entry.namespace, entry.key)),
+        ...sourceRefEntries
+            .filter((entry) => entry.value?.recordId === record.id)
+            .map((entry) => store.delete(entry.namespace, entry.key)),
+    ]);
+}
+export async function updateMemoryRecord(store, record, updatedAt) {
+    const existing = await getMemoryRecord(store, record.scope, record.id);
+    if (existing) {
+        await deleteRecordIndexes(store, existing);
+    }
+    await putRecordWithIndexes(store, record, updatedAt);
+    return record;
+}
+export async function removeMemoryRecord(store, scope, recordId) {
+    const existing = await getMemoryRecord(store, scope, recordId);
+    if (!existing) {
+        return null;
+    }
+    await deleteRecordIndexes(store, existing);
+    await store.delete(buildScopeNamespace(scope), `${recordId}.json`);
+    return existing;
+}
 export async function persistStructuredMemoryRecords(options) {
     const existingRecords = await listStoredRecords(options.store);
     const persistedRecords = [];

package/dist/runtime/harness.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, CancelOptions, HarnessEvent, HarnessStreamItem, RuntimeHealthSnapshot, MessageContent, RunRecord, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, RunSummary, MemorizeInput, MemorizeResult, RecallInput, RecallResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
+import type { ApprovalRecord, CancelOptions, HarnessEvent, HarnessStreamItem, RuntimeHealthSnapshot, ListMemoriesInput, ListMemoriesResult, MessageContent, RemoveMemoryInput, RunRecord, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, RunSummary, MemoryRecord, MemorizeInput, MemorizeResult, RecallInput, RecallResult, UpdateMemoryInput, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
 import { type ToolMcpServerOptions } from "../mcp.js";
 import { type InventoryAgentRecord, type InventorySkillRecord } from "./harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./harness/system/skill-requirements.js";
@@ -70,6 +70,9 @@ export declare class AgentHarnessRuntime {
     }): Promise<RunSummary[]>;
     memorize(input: MemorizeInput): Promise<MemorizeResult>;
     recall(input: RecallInput): Promise<RecallResult>;
+    listMemories(input?: ListMemoriesInput): Promise<ListMemoriesResult>;
+    updateMemory(input: UpdateMemoryInput): Promise<MemoryRecord>;
+    removeMemory(input: RemoveMemoryInput): Promise<MemoryRecord>;
     getRun(runId: string): Promise<RunRecord | null>;
     private getSession;
     getThread(threadId: string): Promise<ThreadRecord | null>;
@@ -102,6 +105,8 @@ export declare class AgentHarnessRuntime {
     private invokeWithHistory;
     private resolveMemoryNamespace;
     private getWorkspaceId;
+    private summarizeMemoryContent;
+    private matchesMemoryFilters;
     private resolveRecallScopes;
     private matchesRecallScope;
     private getMemoryScopeBoost;
@@ -113,6 +118,7 @@ export declare class AgentHarnessRuntime {
     private createMem0MemoryRecord;
     private rankRecallCandidates;
     private rebuildRuntimeMemoryVectorIndex;
+    private refreshStructuredMemoryScope;
     private buildRuntimeMemoryContext;
     private persistRuntimeMemoryCandidates;
     private persistStructuredMemoryCandidates;

package/dist/runtime/harness.js

@@ -31,7 +31,7 @@ import { createDefaultHealthSnapshot, isInventoryEnabled, isThreadMemorySyncEnab
 import { Mem0IngestionSync, Mem0SemanticRecall, readMem0RuntimeConfig, } from "./harness/system/mem0-ingestion-sync.js";
 import { createRuntimeMemoryManager, RuntimeMemoryFormationSync, readRuntimeMemoryFormationConfig, } from "./harness/system/runtime-memory-manager.js";
 import { renderMemoryCandidatesMarkdown } from "./harness/system/runtime-memory-candidates.js";
-import { getMemoryRecord, listMemoryRecordsForScopes, persistStructuredMemoryRecords, } from "./harness/system/runtime-memory-records.js";
+import { findMemoryRecordById, getMemoryRecord, listMemoryRecordsForScopes, persistStructuredMemoryRecords, removeMemoryRecord, updateMemoryRecord, } from "./harness/system/runtime-memory-records.js";
 import { consolidateStructuredMemoryScope } from "./harness/system/runtime-memory-consolidation.js";
 import { normalizeLangMemMemoryKind, readRuntimeMemoryMaintenanceConfig, readRuntimeMemoryPolicyConfig, resolveMemoryNamespace, scoreMemoryText, } from "./harness/system/runtime-memory-policy.js";
 import { resolveRuntimeAdapterOptions } from "./support/runtime-adapter-options.js";
@@ -361,6 +361,98 @@ export class AgentHarnessRuntime {
             .map(({ record }) => record);
         return { items };
     }
+    async listMemories(input = {}) {
+        const binding = this.defaultRuntimeEntryBinding;
+        if (!binding) {
+            throw new Error("listMemories requires a runtime entry binding.");
+        }
+        const workspaceId = this.getWorkspaceId(binding);
+        const scopes = Array.isArray(input.scopes) && input.scopes.length > 0
+            ? Array.from(new Set(input.scopes))
+            : ["thread", "agent", "workspace", "user", "project"];
+        const kinds = input.kinds?.length ? new Set(input.kinds) : null;
+        const statuses = input.status?.length ? new Set(input.status) : new Set(["active"]);
+        const limit = typeof input.limit === "number" && Number.isInteger(input.limit) && input.limit > 0
+            ? input.limit
+            : Number.POSITIVE_INFINITY;
+        const items = (await listMemoryRecordsForScopes(this.runtimeMemoryStore, scopes))
+            .filter((record) => statuses.has(record.status))
+            .filter((record) => !kinds || kinds.has(record.kind))
+            .filter((record) => this.matchesMemoryFilters(record, {
+            threadId: input.threadId,
+            agentId: input.agentId,
+            workspaceId: input.workspaceId ?? workspaceId,
+            userId: input.userId,
+            projectId: input.projectId,
+        }))
+            .sort((left, right) => right.lastConfirmedAt.localeCompare(left.lastConfirmedAt))
+            .slice(0, limit);
+        return { items };
+    }
+    async updateMemory(input) {
+        const binding = this.defaultRuntimeEntryBinding;
+        if (!binding) {
+            throw new Error("updateMemory requires a runtime entry binding.");
+        }
+        if (typeof input.memoryId !== "string" || input.memoryId.trim().length === 0) {
+            throw new Error("updateMemory requires a non-empty memoryId.");
+        }
+        const existing = await findMemoryRecordById(this.runtimeMemoryStore, input.memoryId.trim());
+        if (!existing) {
+            throw new Error(`Memory record not found: ${input.memoryId}`);
+        }
+        const updatedAt = new Date().toISOString();
+        const nextContent = typeof input.content === "string"
+            ? input.content.trim()
+            : existing.content;
+        if (nextContent.length === 0) {
+            throw new Error("updateMemory requires content to remain non-empty.");
+        }
+        const next = {
+            ...existing,
+            content: nextContent,
+            summary: typeof input.summary === "string"
+                ? input.summary.trim() || this.summarizeMemoryContent(nextContent)
+                : (typeof input.content === "string" ? this.summarizeMemoryContent(nextContent) : existing.summary),
+            status: input.status ?? existing.status,
+            confidence: typeof input.confidence === "number" ? Math.max(0, Math.min(1, input.confidence)) : existing.confidence,
+            expiresAt: input.expiresAt === undefined ? existing.expiresAt : (input.expiresAt ?? undefined),
+            sourceType: typeof input.sourceType === "string" && input.sourceType.trim().length > 0 ? input.sourceType.trim() : existing.sourceType,
+            sourceRefs: Array.isArray(input.sourceRefs)
+                ? Array.from(new Set(input.sourceRefs.map((item) => item.trim()).filter((item) => item.length > 0)))
+                : existing.sourceRefs,
+            tags: Array.isArray(input.tags)
+                ? Array.from(new Set(input.tags.map((item) => item.trim()).filter((item) => item.length > 0)))
+                : existing.tags,
+            observedAt: typeof input.observedAt === "string" && input.observedAt.trim().length > 0 ? input.observedAt : existing.observedAt,
+            lastConfirmedAt: typeof input.lastConfirmedAt === "string" && input.lastConfirmedAt.trim().length > 0
+                ? input.lastConfirmedAt
+                : updatedAt,
+            provenance: input.provenance ? { ...existing.provenance, ...input.provenance } : existing.provenance,
+            revision: existing.revision + 1,
+        };
+        await updateMemoryRecord(this.runtimeMemoryStore, next, updatedAt);
+        await this.rebuildRuntimeMemoryVectorIndex();
+        await this.refreshStructuredMemoryScope(binding, next);
+        return next;
+    }
+    async removeMemory(input) {
+        const binding = this.defaultRuntimeEntryBinding;
+        if (!binding) {
+            throw new Error("removeMemory requires a runtime entry binding.");
+        }
+        if (typeof input.memoryId !== "string" || input.memoryId.trim().length === 0) {
+            throw new Error("removeMemory requires a non-empty memoryId.");
+        }
+        const existing = await findMemoryRecordById(this.runtimeMemoryStore, input.memoryId.trim());
+        if (!existing) {
+            throw new Error(`Memory record not found: ${input.memoryId}`);
+        }
+        await removeMemoryRecord(this.runtimeMemoryStore, existing.scope, existing.id);
+        await this.rebuildRuntimeMemoryVectorIndex();
+        await this.refreshStructuredMemoryScope(binding, existing);
+        return existing;
+    }
     async getRun(runId) {
         return this.persistence.getRun(runId);
     }
@@ -514,7 +606,7 @@ export class AgentHarnessRuntime {
         const template = this.runtimeMemoryPolicy?.namespaces[scope] ?? `memories/${scope}s/{${scope}Id}`;
         return resolveMemoryNamespace(template, {
             threadId: options.threadId,
-            agentId: binding.agent.id,
+            agentId: options.agentId ?? binding.agent.id,
             workspaceId,
             userId: options.userId ?? "default",
             projectId: options.projectId ?? workspaceId,
@@ -524,6 +616,27 @@ export class AgentHarnessRuntime {
         const workspaceRoot = binding.harnessRuntime.workspaceRoot ?? this.workspace.workspaceRoot;
         return path.basename(workspaceRoot) || "default";
     }
+    summarizeMemoryContent(content) {
+        return (content.trim().split("\n")[0] || content.trim()).slice(0, 240);
+    }
+    matchesMemoryFilters(record, filters) {
+        if (filters.threadId && record.provenance.threadId !== filters.threadId) {
+            return false;
+        }
+        if (filters.agentId && record.provenance.agentId !== filters.agentId) {
+            return false;
+        }
+        if (filters.workspaceId && record.provenance.workspaceId !== filters.workspaceId) {
+            return false;
+        }
+        if (filters.userId && record.provenance.userId !== filters.userId) {
+            return false;
+        }
+        if (filters.projectId && record.provenance.projectId !== filters.projectId) {
+            return false;
+        }
+        return true;
+    }
     resolveRecallScopes(input) {
         if (Array.isArray(input.scopes) && input.scopes.length > 0) {
             return Array.from(new Set(input.scopes));
@@ -755,6 +868,30 @@ export class AgentHarnessRuntime {
             // Fail open: vector indexing must not break durable memory writes.
         }
     }
+    async refreshStructuredMemoryScope(binding, record) {
+        const provenance = record.provenance;
+        const maxEntries = record.scope === "thread" ? 12 : 20;
+        const titleByScope = {
+            thread: "Thread Structured Memory",
+            agent: "Agent Structured Memory",
+            workspace: "Workspace Structured Memory",
+            user: "User Structured Memory",
+            project: "Project Structured Memory",
+        };
+        await consolidateStructuredMemoryScope({
+            store: this.runtimeMemoryStore,
+            namespace: this.resolveMemoryNamespace(record.scope, binding, {
+                threadId: provenance.threadId,
+                agentId: provenance.agentId,
+                userId: provenance.userId,
+                projectId: provenance.projectId,
+            }),
+            title: titleByScope[record.scope],
+            scope: record.scope,
+            maxEntries,
+            config: this.runtimeMemoryMaintenanceConfig ?? undefined,
+        });
+    }
     async buildRuntimeMemoryContext(binding, threadId, input) {
         const query = typeof input === "string" ? input : JSON.stringify(input ?? "");
         const workspaceId = this.getWorkspaceId(binding);

package/dist/workspace/object-loader.js

@@ -6,7 +6,7 @@ import { resolveIsolatedResourceModulePath } from "../resource/isolation.js";
 import { isExternalSourceLocator, resolveResourcePackageRoot } from "../resource/sources.js";
 import { discoverToolModuleDefinitions, isSupportedToolModulePath } from "../tool-modules.js";
 import { fileExists } from "../utils/fs.js";
-import { readNamedModelItems, readNamedYamlItems, readYamlItems, } from "./yaml-object-reader.js";
+import { readNamedYamlItems, readYamlItems, } from "./yaml-object-reader.js";
 export { normalizeYamlItem, readYamlItems } from "./yaml-object-reader.js";
 const CONVENTIONAL_OBJECT_DIRECTORIES = ["tools"];
 const MODULE_AGENT_FILENAMES = ["agent.yaml", "agent.yml"];
@@ -39,16 +39,10 @@ function conventionalConfigRoot(root) {
 }
 function conventionalDirectoryRoots(root, relativeDir) {
     const resourceRoot = resolveResourcePackageRoot(root);
-    const configRoot = conventionalConfigRoot(root);
-    const candidates = relativeDir === "agents"
-        ? [
-            ...(configRoot ? [path.join(configRoot, "agents")] : []),
-            path.join(root, "agents"),
-        ]
-        : [
-            ...(resourceRoot ? [path.join(resourceRoot, relativeDir)] : []),
-            path.join(root, relativeDir),
-        ];
+    const candidates = [
+        ...(resourceRoot ? [path.join(resourceRoot, relativeDir)] : []),
+        path.join(root, relativeDir),
+    ];
     return Array.from(new Set(candidates));
 }
 export function conventionalPackageRoots(root, relativeDir) {
@@ -569,20 +563,6 @@ function mergeAgentRecord(records, item, sourcePath) {
 function mergeWorkspaceObjectRecord(records, workspaceObject, item, sourcePath) {
     mergeRawItemRecord(records, `${workspaceObject.kind}/${workspaceObject.id}`, item, sourcePath);
 }
-async function loadNamedModelsForRoot(configRoot, mergedObjects) {
-    for (const { item, sourcePath } of await readNamedModelItems(configRoot)) {
-        const workspaceObject = parseWorkspaceObject(item, sourcePath);
-        if (!workspaceObject || workspaceObject.kind !== "model") {
-            continue;
-        }
-        mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
-    }
-}
-async function loadConfigAgentsForRoot(configRoot, mergedAgents) {
-    for (const { item, sourcePath } of await readConfigAgentItems(configRoot)) {
-        mergeAgentRecord(mergedAgents, item, sourcePath);
-    }
-}
 async function loadModuleAgentsForRoot(root, mergedAgents) {
     const modulesRoot = moduleCollectionRoot(root, "agents");
     if (!(await fileExists(modulesRoot))) {
@@ -675,7 +655,7 @@ async function loadModuleObjectsForRoot(root, mergedObjects) {
         mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
     }
 }
-async function loadConfigObjectsForRoot(root, configRoot, mergedObjects) {
+async function loadConfigYamlForRoot(root, configRoot, mergedAgents, mergedObjects) {
     if (!conventionalConfigRoot(root)) {
         return;
     }
@@ -684,7 +664,8 @@ async function loadConfigObjectsForRoot(root, configRoot, mergedObjects) {
         if (!workspaceObject) {
             continue;
         }
-        if (isAgentKind(workspaceObject.kind) || workspaceObject.kind === "model") {
+        if (isAgentKind(workspaceObject.kind)) {
+            mergeAgentRecord(mergedAgents, item, sourcePath);
             continue;
         }
         mergeWorkspaceObjectRecord(mergedObjects, workspaceObject, item, sourcePath);
@@ -708,20 +689,6 @@ async function loadRootObjects(root, mergedObjects) {
 function isAgentKind(kind) {
     return kind === "agent";
 }
-async function readConfigAgentItems(configRoot) {
-    const records = await readYamlItems(configRoot, undefined, { recursive: true });
-    return records.filter(({ item, sourcePath }) => {
-        const kind = typeof item.kind === "string" ? item.kind : undefined;
-        if (!isAgentKind(kind)) {
-            return false;
-        }
-        const relativePath = path.relative(configRoot, sourcePath);
-        if (!relativePath || relativePath.startsWith("..")) {
-            return false;
-        }
-        return !relativePath.includes(path.sep) || relativePath.startsWith(`agents${path.sep}`);
-    });
-}
 export async function readToolModuleItems(root) {
     if (!(await fileExists(root))) {
         return [];
@@ -792,11 +759,9 @@ export async function loadWorkspaceObjects(workspaceRoot, options = {}) {
     const roots = [frameworkWorkspaceRoot(), ...(options.overlayRoots ?? []), workspaceRoot];
     for (const root of roots) {
         const configRoot = conventionalConfigRoot(root) ?? root;
-        await loadNamedModelsForRoot(configRoot, mergedObjects);
-        await loadConfigAgentsForRoot(configRoot, mergedAgents);
+        await loadConfigYamlForRoot(root, configRoot, mergedAgents, mergedObjects);
         await loadModuleAgentsForRoot(root, mergedAgents);
         await loadConventionalObjectsForRoot(root, mergedObjects);
-        await loadConfigObjectsForRoot(root, configRoot, mergedObjects);
         await loadModuleObjectsForRoot(root, mergedObjects);
         await loadRootObjects(root, mergedObjects);
     }

package/dist/workspace/yaml-object-reader.d.ts

@@ -9,7 +9,3 @@ export declare function readNamedYamlItems(root: string, filenames: string[]): P
     item: Record<string, unknown>;
     sourcePath: string;
 }>>;
-export declare function readNamedModelItems(root: string): Promise<Array<{
-    item: Record<string, unknown>;
-    sourcePath: string;
-}>>;

package/dist/workspace/yaml-object-reader.js

@@ -2,7 +2,6 @@ import path from "node:path";
 import { readdir } from "node:fs/promises";
 import { parseAllDocuments } from "yaml";
 import { fileExists, listFilesRecursive, readYamlOrJson } from "../utils/fs.js";
-const MODEL_FILENAMES = ["models.yaml", "models.yml"];
 const ENV_PLACEHOLDER_PATTERN = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g;
 function asObject(value) {
     return typeof value === "object" && value ? value : undefined;
@@ -165,7 +164,10 @@ export async function readYamlItems(root, relativeDir, options = {}) {
         return [];
     }
     const files = options.recursive
-        ? await listFilesRecursive(targetRoot, ".yaml")
+        ? Array.from(new Set([
+            ...(await listFilesRecursive(targetRoot, ".yaml")),
+            ...(await listFilesRecursive(targetRoot, ".yml")),
+        ])).sort()
         : (await readdir(targetRoot, { withFileTypes: true }))
             .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name))
             .map((entry) => path.join(targetRoot, entry.name))
@@ -199,33 +201,3 @@ export async function readNamedYamlItems(root, filenames) {
     }
     return records;
 }
-export async function readNamedModelItems(root) {
-    const filePaths = new Set();
-    for (const filename of MODEL_FILENAMES) {
-        const directPath = path.join(root, filename);
-        if (await fileExists(directPath)) {
-            filePaths.add(directPath);
-        }
-    }
-    for (const extension of [".yaml", ".yml"]) {
-        for (const filePath of await listFilesRecursive(root, extension)) {
-            if (MODEL_FILENAMES.includes(path.basename(filePath))) {
-                filePaths.add(filePath);
-            }
-        }
-    }
-    const records = [];
-    for (const filePath of [...filePaths].sort()) {
-        const parsedDocuments = parseAllDocuments(await readYamlOrJson(filePath));
-        for (const parsedDocument of parsedDocuments) {
-            const resolvedDocument = interpolateEnvPlaceholders(parsedDocument.toJSON(), filePath);
-            for (const item of await objectItemsFromDocument(resolvedDocument, filePath)) {
-                const normalized = normalizeYamlItem(item);
-                if (normalized.kind === "model" && typeof normalized.id === "string" && normalized.id.trim()) {
-                    records.push({ item: normalized, sourcePath: filePath });
-                }
-            }
-        }
-    }
-    return records;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.155",
+  "version": "0.0.156",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",