MemOS Lite Memory — Agent Guide#

This skill describes how to use the MemOS memory tools so you can reliably search and use the user's long-term conversation history.

How memory is provided each turn#

• Automatic recall (hook): At the start of each turn, the system runs a memory search using the user's current message and injects relevant past memories into your context. You do not need to call any tool for that.

• When that is not enough: If the user's message is very long, vague, or the automatic search returns no memories, you should generate your own short, focused query and call memory_search yourself. For example:

  • User sent a long paragraph → extract 1–2 key topics or a short question and search with that.
  • Auto-recall said "no memories" or you see no memory block → call memory_search with a query you derive (e.g. the user's name, a topic they often mention, or a rephrased question).

• When you need more detail: Search results only give excerpts and IDs. Use the tools below to fetch full task context, skill content, or surrounding messages.

Tools — what they do and when to call#

memory_search#

• What it does: Searches the user's stored conversation memory by a natural-language query. Returns a list of relevant excerpts with chunkId and optionally task_id.
• When to call:
  • The automatic recall did not run or returned nothing (e.g. no <memory_context> block, or a note that no memories were found).
  • The user's query is long or unclear — generate a short query yourself (keywords, rephrased question, or a clear sub-question) and call memory_search(query="...").
  • You need to search with a different angle (e.g. filter by role='user' to find what the user said, or use a more specific query).
• Parameters: query (required), optional minScore, role (e.g. "user").
• Output: List of items with role, excerpt, chunkId, and sometimes task_id. Use those IDs with the tools below when you need more context.

task_summary#

• What it does: Returns the full task summary for a given task_id: title, status, and the complete narrative summary of that conversation task (steps, decisions, URLs, commands, etc.).
• When to call: A memory_search hit included a task_id and you need the full story of that task (e.g. what was done, what the user decided, what failed or succeeded).
• Parameters: taskId (from a search hit).
• Effect: You get one coherent summary of the whole task instead of isolated excerpts.

skill_get#

• What it does: Returns the content of a learned skill (experience guide) by skillId or by taskId. If you pass taskId, the system finds the skill linked to that task.
• When to call: A search hit has a task_id and the task is the kind that has a "how to do this again" guide (e.g. a workflow the user has run before). Use this to follow the same approach or reuse steps.
• Parameters: skillId (direct) or taskId (lookup).
• Effect: You receive the full SKILL.md-style guide. You can then call skill_install(skillId) if the user or you want that skill loaded for future turns.

skill_install#

• What it does: Installs a skill (by skillId) into the workspace so it is loaded in future sessions.
• When to call: After skill_get when the skill is useful for ongoing use (e.g. the user's recurring workflow). Optional; only when you want the skill to be permanently available.
• Parameters: skillId.

memory_timeline#

• What it does: Expands context around a single memory chunk: returns the surrounding conversation messages (±N turns) so you see what was said before and after that excerpt.
• When to call: A memory_search hit is relevant but you need the surrounding dialogue (e.g. who said what next, or the exact follow-up question).
• Parameters: chunkId (from a search hit), optional window (default 2).
• Effect: You get a short, linear slice of the conversation around that chunk.

memory_viewer#

• What it does: Returns the URL of the MemOS Memory Viewer (web UI) where the user can browse, search, and manage their memories.
• When to call: The user asks how to view their memories, open the memory dashboard, or manage stored data.
• Parameters: None.
• Effect: You can tell the user to open that URL in a browser.

Quick decision flow#

1. No memories in context or auto-recall reported nothing → Call memory_search with a self-generated short query (e.g. key topic or rephrased question).

2. Search returned hits with task_id and you need full context → Call task_summary(taskId).

3. Task has an experience guide you want to follow → Call skill_get(taskId=...) (or skill_get(skillId=...) if you have the id). Optionally skill_install(skillId) for future use.

4. You need the exact surrounding conversation of a hit → Call memory_timeline(chunkId=...).

5. User asks where to see or manage their memories → Call memory_viewer() and share the URL.

Writing good search queries#

• Prefer short, focused queries (a few words or one clear question).
• Use concrete terms: names, topics, tools, or decisions (e.g. "preferred editor", "deploy script", "API key setup").
• If the user's message is long, derive one or two sub-queries rather than pasting the whole message.
• Use role='user' when you specifically want to find what the user said (e.g. preferences, past questions).