|
| 1 | +# foxmemory-plugin-v2 |
| 2 | + |
| 3 | +An [OpenClaw](https://openclaw.dev) memory plugin that gives a foxlight fox AI long-term and session-scoped memory, backed by the self-hosted **FoxMemory** service (`foxmemory-store`). |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## What it does |
| 10 | + |
| 11 | +The plugin registers five tools with OpenClaw that the resident AI (or any agent) can call: |
| 12 | + |
| 13 | +| Tool | Description | |
| 14 | +|------|-------------| |
| 15 | +| `memory_search` | Semantic search over stored memories | |
| 16 | +| `memory_list` | List all memories in a given scope | |
| 17 | +| `memory_store` | Save a new memory | |
| 18 | +| `memory_get` | Retrieve a specific memory by ID | |
| 19 | +| `memory_forget` | Delete a memory by ID | |
| 20 | + |
| 21 | +Two automatic behaviors wrap each agent turn: |
| 22 | + |
| 23 | +- **Auto-recall** — before a turn, retrieves relevant memories from both session and long-term scopes and injects them into the agent's context so Kite "remembers" |
| 24 | +- **Auto-capture** — after a turn, extracts and stores key facts from the conversation so Kite "learns" |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +## Memory scopes |
| 29 | + |
| 30 | +Memories are isolated into two scopes, with a merged view available: |
| 31 | + |
| 32 | +| Scope | Backing ID | Lifetime | |
| 33 | +|-------|-----------|----------| |
| 34 | +| `session` | `run_id` (the current session key) | Session-local; not visible to long-term searches | |
| 35 | +| `long-term` | `user_id` (configured user ID) | Persists across sessions | |
| 36 | +| `all` | both | Merged and de-duplicated by memory ID | |
| 37 | + |
| 38 | +Scope isolation is strict: a `session` search only queries `run_id`, a `long-term` search only queries `user_id`, and `all` merges both deterministically. |
| 39 | + |
| 40 | +--- |
| 41 | + |
| 42 | +## Backend |
| 43 | + |
| 44 | +When `baseUrl` is configured, the plugin bypasses the Mem0 SDK entirely and routes all storage operations through the FoxMemory HTTP v2 REST API: |
| 45 | + |
| 46 | +| Operation | Endpoint | |
| 47 | +|-----------|----------| |
| 48 | +| Add memories | `POST /v2/memories` | |
| 49 | +| Search | `POST /v2/memories/search` | |
| 50 | +| List | `GET /v2/memories` | |
| 51 | +| Get by ID | `GET /v2/memories/:id` | |
| 52 | +| Delete | `DELETE /v2/memories/:id` | |
| 53 | + |
| 54 | +All v2 responses use a normalized envelope: |
| 55 | +```json |
| 56 | +{ "ok": true, "data": ..., "meta": ... } |
| 57 | +{ "ok": false, "error": { "code": "...", "message": "...", "details": ... } } |
| 58 | +``` |
| 59 | + |
| 60 | +If `baseUrl` is not set, the plugin falls back to the upstream Mem0 SDK (platform or self-hosted OSS mode). |
| 61 | + |
| 62 | +--- |
| 63 | + |
| 64 | +## Configuration |
| 65 | + |
| 66 | +Configure via OpenClaw's plugin settings UI or directly in your OpenClaw config. |
| 67 | + |
| 68 | +| Key | Type | Default | Description | |
| 69 | +|-----|------|---------|-------------| |
| 70 | +| `baseUrl` | string | — | FoxMemory base URL (e.g. `http://your-foxmemory-host:8082`). Enables v2 backend mode. | |
| 71 | +| `userId` | string | `"default"` | User ID for long-term memory scope | |
| 72 | +| `autoCapture` | boolean | `true` | Store key facts after each agent turn | |
| 73 | +| `autoRecall` | boolean | `true` | Inject relevant memories before each agent turn | |
| 74 | +| `mode` | `"platform"` \| `"open-source"` | `"platform"` | Mem0 SDK mode (only relevant when `baseUrl` is unset) | |
| 75 | +| `apiKey` | string | — | Mem0 platform API key (platform mode, no baseUrl) | |
| 76 | +| `customInstructions` | string | — | Natural language rules for what to store/exclude | |
| 77 | +| `customCategories` | object | — | Category name → description map for memory tagging | |
| 78 | +| `enableGraph` | boolean | `false` | Enable Mem0 graph memory (platform mode only) | |
| 79 | +| `searchThreshold` | number | `0.5` | Minimum similarity score for search results (0–1) | |
| 80 | +| `topK` | number | `5` | Max memories to retrieve per search | |
| 81 | +| `requestTimeoutMs` | number | `10000` | HTTP timeout for backend requests | |
| 82 | + |
| 83 | +--- |
| 84 | + |
| 85 | +## Architecture context |
| 86 | + |
| 87 | +This plugin is one layer in the broader Foxlight stack: |
| 88 | + |
| 89 | +``` |
| 90 | +OpenClaw agent runtime |
| 91 | + └── foxmemory-plugin-v2 ← this repo |
| 92 | + └── foxmemory-store (HTTP v2 API) |
| 93 | + ├── Qdrant (vector search) |
| 94 | + └── Neo4j (graph memory) |
| 95 | +``` |
| 96 | + |
| 97 | +The underlying `foxmemory-store` service is built on a forked version of [mem0ai](https://github.com/mem0ai/mem0) 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. |
| 98 | + |
| 99 | +--- |
| 100 | + |
| 101 | +## Development status |
| 102 | + |
| 103 | +This repo is actively under development. The plugin currently contains the upstream `openclaw-mem0` code as a starting point. Remaining milestones: |
| 104 | + |
| 105 | +- **Milestone A** — `FoxmemoryClient` HTTP adapter (add, search, getAll, get, delete) |
| 106 | +- **Milestone B** — Scope isolation parity with strict `run_id` / `user_id` routing |
| 107 | +- **Milestone C** — Config and validation parity with upstream plugin |
| 108 | +- **Milestone D** — Smoke testing against live v2 API + cutover safety |
| 109 | + |
| 110 | +The v1 API is frozen and untouched during this migration. Cutover will only happen after side-by-side smoke validation confirms parity. |
| 111 | + |
| 112 | +--- |
| 113 | + |
| 114 | +## Stack |
| 115 | + |
| 116 | +- **Runtime**: OpenClaw plugin SDK |
| 117 | +- **Language**: TypeScript |
| 118 | +- **Schema validation**: `@sinclair/typebox` |
| 119 | +- **Package manager**: yarn |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +## License and attribution |
| 124 | + |
| 125 | +MIT — see [LICENSE](LICENSE). |
| 126 | + |
| 127 | +This project is based in part on the [OpenClaw mem0 plugin](https://github.com/openclaw/openclaw) and builds on the [mem0](https://github.com/mem0ai/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. |
0 commit comments