Add hybrid instance support with central/project isolation and scope enforcement

* .env.example: Added OPENCLAW_INSTANCE, OPENCLAW_DEFAULT_SCOPE, and OPENCLAW_ALLOWED_SCOPE_PREFIXES configuration options
* .gitignore: Extended runtime DB patterns to cover nested instance directories (runtime/**/*.db, .db-shm, .db-wal)
* README.md: Added Hybrid Mode section with dev:central/project-a/project-b commands, docker-compose.hybrid.yml reference, and new environment variable documentation
* docker

Author: naimkatiman

.env.example

@@ -21,6 +21,20 @@ OPENCLAW_HOST=127.0.0.1
 # Default: 8787
 OPENCLAW_PORT=8787
 
+# Instance name used for logging + health metadata.
+# Example: central | project-a | project-b
+OPENCLAW_INSTANCE=default
+
+# Default scope used when memory updates omit "scope".
+# For project-specific instances, set this to "project".
+OPENCLAW_DEFAULT_SCOPE=general
+
+# Optional comma-separated scope prefixes allowed on this instance.
+# If empty, all scopes are accepted.
+# Example for central: preferences,identity,facts
+# Example for project-only: project,project-a
+OPENCLAW_ALLOWED_SCOPE_PREFIXES=
+
 # ── Security ──────────────────────────────────────────────────────────────────
 
 # API key required on every request as the `x-api-key` header.

.gitignore

@@ -5,6 +5,9 @@
 __pycache__/
 .venv/
 runtime/*.db
+runtime/**/*.db
+runtime/**/*.db-shm
+runtime/**/*.db-wal
 node_modules/
 dist/
 *.tsbuildinfo

README.md

@@ -40,6 +40,27 @@ npm run dev
 
 Server starts at `http://localhost:8787` — Swagger docs at `http://localhost:8787/docs`
 
+### Hybrid Mode (Central + Project Instances)
+
+Run isolated instances with built-in presets:
+
+```bash
+# central user memory (port 8787)
+npm run dev:central
+
+# project memory instances (ports 8788, 8789)
+npm run dev:project-a
+npm run dev:project-b
+```
+
+See full guide: [hybrid-setup.md](hybrid-setup.md)
+
+Docker variant:
+
+```bash
+docker compose -f docker-compose.hybrid.yml up -d
+```
+
 ### Try It Out
 
 ```bash
@@ -93,6 +114,8 @@ Add to your MCP config (e.g. `~/.cursor/mcp.json` or Claude Code settings):
 
 Build first: `npm run build`
 
+For hybrid central/project MCP wiring, see [hybrid-setup.md](hybrid-setup.md).
+
 Available MCP tools:
 | Tool | Description |
 |------|-------------|
@@ -185,7 +208,10 @@ Copy `.env.example` to `.env` and adjust:
 |----------|---------|-------------|
 | `OPENCLAW_HOST` | `127.0.0.1` | Server bind address |
 | `OPENCLAW_PORT` | `8787` | Server port |
+| `OPENCLAW_INSTANCE` | `default` | Instance label (e.g. central, project-a) |
 | `OPENCLAW_DB_PATH` | `./runtime/openclaw.db` | SQLite database path |
+| `OPENCLAW_DEFAULT_SCOPE` | `general` | Scope used when update scope is omitted |
+| `OPENCLAW_ALLOWED_SCOPE_PREFIXES` | *(empty)* | Comma-separated allowed scope prefixes |
 | `OPENCLAW_API_KEY` | *(empty)* | API key for auth (set in production) |
 | `OPENCLAW_CORS_ORIGIN` | `*` | CORS allowed origin |
 

docker-compose.hybrid.yml

@@ -0,0 +1,78 @@
+services:
+  memorycore-central:
+    build: .
+    container_name: memorycore-central
+    restart: unless-stopped
+    ports:
+      - "8787:8787"
+    environment:
+      - NODE_ENV=production
+      - OPENCLAW_HOST=0.0.0.0
+      - OPENCLAW_PORT=8787
+      - OPENCLAW_INSTANCE=central
+      - OPENCLAW_RUNTIME_DIR=/app/runtime
+      - OPENCLAW_DB_PATH=/app/runtime/openclaw.db
+      - OPENCLAW_DEFAULT_SCOPE=preferences
+      - OPENCLAW_ALLOWED_SCOPE_PREFIXES=preferences,identity,facts
+      - OPENCLAW_API_KEY=${OPENCLAW_API_KEY}
+      - OPENCLAW_CORS_ORIGIN=${OPENCLAW_CORS_ORIGIN:-*}
+    volumes:
+      - ./runtime/central:/app/runtime
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8787/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  memorycore-project-a:
+    build: .
+    container_name: memorycore-project-a
+    restart: unless-stopped
+    ports:
+      - "8788:8787"
+    environment:
+      - NODE_ENV=production
+      - OPENCLAW_HOST=0.0.0.0
+      - OPENCLAW_PORT=8787
+      - OPENCLAW_INSTANCE=project-a
+      - OPENCLAW_RUNTIME_DIR=/app/runtime
+      - OPENCLAW_DB_PATH=/app/runtime/openclaw.db
+      - OPENCLAW_DEFAULT_SCOPE=project
+      - OPENCLAW_ALLOWED_SCOPE_PREFIXES=project,project-a
+      - OPENCLAW_API_KEY=${OPENCLAW_API_KEY}
+      - OPENCLAW_CORS_ORIGIN=${OPENCLAW_CORS_ORIGIN:-*}
+    volumes:
+      - ./runtime/project-a:/app/runtime
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8787/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+  memorycore-project-b:
+    build: .
+    container_name: memorycore-project-b
+    restart: unless-stopped
+    ports:
+      - "8789:8787"
+    environment:
+      - NODE_ENV=production
+      - OPENCLAW_HOST=0.0.0.0
+      - OPENCLAW_PORT=8787
+      - OPENCLAW_INSTANCE=project-b
+      - OPENCLAW_RUNTIME_DIR=/app/runtime
+      - OPENCLAW_DB_PATH=/app/runtime/openclaw.db
+      - OPENCLAW_DEFAULT_SCOPE=project
+      - OPENCLAW_ALLOWED_SCOPE_PREFIXES=project,project-b
+      - OPENCLAW_API_KEY=${OPENCLAW_API_KEY}
+      - OPENCLAW_CORS_ORIGIN=${OPENCLAW_CORS_ORIGIN:-*}
+    volumes:
+      - ./runtime/project-b:/app/runtime
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:8787/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s

hybrid-setup.md

@@ -0,0 +1,139 @@
+# Hybrid Setup Guide (Central + Project Instances)
+
+This setup gives you:
+- One central memory instance for user-level facts/preferences.
+- One isolated memory instance per project for project context.
+
+## Topology
+
+```bash
+~/memory-core/   # central instance on 8787 (preferences, identity, facts)
+project-a/       # project-specific instance on 8788 (project scopes only)
+project-b/       # project-specific instance on 8789 (project scopes only)
+```
+
+## 1) Start the central memory instance
+
+From this repository:
+
+```bash
+npm run dev:central
+```
+
+Central defaults:
+- `OPENCLAW_PORT=8787`
+- `OPENCLAW_RUNTIME_DIR=~/memory-core/runtime`
+- `OPENCLAW_ALLOWED_SCOPE_PREFIXES=preferences,identity,facts`
+
+## 2) Start project instances
+
+From this repository:
+
+```bash
+npm run dev:project-a
+npm run dev:project-b
+```
+
+Project defaults:
+- `project-a` runs on `8788` with runtime at `./runtime/project-a`
+- `project-b` runs on `8789` with runtime at `./runtime/project-b`
+- Both enforce project-only scopes via:
+  - `OPENCLAW_DEFAULT_SCOPE=project`
+  - `OPENCLAW_ALLOWED_SCOPE_PREFIXES=project,<project-name>`
+
+### Docker alternative
+
+```bash
+docker compose -f docker-compose.hybrid.yml up -d
+```
+
+## 3) Verify each instance
+
+```bash
+curl http://localhost:8787/health
+curl http://localhost:8788/health
+curl http://localhost:8789/health
+```
+
+Each health response includes:
+- `instance_name`
+- `default_scope`
+- `allowed_scope_prefixes`
+
+## 4) MCP configuration per project
+
+Build once first:
+
+```bash
+npm run build
+```
+
+### Central MCP server
+
+```json
+{
+  "mcpServers": {
+    "memorycore-central": {
+      "command": "node",
+      "args": ["dist/src/mcp.js"],
+      "cwd": "/path/to/Project-AI-MemoryCore",
+      "env": {
+        "OPENCLAW_INSTANCE": "central",
+        "OPENCLAW_RUNTIME_DIR": "/home/you/memory-core/runtime",
+        "OPENCLAW_DB_PATH": "/home/you/memory-core/runtime/openclaw.db",
+        "OPENCLAW_DEFAULT_SCOPE": "preferences",
+        "OPENCLAW_ALLOWED_SCOPE_PREFIXES": "preferences,identity,facts"
+      }
+    }
+  }
+}
+```
+
+### Project A MCP server
+
+```json
+{
+  "mcpServers": {
+    "memorycore-project-a": {
+      "command": "node",
+      "args": ["dist/src/mcp.js"],
+      "cwd": "/path/to/Project-AI-MemoryCore",
+      "env": {
+        "OPENCLAW_INSTANCE": "project-a",
+        "OPENCLAW_RUNTIME_DIR": "/path/to/project-a/.memorycore",
+        "OPENCLAW_DB_PATH": "/path/to/project-a/.memorycore/openclaw.db",
+        "OPENCLAW_DEFAULT_SCOPE": "project",
+        "OPENCLAW_ALLOWED_SCOPE_PREFIXES": "project,project-a"
+      }
+    }
+  }
+}
+```
+
+### Project B MCP server
+
+```json
+{
+  "mcpServers": {
+    "memorycore-project-b": {
+      "command": "node",
+      "args": ["dist/src/mcp.js"],
+      "cwd": "/path/to/Project-AI-MemoryCore",
+      "env": {
+        "OPENCLAW_INSTANCE": "project-b",
+        "OPENCLAW_RUNTIME_DIR": "/path/to/project-b/.memorycore",
+        "OPENCLAW_DB_PATH": "/path/to/project-b/.memorycore/openclaw.db",
+        "OPENCLAW_DEFAULT_SCOPE": "project",
+        "OPENCLAW_ALLOWED_SCOPE_PREFIXES": "project,project-b"
+      }
+    }
+  }
+}
+```
+
+## Migration Strategy
+
+1. Start central memory first and store user preferences/facts there.
+2. Add project-specific instances and keep project context in those DBs only.
+3. In each project workspace, point MCP to that project instance config.
+4. Keep central MCP available for cross-project personal memory.

package.json

@@ -24,8 +24,14 @@
     "build": "tsc -p tsconfig.json",
     "start": "node dist/src/server.js",
     "dev": "tsx src/server.ts",
+    "dev:central": "node scripts/run-instance.mjs --mode http --instance central",
+    "dev:project-a": "node scripts/run-instance.mjs --mode http --instance project-a",
+    "dev:project-b": "node scripts/run-instance.mjs --mode http --instance project-b",
     "cli": "tsx src/cli.ts",
     "mcp": "tsx src/mcp.ts",
+    "mcp:central": "node scripts/run-instance.mjs --mode mcp --instance central",
+    "mcp:project-a": "node scripts/run-instance.mjs --mode mcp --instance project-a",
+    "mcp:project-b": "node scripts/run-instance.mjs --mode mcp --instance project-b",
     "test": "npm run build && node --test dist/tests/*.test.js",
     "clean": "if exist dist rmdir /s /q dist"
   },
@@ -44,4 +50,4 @@
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   }
-}
+}