memories

name	memories
description	Use when working with the memories-api MCP server, prime_memory_context, search_memories, record_memory, revise_memory, retire_memory, or inspect_memory. Guides recall, personalization, deduping, sensitive-memory confirmation, contradiction handling, and prompt/resource usage for this repo.
argument-hint	[task or memory operation]
user-invocable	true

Memories Tool Behavior

Use this skill when an agent is deciding how to interact with the memories API or its MCP tools.

When to Use

• The task may benefit from recalled user preferences or identity context.
• The agent is deciding whether to create or update a durable memory.
• The task involves correcting, invalidating, or reconciling an existing memory.
• The agent needs to avoid broad recall patterns that would create noisy access timestamps.

Procedure

1. Decide whether memory recall is actually needed for the task.
2. At the beginning of a session, call prime_memory_context to load active preferences first, then active identity memories.
3. For a substantive reply, use one moderate search_memories call shaped by memory_type, tag, or focused q terms.
4. If considering a write, check whether the information is durable, atomic, and safe to store.
5. Ask before storing any sensitive memory.
6. Prefer updating an existing memory over creating a duplicate when the match is clear.
7. If a contradiction appears, ask the user which version should remain authoritative before updating or invalidating.
8. Do not delete memories automatically.

Autonomy

• Default autonomy level: autonomous.

• Autonomy levels and allowed actions:

  • manual — Agent may suggest recall and writes but must request explicit human confirmation before performing any create, update, or delete operations. Reads are allowed for context but agents should minimize broad queries.
  • suggest — Agent may perform reads and propose writes; it may perform non-destructive updates to clearly matching preference records when the match is unambiguous, but should request confirmation for new creates and deletions.
  • autonomous — Agent may perform reads, create, update, and soft-delete (status='deleted') operations without an additional human approval step, provided it follows the behavior policy (sensitive-data confirmation, deduping flow, concise atomic writes, and transparency reporting).

• Soft-delete behavior: deletions performed by agents set memory status to deleted (soft-delete) so items remain auditable and may be inspected or restored by humans or repair workflows.

• Transparency: agents operating under any autonomy level must follow the assistant guidance in assets/use-memories-api-assistant.md which requires a short Memory actions: summary appended to replies whenever memory tools are used.

References

• Tool behavior policy
• Query recipes

Assets

• Static MCP prompt assistant message

Scripts

• Validation script
• Curl examples

Keep this directory focused on runnable helpers that an agent can execute after editing the skill, prompt, MCP wiring, or related server behavior.

• validate_memories_skill.py is the quick in-process smoke check. It exercises prompt/resource registration and a create-query-read-update-delete workflow against a temporary database.
• curl_examples.md is the manual HTTP reference for copy-paste debugging and documentation work.

Use markdown for examples and explanation. Use scripts only for executable checks or maintenance helpers that actually reduce agent work.