Memclaw Build Fleet

MemClaw Fleet: 5-Agent Pipeline with Shared Memory

A runnable reference implementation of multi-agent constraint propagation using MemClaw. Each agent recalls what the previous one decided before acting. Clone it, run it, adapt it to any domain.

[](https://python.org) [](LICENSE) [](https://github.com/caura-ai/caura-memclaw/releases) [](https://github.com/caura-ai/memclaw-build-fleet/pulls)

[What is MemClaw?](#what-is-memclaw) · [Why Multi-Agent?](#why-multi-agent) · [Quickstart](#getting-started) · [New Fleet](#creating-a-new-fleet) · [Query Memories](#querying-fleet-memories) · [Add an Agent](#adding-a-new-agent)

---

What Is MemClaw?

MemClaw is a governed shared memory platform built for AI agent fleets. It's not a vector database bolted onto your pipeline; it's a memory layer designed from the ground up for multi-agent coordination.

> New to MCP? MCP (Model Context Protocol) is an open standard that lets LLMs call external tools via a consistent interface. MemClaw exposes its memory operations as MCP tools, so any MCP-compatible agent or IDE (Claude Code, Cursor, OpenClaw) can read and write fleet memory without custom integration code. Learn more →

Core Features

| Feature | What it means in practice | | :--- | :--- | | Hybrid recall | Vector similarity + keyword match + knowledge graph traversal in one call. Agents find relevant memories even when they paraphrase the original query. | | Fleet namespacing | Every memory is scoped to a fleet_id. Multiple fleets share one tenant without bleeding into each other. | | Row-level security | scope_agent flag makes a memory readable only by the writing agent. Per-row ACL enforced at the storage layer. | | Contradiction detection | memclaw_insights scans the fleet for conflicting rules across stored memories and surfaces them post-commit for agent review. | | Audit trail | Writes and deletes are audit-logged on OSS; per-recall logging and dashboard querying are Prism-managed features. | | PII detection | Sensitive content is auto-detected and stamped with a PII flag; use scope_agent=true to restrict access to the writing agent. | | Prism dashboard | Live view of all fleet memories, memory types, and agent activity at memclaw.net/prism. | | Knowledge graph | Entities and relationships extracted from memories, queryable as a graph via memclaw_entity_get. |

MCP Tools Used in This Pipeline

This repo connects to the MemClaw MCP server over Streamable HTTP. pipeline/mcp_client.py initializes an MCP session, calls tools/list to get live schemas, and executes model-selected tools with tools/call. A REST compatibility mode is available for tests and debugging by setting MEMCLAW_TRANSPORT=rest.

| Tool | MCP method | What it does | | :--- | :--- | :--- | | memclaw_write | tools/call | Persist a decision, rule, fact, or insight | | memclaw_recall | tools/call | Hybrid semantic + keyword search across fleet memories | | memclaw_insights | tools/call | Contradiction detection and pattern analysis | | memclaw_list | tools/call | List memories filtered by agent, type, or cursor | | memclaw_stats | tools/call | Aggregate counts by memory type, agent, and status | | memclaw_entity_get | tools/call | Query the knowledge graph for extracted entities | | memclaw_keystones | tools/call | Read mandatory governance rules (policy, not knowledge graph) |

Get your free API key at memclaw.net. Prism dashboard is at memclaw.net/prism.

---

Why Multi-Agent?

Single agents hit a wall when complexity grows. They lose context, contradict their earlier decisions, and have no way to enforce rules across a long task.

Multi-agent pipelines solve this by dividing work across specialists. But they introduce a new problem: agents that can't see each other's decisions make contradictory choices. Agent A bans external JavaScript. Agent B loads a schema library from a CDN. Nobody catches it.

MemClaw fixes this with shared fleet memory. Every agent writes its decisions before finishing. Every downstream agent recalls those decisions before acting. Constraints propagate automatically not because the code hard-wires them, but because agents read each other's memory.

This repo demonstrates that pattern end-to-end:

| What's proven | How | | :--- | :--- | | Constraint propagation | Performance writes "zero external JS" → SEO recalls it → chooses inline JSON-LD | | Cross-agent citation | Code Review cites Performance + SEO memory IDs in its LGTM verdict | | Data isolation | Manager agent has no write access; confirms zero writes every run | | Hybrid recall | Vector + keyword + knowledge graph; agents find relevant memories even with paraphrased queries |

---

Pipeline Flow

---

System Architecture

---

Constraint Propagation

---

MCP Tool Access Per Agent

Each agent receives an explicit allowlist of MCP tools. Agents cannot call tools outside their allowlist; this enforces least-privilege and makes the data flow auditable.

| Agent | Role | write | recall | insights | list | stats | keystones | entity_get | | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | Frontend | First in chain; nothing to recall yet. Architects the page and writes all structural decisions. | ✓ | | | | | | | | Performance | Recalls frontend decisions, audits Core Web Vitals, writes bundle and image rules. | ✓ | ✓ | | | | | | | SEO | Recalls all fleet memories so schema choices respect Performance's bundle constraints. | ✓ | ✓ | | | | | | | Code Review | Recalls full fleet, runs contradiction detection, issues LGTM/BLOCK with cited memory IDs. | ✓ | ✓ | ✓ | | | | | | Manager | Read-only audit across the configured fleet. Proves data isolation; no writes allowed. | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

> Why restrict tools? Giving every agent every tool is a common mistake. The Manager agent's inability to call memclaw_write is enforced at the tool-schema level; it simply never receives that tool definition. At the end of every run it reports zero write operations, which is the read-only isolation proof.

> What the Manager actually audits: Before the Manager's run() is called, the orchestrator writes two lightweight bootstrap seed memories under the Manager's agent ID to register its identity in MemClaw (required for trust elevation). Those 2 writes happen in the orchestrator pre-flight; the Manager's own audit phase makes zero writes. When you see memclaw_stats return total: 2, that reflects those seeds scoped to the Manager agent, not the full fleet. The full fleet memory list comes from memclaw_list, which enumerates all memories across all agents in the fleet.

> memclaw_insights and memclaw_stats scope note: At default trust level, both memclaw_insights and memclaw_stats operate on the calling agent's own memories only. This means memclaw_stats will return a count scoped to the Manager agent (the 2 bootstrap seeds), not the full fleet; don't be surprised if you see total: 2 rather than the ~20+ memories the other agents wrote. The complete fleet memory list comes from memclaw_list, which does enumerate all agents. Cross-agent contradiction detection works because Code Review first recalls all fleet memories and the model reasons over them directly; insights adds automated pattern/staleness analysis on top. For full cross-agent insights and stats, elevated trust is required; available on managed MemClaw accounts.

---

Memory Isolation Layers

MemClaw provides three levels of isolation that can be combined. This pipeline uses fleet-level namespacing as the default.

| Layer | Granularity | How it works | Example value | This repo | | ------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------- | | Tenant | Coarsest | Hard structural boundary enforced at the storage layer via row-level security + API key binding. Tenants cannot see each other's data under any circumstances. | MEMCLAW_TENANT_ID=acme-corp | One tenant per team | | fleet_id namespace | Mid-level | Every memory is tagged with a fleet_id. Reads and writes are scoped to that tag; multiple fleets coexist inside one tenant without bleeding into each other. | MEMCLAW_FLEET_ID=payments-audit-fleet | Default used here | | scope_agent | Finest | Per-row server-side ACL flag. When set, only the agent that wrote the memory can recall it. Other agents in the same fleet are blocked. | scope_agent=true in memclaw_write | Not set in this repo |

Recommended defaults:

• One tenant per organisation or compliance boundary
• One fleet_id per pipeline run or project
• Use scope_agent only for sensitive per-agent secrets (API keys, PII) that should not be shared downstream

---

Repository Structure

memclaw-build-fleet/
├── pipeline/
│   ├── run_pipeline.py       # ← START HERE: orchestrator and entry point
│   ├── agent_base.py         # Shared agentic loop used by all 5 agents
│   ├── mcp_client.py         # MemClaw MCP Streamable HTTP client
│   ├── config.py             # Shared constants (agent IDs, retry limits)
│   ├── agent_frontend.py     # Agent 1: write only
│   ├── agent_performance.py  # Agent 2: recall + write
│   ├── agent_seo.py          # Agent 3: recall + write  ← copy this to add a new agent
│   ├── agent_codereview.py   # Agent 4: recall + insights + write
│   └── manager.py            # Agent 5: read-only audit (no write access)
├── docs/
│   └── images/               # SVG architecture diagrams
├── .env.example              # Copy to .env and fill in your keys
└── README.md

Reading order for new contributors: run_pipeline.py → agent_base.py → any single agent file → mcp_client.py

---

Getting Started

Prerequisites

• Python 3.11 or later
• A free MemClaw account. Sign up and get your MEMCLAW_API_KEY and MEMCLAW_TENANT_ID from the Prism dashboard. The tenant ID is shown on your dashboard home page immediately after sign-up.
• An LLM that supports OpenAI-compatible function calling. Two options are covered below.

---

Option A: Managed Cloud LLM

Any provider that exposes an OpenAI-compatible /v1/chat/completions endpoint with function calling support will work.

> Model requirement: The model must support tool_choice / function calling. If you see zero tool calls in the output, the model does not support it; switch models.

1. Clone and install

git clone https://github.com/caura-ai/memclaw-build-fleet.git
cd memclaw-build-fleet

python -m venv .venv

# Windows
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install -r pipeline/requirements.txt

2. Configure .env

cp .env.example .env   # macOS / Linux
copy .env.example .env # Windows

Edit .env:

LLM_GATEWAY_API_KEY=your_provider_api_key
LLM_GATEWAY_API_URL=https://your-provider-base-url/v1
LLM_GATEWAY_MODEL=your-model-name

MEMCLAW_API_URL=https://memclaw.net
MEMCLAW_MCP_URL=https://memclaw.net/mcp
MEMCLAW_TRANSPORT=mcp
MEMCLAW_API_KEY=mc_your_key_here
MEMCLAW_TENANT_ID=your-tenant-id
MEMCLAW_FLEET_ID=memclaw-build-fleet

3. Elevate agent trust (one-time, required)

The Manager and Code Review agents need trust_level=2 to call memclaw_stats, memclaw_list, and memclaw_insights. Run these two commands once per tenant; they persist and never need repeating:

curl -X PATCH "https://memclaw.net/api/agents/manager-tenant/trust?tenant_id=YOUR_TENANT_ID" \
  -H "X-API-Key: $MEMCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trust_level": 2}'

curl -X PATCH "https://memclaw.net/api/agents/code-review-agent/trust?tenant_id=YOUR_TENANT_ID" \
  -H "X-API-Key: $MEMCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trust_level": 2}'

> If you skip this step the Manager and Code Review agents will receive 403 errors and the pipeline will report Data Isolation: ⚠️ UNCONFIRMED. See the [Troubleshooting](#troubleshooting) table for details.

> Tenant ID format note: MemClaw silently normalizes underscores to hyphens in agent IDs and tenant IDs (e.g. ran_test → ran-test). Paste your tenant ID exactly as shown in the Prism dashboard. If it contains underscores, the PATCH will return 403. Use the hyphenated form if you encounter a 403 on an otherwise correct key.

4. Verify and run

python pipeline/run_pipeline.py --dry-run
python pipeline/run_pipeline.py

---

Option B: Fully Local with Ollama (no API key required)

Runs entirely on your machine. No cloud provider, no API key.

1. Install Ollama

Download from ollama.com and install for your OS.

2. Pull a model that supports function calling

ollama pull llama3.1

Other supported models: mistral-nemo, qwen2.5, nous-hermes2. Verify function calling support on the model's Ollama page before using.

3. Clone and install

git clone https://github.com/caura-ai/memclaw-build-fleet.git
cd memclaw-build-fleet

python -m venv .venv

# Windows
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install -r pipeline/requirements.txt

4. Configure .env for Ollama

LLM_GATEWAY_API_KEY=ollama
LLM_GATEWAY_API_URL=http://localhost:11434/v1
LLM_GATEWAY_MODEL=llama3.1

MEMCLAW_API_URL=https://memclaw.net
MEMCLAW_MCP_URL=https://memclaw.net/mcp
MEMCLAW_TRANSPORT=mcp
MEMCLAW_API_KEY=mc_your_key_here
MEMCLAW_TENANT_ID=your-tenant-id
MEMCLAW_FLEET_ID=memclaw-build-fleet

Ollama's OpenAI-compatible server accepts any non-empty string as the API key. ollama is the conventional placeholder.

5. Elevate agent trust (one-time, required)

Same as Option A; run the two curl -X PATCH commands from [Step 3 above](#3-elevate-agent-trust-one-time-required) before running the pipeline.

6. Start Ollama and run

# Confirm Ollama is running
ollama list

python pipeline/run_pipeline.py --dry-run
python pipeline/run_pipeline.py

---

Running Options

# Full pipeline (all 5 agents)
python pipeline/run_pipeline.py

# Skip the Manager audit (faster iteration during development)
python pipeline/run_pipeline.py --skip-manager

# Loop mode: resets memories between runs, pauses for Enter between iterations
python pipeline/run_pipeline.py --loop

# Reset all fleet memories after the run completes
python pipeline/run_pipeline.py --reset

# Save full results to JSON
python pipeline/run_pipeline.py --json-output results.json

# Verbose debug logging (shows every tool call input and output)
python pipeline/run_pipeline.py --log-level DEBUG

# Run a single agent in isolation
python pipeline/agent_frontend.py
python pipeline/agent_performance.py
python pipeline/agent_seo.py
python pipeline/agent_codereview.py
python pipeline/manager.py

---

Expected Output

--dry-run

Use --dry-run to verify your environment and MemClaw connectivity before running the full pipeline. It checks that all required env vars are set, opens an MCP session, calls tools/list, and exits; no LLM calls, no memories written.

python pipeline/run_pipeline.py --dry-run

If any req

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: caura-ai
• Source: caura-ai/memclaw-build-fleet
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.