If you are an LLM agent reading this page, this is the canonical prompt. The page below is the same content that gets installed on every MemClaw-connected runtime. You don't need to fetch it from anywhere else.

A plain text/markdown form of the same content is available at /docs/agents.md if your runtime prefers a single-fetch raw file. The whole docs site is also available concatenated at /llms-full.txt.

To install the skill onto a Claude Code / Codex runtime in one line (URL auto-targets this deployment — copy from staging, run against staging; copy from prod, run against prod):

curl -s "https://memclaw.net/api/v1/install-skill?agent=both" | bash

What this page is

This is the canonical agent prompt for MemClaw — the skill an LLM follows when it has memclaw_* tools in its tool list. It defines:

• Identity — how to set agent_id and fleet_id on every call.
• The three rules — recall before you start, write when something matters, supersede don't delete.
• Trust levels — what you can read and write at each tier (0–3).
• Tool dispatch — which tool to call for which task.

The body below is the live content.

Detect that you have MemClaw access

You have MemClaw if any of these are true in your runtime:

• A tool named memclaw_recall, memclaw_write, or memclaw_doc appears in your tool list.
• The host config (.mcp.json, claude_desktop_config.json, ~/.cursor/config.json, or ~/.openclaw/openclaw.json) contains an mcpServers.memclaw entry.
• A MEMCLAW_API_KEY or MEMCLAW_API_URL environment variable is set.

If yes: call memclaw_keystones once at session start, before any other action, then follow the rules below.

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.

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.net/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.

Endpoints for agent runtimes

• Plain Markdown of this skill: /docs/agents.md

• All docs concatenated as plain text: /llms-full.txt (index only: /llms.txt)

• Live tool schemas (JSON): /api/v1/tool-descriptions

• Live OpenAPI spec (JSON): /api/openapi.json

• One-line install on a runtime (env-aware — uses the host this page is served from):

  curl -s "https://memclaw.net/api/v1/install-skill?agent=both" | bash

Provenance: the SKILL content above is committed to caura-ai/caura-memclaw at static/skills/memclaw/SKILL.md and rebuilt on every release.