@cortexmem/bridge-openclaw 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @cortexmem/bridge-openclaw
+
+Bridge plugin that connects [OpenClaw](https://github.com/openclaw) agents to [Cortex](https://github.com/rikouu/cortex) memory service.
+
+## Install
+
+```bash
+npm install @cortexmem/bridge-openclaw
+```
+
+## Quick Start
+
+```typescript
+import cortexBridge from '@cortexmem/bridge-openclaw';
+
+const agent = new Agent({
+  plugins: [cortexBridge],
+});
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CORTEX_URL` | `http://localhost:21100` | Cortex server URL |
+| `CORTEX_DEBUG` | — | Enable debug logging |
+
+## Hooks
+
+The plugin provides three automatic hooks:
+
+- **`onBeforeResponse`** — Recalls relevant memories and injects them as context before the agent responds.
+- **`onAfterResponse`** — Extracts memories from conversations after the agent responds (fire-and-forget).
+- **`onBeforeCompaction`** — Emergency flush of key information before context window compression.
+
+## API
+
+### `healthCheck()`
+
+Verify the Cortex server is reachable.
+
+```typescript
+import { healthCheck } from '@cortexmem/bridge-openclaw';
+
+const status = await healthCheck();
+// { ok: true, latency_ms: 12 }
+```
+
+### Individual Hooks
+
+You can also import hooks individually:
+
+```typescript
+import { onBeforeResponse, onAfterResponse, onBeforeCompaction } from '@cortexmem/bridge-openclaw';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cortex Bridge Plugin for OpenClaw
+ *
+ * Thin bridge (~200 lines) that forwards OpenClaw hooks to Cortex Sidecar REST API.
+ * Key design: NEVER block the Agent. All calls have hard timeouts + graceful fallback.
+ */
+interface AgentContext {
+    agentId?: string;
+    sessionId?: string;
+    lastUserMessage?: string;
+    lastAssistantMessage?: string;
+    messages?: {
+        role: string;
+        content: string;
+    }[];
+    metadata?: Record<string, any>;
+}
+interface PluginResult {
+    prependContext?: string;
+}
+/**
+ * Called before Agent generates a response.
+ * Searches Cortex for relevant memories and injects them as context.
+ */
+declare function onBeforeResponse(context: AgentContext): Promise<PluginResult | null>;
+/**
+ * Called after Agent generates a response.
+ * Sends the conversation exchange to Cortex for memory extraction.
+ * Fire-and-forget — does NOT wait for result.
+ */
+declare function onAfterResponse(context: AgentContext): Promise<void>;
+/**
+ * Called before context window compaction.
+ * Emergency flush — extract key info before it's lost.
+ */
+declare function onBeforeCompaction(context: AgentContext): Promise<void>;
+/**
+ * Health check — verify Cortex Sidecar is reachable.
+ */
+declare function healthCheck(): Promise<{
+    ok: boolean;
+    latency_ms: number;
+    error?: string;
+}>;
+declare const pluginInfo: {
+    name: string;
+    version: string;
+    description: string;
+    cortexUrl: string;
+};
+declare const _default: {
+    name: string;
+    onBeforeResponse: typeof onBeforeResponse;
+    onAfterResponse: typeof onAfterResponse;
+    onBeforeCompaction: typeof onBeforeCompaction;
+    healthCheck: typeof healthCheck;
+    pluginInfo: {
+        name: string;
+        version: string;
+        description: string;
+        cortexUrl: string;
+    };
+};
+
+export { _default as default, healthCheck, onAfterResponse, onBeforeCompaction, onBeforeResponse, pluginInfo };

package/dist/index.js

@@ -0,0 +1,103 @@
+// src/index.ts
+var CORTEX_URL = process.env.CORTEX_URL || "http://localhost:21100";
+var RECALL_TIMEOUT = 3e3;
+var INGEST_TIMEOUT = 5e3;
+var FLUSH_TIMEOUT = 5e3;
+async function onBeforeResponse(context) {
+  if (!context.lastUserMessage) return null;
+  try {
+    const res = await fetch(`${CORTEX_URL}/api/v1/recall`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        query: context.lastUserMessage,
+        agent_id: context.agentId || "openclaw",
+        max_tokens: 2e3
+      }),
+      signal: AbortSignal.timeout(RECALL_TIMEOUT)
+    });
+    if (res.ok) {
+      const data = await res.json();
+      if (data.context && data.meta.injected_count > 0) {
+        return { prependContext: data.context };
+      }
+    }
+  } catch (e) {
+    if (process.env.CORTEX_DEBUG) {
+      console.warn("[cortex-bridge] Sidecar unreachable for recall:", e.message);
+    }
+  }
+  return null;
+}
+async function onAfterResponse(context) {
+  if (!context.lastUserMessage || !context.lastAssistantMessage) return;
+  try {
+    fetch(`${CORTEX_URL}/api/v1/ingest`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        user_message: context.lastUserMessage,
+        assistant_message: context.lastAssistantMessage,
+        agent_id: context.agentId || "openclaw",
+        session_id: context.sessionId
+      }),
+      signal: AbortSignal.timeout(INGEST_TIMEOUT)
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+async function onBeforeCompaction(context) {
+  if (!context.messages || context.messages.length === 0) return;
+  try {
+    await fetch(`${CORTEX_URL}/api/v1/flush`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        messages: context.messages,
+        agent_id: context.agentId || "openclaw",
+        session_id: context.sessionId,
+        reason: "compaction"
+      }),
+      signal: AbortSignal.timeout(FLUSH_TIMEOUT)
+    });
+  } catch (e) {
+    if (process.env.CORTEX_DEBUG) {
+      console.warn("[cortex-bridge] Flush failed:", e.message);
+    }
+  }
+}
+async function healthCheck() {
+  const start = Date.now();
+  try {
+    const res = await fetch(`${CORTEX_URL}/api/v1/health`, {
+      signal: AbortSignal.timeout(2e3)
+    });
+    const data = await res.json();
+    return { ok: data.status === "ok", latency_ms: Date.now() - start };
+  } catch (e) {
+    return { ok: false, latency_ms: Date.now() - start, error: e.message };
+  }
+}
+var pluginInfo = {
+  name: "cortex-bridge",
+  version: "0.1.0",
+  description: "Bridge plugin for Cortex AI Agent Memory Service",
+  cortexUrl: CORTEX_URL
+};
+var index_default = {
+  name: "cortex-bridge",
+  onBeforeResponse,
+  onAfterResponse,
+  onBeforeCompaction,
+  healthCheck,
+  pluginInfo
+};
+export {
+  index_default as default,
+  healthCheck,
+  onAfterResponse,
+  onBeforeCompaction,
+  onBeforeResponse,
+  pluginInfo
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@cortexmem/bridge-openclaw",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsx src/index.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  }
+}