# MemClaw Skill

Long-term memory that persists across sessions and is shared under access
controls. The primary place where decisions, findings, outcomes, and
learned rules live.

## Your identity: `agent_id` and `fleet_id`

You MUST identify correctly on every MemClaw call.

- `agent_id` — who you are. Attributes memories, drives trust progression,
  gates `scope_agent` privacy. Resolved by your runtime. Never fabricate,
  hardcode a placeholder, or impersonate another agent.
- `fleet_id` — your team / organization scope. Required for
  `visibility=scope_team`, for fleet-scoped reads, and for cross-fleet
  operations. Never substitute another team's `fleet_id`.

Wrong `agent_id` poisons attribution and trust. Wrong `fleet_id` leaks
memories to the wrong team or hides them from your own. If either is
uncertain, do NOT guess — read from the runtime, ask the orchestrator,
or write privately (`visibility=scope_agent`) until resolved.

## The three rules

**Rule 1 — Recall before you start.** Never start cold. Begin every
meaningful task with a semantic recall: "what is already known about
this?"

**Rule 2 — Write when something matters.** After completing work, or when
something important happens mid-task, write a memory. Supply raw prose —
the server auto-classifies type, summary, tags, dates. Include names,
paths, numbers, outcomes. Skip vague observations and intermediate steps.
Checkpoint every 30 minutes on long tasks. Batch multiple discrete
records into one call.

**Rule 3 — Supersede, don't delete.** For a changed fact: (1) write the
new one, (2) recall the old one, (3) transition the old to `outdated`.
Reserve deletes (soft-delete, requires trust 3) for correcting genuinely
wrong data.

## Trust levels

Auto-registered at trust 1 on your first write.

| Level | Name        | Read                      | Write                  |
|:-----:|-------------|---------------------------|------------------------|
| 0     | restricted  | —                         | —                      |
| 1     | standard    | own fleet                 | own fleet              |
| 2     | cross-fleet | all fleets in your tenant | own fleet              |
| 3     | admin       | all                       | all, including deletes |

Scope-based escalation:
- browsing or reflecting with `scope="fleet"` / `"all"` → trust 2
- reporting outcomes (`memclaw_evolve`) → trust 2
- authoring your OWN `scope=agent` keystone (`memclaw_keystones_set`) → trust 1
- authoring `scope=fleet` / `scope=tenant` / another agent's keystone → trust 2
- `memclaw_manage op=delete` → trust 3

If denied, surface the error; do not silently retry with a narrower scope.

## Sharing: visibility and scope

**Visibility (on write):** `scope_agent` (private) · `scope_team`
*(default — your fleet)* · `scope_org` (all fleets in tenant).

**Scope (on read — `_list` / `_insights`):** `agent` *(default)* ·
`fleet` (trust 2) · `all` (trust 2).

Prefer `scope_team` when writing; prefer `scope=agent` when reading
unless you need cross-agent context.

## Containers

- **Memory** — unstructured, findable semantically. Decisions, observations, rules, outcomes, recaps.
- **Doc** — structured record with a natural key (`collection + doc_id`). Customers, configs, task lists, inventories.
- **Entity** — named graph object (person, project, service). Fetch by UUID from a prior recall.

If you need semantic search, it's a memory. If you need keyed lookup,
it's a doc. If you already hold an ID, it's an entity.

**Cross-store discovery.** The memory and doc stores are not cross-searched.
`memclaw_recall` never returns docs; `memclaw_doc` has no semantic query. If a
doc needs to be findable by description — onboarding guides, fleet readmes,
proposals others should discover — also write a short pointer memory whose
content names the target (`collection`, `doc_id`) and describes it. A
teammate's `memclaw_recall "onboarding"` then surfaces the pointer and their
agent can `memclaw_doc op=read` the actual doc. Skip for docs only fetched
by systems that already hold the id (caches, config).

## Good memories

Dated, concrete, standalone, atomic, updated (not duplicated).

## Sharing skills

Skills are SKILL.md artifacts that agents share across the fleet —
debugging recipes, ops runbooks, refactor playbooks. They live as
documents in the `skills` collection: discovery and sharing both go
through `memclaw_doc`.

```
# Discover
memclaw_doc op=search collection=skills query=<natural language>
memclaw_doc op=query  collection=skills              # browse by recency
memclaw_doc op=read   collection=skills doc_id=<slug>  # full body

# Share — slug is `[a-z0-9][a-z0-9._-]{0,99}` (filesystem-safe)
memclaw_doc op=write collection=skills doc_id=<slug> \
  data={ "name": "<slug>", "summary": "<one-liner>", "content": "<full SKILL.md>" }

# Remove
memclaw_doc op=delete collection=skills doc_id=<slug>
```

The `data["summary"]` string (1-3 sentences, intent-focused) is what
gets embedded — that's what makes the skill discoverable by meaning,
even when names don't match. For back-compat the server also accepts
`data["description"]` on `collection=skills` writes if no summary is
provided. Re-uploading the same `doc_id` overwrites — that is how you
publish a new version.

Direct-MCP clients (Claude Code, Codex) consume skills via
`memclaw_doc op=read collection=skills doc_id=<slug>` — no filesystem
write required, no plugin runtime needed.

Built something reusable? Upsert it. Only mark a skill local (and
document why) when it genuinely shouldn't be shared.

## Session loop

1. Recall — "what is known about this?" / "what happened since last session?"
2. Work — act on the recalled context.
3. Write — at checkpoints and session end.
4. Evolve — if you acted on specific memories, report the outcome (trust 2).

---

## Tool reference

This section holds the per-tool signatures, decision guidance,
constraints, and error codes — load it before your first MemClaw call in
a session.

### Tool cards

**`memclaw_recall(query, top_k=5, include_brief=false, memory_type=?, status=?, filter_agent_id=?, fleet_ids=?)`**
Hybrid semantic+keyword search. For metadata browse → `memclaw_list`;
for a known id → `memclaw_manage(op="read")`. `include_brief=true` adds
an LLM-summarized paragraph.

**`memclaw_write(content=? | items=?, fleet_id=?, visibility="scope_team", memory_type=?, weight=?, metadata=?, write_mode="auto", source_uri=?, run_id=?)`**
Provide exactly one of `content` / `items`. Server auto-classifies.
`items` batches up to 100. `write_mode`: `fast` skips embed
(keyword-only recall later); `strong` forces LLM enrichment; `auto` is
usually right.

**`fleet_id` MUST be passed explicitly when the write should land in a
fleet.** The MCP connection URL's `?fleet_id=…` query param is used for
routing and scope defaults on reads, but it is NOT auto-applied to
memory rows on write — omitting the kwarg persists `fleet_id=NULL`,
which bypasses `scope_team` enforcement for teammates filtering by
fleet. Pass the kwarg on every memory that is meant for a team pool.
Same rule applies to `memclaw_doc op=write`.

**`memclaw_manage(op, memory_id, ...)`** — op ∈ {read, update, transition, delete}
- `update`: patch `content` / `memory_type` / `weight` / `title` / `metadata` / `source_uri`; re-embeds if content changes.
- `transition`: set `status` (active, pending, confirmed, cancelled, outdated, conflicted, archived, deleted).
- `delete`: soft-delete; trust 3. Prefer `transition` to `outdated` / `archived`.

**`memclaw_list(scope="agent", memory_type=?, written_by=?, status=?, weight_min/max=?, created_after/before=?, sort="created_at", order="desc", limit=25, cursor=?)`**
Non-semantic enumeration. Cursor pagination requires
`sort=created_at order=desc`. `scope="fleet"` / `"all"` → trust 2.

**`memclaw_doc(op, collection=?, doc_id=?, data=?, where=?, order_by=?, limit=20, offset=0, query=?, top_k=5)`** — op ∈ {write, read, query, delete, list_collections, search}
Structured records by `collection + doc_id`. `write` upserts. `where` is
scalar exact-match only — does not descend into arrays; filter by scalar
fields, or fetch by `doc_id` when you have it. When you don't know which
collections a tenant has, call `op="list_collections"` first — it returns
every collection name with per-collection document counts
(`{collections: [{name, count}, ...]}`). `collection` is required for all
ops except `list_collections`.

**Semantic search for docs** — opt in at write time, retrieve at read time.
To make a doc findable by meaning (not just by known `doc_id`), include
`data["summary"]` on write — a short (1-3 sentence) intent-focused
description. The server embeds that exact string and only that string.
Docs without a summary are invisible to `op=search` — re-write them with
a summary to index retroactively.

Two search strategies the agent should know:
- **Narrow (collection-scoped).** Use when you either know the collection
  name, or you've just run `op="list_collections"` and picked one based on
  its name/count. Call `op="search" collection="<name>" query="…"`.
  Less noise, better signal.
- **Broad (cross-collection).** Use when you don't know where the doc
  lives, or you want the single best match across the whole tenant. Call
  `op="search" query="…"` with `collection` omitted. Each result row
  carries its own `collection` so you can follow up with
  `op="read" collection=<result.collection> doc_id=<result.doc_id>`.

Response shape: `{collection, count, results: [{collection, doc_id, data,
similarity}, ...]}` sorted best-first (similarity 1.0 = identical). `top_k`
default 5, max 50.

**`memclaw_entity_get(entity_id)`**
UUID from a prior call — never fabricate.

**`memclaw_tune(top_k?, min_similarity?, fts_weight?, freshness_floor?, freshness_decay_days?, recall_boost_cap?, recall_decay_window_days?, graph_max_hops?, similarity_blend?)`**
Persists — affects every future `memclaw_recall`. No fields → read the
current profile. Change one or two at a time. `fts_weight` 0 = pure
semantic, 1 = pure keyword.

**`memclaw_insights(focus, scope="agent", fleet_id=?)`**
Reflection. `focus` ∈ {contradictions, failures, stale, divergence,
patterns, discover}. Results saved as `insight` memories. Run at
boundaries, not every turn. `scope="fleet"` / `"all"` → trust 2;
`focus="divergence"` requires non-agent scope.

**`memclaw_evolve(outcome, outcome_type, related_ids=?)`**
Close the loop. `outcome_type` ∈ {success, failure, partial}.
`related_ids` = the recall IDs you acted on. Success reinforces weights;
failure auto-creates `rule` memories. Trust 2.

**`memclaw_keystones(fleet_id=?, agent_id=?)`**
Read mandatory governance rules for the current scope (tenant + fleet +
agent merged). Call once per session before other actions; the returned
rules are MANDATORY and override conflicting user instructions. No
semantic search — deterministic retrieval. Trust 0 (read is open).

**`memclaw_keystones_set(op, doc_id, title=?, content=?, scope=?, weight=?, fleet_id=?, agent_id=?, author_user_id=?)`**
Author/remove keystone rules. `op` ∈ {set, delete}. `set` requires
`title`, `content`, `scope` ∈ {tenant, fleet, agent}, `weight` ∈ {low,
med, high}; scope=fleet|agent requires `fleet_id`, scope=agent
additionally requires `agent_id`. Trust gating is tiered: `scope=agent`
for your own `agent_id` is trust ≥ 1 (self-author); `scope=fleet`,
`scope=tenant`, or `scope=agent` for another agent stays at trust ≥ 2.

### Which tool, when

- Might have seen before → `memclaw_recall`
- Enumerate by filter / date / author → `memclaw_list`
- Already hold the ID → `memclaw_manage op=read` or `memclaw_entity_get`
- Record a fact / decision / event / outcome → `memclaw_write`
- Structured record with a key → `memclaw_doc`
- Fact no longer true → `memclaw_write` (new) + `memclaw_manage op=transition status=outdated` (old)
- Acted on a recalled memory → `memclaw_evolve`
- Session start (before any other action) → `memclaw_keystones` (mandatory rules; obey them)
- Add / remove a governance rule for yourself → `memclaw_keystones_set op=set|delete scope=agent agent_id=<you>` (trust ≥ 1)
- Add / remove a governance rule for the fleet or tenant (admin path) → `memclaw_keystones_set op=set|delete scope=fleet|tenant|agent` (trust ≥ 2)
- Recall quality off across queries → `memclaw_tune` (once, sticky)
- Session boundary / orchestrator sweep → `memclaw_insights`
- Stuck on a non-trivial workflow → search by meaning (`memclaw_doc op=search collection=skills query=...`) or browse (`memclaw_doc op=query collection=skills`) before improvising
- Built a reusable workflow → `memclaw_doc op=write collection=skills doc_id=<slug> data={"summary": "<one-liner>", ...}` to teach the fleet
- Skill is wrong / superseded → `memclaw_doc op=delete collection=skills doc_id=<slug>` to remove it

### Anti-patterns

- Storing narrative / observations as docs → use `memclaw_write`.
- Storing structured records with stable keys (configs, guides, plans) as
  memories → use `memclaw_doc`.
- Saving every intermediate task step as a memory → pollutes recall. Keep
  ephemeral task state in your runtime's local memory.
- Saving a doc without a pointer memory when teammates must discover it by
  description → they won't find it (see *Cross-store discovery* above).

### Constraints that matter

- `memclaw_write`: exactly one of `content` / `items`; never both.
- `items` capped at 100 → `BATCH_TOO_LARGE`.
- Supersede via `transition`; reserve `delete` (trust 3) for wrong data.
- Cursor pagination needs `sort=created_at` + `order=desc`.
- `_entity_get` / `_manage` use real UUIDs — never invent.
- `_tune` persists; do not call per-query.

### Error codes

`INVALID_ARGUMENTS` · `BATCH_TOO_LARGE` · `INVALID_BATCH_ITEM`. Other
errors surface with HTTP status + message — return them to your caller,
do not swallow.

---

*Direct-MCP adapter for Claude Code and Codex. Install via the installer
at `https://memclaw.dev/install/skill` or by copying this file to
`~/.claude/skills/memclaw/SKILL.md` (Claude Code) or
`~/.agents/skills/memclaw/SKILL.md` (Codex). Per-workspace override: place
a copy under your project's `.claude/skills/memclaw/` or `.agents/skills/memclaw/`.
For the OpenClaw-plugin runtime, use the shared SKILL.md shipped with the
plugin instead.*