@amentilabs/openclaw-zvec-memory

Local-first vector memory with graph edges for OpenClaw agents, powered by zvec-memory.

Your agent gets persistent memory that lives on your machine. No cloud, no API keys, no data leaving your network. Memories are connected through similarity edges, so recalling one fact surfaces related context automatically.

How it works

Auto-Recall — Before the agent responds, the plugin searches local memory for relevant context and injects it. Graph edges mean related memories come along for free.

Auto-Capture — After the agent responds, the conversation is sent through fact extraction. Important information gets stored automatically with embeddings and graph edges.

Both run silently. No prompting needed.

Setup

1. Install zvec-memory (Python)

pip install zvec-memory[server]
# or from source:
cd zvec-memory && pip install -e ".[server]"

2. Install the plugin

openclaw plugins install @amentilabs/openclaw-zvec-memory

3. Configure

Add to your openclaw.json:

{
  "plugins": {
    "entries": {
      "openclaw-zvec-memory": {
        "enabled": true,
        "config": {}
      }
    }
  }
}

That's it. The plugin auto-starts the Python server and connects.

Configuration

| Key | Type | Default | Description | |---|---|---|---| | serverUrl | string | http://localhost:8400 | zvec-memory server URL | | autoStartServer | boolean | true | Auto-start the Python server | | pythonPath | string | python3 | Python binary path | | venvPath | string | — | Virtualenv path (uses its Python) | | autoRecall | boolean | true | Inject memories before each turn | | autoCapture | boolean | true | Extract facts after each turn | | topK | number | 5 | Max memories per recall | | followEdges | boolean | true | Use graph traversal for richer recall | | maxHops | number | 1 | Max graph hops | | userId | string | default | User ID (stored as source) |

Custom Python/venv example

{
  "config": {
    "autoStartServer": true,
    "venvPath": "~/.venvs/zvec-memory",
    "topK": 10,
    "followEdges": true
  }
}

Connect to existing server

{
  "config": {
    "autoStartServer": false,
    "serverUrl": "http://localhost:8400"
  }
}

Agent Tools

| Tool | Description | |---|---| | memory_search | Search memories with vector similarity + optional graph traversal | | memory_store | Save a fact with type, importance, and tags | | memory_get | Retrieve a specific memory by ID | | memory_list | List stored memories (broad search) | | memory_forget | Delete by ID or search-and-delete |

CLI

# Search memories with graph traversal
openclaw zvec search "what does the user prefer"

# Search without graph edges
openclaw zvec search "preferences" --no-graph

# Memory and graph statistics
openclaw zvec stats

# Export graph (JSON or DOT for visualization)
openclaw zvec graph-export
openclaw zvec graph-export --format dot | dot -Tpng -o graph.png

Why zvec-memory?

| Feature | zvec-memory | supermemory | mem0 (OSS) | |---|---|---|---| | Local-first | ✅ Everything on disk | ❌ Cloud API | ⚠️ Needs Qdrant + LLM API | | Graph edges | ✅ Similarity + typed edges | ❌ | ⚠️ Platform only | | Version chains | ✅ root_id/parent_id | ✅ parentMemoryId | ❌ | | Zero cloud deps | ✅ Ollama optional | ❌ Requires API key | ❌ Requires OpenAI | | Auto-forget | ✅ Temporal expiry | ✅ | ❌ | | Fact extraction | ✅ Ollama-based | ✅ Built-in | ✅ LLM-required |

Architecture

┌──────────────────┐     HTTP      ┌──────────────────┐
│  OpenClaw Agent  │ ←──────────→  │  zvec-memory     │
│  (TypeScript)    │   localhost    │  FastAPI server   │
│                  │               │  (Python)         │
│  • 5 tools       │               │  • Zvec vectors   │
│  • auto-recall   │               │  • SQLite graph   │
│  • auto-capture  │               │  • Ollama embed   │
│  • CLI           │               │  • Fact extractor │
└──────────────────┘               └──────────────────┘

License

MIT