UpdateUserMemory

Writes or deletes a persistent memory entry in the caller's personal user folder.

Overview

Memory entries are stored in data/users/{userId}/memory/ as individual Markdown files with YAML frontmatter. An index (MEMORY.md) is automatically maintained and injected into the LLM system prompt at the start of every movement, giving the agent immediate awareness of what has been stored without reading every fact file.

Use ReadUserMemory to load the full body of a specific entry.

Actions

`upsert`

Creates a new entry or replaces an existing one with the same name.

Required fields: action, name, type, description, body

{
  "action": "upsert",
  "name": "preferred-language",
  "type": "user",
  "description": "User prefers Japanese output",
  "body": "Always respond in Japanese unless the user explicitly asks for another language."
}

The index line in MEMORY.md will be:

- [preferred-language](preferred-language.md) — User prefers Japanese output

`delete`

Moves the fact file to trash/ (no hard delete) and removes its index line from MEMORY.md.

Required fields: action, name

{
  "action": "delete",
  "name": "preferred-language"
}

Returns an error if the entry does not exist.

Parameters

Parameter	Type	Required	Description
`action`	`"upsert" \| "delete"`	Yes	Operation to perform
`name`	string	Yes	Entry identifier: alphanumeric, dash, underscore only; no `.md` extension
`type`	`"user" \| "feedback" \| "project" \| "reference"`	For upsert	Category of the entry
`description`	string	For upsert	One-line summary shown in MEMORY.md index
`body`	string	For upsert	Full content of the fact file

Memory types

Type	Intended use
`user`	Long-term user preferences, standing instructions
`feedback`	Corrections the user has given (e.g. "don't do X")
`project`	Project-specific facts (stack, conventions, key files)
`reference`	Reference data (URLs, credentials patterns, external IDs)

Notes

Idempotent upsert: calling upsert twice with the same name replaces the entry; no duplicate index lines are created.
Soft delete: deleted entries land in trash/ and are never immediately erased.
Owner-only: requires an authenticated user (ctx.userId). Cross-user writes are not possible.
Name format: only [a-zA-Z0-9_-] are allowed. The .md extension is appended automatically.

2.5 KiB Raw Blame History