add-memory-type

## Purpose Use this skill when the user wants to create or update an OpenMates memory type or settings/memories category. OpenMates memories are user-facing, app-scoped encrypted data categories that users can manage in Settings > Apps and share with a mate only after per-conversation permission. This is not for Codex memory, agent memory, browser storage, or generic notes. ## Core Product Rule: Keep Memory Schemas Minimal Memory entries must be easy for normal users to fill out. Target **1-4 user-entered fields** per memory entry. Rules: - Prefer 1-2 fields when the memory is a simple preference. - Prefer 3-4 fields only when list entries need a title plus essential context. - Avoid 5+ user-entered fields unless the user explicitly approves the extra friction. - Do not model every possible detail. Store the minimum useful data that helps the mate personalize future answers. - Use `notes` as an optional multiline field only when it meaningfully replaces several niche fields. - Do not add `added_date`; it is auto-injected by backend/frontend metadata generation. - Do not collect sensitive fields unless the user confirms the need and the privacy boundary is explicit. ## Arguments Parse `$ARGUMENTS` as optional hints: - `appId` — parent OpenMates app directory, such as `travel`, `books`, `health`, or `code` - `memoryId` — memory category id, snake_case preferred, such as `favorite_books` or `communication_style` If either value is missing, infer it during discovery or ask during the clarifying rounds. Do not invent a final app or ID without user confirmation. ## Workflow Follow this structure closely. The user expects the same deliberate plan-before-build flow as focus mode authoring: existing-state research, clarification, internal research, external research, more clarification, draft, feedback, finalization, then implementation. Every clarifying question must include `Recommendation:` with the evidence-based preferred answer and rationale plus `Examples:` with task-specific options or outcomes. If uncertain, recommend the safest reversible default and state the uncertainty. ### Step 1: Check Existing Memory Types First inspect how memory types already exist and how the target app is structured. Read or search these paths as relevant: - `docs/user-guide/apps/settings-and-memories.md` - `backend/shared/python_schemas/app_metadata_schemas.py` (`AppMemoryFieldDefinition`) - `backend/apps/*/app.yml` (`settings_and_memories`) - `backend/apps/{appId}/app.yml` - `frontend/packages/ui/src/i18n/sources/settings/app_settings_memories.yml` - `frontend/packages/ui/scripts/generate-apps-metadata.js` - `frontend/packages/ui/src/types/apps.ts` (`MemoryFieldMetadata`, `SchemaPropertyDefinition`) - `frontend/packages/ui/src/components/settings/AppSettingsMemoriesCreateEntry.svelte` - `frontend/packages/ui/src/components/settings/AppSettingsMemoriesCategory.svelte` - `frontend/apps/web_app/tests/mention-dropdown-settings-memory.spec.ts` - `frontend/apps/web_app/tests/cli-memories.spec.ts` Identify whether the request is: - creating a new memory type - updating an existing memory type - simplifying an over-complex schema - adding examples/i18n only - changing how a skill or focus mode uses existing memory data ### Step 2: Ask 3 Clarifying Rounds Ask exactly one clear question per round and wait for the user's answer before continuing. Stop early only if the user explicitly says to skip clarification. Use these topics unless the repo context reveals more urgent blockers: - Round 1: What user data should this memory help the mate remember? - Round 2: Which app should own it, and should it be a new category or update an existing one? - Round 3: Should this be a `single` preference or a `list` of entries, and what are the 1-4 essential fields? If the user proposes more than 4 fields, challenge the scope before proceeding: ask which fields are truly necessary for useful personalization and which can be merged into optional `notes` or left out. ### Step 3: Search Internal Context Based on the answers, search internal sources for relevant connected information and ideas. Check: - similar `settings_and_memories` schemas in other apps - related app skills or focus modes that may request this memory - GitHub issues for related product ideas, privacy concerns, or prior decisions - docs and tests for the affected app/domain - settings UI behavior for the proposed field types - whether the memory should appear in mention dropdowns or app-store examples Use GitHub Issues by default for tracker searches. Do not create or update an issue unless the user asks. ### Step 4: Search External Context Search externally for ideas and best practices relevant to the requested memory type. Use: - GitHub search for similar app data models, AI assistant memories, preference schemas, or user profile data categories - web search for domain best practices - official or authoritative sources when the memory touches health, finance, legal, safety, education, jobs, security, privacy, minors, or other high-risk topics Keep this research practical. Extract only fields and privacy boundaries that improve the OpenMates memory contract. Do not copy large data models; OpenMates memory entries should stay minimal. ### Step 5: Ask 3 More Clarifying Rounds Ask exactly one clear question per round and wait for the user's answer before continuing. These questions must be informed by internal and external research. Use them to resolve: - which proposed fields can be removed or merged to keep the schema within 1-4 fields - sensitive fields to avoid - required vs optional fields - title/subtitle display behavior in settings - example entries - how the AI may use this memory and when it must ask for permission - how proactive, cautious, structured, or conversational the mate should be when suggesting saved entries ### Step 6: Suggest a Draft Present a concise draft and ask for feedback before editing product files. The draft must include: - display name - parent app - runtime memory ID - type (`single` or `list`) - default-enabled behavior, including `default_enabled: false` only when the memory type intentionally ships off - one-line description - schema fields, explicitly marking the 1-4 user-entered fields - required fields - title/subtitle display fields - example entries - how the AI may use this memory after permission - how the AI should suggest saving new entries - non-goals - safety, privacy, and data-use rules If the draft has more than 4 user-entered fields, include a short justification and ask the user to explicitly approve the extra complexity. For updates, show a focused diff-style summary of what will change. ### Step 7: Ask for Feedback Wait for the user's feedback. Do not implement before this gate unless the user explicitly says to proceed without draft approval. ### Step 8: Finalize the Draft Incorporate feedback and show the final version briefly. Confirm any remaining tradeoffs, such as default-enabled behavior, field count, required fields, or sensitive data boundaries. ### Step 8b: Define Phase Gates Before implementation, record the phase gate in the draft, inline contract, or full spec: 1. Implement and test memory behavior through OpenMates CLI against the dev server first when the memory is created, read, selected, or used outside static metadata. Mocked OpenMates API calls, mocked SDK clients, stubbed servers, direct function calls, and fixture replay do not satisfy this gate. 2. Implement and test npm SDK and pip SDK parity locally against the dev server when the memory behavior is exposed programmatically. After local CLI and SDK evidence is green, reproduce or wire the same coverage into GitHub Actions for CI/daily tests. 3. Implement web settings, mention dropdown behavior, and Playwright coverage only after CLI and required SDK evidence are green. 4. Run deployed Playwright visual smoke for larger web/UI surfaces in both laptop and mobile viewports, fixing and redeploying any objective rendering, error, loading, or responsiveness issue, then ask the user to confirm the deployed dev web behavior works and looks correct before starting Apple parity. Use Firecrawl only as a recorded fallback when Playwright is impractical or blocked. `*.spec.ts` evidence alone is not enough. 5. Start Apple parity only after CLI, SDK, web, and user-confirmation evidence are complete, or after an explicit waiver/blocker is recorded. ### Step 9: Implement the Memory Type Update the current OpenMates metadata and i18n sources. Primary implementation target: - `backend/apps/{appId}/app.yml` under `settings_and_memories:` Usually required i18n target: - `frontend/packages/ui/src/i18n/sources/settings/app_settings_memories.yml` Potentially relevant docs/tests: - `docs/user-guide/apps/settings-and-memories.md` - app-specific docs under `docs/user-guide/apps/` or `docs/architecture/apps/` - `frontend/apps/web_app/tests/mention-dropdown-settings-memory.spec.ts` - `frontend/apps/web_app/tests/cli-memories.spec.ts` Rules: - Runtime `id` is snake_case. - Use `settings_and_memories`, not legacy `memory_fields` or `memory`, for new work. - Use `type: single` for one user preference object and `type: list` for repeatable entries. - Do not add `stage`; memory types are enabled by default unless `default_enabled: false` is explicitly needed. - Add `icon_image` only if an appropriate existing icon exists. - Keep user-entered schema fields to 1-4 whenever possible. - Mark exactly one useful `is_title: true` field for list readability when possible. - Use `is_subtitle: true` only when it materially improves scanning. - Prefer enum fields only when the choices are stable and user-friendly. - Prefer `format: date`, `format: uri`, or `format: email` only when the UI and validation benefit. - Use `multiline: true` for optional notes, not for every text field. - Do not add `added_date`; it is auto-injected. - Do not add sensitive identifiers, secrets, payment details, medical record numbers, government IDs, or credentials. - For health/legal/finance/safety memories, add conservative wording in the draft and avoid encouraging diagnosis, legal advice, or financial decisions based only on saved memory. ### Step 10: Validate Run the smallest checks that prove the change. Usually relevant: - `cd frontend/packages/ui && npm run build:translations` after i18n YAML edits - `cd frontend/packages/ui && npm run generate-apps-metadata` after app metadata edits - `cd frontend/packages/ui && npm run validate:locales` if translations changed - targeted lint or typecheck command for changed areas when available For user-facing memory behavior, propose the relevant E2E test path and use the repo test runner after deploy when running Playwright: - `python3 scripts/tests.py run --spec mention-dropdown-settings-memory.spec.ts` - `python3 scripts/tests.py run --spec cli-memories.spec.ts` - a new or updated app-specific memory spec if needed Do not run Playwright locally. ## Draft Template Use this structure for Step 6 and Step 8. ```markdown ## Memory Type Draft Name: App: Memory ID: Type: single | list Default enabled: Description: User-entered fields (target 1-4): 1. field_name — type — required/optional — purpose Auto-generated fields: - added_date (injected automatically; do not define manually) Title/subtitle display: Example entries: - ... How the AI may use it after permission: How the AI may suggest saving it: Non-goals: Safety and privacy: Open questions: ``` ## Implementation Checklist Before finishing, verify: - memory ID is snake_case - app uses `settings_and_memories:` - schema has 1-4 user-entered fields unless explicitly approved otherwise - schema has no manual `added_date` - required fields are genuinely necessary - at least one field is marked `is_title: true` for list entries when possible - any `is_subtitle: true` field is actually useful for scanning - examples match the schema and avoid private or sensitive values - i18n keys exist in `settings/app_settings_memories.yml` - generated translations and app metadata were rebuilt if source files changed - docs/tests were updated or explicitly deferred ## When to Escalate to a Full Spec Use `create-plan` before implementation if the memory type changes persistence, permissions, encryption, sharing, Directus schema, sync behavior, AI permission dialogs, new API routes, or app skill behavior. Pure metadata/i18n additions can usually follow this skill without a full spec.