Summary

Add memory_add to memory-core as the canonical way for agents to write durable memory.

The tool should replace ad-hoc model edits to memory markdown with a structured write path. It should still write to workspace markdown first, specifically memory/YYYY-MM-DD.md, so markdown remains the source of truth and backends consume/index it rather than owning a separate write source.

Each write should create one complete semantic memory unit with a persistent memoryId, category, timestamps, and an explicit markdown boundary. That gives backends enough metadata to preserve the memory as coherent content during indexing and recall, and gives future maintenance tools a stable target for replacing or deleting the memory later.

Motivation

memory-core currently has recall tools, but no explicit semantic write primitive. Agents can edit memory files directly or rely on backend-specific tools, which makes memory writes inconsistent across backends.

The missing abstraction is a semantic memory unit. When a user explicitly asks the agent to remember something, that memory is usually a complete preference, decision, fact, correction, or entity detail. It should be stored and indexed as one coherent unit, not accidentally split into unrelated chunks.

We have already implemented and used this pattern in production: an explicit memory-write tool stores user-approved memories as managed markdown units, assigns stable IDs, checks duplicates, and lets memory backends consume the markdown corpus. This proposal extracts the portable part of that design into memory-core so it can work across backends.

Relevant community feedback:

• #43747: memory management feels inconsistent and chaotic.
• #48558: asks for native memory-tool-style behavior.
• #62184: needs a better path for explicit corrections and lessons.
• #68751: shows the risk of raw transcript/session text being reinterpreted as memory.

Other related discussions point in the same direction: #43002, #59095, #50096, #68449, #68473, #67697, #6877, #6878, #34951, #8185, #45608, #56072, #24173, #60572, and #65411.

Proposal

Add a memory_add tool that:

• Accepts memory text and optional category.
• Normalizes and validates the text.
• Checks existing memory blocks for duplicates.
• Appends a managed memory unit to memory/YYYY-MM-DD.md.
• Returns duplicate when similar memory already exists.
• Returns created with a stable memoryId when a new unit is written.

Tool schema

export const MemoryCategorySchema = Type.Union([
  Type.Literal("preference"),
  Type.Literal("fact"),
  Type.Literal("decision"),
  Type.Literal("entity"),
  Type.Literal("other"),
]);

export type MemoryCategory = Static<typeof MemoryCategorySchema>;

export const MemoryAddSchema = Type.Object({
  text: Type.String({ description: "Complete semantic memory unit to store" }),
  category: Type.Optional(MemoryCategorySchema),
});

type MemoryAddParams = Static<typeof MemoryAddSchema>;

text is the complete semantic memory unit to store. category is optional metadata for indexing, filtering, and future UI display.

The category set follows the existing memory-lancedb/production convention. When category is not provided, memory_add can infer it using deterministic rules rather than requiring an LLM call. The initial heuristic can stay conservative, mapping explicit preferences, decisions, factual statements, entity details, and fallback cases into the fixed enum.

Memory kind

Introduce a small MemoryKind distinction:

type MemoryKind = "UNIT" | "RAW";

UNIT memories are managed semantic units created by tools such as memory_add. They have stable UNIT:<uuid> IDs and are safe targets for future mutation tools.

RAW memories are existing plain markdown content parsed from the memory corpus. They can be searched and used for duplicate detection, but should be treated as read-only unless later converted into managed units.

This gives memory-core a clear boundary between curated, user-approved memory units and legacy/raw markdown text.

Result shape

Created:

{
  "action": "created",
  "memoryId": "UNIT:<uuid>",
  "kind": "UNIT",
  "path": "memory/2026-04-22.md",
  "category": "decision",
  "text": "Use pnpm for dependency management in this workspace."
}

Duplicate:

{
  "action": "duplicate",
  "existing": {
    "memoryId": "UNIT:<uuid>",
    "kind": "UNIT",
    "path": "memory/2026-04-22.md",
    "category": "decision",
    "text": "Use pnpm for dependency management in this workspace."
  }
}

Failed:

{
  "action": "failed",
  "error": "text_required"
}

The exact error codes can be refined in the PR, but the important contract is that successful writes return a stable memoryId, and duplicate detection is explicit and non-writing.

Managed memory unit

Example markdown representation:

<!-- openclaw:memory:item:start memory_id=UNIT:<uuid> category=decision created_at=... updated_at=... -->
Use pnpm for dependency management in this workspace.
<!-- openclaw:memory:item:end -->

The HTML comments are storage metadata. They define the unit boundary, stable ID, category, and timestamps, but should be filtered out of indexed chunks and recall text. Backends should index the memory body as the semantic content, while preserving the memoryId as metadata.

Backends should preserve this unit boundary during indexing and recall. If they chunk internally, they should keep the shared memoryId so future mutation can operate on the complete memory.

Future work

Once memory_add establishes the managed memory unit format, memory-core can add explicit mutation tools on top of the same memoryId contract:

• memory_replace or memory_update to replace the text of a UNIT:* memory while preserving its identity and creation metadata.
• memory_remove or memory_delete to remove a UNIT:* memory by stable ID.
• Query-assisted mutation flows can return candidates first, then require a memoryId for destructive changes.
• RAW:* memories should remain searchable and useful for duplicate detection, but not directly mutable by these tools.

The naming can be decided separately, but the core requirement is that future mutation operates on complete semantic units, not arbitrary text spans.

Validation

Tests should cover:

• Creating a managed unit in memory/YYYY-MM-DD.md.
• Returning duplicate without writing.
• Preserving semantic unit boundaries.
• Filtering marker comments out of indexed chunks and recall text.
• Distinguishing UNIT from RAW memory.
• Treating raw markdown as searchable but not directly writable.
• Working without backend-specific storage.