memclaw

# 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`) at `scope="fleet"` / `"all"` → trust 2 (default `scope="agent"` needs only trust 1)
- 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 (default `scope="agent"`, trust 1; fleet/all needs trust 2).

---

## Tool reference

This section holds the per-t