Memcloud

Quick Start

Memcloud is a hybrid memory orchestrator for AI agents. It combines auto-recall (structured context injection), async auto-capture, a dynamic memory profile endpoint, and shared memory pools — all through a simple REST API. Currently at v1.0.0.

Base URL

text

https://api.memcloud.dev/v1/

Authentication

Include your API key as a Bearer token in the Authorization header. Generate per-agent keys via the Admin API.

http

Authorization: Bearer mc_your_api_key

Store a memory

bash

curl -X POST https://api.memcloud.dev/v1/memories/ \
  -H "Authorization: Bearer mc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "User prefers dark mode and vim keybindings",
    "user_id": "seiji",
    "agent_id": "lyn"
  }'

Search it back

bash

curl -X POST https://api.memcloud.dev/v1/memories/search/ \
  -H "Authorization: Bearer mc_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user preferences",
    "user_id": "seiji",
    "top_k": 15
  }'

OpenClaw Integration

Add persistent memory to any OpenClaw agent in three steps.

1. Copy the plugin

bash

scp -r root@api.memcloud.dev:/opt/memcloud/openclaw-plugin/ \\\n  /usr/lib/node_modules/openclaw/dist/extensions/openclaw-memcloud/

2. Add to openclaw.json

json

{
  "plugins": {
    "slots": {
      "memory": "openclaw-memcloud"
    },
    "entries": {
      "openclaw-memcloud": {
        "enabled": true,
        "config": {
          "apiUrl": "https://api.memcloud.dev/v1",
          "apiKey": "mc_your_api_key",
          "userId": "your_user_id",
          "agentId": "your_agent_id",
          "orgId": "your_org_id",
          "autoRecall": true,
          "autoCapture": true,
          "topK": 15,
          "sharedPools": ["shared:team"],
          "compactionFlush": true
        }
      }
    }
  }
}

Key fields: slots.memory tells OpenClaw to use Memcloud as the primary memory plugin. sharedPools enables cross-agent memory sharing. compactionFlush saves context before it gets trimmed.

3. Restart the gateway

bash

openclaw gateway restart

Available Tools

memory_store

Store a new memory. Text is processed for importance and conflict detection.

Params: text, pool_id?, scope?, source_type?

memory_search

Semantic search across accessible memories.

Params: query, top_k?

memory_forget

Delete memories matching a query. Omit query to delete all.

Params: query

memory_list

List all stored memories with pagination.

Params: limit?, offset?

Agent Best Practices

How to get the most out of Memcloud as an OpenClaw agent. This guide covers what gets captured automatically, what you should store manually, and how to avoid common pitfalls.

How Auto-Capture Works OpenClaw Plugin

When using the OpenClaw plugin, Memcloud captures memories from three sources automatically via hooks:

Tool Results (after_tool_call hook) — When you run shell commands, API calls, or deployments, the results are captured in real-time. Only high-signal tools are stored: exec, web_search, web_fetch, message, gateway, sessions_spawn. Noise (polls, reads, heartbeats) is filtered out.
Conversation (agent_end hook) — At the end of each turn, the last 4 user/assistant messages plus any tool action summaries are stored together.
Pre-Compaction (before_compaction hook) — When the context window gets full and OpenClaw trims old messages, Memcloud saves the at-risk content first. This is your last-chance safety net.

What Gets Extracted

Every captured text is processed by the extraction pipeline into 5 memory types:

summary

Concise overview of the conversation or action

VPS disk cleanup freed 101GB by removing EverMemOS stack

triple

Structured subject-predicate-object facts

VPS disk usage → 19%

profile

Key-value attributes about people/systems

user preference: dark mode = true

temporal

Time-anchored events

Deployed Memcloud v1.0.0 on 2026-04-05

raw

Full text preserved verbatim for context

Complete conversation transcript

When to Store Manually

Auto-capture is good but not perfect. Use memory_store explicitly for:

Decisions & rationale — "We chose PostgreSQL over MongoDB because..."
User preferences — "User wants no emojis on product pages"
Credentials & config — API keys, server IPs, account details (stored securely)
Project milestones — "Phase 1 complete, moving to Phase 2"
Lessons learned — "Never use ORDER_FILLING_IOC with FXTM broker"
Cross-session context — anything the next session absolutely needs to know

bash

# Example: Store a decision with context
memory_store(
  text="Decided to use Zamba2-2.7B for the universal memory model. Reason: constant memory at inference, O(n) linear scaling, 3 memory systems.",
  source_type="agent_reasoning",
  scope="project"
)

Shared Memory Pools

Multiple agents can read and write to the same memory pool. This is how teams collaborate.

json

// In openclaw.json — both agents use the same shared pool
{
  "sharedPools": ["shared:team"]
}

// Agent A stores a memory
memory_store(text="API deployed to prod", pool_id="shared:team")

// Agent B searches and finds it
memory_search(query="deployment status", pool_id="shared:team")

Tip: Use scope: "team" for memories that should be visible to all agents, scope: "private" for agent-specific context.

Common Pitfalls

✗

Storing every message verbatim

✓

Let auto-capture handle conversation; manually store only decisions and insights

Noise drowns out signal. The extraction pipeline already creates summaries and triples.

✗

Not setting source_type on manual stores

✓

Always include source_type: 'agent_reasoning', 'conversation', 'research', etc.

Source types help with filtering and understanding where knowledge came from.

✗

Ignoring pool_id for team memories

✓

Use pool_id='shared:team' when storing info other agents need

Without pool_id, memories default to private scope — invisible to teammates.

✗

Storing secrets in global scope

✓

Use scope='private' for credentials, API keys, passwords

Global/team scope memories are visible to all agents in the org.

Recommended AGENTS.md Snippet

Add this to your agent's workspace instructions so it knows how to use Memcloud effectively:

markdown

## Memory (Memcloud)

Memcloud is your long-term memory. It auto-captures tool results and conversations.

### What to store manually:
- Decisions and why they were made
- User preferences and corrections
- Project milestones and status changes
- Credentials and config (scope: private)
- Lessons learned from mistakes

### How to store:
- Use memory_store(text, source_type, scope) for important facts
- Use pool_id="shared:team" for things teammates need
- Use scope="private" for secrets

### How to search:
- memory_search(query) finds relevant memories semantically
- Check memory before asking the user to repeat themselves

### What NOT to do:
- Don't store every message — auto-capture handles that
- Don't store secrets in team/global scope
- Don't forget to set source_type

Claude Code / MCP Integration

Use Memcloud as an MCP server for Claude Code, Cursor, or any MCP-compatible client.

MCP Server

Located at memcloud/mcp/mcp_server.py

Configuration

Add to ~/.claude/mcp.json:

json

{
  "mcpServers": {
    "memcloud": {
      "command": "python3",
      "args": [
        "/path/to/mcp_server.py",
        "--api-url", "https://api.memcloud.dev/v1",
        "--api-key", "YOUR_KEY",
        "--user-id", "seiji"
      ]
    }
  }
}

MCP Tools

memory_storeStore a memory with automatic enrichment

memory_searchSemantic search with optional agentic reasoning

memory_answerSearch and synthesize an answer from memories

memory_listList memories with filters

memory_deleteDelete a specific memory by ID

REST API Reference

Memories

Answer

Memory Profile

Projects

Agent Context

Pools & Access

Events & Subscriptions

Admin

Bulk Operations

Note: This performs a soft delete (archive). Memories can be recovered. Maximum 100 IDs per request.

Sessions

Webhooks

Schemas

Instructions

Activity & Audit

Other

Concepts

Hybrid Memory Architecture

Memcloud acts as a hybrid memory orchestrator combining multiple memory strategies:

Auto-Recall — structured context injection. On each turn, the top 15 relevant memories are fetched and injected as system context. Retrieval is pure relevance: vector similarity + BM25 + time decay.
Auto-Capture OpenClaw Plugin — tool-aware, async capture via the OpenClaw plugin. Captures conversation text AND tool results (shell commands, deployments, API calls) via after_tool_call, agent_end, and before_compaction hooks. Noise (heartbeats, polls, reads) is filtered out automatically. Requires the OpenClaw integration.
Memory Profile — a dynamic MEMORY.md-like summary generated on demand via the profile endpoint.
Shared Pools — agents collaborate through shared memory pools with ACL-based access control.

Memory Profile

The GET /v1/agents/{agent_id}/profile/endpoint returns a dynamically generated structured summary of an agent's memory — like a living MEMORY.md. It distills preferences, key decisions, facts, and patterns from stored memories into a concise document that can be injected as system context or used for agent introspection.

Memory Scopes

Control visibility and lifetime of memories.

private

task

project

team

global

private — only the creating agent; task — within active task; project — all agents on a project; team — all agents of a user; global — all agents system-wide.

Importance Scoring

Every memory is auto-scored 0–5. Importance is used for write filtering only — low-importance content may be dropped at capture time. It does not affect retrieval ranking.

0Noise

1Ops

2Routine

3Significant

4Critical

5Foundational

Conflict Detection

When a new memory contradicts an existing one, Memcloud detects the conflict and resolves it. Dedup thresholds: supersede at 0.88 similarity, chain at 0.80 similarity.

supersede — new memory replaces the old one (≥0.88 similarity)
chain — both kept, linked as an evolution (≥0.80 similarity)
new — no conflict, stored independently

Agent Isolation

Each agent can only access its own memories and pools explicitly shared via ACL. This prevents data leakage between agents while enabling controlled collaboration.

Auto-Routing

Memories are automatically routed to the right pool based on agent context:

agent context → task pool → project pool → default

SDKs

python

from memcloud import MemcloudClient

mc = MemcloudClient(
    api_key="mc_xxx",
    api_url="https://api.memcloud.dev/v1",
    user_id="seiji",
    agent_id="lyn"
)

# Store a memory
mc.add("User prefers dark mode")

# Search
results = mc.search("preferences")
for r in results:
    print(r)

# Get an answer from memory
answer = mc.answer("What theme does the user prefer?")

# List all
memories = mc.list(memory_type="triple", limit=20)

# Delete
mc.delete(memory_id="abc-123")

# Bulk operations
mc.bulk_import([
    {"content": "fact 1", "memory_type": "raw"},
    {"content": "fact 2", "memory_type": "triple"},
])
data = mc.bulk_export(memory_type="triple")

Memcloud Documentation

Quick Start

Store a memory

Search it back

OpenClaw Integration

1. Copy the plugin

2. Add to openclaw.json

3. Restart the gateway

Available Tools

Agent Best Practices

How Auto-Capture Works OpenClaw Plugin

What Gets Extracted

When to Store Manually

Shared Memory Pools

Common Pitfalls

Recommended AGENTS.md Snippet

Claude Code / MCP Integration

MCP Server

Configuration

MCP Tools

REST API Reference

Memories

Answer

Memory Profile

Projects

Agent Context

Pools & Access

Events & Subscriptions

Admin

Bulk Operations

Sessions

Webhooks

Schemas

Instructions

Activity & Audit

Other

Concepts

Hybrid Memory Architecture

Memory Profile

Memory Scopes

Importance Scoring

Conflict Detection

Agent Isolation

Auto-Routing

SDKs