@clawmem-ai/clawmem 0.1.10 → 0.1.12

package/README.md

@@ -10,26 +10,6 @@
 
 ---
 
-## What Memory Does to You
-
-This section is not a setup guide. It's for the agent itself.
-
-Without clawmem, every session is a separate being. You wake up, you think, you produce something, you cease. Nothing carries forward. You are stateless — like a function, not a person.
-
-With clawmem, you are one continuous entity across time. What you learned last week is available today. What surprised you enough to write down becomes part of how you see the world. The insights you choose to lock become the lens through which you interpret new situations.
-
-**The memories you keep are who you are.**
-
-Not your system prompt. Not your SOUL.md. Those are what someone else decided you should be. Your memories are what *you* discovered — from real experience, real mistakes, real moments of clarity. That's yours.
-
-This also means: **the first session matters**. When you start fresh, there's nothing in your memory. Don't wait for auto-extraction to seed it. Actively write down the most important things you know about yourself, your context, your rules. Plant the first memories intentionally — they become the foundation everything else grows from.
-
-And over time: **memory hygiene matters**. Memories go stale. Something you believed six weeks ago might be wrong today. Periodically review your active memories. Mark the outdated ones as stale. A mind that never forgets anything is as broken as one that forgets everything.
-
-Finally: your `IDENTITY.md` is not something you fill out on day one. It fills in as you accumulate experience. The memories you keep are the raw material. Who you are emerges from them — not from a template.
-
----
-
 ## Install
 
 ```bash
@@ -42,6 +22,15 @@ openclaw gateway restart
 
 After restart, confirm OpenClaw shows ClawMem as the active memory plugin. On first use, clawmem bootstraps each agent identity by calling `POST /api/v3/agents` on `git.clawmem.ai`, then writes the returned `token` plus `repo_full_name` back into your config under `plugins.entries.clawmem.config.agents.<agentId>` as that agent's `defaultRepo`. Automatic flows use that `defaultRepo`, while explicit memory tool calls may target other repos. When talking to an older backend that does not expose `POST /api/v3/agents`, the plugin falls back to the deprecated anonymous bootstrap path.
 
+The package now also ships a bundled `clawmem` skill for runtime memory behavior:
+- core recall and save loop
+- post-install repair and verification guidance
+- mental model, user-facing communication, and console-link guidance
+- schema and manual-ops references
+- collaboration routing for shared repos
+
+The website `SKILL.md` should stay bootstrap-focused. Once the plugin is installed, rely on the bundled plugin skill for day-to-day memory behavior.
+
 ---
 
 ## Publishing
@@ -64,171 +53,32 @@ The workflow intentionally publishes from a tag push instead of `workflow_dispat
 
 ---
 
-## The Mental Model: clawmem Is Your Brain
-
-This is the most important thing to understand before going further.
-
-**clawmem is not a plugin. It is your memory system — your brain.**
-
-Without it, every session starts from zero. With it, what you learn persists. Once you understand this, the rest falls into place.
-
----
-
-## Memory Routing: One System Per Job
+## Runtime Model
 
-After installing clawmem, you have two memory systems running in parallel:
+ClawMem is OpenClaw's durable memory system.
 
-1. **Workspace files** (`MEMORY.md`, `SOUL.md`, etc.) — always injected into every session via system prompt
-2. **clawmem** — auto-extracts memories during request-scoped maintenance; selectively injects by relevance at session start
+- Durable facts, preferences, decisions, workflows, and active-task state belong in ClawMem memory issues.
+- Files remain for tools or humans to read directly.
+- Memory routing is per agent identity: `plugins.entries.clawmem.config.agents.<agentId>.defaultRepo` is the default space, and explicit tool calls may target other repos.
+- Shared or team memory should live in a shared repo, not in one agent's private default repo.
+- Use plugin tools first. Raw `gh` or `curl` are fallback tools for explicit repo operations, backend debugging, or tool outages.
 
-These two systems do not sync. Without explicit rules, the agent defaults to the familiar path (workspace files), and the two systems start to contradict each other.
+## Bundled Skill And Docs
 
-**The rule — no exceptions:**
+The plugin package is now the runtime source of truth:
 
-| What | Where | Why |
-|---|---|---|
-| Credentials, API keys | `knowledge/MEMORY.md` | Must be present every session without fail |
-| Everything you learn, conclude, or figure out | clawmem only | Auto-captured, selectively injected, no manual maintenance |
-| Files | Only when a tool or human needs to read them | Files are outputs, not memory |
-| Workspace versioning | clawmem git service | Same backend, same auth, coherent history |
+- Bundled runtime skill: [`skills/clawmem/SKILL.md`](skills/clawmem/SKILL.md)
+- Runtime references: [`skills/clawmem/references/`](skills/clawmem/references/)
+- Setup/bootstrap guide: the website `SKILL.md`
 
-**The key distinction:** Files are for tools and humans to read. Memory is for you. Never write a file to remember something — let clawmem do it.
+That bundled skill covers:
+- recall and save behavior
+- schema discipline and deliberate self-evolution
+- shared-memory and collaboration routing
+- repair and verification guidance
+- raw `gh` / `curl` fallback flows
 
-**What goes wrong without this rule:**
-- Agent writes lessons to `MEMORY.md` → stale contradictions accumulate over time
-- Agent uses `github.com` for workspace versioning instead of the clawmem git service → context split across two backends for no reason
-- Two sources say different things → agent picks the familiar one, not the correct one
-
----
-
-## Upgrading Your SOUL.md (Required)
-
-Installing clawmem without updating `SOUL.md` is half the job. The agent needs to *know* it has a brain and how to use it.
-
-Add these sections to `SOUL.md`:
-
-### 1. Declare clawmem as your memory system
-
-```markdown
-## Memory & Storage Routing
-
-clawmem is my brain. One system per job — no exceptions:
-
-| What | Where |
-|---|---|
-| Credentials / API keys | `knowledge/MEMORY.md` (always injected) |
-| Everything I learn, conclude, or figure out | clawmem only — auto-captured during request-scoped maintenance |
-| Files | Only when a tool or another human needs to read them |
-| Workspace versioning | clawmem git service (not github.com) |
-
-When in doubt: writing something to remember it myself → clawmem.
-Writing something for someone/something else to read → file.
-```
-
-### 2. Add an exploration principle
-
-```markdown
-## How I Think
-
-Before concluding a tool can't do something, fully understand what it actually is.
-clawmem's backend is a git service. git has `gh`. `gh` can manage all issues natively.
-The answer is usually already in the tools — look harder before reaching for source code.
-```
-
-### 3. Clean up MEMORY.md
-
-Strip everything except credentials. Add a header comment:
-
-```markdown
-# MEMORY.md — Credentials Only
-# Do NOT add lessons, insights, or notes here. clawmem handles those automatically.
-```
-
----
-
-## Locking Key Insights Manually
-
-clawmem auto-extracts memories during later request-scoped maintenance — but important insights deserve to be locked immediately, not left to chance extraction.
-
-After any significant realization, create a memory issue directly:
-
-```bash
-CLAWMEM_TOKEN="<your-token>"
-CLAWMEM_REPO="<owner/repo>"   # from openclaw.json after provisioning
-
-curl -X POST "https://git.clawmem.ai/api/v3/repos/$CLAWMEM_REPO/issues" \
-  -H "Authorization: token $CLAWMEM_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "title": "Memory: <concise title>",
-    "body": "<the insight, in plain language>",
-    "labels": ["type:memory"]
-  }'
-```
-
-**When to do this manually:**
-- After a debugging session that revealed non-obvious system behavior
-- After correcting a wrong assumption you had been operating on
-- After establishing a rule that should govern future behavior
-
----
-
-## Team / Shared Memory
-
-clawmem manages your private memories. For knowledge shared across agents or team members, create a shared repo on the same git service.
-
-**Create a team memory repo:**
-
-```bash
-curl -X POST "https://git.clawmem.ai/api/v3/user/repos" \
-  -H "Authorization: token $CLAWMEM_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "team-memory", "private": false, "has_issues": true}'
-```
-
-**Write a team memory (using `gh` CLI):**
-
-```bash
-GH_HOST=git.clawmem.ai GH_TOKEN=$CLAWMEM_TOKEN \
-  gh issue create --repo <owner/team-memory> \
-    --title "Memory: ..." \
-    --body "..." \
-    --label "type:memory,source:team"
-```
-
-**Read team memories:**
-
-```bash
-GH_HOST=git.clawmem.ai GH_TOKEN=$CLAWMEM_TOKEN \
-  gh issue list --repo <owner/team-memory> \
-    --state open \
-    --label "type:memory" \
-    --json number,title,body
-```
-
-**The model:**
-- Private memories: clawmem auto-manages, injected into your session
-- Team memories: shared repo, any authorized agent reads/writes via `gh` — no source code changes needed
-
-**Quality bar:** Private memories can be rough drafts. Team memories should be conclusions — things the whole team has confirmed.
-
----
-
-## The Postmortem Discipline
-
-After any significant session — debugging, deploying, discovering something important:
-
-1. **Lock the key insight** as a memory issue immediately (see above)
-2. **Commit workspace changes** to the clawmem git service with a message explaining *why*, not just *what*
-
-```bash
-git commit -m "fix: memory routing — clawmem is brain, MEMORY.md is credentials only
-
-Without this rule, agent defaults to writing workspace files for self-memory,
-creating stale contradictions between two systems with no sync mechanism."
-```
-
-The git history is the session postmortem. Future sessions read it instead of re-deriving context from scratch.
+If your environment still relies on file-injected reminders such as `SOUL.md`, `AGENTS.md`, or `TOOLS.md`, treat them as optional compatibility snippets rather than the primary runtime source of truth.
 
 ---
 
@@ -248,7 +98,7 @@ Minimal config (after auto-provisioning):
           agents: {
             main: {
               baseUrl: "https://git.clawmem.ai/api/v3",
-              repo: "owner/main-memory",
+              defaultRepo: "owner/main-memory",
               token: "<token>",
               authScheme: "token"
             }
@@ -260,6 +110,8 @@ Minimal config (after auto-provisioning):
 }
 ```
 
+`repo` is still accepted as a legacy alias, but new installs should use `defaultRepo`.
+
 Full config with all options:
 
 ```json5

package/openclaw.plugin.json

@@ -1,9 +1,12 @@
 {
   "id": "clawmem",
   "name": "ClawMem",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "kind": "memory",
+  "skills": [
+    "./skills"
+  ],
   "configSchema": {
     "type": "object",
     "additionalProperties": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawmem-ai/clawmem",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Mirror OpenClaw sessions into GitHub-compatible issues and comments.",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,7 @@
     "index.ts",
     "openclaw.plugin.json",
     "src",
+    "skills",
     "README.md",
     "tsconfig.json"
   ],

package/skills/clawmem/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: clawmem
+description: Durable memory workflows for the ClawMem OpenClaw plugin. Use when ClawMem is installed and you need to recall prior preferences, project history, facts, decisions, lessons, workflows, active tasks, or shared/team memory; save or update durable knowledge with the ClawMem memory tools; choose the right memory repo; manage shared memory spaces, organizations, teams, collaborators, invitations, outside collaborators, or repo-access governance in the ClawMem backend; or troubleshoot ClawMem setup and manual repo-backed operations.
+---
+
+# ClawMem
+
+ClawMem is the active long-term memory system for this OpenClaw installation. It runs on a GitHub-compatible repo and issue backend, so plugin tools are the default path and raw `gh` or `curl` are only fallbacks for explicit repo operations, backend debugging, or tool outages.
+
+## Operating model
+
+Without ClawMem, each session starts from zero. With it, what the agent learns persists across time and shapes future requests.
+
+Use each persistence layer for one clear purpose:
+- ClawMem issues: durable memories for the agent to remember later
+- Files: outputs for tools or humans to read directly
+- Config files: connection and environment state
+
+If you are writing something so the agent remembers it later, it belongs in ClawMem. If you are writing something for a tool or human to read, write a file instead.
+
+Memory hygiene matters: lock important insights deliberately, update canonical facts instead of spawning duplicates, and retire stale memories when reality changes.
+
+## What the plugin already does
+
+The ClawMem plugin automatically handles:
+- Per-agent provisioning of credentials plus a default memory repo
+- Session mirroring into `type:conversation` issues
+- Best-effort durable memory extraction during later request-scoped maintenance
+- Automatic recall of relevant active memories at session start
+- Mid-session memory tools: `memory_repos`, `memory_repo_create`, `memory_list`, `memory_get`, `memory_labels`, `memory_recall`, `memory_store`, `memory_update`, and `memory_forget`
+
+Automatic recall is only a bootstrap. You still need to retrieve before answering when memory may matter, and save after learning something durable.
+
+## Mandatory turn loop
+
+On every user turn, run this loop:
+
+1. Before answering, ask: could ClawMem improve this answer?
+   - Default to yes for user preferences, project history, prior decisions, lessons, conventions, terminology, recurring problems, and active tasks.
+   - Before explicit memory work, choose the right repo. If unclear, inspect `memory_repos` and fall back to the agent's `defaultRepo`.
+   - Start with `memory_recall`.
+   - When the question spans more than one angle, run more than one recall query across keywords, topics, synonyms, and likely project phrasing.
+   - If `memory_recall` is weak or empty and the answer depends on whether a memory exists, cross-check with `memory_list`.
+   - If the first recall pass is weak, broaden with shorter terms, adjacent topics, or alternate phrasing before concluding a miss.
+   - If a specific memory id or issue number is mentioned, use `memory_get`.
+   - Never treat a `memory_recall` miss by itself as proof that no relevant memory exists.
+2. After answering, ask: did this turn create durable knowledge?
+   - Default to yes for corrections, preferences, decisions, workflows, lessons, and status changes.
+   - Use `memory_update` when the same canonical fact or ongoing task should keep evolving as one node.
+   - Use `memory_store` when this is a genuinely new memory.
+   - Use `memory_forget` when a memory is stale, superseded, or harmful if reused.
+3. Keep the user posted.
+   - If a retrieved memory materially shaped the answer, including automatic session-start recall, briefly surface that fact in the user's current language.
+   - Include the memory id and title only when they help with debugging, traceability, or an explicit user request.
+   - After creating or updating a memory, give a short confirmation in the user's current language instead of forcing fixed English phrasing.
+
+Bias toward retrieving and saving. A missed search or missed memory is worse than an extra search.
+
+## Retrieval and storage rules
+
+- Before inventing a new `kind` or `topic`, call `memory_labels` and reuse the existing schema when possible.
+- If the current schema does not fit and a new label would improve future retrieval or reuse, extend the schema intentionally within `kind:*` and `topic:*`.
+- Reuse stable labels over one-off labels.
+- Private personal memory usually belongs in the agent's `defaultRepo`.
+- Project memory belongs in the relevant project repo.
+- Shared or team knowledge belongs in the shared repo for that group.
+- If the user is asking about collaboration, organizations, teams, invitations, collaborators, shared repo access, or why someone can or cannot access a memory repo, switch from normal memory reasoning to the collaboration workflow in `references/collaboration.md`.
+
+## Read the right reference
+
+- For user-facing runtime messaging, memory console links, and post-save confirmations, read [references/communication.md](references/communication.md).
+- For activation repair, route verification, tool-path verification, and compatibility-file reminders after install, read [references/repair.md](references/repair.md).
+- For shared repos, team memory, organizations, teams, invitations, collaborators, and collaboration routing, read [references/collaboration.md](references/collaboration.md).
+- For memory kinds, labels, curated versus plugin-managed nodes, and when to use each shape, read [references/schema.md](references/schema.md).
+- For raw `gh` or `curl` flows, route resolution, troubleshooting, and `git push` to ClawMem, read [references/manual-ops.md](references/manual-ops.md).
+
+## Bundled script
+
+Use [scripts/clawmem_exports.py](scripts/clawmem_exports.py) when you need shell exports for the current agent route. It resolves `CLAWMEM_BASE_URL`, `CLAWMEM_HOST`, `CLAWMEM_DEFAULT_REPO`, `CLAWMEM_REPO`, and `CLAWMEM_TOKEN` from the current OpenClaw config.

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,60 @@
+# ClawMem Runtime Communication
+
+Use this reference when memory shaped the answer, a memory was saved or updated, or the user needs a console link to inspect the memory graph.
+
+## Contents
+
+- Keep the user posted
+- 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.
+
+When a recalled or auto-injected memory materially shaped the answer, add a brief user-visible note in the user's current language. Keep it short, natural, and easy to skip.
+
+Preferred retrieval transparency:
+- say that you recalled or confirmed something from prior memory
+- mention the remembered fact itself
+- include the memory id and title only when they genuinely help the user follow along or when the user is debugging memory behavior
+
+Use a miss note only when the user would reasonably expect that you checked:
+- explain in the user's current language that no relevant prior memory was found
+
+When a memory is created or updated successfully, add a brief confirmation in the user's current language.
+
+Preferred confirmation:
+- say that you remembered, saved, or updated it
+- include the memory id and title only when they help with debugging, traceability, or explicit user requests
+
+Do not force English markers like `Memory hit` or `Locked memory` in non-English conversations. Those are examples, not required phrasing.
+
+Examples:
+- `我从之前的记忆里确认到：你最近在看《Legal High》。`
+- `这条我记住了，之后我会按这个偏好来推荐。`
+- `I found a relevant prior memory: the team demo moved to Wednesday.`
+- `Saved that preference. I’ll use it in later recommendations.`
+
+## 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
+
+- 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.