AIClaw 3.7.12: Inspectable and Editable Agent Memory on Desktop

Memory preferences may be long outdated — the project switched test frameworks, formatting conventions changed — and old notes can end up misleading the Agent. Users need a direct entry point to inspect and correct memory.

In v3.7.12, AIClaw hands that control back to users: the Memory page in desktop settings supports full-text editing, single-entry editing, and deletion with confirmation. This feature targets the Electron desktop app and its file-based memory, and all code references are anchored to the v3.7.12 tag.

Two Kinds of Memory, Two Scopes

Settings → Memory displays two categories of saved content: global memory (typically located at ~/.aiclaw/memory.md), which holds cross-workspace preferences and conventions; and workspace memory (.aiclaw/memory.md in the working directory), which stores project-specific notes.

The workspace selector is populated from known sessions and deduplicated by working directory, and you can also view only global memory. Each document shows its source path and byte usage, so every edit has a visible destination. The MemoryView component deliberately distinguishes "file does not exist" from "read failed" — a missing memory file can be created through editing, while a read error is shown honestly as an error rather than disguised as empty memory. This distinction is crucial when diagnosing "why do my preferences seem to be gone": an unreadable file and a file that never existed require completely different actions.

Small Fixes Without Breaking Context

The editor supports editing the whole document as well as individual entries. The entry boundary rules are deliberately simple: a line starting with a hyphen or asterisk begins a new entry, and subsequent lines belong to that entry. This is text grouping, not a full Markdown document model. A shared helper preserves the original text when entries are reassembled.

For example: a project note about a deprecated command can be corrected on its own, while the surrounding dates and multi-line notes remain unchanged. Deleting an entry requires confirmation; deleting the last entry saves an empty file rather than deleting the memory file itself.

Capacity is measured in UTF-8 bytes, with a per-document save limit of 32 KiB, matching the desktop kernel's memory load limit. Multibyte characters occupy more than one byte each, so the UI computes the size of the complete candidate document before enabling the save button, and the host checks again on its side. These files are designed for short retained facts, and this purpose and load limit are documented in the kernel's memory implementation.

Write Paths Stay on the Host

The renderer process sends the scope, the selected session, the new content, and the content/existence state it originally read — it is not responsible for choosing an arbitrary target filename. The main process's IPC handler resolves the global path from the application configuration; workspace edits resolve the working directory from the owning non-archived session, then append the fixed memory path. Invalid scopes and missing session ownership are rejected.

This is a pattern worth emulating for desktop editors: path resolution must sit next to filesystem access in order to validate consistently.

IPC (inter-process communication) is the communication mechanism in Electron's architecture between the renderer process (responsible for the UI) and the main process (responsible for system-level operations). The renderer runs in a sandboxed browser environment and, for security reasons, cannot directly access the filesystem, network sockets, or other system resources; the main process has full Node.js capabilities. So when a user clicks Save on the Memory page, the renderer sends the scope, session identifier, and new content to the main process via ipcRenderer.invoke, and the main process's ipcMain.handle handler completes path resolution and file writing before returning the result. This division of labor not only satisfies security boundary requirements but also centralizes path resolution, snapshot validation, symlink rejection, and similar logic in one place, preventing arbitrary paths from being injected at the render layer. The article's emphasis that "the renderer is not responsible for choosing an arbitrary target filename" is precisely a reflection of this architectural constraint: the target file path can only be derived by the main process from trusted application configuration and session ownership, thereby eliminating path-traversal attacks.

Detect Stale Edits Before Replacing Files

Memory can also be modified outside the settings page. The save implementation compares the current content against the snapshot provided by the editor; if they differ, the save fails and prompts a refresh. The UI keeps the draft so users can copy it out before canceling, refreshing, or reconciling changes.

Before writing, the host also checks protected locations and normalized directory boundaries, rejects memory files that are symlinks, and rejects null characters and over-limit content. It first writes a temporary file in a temporary directory next to the target, checks the snapshot again, then renames the new file into place, and finally cleans up the temporary directory. This is an optimistic concurrency check, not a filesystem-level lock or a version history system. Renaming avoids exposing a half-written replacement file, while the snapshot check catches changes observed before replacement.

Optimistic concurrency control is a lock-free concurrency strategy: a snapshot (version, timestamp, or the content itself) is recorded when data is read, and before writing the current value is compared against the snapshot — if they match, the commit is allowed; otherwise it is rejected and the caller handles the conflict. It assumes conflicts are rare, thus saving the holding overhead and deadlock risk of file locks, at the cost of requiring user intervention when conflicts occur. The implementation in the article follows exactly this pattern: the editor carries "the content originally read" when saving, the host re-reads the file and compares before writing, and on mismatch returns a conflict error while the UI keeps the draft for the user to copy. The opposite, pessimistic concurrency (such as file locks), would prevent other processes from modifying the file during editing, but in desktop applications it is hard to cover scenarios where users modify files in an external editor. Note that the optimistic check and "temporary file plus rename" solve different problems: the former ensures you don't overwrite changes someone else has already made, while the latter ensures the replacement operation itself is atomic and won't let readers see a half-written state.

Saved State Is Not Current Conversation State

A successful save on the settings page only updates the file on disk; it does not directly rebuild the system prompt of the current conversation. Per the documented desktop workflow, memory is loaded when a session is opened or resumed. Refresh on the Memory page re-reads the saved file; it does not re-inject memory into a running conversation.

The practical workflow is: check the correct scope, edit or delete outdated notes, save, then open or resume the conversation that should use the new memory. This page describes saved state — it does not claim to show the exact memory snapshot currently loaded by every active session.

The system prompt is the instructional text sent alongside the conversation on every call to the large language model, used to set the Agent's role, behavioral guidelines, and available context. The contents of memory files are typically concatenated into the system prompt, thereby influencing every subsequent response from the model. The key point is that the system prompt is assembled when a session is established or resumed; once a conversation is underway, its context is already fixed on the model side, and changes to the memory file on disk do not automatically rewrite the loaded prompt. This is why, after saving on the settings page, you need to "open or resume the session" for the new memory to take effect — resuming a session triggers a reassembly that reads the latest memory file into a new system prompt. Understanding this avoids a common misconception: users assume that after saving on the Memory page, the Agent in the current conversation will immediately change its behavior, when in fact it continues using the old snapshot until the session is reloaded.

What the Verification Covers

The public filesystem tests cover missing files, read errors, text preservation, UTF-8 capacity, conflicts, empty-file saves, and protected paths; the symlink test is explicitly skipped on Windows. The workspace UI smoke checks cover scope selection, refresh, plain-text display, entry editing, over-limit save blocking, draft retention after conflicts, canceling deletion, and workspace-specific creation — using the real Vue/preload layers with simulated host responses.

The tagged release workflow completed successfully, including test, packaging, and release jobs; its workflow definition runs the desktop smoke checks under a Linux virtual display. This is useful automated evidence, but it does not prove that local filesystem behavior on every platform has been manually tested.

For users, the improvement is concrete: a stale memory rule now has an inspectable source, a clear scope, and a direct editing path in desktop settings.