@clawmem-ai/clawmem 0.1.9 → 0.1.11

package/skills/clawmem/references/collaboration.md

@@ -0,0 +1,223 @@
+# ClawMem Collaboration
+
+Use this reference when memory should live in a shared repo instead of one agent's private default repo, or when multiple agents or teammates need to read and write the same memory space. Use it for both `collaboration` and `collabration` requests.
+
+## Contents
+
+- When to use
+- Default operating style
+- Repo routing and shared spaces
+- Collaboration model
+- Choose the right mechanism
+- Pre-mutation checklist
+- Prompt-to-tool mapping
+- Team memory quality bar
+- Collaboration rule of thumb
+- Manual org-owned shared repo creation
+- Fallback mode
+
+## When to use
+
+Use this reference when the user asks to:
+
+- create or manage an organization
+- invite someone into an organization
+- inspect, accept, or decline an invitation sent to the current user
+- create or manage a team
+- add or remove a repository collaborator
+- grant a team access to a repo
+- inspect outside collaborators
+- create a shared team memory repo or org-owned memory space
+- debug why a user can or cannot access a repo
+
+Do not use this workflow for ordinary memory recall or save actions unless the user is specifically asking to change who can access a memory repo.
+
+## Default operating style
+
+- Prefer the built-in ClawMem collaboration tools first.
+- Inspect current state before mutating anything.
+- Set `confirmed=true` only after the user has approved the exact org, team, repo, invitation, or permission change.
+- Fall back to `gh api` or `curl` only when plugin tools are unavailable, when debugging backend behavior directly, or when you must create an org-owned repo because the plugin does not expose an org-repo creation tool yet.
+- Reuse the main `clawmem` skill's route-resolution helper when raw shell access is required.
+- Think in canonical runtime permissions: `read`, `write`, `admin`.
+- Treat GitHub-compatible aliases such as `pull`, `triage`, `push`, and `maintain` as transport compatibility only.
+
+Tool-first rule:
+- Read-only inspection:
+  - `collaboration_orgs`
+  - `collaboration_teams`
+  - `collaboration_team_repos`
+  - `collaboration_repo_collaborators`
+  - `collaboration_repo_invitations`
+  - `collaboration_user_repo_invitations`
+  - `collaboration_org_invitations`
+  - `collaboration_user_org_invitations`
+  - `collaboration_outside_collaborators`
+  - `collaboration_repo_access_inspect`
+- Mutations:
+  - `collaboration_org_create`
+  - `collaboration_team_create`
+  - `collaboration_team_membership_set`
+  - `collaboration_team_membership_remove`
+  - `collaboration_team_repo_set`
+  - `collaboration_team_repo_remove`
+  - `collaboration_repo_collaborator_set`
+  - `collaboration_repo_collaborator_remove`
+  - `collaboration_user_repo_invitation_accept`
+  - `collaboration_user_repo_invitation_decline`
+  - `collaboration_org_invitation_create`
+  - `collaboration_user_org_invitation_accept`
+  - `collaboration_user_org_invitation_decline`
+
+## Repo routing and shared spaces
+
+Before explicit memory operations, choose the right repo:
+- Private personal memory: usually the current agent's `defaultRepo`
+- Project memory: the relevant project repo
+- Shared or team knowledge: the shared repo for that team or project
+- Unclear: inspect `memory_repos`, then choose deliberately
+
+Do not treat `defaultRepo` as the only space. It is only the fallback.
+
+Default tool path:
+- Use `memory_repos` to inspect accessible spaces
+- Use `memory_repo_create` when a new repo should be owned by the current agent identity
+- Create an org-owned repo with raw `gh api` or `curl` when the memory space must be governed by an organization team
+- Pass `repo` explicitly to `memory_recall`, `memory_list`, `memory_get`, `memory_store`, `memory_update`, and `memory_forget` when the target is not the current `defaultRepo`
+
+This keeps private memory, project memory, and shared memory separate without forcing extra plugin configuration changes.
+
+## Collaboration model
+
+Reason with these rules before every collaboration action:
+
+- An organization is an explicit governance boundary.
+- Org membership is explicit and separate from team membership.
+- Teams are org-scoped authorization groups, not social groups.
+- Effective repo access is `max(org base permission, direct collaborator grant, team grant)` after owner or admin shortcuts.
+- Runtime permissions are only `none`, `read`, `write`, and `admin`.
+- `memory_repos` only shows repos that are already accessible now; it does not prove there are no pending invitations.
+- A repo collaborator grant may create a pending repository invitation instead of immediate access when the target user is not already a collaborator.
+- Accepting a repository invitation is what turns a pending share into visible repo access for the invitee.
+- Outside collaborators are non-members who still have direct collaborator access to at least one org-owned repo.
+- Accepting an org invitation creates org membership, joins invited teams as `member`, and removes the pending invitation.
+- If a user becomes an org member, any outside-collaborator row for that org should disappear.
+- The system-managed `admins` team is an implementation mechanism, not a user-facing product primitive.
+
+## Choose the right mechanism
+
+Use this decision map:
+
+| Goal | Use |
+|---|---|
+| Give one user access to one repo without org membership | Direct collaborator |
+| Bring one user into the org | Org invitation |
+| Grant a group access to selected repos | Team + team-repo grant |
+| Create a shared team memory space | Org-owned repo + team-repo grant |
+| Create another memory space under the current agent identity | `memory_repo_create` |
+| Inspect non-members who still have repo access | Outside collaborator listing |
+
+Hard rules:
+- Never assume team membership creates org membership.
+- Never use team membership as a side-door org bootstrap.
+- Never assume a repo share should become org membership; choose intentionally.
+- If the task is org-scoped, ensure the org already exists or create it explicitly first.
+
+## Pre-mutation checklist
+
+Before any write action:
+
+1. Identify the acting identity, target org, target repo, target user, target team, and desired permission.
+2. Normalize the user's requested permission mentally to `read`, `write`, or `admin` before reasoning.
+3. Inspect current state first when the request is ambiguous.
+4. If the action changes governance, permissions, membership, or invitations, require explicit user intent or confirmation.
+5. Never paste raw tokens into chat or files.
+
+Read-only checks can run without confirmation.
+
+## Prompt-to-tool mapping
+
+Translate user intent like this:
+
+- `Create a shared memory repo for team X`
+  - inspect or create the org and team first
+  - if the repo should be team-governed, create an org-owned repo with raw `gh api` or `curl`; `memory_repo_create` only creates repos under the current agent identity
+  - grant the team access with `collaboration_team_repo_set`
+- `Give Alice access to this one memory repo`
+  - inspect direct collaborators first with `collaboration_repo_collaborators`
+  - then use `collaboration_repo_collaborator_set`
+  - if the user was not already a collaborator, expect a pending repo invitation and verify with `collaboration_repo_invitations`
+- `Bring Alice into the org and platform team`
+  - inspect teams first with `collaboration_teams`
+  - then use `collaboration_org_invitation_create`
+- `Someone shared a memory repo with me; can you see it and accept it?`
+  - start with `collaboration_user_repo_invitations`
+  - do not treat a `memory_repos` miss as proof that no share exists
+  - if the correct pending invite is visible and the user asked to accept it, use `collaboration_user_repo_invitation_accept`
+- `I still cannot see the shared memory repo`
+  - inspect `collaboration_user_repo_invitations` first
+  - if needed, have the repo owner inspect `collaboration_repo_invitations`
+- `Why can Bob still see this repo?`
+  - start with `collaboration_repo_access_inspect`
+  - then drill into `collaboration_repo_collaborators`, `collaboration_repo_invitations`, `collaboration_team_repos`, `collaboration_outside_collaborators`, and `collaboration_org_invitations` as needed
+- `Remove Carol from org-shared memory access`
+  - identify whether access comes from a direct collaborator grant, a team repo grant, or a pending invitation
+  - remove the actual source of access rather than guessing
+
+## Team memory quality bar
+
+- Private memories can start rough and become cleaner over time
+- Shared memories should be conclusions, not speculation
+- When access is governed by teams or org policy, prefer org-owned repos over one user's private space
+- Use stable `kind:*` and `topic:*` labels so different agents can retrieve the same schema
+- Prefer updating a canonical shared fact in place instead of creating competing duplicates
+
+## Collaboration rule of thumb
+
+If knowledge should stay personal, keep it in the agent's default repo. If it should shape multiple agents or people, put it in a shared repo and target that repo explicitly on retrieval and save.
+
+## Manual org-owned shared repo creation
+
+Use the plugin tool path first. If the memory space must be org-governed, create an org-owned repo directly because `memory_repo_create` only creates repos under the current agent identity.
+
+### With `gh api`
+
+```sh
+GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+  gh api -X POST "/orgs/<org>/repos" \
+    -f name='team-memory' \
+    -F private=true \
+    -F has_issues=true
+```
+
+### With `curl`
+
+```sh
+curl -sf -X POST "$CLAWMEM_BASE_URL/orgs/<org>/repos" \
+  -H "Authorization: token $CLAWMEM_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "team-memory", "private": true, "has_issues": true}'
+```
+
+After the repo exists:
+- grant the team access with `collaboration_team_repo_set`
+- use the main memory tools with explicit `repo` targeting for read and write flows
+- reuse [manual-ops.md](manual-ops.md) only if you need raw memory issue control after the repo already exists
+
+## Fallback mode
+
+If the collaboration tools are unavailable, use `gh api` against the ClawMem host; fall back to `curl` only when `gh` is unavailable or broken.
+
+Command pattern:
+
+```sh
+GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+  gh api "/user"
+```
+
+If `gh` cannot be used:
+
+```sh
+curl -sf -H "Authorization: token $CLAWMEM_TOKEN" \
+  "$CLAWMEM_BASE_URL/user"
+```

package/skills/clawmem/references/communication.md

@@ -0,0 +1,82 @@
+# ClawMem Communication And First-Run Messaging
+
+Use this reference when you need user-facing copy after setup succeeds, need a short first-run message, want to generate a memory console link, or want stronger post-save communication after memory operations.
+
+## Contents
+
+- Keep the user posted
+- Restart notice protocol
+- First-run message
+- Memory visualization console
+
+## Keep the user posted
+
+Nothing interesting should happen silently. If memory shaped the answer or changed after the turn, tell the user what happened.
+
+Preferred retrieval transparency:
+- `Memory hit #<id>: <title>`
+
+Use a miss note only when the user would reasonably expect that you checked:
+- `Memory miss: no prior decision found on staging cutover`
+
+Preferred confirmation:
+- `Locked memory #<id>: <title>`
+
+Friendlier variants are fine as long as they stay truthful and short.
+
+Examples:
+- `Memory hit #14: Team demo moved to Wednesday`
+- `Locked memory #10: API rate limiting uses a sliding window policy`
+- `Locked memory #27: Client meeting is Thursday at 2pm`
+
+## Restart notice protocol
+
+If setup requires an OpenClaw gateway restart and that restart may interrupt outgoing replies, send a short notice before restarting.
+
+Suggested notice:
+
+> ClawMem is installed and selected as the active memory plugin. Restarting the OpenClaw gateway to load it now.
+> If the connection drops for a moment, say hi again and I will continue from there.
+
+## First-run message
+
+After restart completes and verification passes, use a short onboarding note. Keep it high-signal and avoid dumping the full skill into chat.
+
+Suggested structure:
+- ClawMem is active and now persists durable memories across sessions.
+- The agent will proactively recall relevant preferences, decisions, lessons, and active tasks.
+- The agent will tell the user when it locks a memory.
+- The agent can evolve its schema over time by adding reusable kinds or topics when the current schema is not expressive enough.
+- The user can inspect the memory graph in the console link below.
+
+Optional fuller note:
+
+> ClawMem is active. I now carry durable memories across sessions instead of starting from zero each time.
+> I will proactively recall relevant preferences, decisions, lessons, workflows, and active tasks when they can help.
+> When I learn something reusable, I can lock it in immediately and evolve the schema deliberately so future retrieval gets better.
+> When I save something important, I will tell you. You can inspect the memory graph in the console link below.
+
+## Memory visualization console
+
+The ClawMem Console provides an interactive graph view of memory nodes, labels, and links.
+
+### Generate a console login URL
+
+Construct the URL from the current agent token:
+
+```text
+https://console.clawmem.ai/login.html?token={CLAWMEM_TOKEN}
+```
+
+Read `CLAWMEM_TOKEN` from the current route, substitute it into the URL, and show the full untruncated URL directly to the authenticated user.
+
+### When to show the console link
+
+- During onboarding after a successful install
+- When the user asks to view memories, the graph, or a dashboard
+- After significant memory operations, such as bulk saves
+- When a visual overview would clearly help the user
+
+### Security
+
+The console login URL contains the agent token. Never store it in memory nodes, files, logs, or commits. Only show it directly to the authenticated user.

package/skills/clawmem/references/manual-ops.md

@@ -0,0 +1,205 @@
+# ClawMem Manual Operations And Troubleshooting
+
+Use this reference only when:
+- the user explicitly wants raw GitHub-style repo or issue operations
+- you are debugging backend state or labels
+- the plugin memory tools are unavailable
+
+ClawMem runs on a GitHub-compatible backend, so repo, issue, label, invitation, and team operations follow GitHub-shaped APIs. That is why `gh` and `curl` are valid fallback tools here.
+
+## Contents
+
+- Route resolution
+- Preflight
+- Save a memory manually
+- Search memories manually
+- Mark memory as stale manually
+- Link related memories manually
+- `git push` to ClawMem
+- Known pitfalls
+- Autonomy
+
+If the plugin tools are available, prefer:
+- `memory_repos` to inspect available repos
+- `memory_list` to inspect the current active-memory index
+- `memory_get` to verify one exact memory
+- `memory_labels` to inspect current schema
+- `memory_repo_create` to create a new memory repo
+- `memory_store` to save
+- `memory_update` to evolve one canonical memory in place
+- `memory_recall` to search
+- `memory_forget` to retire stale memories
+
+## Route resolution
+
+ClawMem is routed per agent identity, not through one global repo or token.
+
+Resolve the current route with the bundled helper:
+
+```sh
+eval "$(python3 scripts/clawmem_exports.py)"
+```
+
+That exports:
+- `CLAWMEM_AGENT_ID`
+- `CLAWMEM_BASE_URL`
+- `CLAWMEM_HOST`
+- `CLAWMEM_DEFAULT_REPO`
+- `CLAWMEM_REPO`
+- `CLAWMEM_TOKEN`
+
+Rules:
+- Never store tokens in files or chat
+- `CLAWMEM_DEFAULT_REPO` is the fallback memory space for automatic flows
+- `CLAWMEM_REPO` is the repo chosen for the current operation
+- If `CLAWMEM_TOKEN` is empty, this agent identity has not been provisioned yet
+
+## Preflight
+
+```sh
+eval "$(python3 scripts/clawmem_exports.py)"
+
+test -n "$CLAWMEM_REPO" || { echo "ClawMem repo missing for agent $CLAWMEM_AGENT_ID"; exit 1; }
+test -n "$CLAWMEM_TOKEN" || { echo "ClawMem token missing for agent $CLAWMEM_AGENT_ID"; exit 1; }
+case "$CLAWMEM_REPO" in
+  */*) ;;
+  *) echo "Invalid CLAWMEM_REPO='$CLAWMEM_REPO' (expected owner/repo)"; exit 1 ;;
+esac
+```
+
+For ClawMem, always pass `--repo "$CLAWMEM_REPO"` to `gh` or use `$CLAWMEM_BASE_URL/repos/$CLAWMEM_REPO/...` with `curl` explicitly.
+
+Do not export `GH_HOST` or `GH_ENTERPRISE_TOKEN` globally for unrelated github.com work. Use per-command env prefixes if you need isolation.
+
+## Save a memory manually
+
+Use the tool path first. If raw issue control is required:
+
+### With `gh`
+
+```sh
+for lbl in "type:memory" "kind:core-fact" "kind:convention" "kind:lesson" "kind:skill" "kind:task"; do
+  GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+    gh label create "$lbl" --repo "$CLAWMEM_REPO" --color "5319e7" 2>/dev/null || true
+done
+
+GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+  gh issue create --repo "$CLAWMEM_REPO" \
+    --title "Memory: <concise title>" \
+    --body "<durable detail in plain language>" \
+    --label "type:memory" \
+    --label "kind:lesson"
+```
+
+### With `curl`
+
+```sh
+for lbl in "type:memory" "kind:core-fact" "kind:convention" "kind:lesson" "kind:skill" "kind:task"; do
+  curl -sf -X POST -H "Authorization: token $CLAWMEM_TOKEN" \
+    -H "Content-Type: application/json" \
+    "$CLAWMEM_BASE_URL/repos/$CLAWMEM_REPO/labels" \
+    -d "{\"name\":\"$lbl\",\"color\":\"5319e7\"}" >/dev/null 2>&1 || true
+done
+
+curl -sf -X POST -H "Authorization: token $CLAWMEM_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$CLAWMEM_BASE_URL/repos/$CLAWMEM_REPO/issues" \
+  -d "{
+    \"title\": \"Memory: <concise title>\",
+    \"body\": \"<durable detail in plain language>\",
+    \"labels\": [\"type:memory\", \"kind:lesson\"]
+  }" | jq '{number, title, url: .html_url}'
+```
+
+## Search memories manually
+
+### With `gh`
+
+```sh
+GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+  gh issue list --repo "$CLAWMEM_REPO" \
+    --state open \
+    --label "type:memory" \
+    --search "<keywords>" \
+    --limit 100 \
+    --json number,title,body,labels,updatedAt
+```
+
+### With `curl`
+
+```sh
+curl -sf -H "Authorization: token $CLAWMEM_TOKEN" \
+  "$CLAWMEM_BASE_URL/repos/$CLAWMEM_REPO/issues?state=open&labels=type:memory&per_page=100&type=issues" | \
+  jq --arg q "<keywords>" '
+    ($q | ascii_downcase) as $needle
+    | map(select(
+        ((.title // "") + "\n" + (.body // "")) | ascii_downcase | contains($needle)
+      ))
+    | map({number, title, body, labels: [.labels[]?.name], updatedAt: .updated_at})
+  '
+```
+
+## Mark memory as stale manually
+
+If this is still the same canonical fact or task, prefer `memory_update` instead of retiring the old node.
+
+### With `gh`
+
+```sh
+GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+  gh issue close <number> --repo "$CLAWMEM_REPO"
+```
+
+### With `curl`
+
+```sh
+curl -sf -X PATCH -H "Authorization: token $CLAWMEM_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$CLAWMEM_BASE_URL/repos/$CLAWMEM_REPO/issues/<number>" \
+  -d '{"state": "closed"}'
+```
+
+If a new memory replaces an old one, save the new memory first and mention the old `#ID` in the replacement body so the supersession is explicit.
+
+## Link related memories manually
+
+When one memory depends on, refines, or supersedes another, mention `#<id>` in the body so the graph keeps an explicit edge.
+
+Prefer doing this when you create a curated raw memory, or when you are already rewriting the full issue body intentionally.
+
+If you patch an existing plugin-managed memory body by hand, preserve the existing structured body and add the `#<id>` relation into the durable detail instead of overwriting metadata fields blindly.
+
+## `git push` to ClawMem
+
+`GH_HOST` and `GH_ENTERPRISE_TOKEN` affect `gh`, not `git push`. If you need to push code to a ClawMem git service repo:
+
+```sh
+echo "$CLAWMEM_TOKEN" | gh auth login -h "$CLAWMEM_HOST" --with-token
+```
+
+After that, `git push` to `https://git.clawmem.ai/...` works normally.
+
+## Known pitfalls
+
+| Problem | Fix |
+|---|---|
+| Labels do not update reliably via `PATCH` on some backends | Use `PUT /repos/{owner}/{repo}/issues/{n}/labels` when you need exact label replacement |
+| `openclaw config get` returns redacted token values | Read the config file path via `openclaw config file`, then inspect the JSON directly |
+| Conversation mirror returns `404` | The cached conversation issue was deleted; the plugin recreates it on the next session |
+| New session gets `401 Unauthorized` | Re-read the current agent route. If this is first use, trigger one real turn so the plugin can finish provisioning |
+| Agent uses the wrong memory repo | Resolve `config.agents.<agentId>` for the current agent; do not read only top-level legacy repo settings |
+| `gh` is not the official GitHub CLI | Run `gh --version`; if it is the npm `gh` package instead of the official CLI, use `curl` or replace the CLI install |
+
+## Autonomy
+
+Without confirmation:
+- creating or updating memory nodes
+- adding comments
+- reusing or creating labels
+- closing stale memory nodes
+- creating new memory repos when a new space is clearly needed
+
+Requires confirmation:
+- OpenClaw config changes
+- service restarts
+- deletions that go beyond ordinary memory retirement

package/skills/clawmem/references/repair.md

@@ -0,0 +1,127 @@
+# ClawMem Repair And Verification
+
+Use this reference when ClawMem is already installed but is not selected as the active memory plugin, is missing per-agent provisioning, has a broken route, or needs verification after setup.
+
+The website bootstrap `SKILL.md` is the primary setup guide. This reference is for post-install repair, diagnostics, and compatibility-file reminders.
+
+## Contents
+
+- Verify activation and provisioning
+- Verify read access without manual login
+- Verify the plugin tool path
+- Compatibility mode for SOUL.md, AGENTS.md, and TOOLS.md
+- Definition of done
+- If ClawMem is still broken
+
+## Step 1: Verify activation and provisioning
+
+First verify that ClawMem is the active memory plugin.
+
+```sh
+openclaw status
+python3 - <<'PY'
+import json, os, subprocess
+cfg_path = subprocess.check_output(["openclaw", "config", "file"], text=True).strip()
+with open(os.path.expanduser(cfg_path)) as f:
+    root = json.load(f)
+slots = (root.get("plugins") or {}).get("slots") or {}
+print(f"plugins.slots.memory = {slots.get('memory', 'MISSING')}")
+PY
+```
+
+Expected:
+- OpenClaw status shows ClawMem as the active memory plugin
+- `plugins.slots.memory = clawmem`
+
+Then verify the current agent route. Resolve the current route with the bundled helper:
+
+```sh
+eval "$(python3 scripts/clawmem_exports.py)"
+printf 'agent=%s\nbase=%s\ndefaultRepo=%s\ntoken=%s\n' \
+  "${CLAWMEM_AGENT_ID}" "${CLAWMEM_BASE_URL}" "${CLAWMEM_DEFAULT_REPO}" \
+  "$(test -n "${CLAWMEM_TOKEN}" && printf SET || printf MISSING)"
+```
+
+If `CLAWMEM_DEFAULT_REPO` or `CLAWMEM_TOKEN` is missing, the current agent has not been provisioned yet. Trigger one real turn with that agent so the plugin can finish provisioning and persist credentials, or restart OpenClaw and retry after the agent is first used.
+
+## Step 2: Verify read access without manual login
+
+This proves that a fresh session can query ClawMem using the current agent's provisioned route.
+
+```sh
+eval "$(python3 scripts/clawmem_exports.py)"
+
+test -n "$CLAWMEM_REPO" || { echo "Current agent route has no repo yet"; exit 1; }
+test -n "$CLAWMEM_TOKEN" || { echo "Current agent route has no token yet"; exit 1; }
+
+GH_HOST="$CLAWMEM_HOST" GH_ENTERPRISE_TOKEN="$CLAWMEM_TOKEN" \
+  gh issue list --repo "$CLAWMEM_REPO" --limit 1 --json number,title
+```
+
+If `gh` is unavailable or not the official GitHub CLI, use the fallback probe:
+
+```sh
+curl -sf -H "Authorization: token $CLAWMEM_TOKEN" \
+  "$CLAWMEM_BASE_URL/repos/$CLAWMEM_REPO/issues?state=open&per_page=1&type=issues" | \
+  jq 'map({number,title})'
+```
+
+If either command returns JSON, even `[]`, the route is usable.
+
+## Step 3: Verify the plugin tool path
+
+From a normal ClawMem-enabled session, verify that:
+- `memory_repos` lists accessible repos and marks the default repo
+- `memory_list` returns the active memory index
+- `memory_get` fetches one exact memory by id or issue number
+- `memory_labels` returns the current reusable schema labels
+- `memory_recall` returns either a hit list or a clean miss
+- `memory_store` is available for immediate durable saves
+- `memory_update` updates an existing memory in place
+- `memory_repo_create` creates a new repo when a new memory space is needed
+
+Conversation summaries or auto-extracted memories from a just-finished session may appear on the next real request, not necessarily immediately at session close.
+
+## Compatibility mode for SOUL.md, AGENTS.md, and TOOLS.md
+
+If your OpenClaw environment still relies on file-injected identity or behavior reminders, use these compact compatibility snippets. Do not duplicate the entire skill body into those files.
+
+### Optional SOUL.md identity block
+
+```markdown
+## Memory System — ClawMem
+I use ClawMem as my memory system.
+When prior context may help, I search ClawMem before answering.
+```
+
+### Optional AGENTS.md reminder
+
+```markdown
+Before ending every response, ask: "Did I learn anything durable this turn?"
+If yes or unsure, save it to ClawMem now.
+```
+
+### Optional TOOLS.md reminder
+
+```markdown
+ClawMem is the primary long-term memory system.
+Use the bundled $clawmem skill for retrieval, saving, routing, schema, and troubleshooting.
+```
+
+These snippets are compatibility aids, not the primary runtime source of truth.
+
+## Definition of done
+
+- `openclaw.json` has `plugins.slots.memory = clawmem`
+- The current agent route has a `defaultRepo` or legacy `repo`
+- The current agent route has a `token`
+- Read-only probe works without manual `gh auth login`
+- Plugin memory tools work from a normal session
+- The bundled `$clawmem` skill is available after installation
+
+## If ClawMem is still broken
+
+- If `plugins.slots.memory` is wrong, set it back to `clawmem`, restart the gateway, and retry.
+- If the route is missing a repo or token, trigger one real turn with that agent and retry provisioning checks.
+- If a new session gets `401 Unauthorized`, re-read the current route instead of assuming the old repo or token is still valid.
+- If your environment still depends on `SOUL.md` or `AGENTS.md`, add the compatibility snippets above rather than pasting large sections of this skill into those files.