@poncho-ai/harness 0.59.11 → 0.59.13

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.11 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.59.13 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -9,8 +9,8 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            560.62 KB
-ESM ⚡️ Build success in 239ms
+ESM dist/index.js            561.36 KB
+ESM ⚡️ Build success in 214ms
 DTS Build start
-DTS ⚡️ Build success in 7569ms
-DTS dist/index.d.ts 102.06 KB
+DTS ⚡️ Build success in 8568ms
+DTS dist/index.d.ts 102.50 KB

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @poncho-ai/harness
 
+## 0.59.13
+
+### Patch Changes
+
+- [`bf77523`](https://github.com/cesr/poncho-ai/commit/bf775237af883a53ee90f0a620434a1929ac82ea) Thanks [@cesr](https://github.com/cesr)! - `memory_main_edit` now treats an empty `old_str` as append: `new_str` is
+  appended to the end of memory (separated by a blank line when memory is
+  non-empty). This also handles the first-ever write into empty memory, so
+  `memory_main_edit` alone can bootstrap, add new facts, and edit existing
+  text — consumers that want to drop `memory_main_write` from the tool
+  surface no longer lose the ability to seed empty memory.
+
+  Both `memory_main_edit` and `memory_main_write` now return a minimal
+  `{ ok: true, bytes }` result instead of echoing the entire memory
+  document back as the tool result, which kept re-injecting the whole
+  document into the conversation on every targeted edit.
+
+## 0.59.12
+
+### Patch Changes
+
+- [`4dc94a7`](https://github.com/cesr/poncho-ai/commit/4dc94a7d7d1d411baa9ca4ac1e98053d6d2e66c3) Thanks [@cesr](https://github.com/cesr)! - `defaultAgentDefinition()` accepts an optional `tagline` to override the
+  opening line's descriptor ("You are **{name}**, {tagline}."). Default is
+  unchanged ("a helpful assistant built with Poncho"). Lets SDK consumers
+  shipping a differently-branded product keep the framework name out of the
+  agent's system prompt.
+
 ## 0.59.11
 
 ### Patch Changes

package/dist/index.d.ts

@@ -853,9 +853,18 @@ interface DefaultAgentDefinitionOptions {
     maxSteps?: number;
     /** Hard timeout in seconds. Default: 300. */
     timeout?: number;
+    /**
+     * The descriptor that follows the name in the opening line
+     * ("You are **{name}**, {tagline}."). Default:
+     * "a helpful assistant built with Poncho". SDK consumers shipping a
+     * differently-branded product can override this so the framework name
+     * does not leak into the agent's system prompt.
+     */
+    tagline?: string;
 }
 declare const DEFAULT_AGENT_NAME = "agent";
 declare const DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+declare const DEFAULT_TAGLINE = "a helpful assistant built with Poncho";
 declare const DEFAULT_MODEL_PROVIDER: "anthropic";
 declare const DEFAULT_MODEL_NAME = "claude-opus-4-5";
 declare const DEFAULT_TEMPERATURE = 0.2;
@@ -2383,4 +2392,4 @@ type NewEntryNoId = NewConversationEntry extends infer T ? T extends NewConversa
  */
 declare const appendEntriesSafe: (store: ConversationStore, conversation: Pick<Conversation, "conversationId" | "ownerId" | "tenantId">, entries: NewEntryNoId[], log: Logger) => Promise<ConversationEntry[]>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -670,6 +670,7 @@ var loadPonchoConfig = async (workingDir) => {
 import { randomBytes } from "crypto";
 var DEFAULT_AGENT_NAME = "agent";
 var DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+var DEFAULT_TAGLINE = "a helpful assistant built with Poncho";
 var DEFAULT_MODEL_PROVIDER = "anthropic";
 var DEFAULT_MODEL_NAME = "claude-opus-4-5";
 var DEFAULT_TEMPERATURE = 0.2;
@@ -685,6 +686,7 @@ var defaultAgentDefinition = (opts = {}) => {
   temperature: ${opts.temperature}` : "";
   const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
   const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+  const tagline = opts.tagline ?? DEFAULT_TAGLINE;
   return `---
 name: ${name}
 id: ${id}
@@ -699,7 +701,7 @@ limits:
 
 # {{name}}
 
-You are **{{name}}**, a helpful assistant built with Poncho.
+You are **{{name}}**, ${tagline}.
 
 Working directory: {{runtime.workingDir}}
 Environment: {{runtime.environment}}
@@ -1640,7 +1642,7 @@ When \`memory.enabled\` is true in \`poncho.config.js\`, the harness enables a s
 
 - A single persistent main memory document is loaded at run start and interpolated into the system prompt under \`## Persistent Memory\`.
 - \`memory_main_write\` overwrites the entire memory document (for initial writes or full rewrites).
-- \`memory_main_edit\` performs targeted string-replacement edits on memory (find \`old_str\`, replace with \`new_str\`), mirroring \`edit_file\` semantics. The tool description instructs the model to proactively evaluate each turn whether durable memory should be updated.
+- \`memory_main_edit\` performs targeted string-replacement edits on memory (find \`old_str\`, replace with \`new_str\`), mirroring \`edit_file\` semantics. An empty \`old_str\` appends \`new_str\` to the end of memory, which also handles the first-ever write into empty memory. The tool description instructs the model to proactively evaluate each turn whether durable memory should be updated.
 - \`conversation_recall\` can search, browse, and fetch past conversations. It supports keyword search (scoring by relevance), date-range filtering (\`after\`/\`before\`), and fetching a specific conversation's full message history by ID.
 
 \`\`\`javascript
@@ -5968,22 +5970,22 @@ var createMemoryTools = (store, options) => {
           throw new Error("content is required");
         }
         const memory = await resolveStore(context).updateMainMemory({ content });
-        return { ok: true, memory };
+        return { ok: true, bytes: memory.content.length };
       }
     }),
     defineTool6({
       name: "memory_main_edit",
-      description: "Edit persistent main memory by replacing an exact string match with new content. The old_str must match exactly one location in memory. Use an empty new_str to delete matched content. Proactively evaluate every turn whether memory should be updated.",
+      description: "Edit persistent main memory. With a non-empty old_str, replace that exact string (which must match exactly one location) with new_str; use an empty new_str to delete the matched content. With an empty old_str, append new_str to the end of memory \u2014 use this to add a brand-new fact or to write the first fact when memory is still empty. Proactively evaluate every turn whether memory should be updated.",
       inputSchema: {
         type: "object",
         properties: {
           old_str: {
             type: "string",
-            description: "The exact text to find and replace (must be unique in memory). Include surrounding context if needed to ensure uniqueness."
+            description: "The exact text to find and replace (must be unique in memory). Include surrounding context if needed to ensure uniqueness. Leave empty to append new_str to the end of memory instead."
           },
           new_str: {
             type: "string",
-            description: "The replacement text (use empty string to delete the matched content)"
+            description: "The replacement text (use empty string to delete the matched content), or the text to append when old_str is empty."
           }
         },
         required: ["old_str", "new_str"],
@@ -5992,26 +5994,33 @@ var createMemoryTools = (store, options) => {
       handler: async (input, context) => {
         const oldStr = typeof input.old_str === "string" ? input.old_str : "";
         const newStr = typeof input.new_str === "string" ? input.new_str : "";
-        if (!oldStr) {
-          throw new Error("old_str must not be empty.");
-        }
         const current = await resolveStore(context).getMainMemory();
         const content = current.content;
-        const first = content.indexOf(oldStr);
-        if (first === -1) {
-          throw new Error(
-            "old_str not found in memory. Make sure it matches exactly, including whitespace and line breaks."
-          );
-        }
-        const last = content.lastIndexOf(oldStr);
-        if (first !== last) {
-          throw new Error(
-            "old_str appears multiple times in memory. Please provide more context to ensure a unique match."
-          );
+        let newContent;
+        if (!oldStr) {
+          if (!newStr) {
+            throw new Error("new_str must not be empty when appending (old_str is empty).");
+          }
+          newContent = content ? `${content.replace(/\s+$/, "")}
+
+${newStr}` : newStr;
+        } else {
+          const first = content.indexOf(oldStr);
+          if (first === -1) {
+            throw new Error(
+              "old_str not found in memory. Make sure it matches exactly, including whitespace and line breaks."
+            );
+          }
+          const last = content.lastIndexOf(oldStr);
+          if (first !== last) {
+            throw new Error(
+              "old_str appears multiple times in memory. Please provide more context to ensure a unique match."
+            );
+          }
+          newContent = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
         }
-        const newContent = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
         const memory = await resolveStore(context).updateMainMemory({ content: newContent });
-        return { ok: true, memory };
+        return { ok: true, bytes: memory.content.length };
       }
     }),
     defineTool6({
@@ -14656,6 +14665,7 @@ export {
   DEFAULT_MAX_STEPS,
   DEFAULT_MODEL_NAME,
   DEFAULT_MODEL_PROVIDER,
+  DEFAULT_TAGLINE,
   DEFAULT_TEMPERATURE,
   DEFAULT_TIMEOUT,
   InMemoryConversationStore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.59.11",
+  "version": "0.59.13",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/default-agent.ts

@@ -37,10 +37,19 @@ export interface DefaultAgentDefinitionOptions {
   maxSteps?: number;
   /** Hard timeout in seconds. Default: 300. */
   timeout?: number;
+  /**
+   * The descriptor that follows the name in the opening line
+   * ("You are **{name}**, {tagline}."). Default:
+   * "a helpful assistant built with Poncho". SDK consumers shipping a
+   * differently-branded product can override this so the framework name
+   * does not leak into the agent's system prompt.
+   */
+  tagline?: string;
 }
 
 export const DEFAULT_AGENT_NAME = "agent";
 export const DEFAULT_AGENT_DESCRIPTION = "A helpful Poncho assistant";
+export const DEFAULT_TAGLINE = "a helpful assistant built with Poncho";
 export const DEFAULT_MODEL_PROVIDER = "anthropic" as const;
 export const DEFAULT_MODEL_NAME = "claude-opus-4-5";
 export const DEFAULT_TEMPERATURE = 0.2;
@@ -66,6 +75,7 @@ export const defaultAgentDefinition = (
     opts.temperature !== undefined ? `\n  temperature: ${opts.temperature}` : "";
   const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
   const timeout = opts.timeout ?? DEFAULT_TIMEOUT;
+  const tagline = opts.tagline ?? DEFAULT_TAGLINE;
 
   return `---
 name: ${name}
@@ -81,7 +91,7 @@ limits:
 
 # {{name}}
 
-You are **{{name}}**, a helpful assistant built with Poncho.
+You are **{{name}}**, ${tagline}.
 
 Working directory: {{runtime.workingDir}}
 Environment: {{runtime.environment}}

package/src/memory.ts

@@ -192,15 +192,17 @@ export const createMemoryTools = (
           throw new Error("content is required");
         }
         const memory = await resolveStore(context).updateMainMemory({ content });
-        return { ok: true, memory };
+        return { ok: true, bytes: memory.content.length };
       },
     }),
     defineTool({
       name: "memory_main_edit",
       description:
-        "Edit persistent main memory by replacing an exact string match with new content. " +
-        "The old_str must match exactly one location in memory. " +
-        "Use an empty new_str to delete matched content. " +
+        "Edit persistent main memory. With a non-empty old_str, replace that exact " +
+        "string (which must match exactly one location) with new_str; use an empty " +
+        "new_str to delete the matched content. With an empty old_str, append new_str " +
+        "to the end of memory — use this to add a brand-new fact or to write the first " +
+        "fact when memory is still empty. " +
         "Proactively evaluate every turn whether memory should be updated.",
       inputSchema: {
         type: "object",
@@ -209,11 +211,14 @@ export const createMemoryTools = (
             type: "string",
             description:
               "The exact text to find and replace (must be unique in memory). " +
-              "Include surrounding context if needed to ensure uniqueness.",
+              "Include surrounding context if needed to ensure uniqueness. " +
+              "Leave empty to append new_str to the end of memory instead.",
           },
           new_str: {
             type: "string",
-            description: "The replacement text (use empty string to delete the matched content)",
+            description:
+              "The replacement text (use empty string to delete the matched content), " +
+              "or the text to append when old_str is empty.",
           },
         },
         required: ["old_str", "new_str"],
@@ -222,26 +227,35 @@ export const createMemoryTools = (
       handler: async (input, context) => {
         const oldStr = typeof input.old_str === "string" ? input.old_str : "";
         const newStr = typeof input.new_str === "string" ? input.new_str : "";
-        if (!oldStr) {
-          throw new Error("old_str must not be empty.");
-        }
         const current = await resolveStore(context).getMainMemory();
         const content = current.content;
-        const first = content.indexOf(oldStr);
-        if (first === -1) {
-          throw new Error(
-            "old_str not found in memory. Make sure it matches exactly, including whitespace and line breaks.",
-          );
-        }
-        const last = content.lastIndexOf(oldStr);
-        if (first !== last) {
-          throw new Error(
-            "old_str appears multiple times in memory. Please provide more context to ensure a unique match.",
-          );
+        let newContent: string;
+        if (!oldStr) {
+          // Append mode: add new_str to the end. Handles the first-ever write
+          // (empty memory) and adding new facts without needing existing text
+          // to match. Separate from prior content with a blank line when both
+          // sides are non-empty.
+          if (!newStr) {
+            throw new Error("new_str must not be empty when appending (old_str is empty).");
+          }
+          newContent = content ? `${content.replace(/\s+$/, "")}\n\n${newStr}` : newStr;
+        } else {
+          const first = content.indexOf(oldStr);
+          if (first === -1) {
+            throw new Error(
+              "old_str not found in memory. Make sure it matches exactly, including whitespace and line breaks.",
+            );
+          }
+          const last = content.lastIndexOf(oldStr);
+          if (first !== last) {
+            throw new Error(
+              "old_str appears multiple times in memory. Please provide more context to ensure a unique match.",
+            );
+          }
+          newContent = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
         }
-        const newContent = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
         const memory = await resolveStore(context).updateMainMemory({ content: newContent });
-        return { ok: true, memory };
+        return { ok: true, bytes: memory.content.length };
       },
     }),
     defineTool({