# 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`

```json
{
  "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`

```json
{
  "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.