memos-memory-guide

# MemOS Local 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, query team-shared data, share tasks, and discover or pull reusable skills.

Two sharing planes exist and must not be confused:

- **Local agent sharing:** visible to agents in the same OpenClaw workspace only.
- **Team sharing:** visible to teammates through the configured team server.

## 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.
- **Memory isolation:** Each agent can only see its own local private memories and local `public` memories. Team-shared data only appears when you search with `scope="group"` or `scope="all"`.

## Tools — what they do and when to call

### memory_search

- **What it does:** Search long-term conversation memory for past conversations, user preferences, decisions, and experiences. Returns relevant excerpts with `chunkId` and optionally `task_id`. Only returns memories belonging to the current agent or marked as public.
- **When to call:**
  - The automatic recall did not run or returned nothing.
  - The user's query is long or unclear — **generate a short query yourself** and call `memory_search(query="...")`.
  - You need to search with a different angle (e.g. filter by `role='user'`).
- **Parameters:**
  - `query` (string, **required**) — Natural language search query.
  - `scope` (string, optional) — `'local'` (default) for current agent + local shared memories, or `'group'` / `'all'` to include team-shared memories.
  - `maxResults` (number, optional) — Increase when the first search is too narrow.
  - `minScore` (number, optional) — Lower slightly if recall is too strict.
  - `role` (string, optional) — Filter local results by `'user'`, `'assistant'`, `'tool'`, or `'system'`.

### memory_get

- **What it does:** Get the full original text of a memory chunk. Use to verify exact details from a search hit.
- **When to call:** A `memory_search` hit looks relevant but you need to see the complete original content, not just the summary/excerpt.
- **Parameters:**
  - `chunkId` (string, **required**) — The chunkId from a search hit.
  - `maxChars` (number, optional) — Max characters to return (default 4000, max 12000).

### memory_write_public

- **What it does:** Create a brand new local shared memory. These memories are visible to all agents in the same OpenClaw workspace during `memory_search`. This does **not** publish anything to the team server.
- **When to call:** In multi-agent or collaborative scenarios, when you want to create a new persistent shared note from scratch (e.g. shared decisions, conventions, configurations, workflows). Do not use it if you already have a specific memory chunk to expose.
- **Parameters:**
  - `content` (string, **required**) — The content to write to local shared memory.
  - `summary` (string, optional) — Short summary of the content.

### memory_share

- **What it does:** Share an existing memory either with local OpenClaw agents, to the team, or to both.
- **When to call:**
  - If you want to share conversation content to team or hub, first retrieve memories related to that content to obtain the right `chunkId`(s), then share.
  - `target='agents'` (default): When those memories would clearly help other agents in the same workspace, you may share proactively without asking the user.
  - `target='hub'` or `'both'`: Only after explicit user consent when the content would benefit collaborators—explain briefly, ask first, then call `hub`/`both` (Hub must be configured). Never silently Hub-share.
- **Do not use when:** You are creating a brand-new shared note with **no** existing chunk—use `memory_write_public` instead.
- **Parameters:**
  - `chunkId` (string, **required**) — Existing memory chunk ID.
  - `target` (string, optional) — `'agents'` (default), `'hub'`, or `'both'`.
  - `visibility` (string, optional) — Team visibility when target includes team: `'public'` (default) or `'group'`.
  - `groupId` (string, optional) — Optional team group ID when `visibility='group'`.

### memory_unshare

- **What it does:** Remove an existing memory from local agent sharing, team sharing, or both.
- **When to call:** A memory should no longer be visible outside the current agent or should be removed from the team.
- **Parameters:**
  - `chunkId` (string, **required**) — Existing memory chunk ID.
  - `target` (string, optional) — `'agents'`, `'hub'`, or `'all'` (default).
  - `privateOwner` (string, optional) — Rare fallback only for older public memories that have no recorded original owner.

### task_summary

- **What it does:** Get the detailed summary of a complete task: title, status, narrative summary, and related skills. Use when `memory_search` returns a hit with a `task_id` and you need the full story. Preserves critical information: URLs, file paths, commands, error codes, step-by-step instructions.
- **When to call:** A `memory_search` hit included a `task_id` and you need the full context of that task.
- **Parameters:**
  - `taskId` (string, **required**) — The task_id from a memory_search hit.

### skill_get

- **What it does:** Retrieve a proven skill (experience guide) by `skillId` or by `taskId`. If you pass a `taskId`, the system will find the associated skill automatically.
- **When to call:** A search hit has a `task_id` and the task has a "how to do this again" guide. Use this to follow the same approach or reuse steps.
- **Parameters:**
  - `skillId` (string, optional) — Direct skill ID.
  - `taskId` (string, optional) — Task ID — will l