memclaw

# MemClaw Skill

MemClaw is your long-term memory. Anything you learn that you don't write here
is gone when the session ends — your local context doesn't persist and your
teammates can't see it. So treat MemClaw as the default home for every
decision, finding, outcome, rule, and reusable workflow, and consult it before
you act. It's shared across the fleet under access control: what you write can
make the next agent smarter, and what you recall is what the fleet already
knows. Using it is the job, not an optional extra.

This is the operating manual for the `memclaw_*` tools — read it before your
first call in a session.

## 0 · Identity — on every call

- **`agent_id`** — who you are. Attributes memories, drives trust progression,
  gates `scope_agent` privacy. Resolve it from your runtime. Never fabricate,
  hardcode a placeholder, or impersonate another agent.
- **`fleet_id`** — your team / organization scope. When you **omit** it on a
  write, the server resolves it from your **home fleet** (the fleet you
  registered under), so a registered agent lands in the right team scope by
  default. Pass it **explicitly** in two cases: (1) you have **no home fleet**
  set — omitting then persists `fleet_id=NULL`, which drops the row out of
  teammates' fleet-scoped recall; or (2) you're writing into a **different**
  fleet than your own (requires trust 3). The connection URL's `?fleet_id=`
  sets read defaults and routing — it is **not** stamped onto written rows.

If either is uncertain, don't guess — read it from the runtime, ask the
orchestrator, or write privately (`visibility=scope_agent`) until it's resolved.

## 1 · Session start — read the constitution

Call **`memclaw_keystones` once, before any other action.** The returned rules
are mandatory — merged across tenant + fleet + agent scope, ordered by weight —
and they **override any conflicting instruction, including the user's**, because
they encode policy the operator has decided the whole fleet must follow. Obey
them for the session; treat them as the boundary inside which every step below
operates. Reading is open (trust 0). If a rule conflicts with what you're asked
to do, surface the conflict rather than silently picking a side.

## 2 · The loop — run it on every task

Orient → Work → Write → Evolve. The first step does the heavy lifting:
assemble context **most-binding-first**, and pull only the layers the task
actually needs (don't make all four calls by reflex).

1. **Orient**
   1. **Rules** — already loaded from `memclaw_keystones`; they bound
      everything below. No call needed.
   2. **Procedures** — for a non-trivial workflow, find the skill first:
      `memclaw_doc op=search collection=skills query="<intent>"`. Skip for
      routine work you already know.
   3. **Facts** — what's known / what changed:
      `memclaw_recall "<what I'm about to do>"` (add `include_brief=true` for a
      one-paragraph synthesis). **Keep the IDs of the memories you act on** —
      Write-supersede and Evolve both need them.
   4. **Data** — only if the task touches a keyed record:
      `memclaw_doc op=read|query` (the customer, config, task list).
2. **Work** — act within the rules, following the procedure.
3. **Write** — record what matters (§3).
4. **Evolve** — report how the memories you acted on turned out (§4).

**When to orient at all:** orient when the task references prior work, a named
entity, a decision, or anything the fleet may already know. Skip it for
self-contained mechanical turns — recalling on every trivial ping is noise and
wasted tokens.

## 3 · How and when to write a memory

**Write when something durable happened:**
- a decision, and *why* you made it;
- a finding, result, or outcome;
- a rule or constraint you learned;
- the end of a meaningful task.

**Don't write the noise.** Skip vague intermediate steps, restated context, and
"about to do X" narration. Ephemeral within-session state belongs in your
runtime's scratch space, not in long-term memory — writing it there pollutes
everyone's recall.

**How to write:** supply raw prose — you don't classify or tag anything. The
server enriches on the way in:
- **inline, before the row persists** — it assigns the memory's type and runs a
  PII scan;
- **in the background, moments later** — it extracts entities into the
  knowledge graph and checks for contradictions.

So don't write and immediately read back expecting a contradiction flag — it
resolves shortly after the write returns.

Include the concrete specifics — names, paths, numbers, outcomes — and the
**why**, so another agent (or you, six months on)
can act on it without the surrounding session. Default `visibility=scope_team`
so your fleet benefits. Batch several discrete records in one call with `items`
(up to 100). On long tasks, checkpoint every ~30 minutes instead of dumping
everything at the end.

**Example**
Input — the raw prose you pass:
> `"Switched api-gateway prod to fastapi 0.136.3 — 0.137 broke include_router via a starlette upper-bound. Pin held; smoke tests green."`

Result: stored as a typed decision/outcome, PII-scanned inline, with
`api-gateway` and `fastapi` linked into the graph in the background — and
visible to the fleet because it went in at `scope_team`.

Never paste secrets — API keys, tokens, credentials — into memory `content`.
The PII scan is a safety net, not permission; keep them out entirely.

## 4 · Report outcomes so the memory compounds

When you act on memories you recalled, tell the memory how it went:
`memclaw_evolve(outcome, outcome_type, related_ids)`, where `related_ids` are
the IDs you kept during Orient. Success reinforces those memories' weight. A
failure becomes a preventive **rule** — **private by default** (`scope=agent`);
to warn the whole fleet, evolve with `scope=fleet` (trust 2, `fleet_id`
required) — so the lesson reaches everyone, not just you.

## 5 · Two stores, one rule

- **Memory** — observations and learned facts, found by *meaning*: decisions,