@foxlight-foundation/foxmemory-plugin-v2 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Build
+        run: yarn build
+
+      - name: Publish
+        run: yarn publish --access public --non-interactive
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Foxlight contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project is based in part on the OpenClaw mem0 plugin, which itself builds
+on the mem0 memory layer for AI applications:
+
+  mem0 — https://github.com/mem0ai/mem0
+  Copyright (c) 2024 Mem0 AI
+  Licensed under the Apache License, Version 2.0

package/README.md

@@ -0,0 +1,189 @@
+# foxmemory-plugin-v2
+
+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`).
+
+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
+
+```bash
+openclaw plugins install @foxlight-foundation/foxmemory-plugin-v2
+```
+
+Pin to an exact version (recommended for production):
+
+```bash
+openclaw plugins install @foxlight-foundation/foxmemory-plugin-v2 --pin
+```
+
+---
+
+## Configuration
+
+### FoxMemory backend (recommended)
+
+Point the plugin at your self-hosted `foxmemory-store` instance:
+
+```json
+{
+  "baseUrl": "http://your-foxmemory-host:8082",
+  "userId": "your-user-id",
+  "autoCapture": true,
+  "autoRecall": true
+}
+```
+
+### Mem0 platform (cloud)
+
+Use Mem0's managed cloud platform instead:
+
+```json
+{
+  "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`:
+
+```json
+{
+  "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:
+```json
+{ "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](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.
+
+---
+
+## 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](LICENSE).
+
+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.