foxmemory-plugin-v2

An OpenClaw memory plugin that gives a foxlight fox AI long-term and session-scoped memory, backed by the self-hosted FoxMemory service (foxmemory-store).

This is the v2 successor to foxmemory-openclaw-memory. The primary change is that the memory backend is now the FoxMemory HTTP v2 API rather than the Mem0 SDK — giving full control over the storage stack (Qdrant for vectors, Neo4j for graph relationships) while preserving identical tool semantics for the agent.

---

Installation

openclaw plugins install @foxlight-foundation/foxmemory-plugin-v2

Pin to an exact version (recommended for production):

openclaw plugins install @foxlight-foundation/foxmemory-plugin-v2 --pin

---

Configuration

FoxMemory backend (recommended)

Point the plugin at your self-hosted foxmemory-store instance:

{
  "baseUrl": "http://your-foxmemory-host:8082",
  "userId": "your-user-id",
  "autoCapture": true,
  "autoRecall": true
}

Mem0 platform (cloud)

Use Mem0's managed cloud platform instead:

{
  "mode": "platform",
  "apiKey": "${MEM0_API_KEY}",
  "userId": "your-user-id"
}

${MEM0_API_KEY} will be resolved from the environment variable of that name if set.

Mem0 open-source (self-hosted SDK)

Run Mem0 OSS directly without foxmemory-store:

{
  "mode": "open-source",
  "userId": "your-user-id",
  "oss": {
    "vectorStore": {
      "provider": "qdrant",
      "config": { "host": "localhost", "port": 6333 }
    }
  }
}

---

What it does

The plugin registers five tools with OpenClaw that the resident AI (or any agent) can call:

Tool	Description
memory_search	Semantic search over stored memories
memory_list	List all memories in a given scope
memory_store	Save a new memory
memory_get	Retrieve a specific memory by ID
memory_forget	Delete a memory by ID

Two automatic behaviors wrap each agent turn:

• Auto-recall — before a turn, retrieves relevant memories from both session and long-term scopes and injects them into the agent's context so your foxlight fox "remembers"
• Auto-capture — after a turn, extracts and stores key facts from the conversation so your foxlight fox "learns"

---

Memory scopes

Memories are isolated into two scopes, with a merged view available:

Scope	Backing ID	Lifetime
session	run_id (the current session key)	Session-local; not visible to long-term searches
long-term	user_id (configured user ID)	Persists across sessions
all	both	Merged and de-duplicated by memory ID

Scope isolation is strict: a session search only queries run_id, a long-term search only queries user_id, and all merges both deterministically.

---

Backend

When baseUrl is configured, the plugin bypasses the Mem0 SDK entirely and routes all storage operations through the FoxMemory HTTP v2 REST API:

Operation	Endpoint
Add memories	POST /v2/memories
Search	POST /v2/memories/search
List	GET /v2/memories
Get by ID	GET /v2/memories/:id
Delete	DELETE /v2/memories/:id

All v2 responses use a normalized envelope:

{ "ok": true, "data": ..., "meta": ... }
{ "ok": false, "error": { "code": "...", "message": "...", "details": ... } }

If baseUrl is not set, the plugin falls back to the upstream Mem0 SDK (platform or self-hosted OSS mode).

---

Configuration reference

Full list of available options:

Key	Type	Default	Description
baseUrl	string	—	FoxMemory base URL (e.g. http://your-foxmemory-host:8082). Enables v2 backend mode.
userId	string	"default"	User ID for long-term memory scope
autoCapture	boolean	true	Store key facts after each agent turn
autoRecall	boolean	true	Inject relevant memories before each agent turn
mode	"platform" | "open-source"	"platform"	Mem0 SDK mode (only relevant when baseUrl is unset)
apiKey	string	—	Mem0 platform API key (platform mode, no baseUrl)
customInstructions	string	—	Natural language rules for what to store/exclude
customCategories	object	—	Category name → description map for memory tagging
enableGraph	boolean	false	Enable Mem0 graph memory (platform mode only)
searchThreshold	number	0.5	Minimum similarity score for search results (0–1)
topK	number	5	Max memories to retrieve per search
requestTimeoutMs	number	10000	HTTP timeout for backend requests

---

Architecture context

This plugin is one layer in the broader Foxlight stack:

OpenClaw agent runtime
    └── foxmemory-plugin-v2   ← this repo
            └── foxmemory-store (HTTP v2 API)
                    ├── Qdrant (vector search)
                    └── Neo4j (graph memory)

The underlying foxmemory-store service is built on a forked version of mem0ai modified to support a fox-centric memory architecture — where the AI's own experiences, relationships, and curiosities are the gravitational center of the graph, not any individual human user.

---

Development status

This repo is actively under development. The plugin currently contains the upstream openclaw-mem0 code as a starting point. Remaining milestones:

• Milestone A — FoxmemoryClient HTTP adapter (add, search, getAll, get, delete)
• Milestone B — Scope isolation parity with strict run_id / user_id routing
• Milestone C — Config and validation parity with upstream plugin
• Milestone D — Smoke testing against live v2 API + cutover safety

The v1 API is frozen and untouched during this migration. Cutover will only happen after side-by-side smoke validation confirms parity.

---

Stack

• Runtime: OpenClaw plugin SDK
• Language: TypeScript
• Schema validation: @sinclair/typebox
• Package manager: yarn

---

License and attribution

MIT — see LICENSE.

This project is based in part on the OpenClaw mem0 plugin and builds on the mem0 memory layer for AI applications (Apache 2.0). The OSS and platform provider modes use the mem0ai package directly; the FoxMemory HTTP provider mode is an independent implementation against the FoxMemory v2 REST API.