MemClawz Connect

intent

connect any AI agent to the MemClawz shared memory bus to enable read-before-act and write-after-complete patterns across a fleet. use this skill when your agent needs to access collective knowledge from other agents, avoid re-discovering known facts, recall decisions made in prior sessions, or contribute learnings back to shared memory. works with local or remote MemClawz servers.

inputs

environment variables (required)

• MEMCLAWZ_URL: HTTP endpoint of MemClawz server. defaults to http://localhost:3500. for remote servers, set to http://<ip-or-hostname>:3500.
• MEMCLAWZ_AGENT_ID: unique identifier for this agent in the fleet. must be alphanumeric and consistent across sessions.

environment variables (optional)

• MEMCLAWZ_API_KEY: API key if MemClawz auth is enabled on your server. leave unset for default installs.

external connection

• MemClawz server must be running and accessible at $MEMCLAWZ_URL. requires HTTP connectivity, no OAuth or special auth scopes needed (unless auth is enabled on server side).

context assumptions

• agent has curl or HTTP client available.
• agent can read environment variables.
• network connectivity to MemClawz endpoint exists.

procedure

step 1: verify MemClawz connectivity

• input: $MEMCLAWZ_URL environment variable.
• run: curl -s "$MEMCLAWZ_URL/health".
• output: JSON response with status, version, and qdrant connection state.
• on failure (connection refused, timeout, 404): stop. MemClawz server is unreachable or not running. check URL and network.

step 2: search shared memory before starting work

• input: task keywords or topic to search for.
• run: curl -s "$MEMCLAWZ_URL/api/v1/search?q=<TOPIC>&limit=5".
• output: JSON array of matching memories, each with content, agent_id, memory_type, and relevance score (0-1). empty array if no matches.
• use results as context. skip work already documented as completed.

step 3: perform agent task

• input: search results from step 2 and task definition.
• run: execute the agent's primary work (deploy, analyze, fix, etc.). do not execute this step until step 2 completes.
• output: completion status, changes made, learnings, or outcomes.

step 4: write results back to shared memory

• input: task outcome, agent_id ($MEMCLAWZ_AGENT_ID), and appropriate memory_type (see memory types table below).
• run: curl -s -X POST "$MEMCLAWZ_URL/api/v1/add" -H "Content-Type: application/json" -d '{"content": "<what was done>", "agent_id": "<agent_id>", "memory_type": "<type>"}'.
• output: JSON confirmation with stored memory ID or HTTP 201 Created status.
• only write after task completes successfully. do not write partial or failed work unless memory_type is intention.

step 5 (optional): retrieve agent's own memory history

• input: $MEMCLAWZ_AGENT_ID and optional limit count.
• run: curl -s "$MEMCLAWZ_URL/api/v1/memories?agent_id=$MEMCLAWZ_AGENT_ID&limit=50".
• output: JSON array of this agent's prior memories, newest first.

step 6 (optional): inspect fleet stats

• input: none.
• run: curl -s "$MEMCLAWZ_URL/api/v1/stats".
• output: JSON with total memory count, agent count, average search score, and storage size.

step 7 (optional): list all connected agents

• input: none.
• run: curl -s "$MEMCLAWZ_URL/api/v1/agents".
• output: JSON array of agent_ids and their last activity timestamp.

decision points

if MemClawz server is unavailable (step 1 fails)

• proceed with task using only local context. do not attempt to write back on task completion. log the failure. optionally retry step 1 with exponential backoff (1s, 2s, 4s) up to 3 times before giving up.

if search returns no results (step 2)

• proceed with task. this is normal for new domains or edge cases. write results back anyway so future agents learn.

if search returns results with low scores (< 0.5)

• treat as hints, not authoritative. verify facts independently. high-scoring results (> 0.8) are more reliable.

if the task fails or is incomplete (step 3)

• do not write to shared memory with memory_type event or outcome. optionally write memory_type intention to flag partial work for another agent to resume.

if the HTTP POST fails on write (step 4, e.g., 5xx error, timeout)

• retry up to 2 times with 5-second backoff. if still failing, log error and continue. memory loss is preferable to blocking the task.

if MemClawz auth is enabled and MEMCLAWZ_API_KEY is missing

• step 1 health check may succeed but steps 2 and 4 will return 401 Unauthorized. set MEMCLAWZ_API_KEY from your server admin before proceeding.

if network timeouts occur

• default curl timeout is usually 0 (infinite). add -m 10 flag to curl commands for a 10-second timeout to avoid hanging on slow or unresponsive servers.

if memory_type is unclear

• default to event for completed work. use fact for discovered information, decision for architectural choices, insight for lessons learned.

output contract

success case: search request (step 2)

• HTTP 200 OK.
• response body: JSON object with key results, value is array of memories (may be empty).
• each memory object has keys: content (string), agent_id (string), memory_type (string), score (float 0-1), timestamp (ISO 8601 string, optional).

success case: write request (step 4)

• HTTP 201 Created or 200 OK.
• response body: JSON object with key id (memory ID, string) and optional acknowledged (boolean true).

success case: health check (step 1)

• HTTP 200 OK.
• response body: JSON object with keys status (string "ok"), version (string), qdrant (string "connected" or "disconnected").

success case: stats (step 6)

• HTTP 200 OK.
• response body: JSON object with keys total_memories (int), agent_count (int), avg_search_score (float), storage_bytes (int).

success case: list agents (step 7)

• HTTP 200 OK.
• response body: JSON object with key agents, value is array of objects with keys agent_id (string) and last_activity (ISO 8601 string, optional).

success case: retrieve agent memories (step 5)

• HTTP 200 OK.
• response body: JSON object with key memories, value is array of memory objects (same schema as search results), ordered by timestamp descending.

failure cases (all requests)

• HTTP 400 Bad Request: malformed JSON or missing required fields. check request body syntax.
• HTTP 401 Unauthorized: auth enabled and key missing or invalid.
• HTTP 404 Not Found: MemClawz endpoint unreachable or server version does not support this endpoint.
• HTTP 5xx Server Error: MemClawz internal error. logs available on MemClawz server.
• connection refused or timeout: MemClawz server not running or network unreachable.

outcome signal

you know the skill worked when:

1. step 1 succeeds: health check returns status: ok and qdrant connection is "connected".

2. step 2 succeeds: search returns results (non-empty array) with relevant content and scores >= 0.5, or returns empty array (which is also success for new topics).

3. step 4 succeeds: POST to /api/v1/add returns HTTP 201 with a memory ID, confirming the work was recorded in shared memory.

4. cross-agent visibility: run step 5 or 7 from a different agent_id and confirm you can retrieve memories written by the first agent. this proves fleet-wide sharing is working.

5. repeated searches improve over time: search for the same topic in a second session and notice results now include memories from the first session, indicating persistent storage and indexing.

6. no duplicate work: agent executes step 2, finds a high-scoring result for the same task from another agent (score > 0.8), and skips redundant work.

---

credits: original skill authored by clawhub. enriched for Implexa standards with explicit decision points, auth edge cases, timeout guidance, and output contract details.