@ubundi/openclaw-cortex 0.3.2 → 0.3.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +54 -13
- package/dist/core/config/schema.js +1 -1
- package/dist/core/config/schema.js.map +1 -1
- package/openclaw.plugin.json +14 -4
- package/package.json +23 -6
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025-2026 Ubundi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
# @ubundi/openclaw-cortex
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@ubundi/openclaw-cortex)
|
|
4
|
+
[](https://github.com/Ubundi/openclaw-cortex/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
3
7
|
|
|
4
8
|
|
|
5
|
-
OpenClaw plugin for [Cortex](https://github.com/ubundi/cortex) long-term memory. Gives your agent persistent memory that survives across sessions — who you are, what your project does, decisions you made weeks ago, and how things changed over time.
|
|
9
|
+
[OpenClaw](https://github.com/openclaw/openclaw) plugin for [Cortex](https://github.com/ubundi/cortex) long-term memory. Gives your agent persistent memory that survives across sessions — who you are, what your project does, decisions you made weeks ago, and how things changed over time.
|
|
6
10
|
|
|
7
11
|
- **Auto-Recall** — injects relevant memories before every agent turn via `before_agent_start` hook
|
|
8
12
|
- **Auto-Capture** — extracts facts from conversations via `agent_end` hook
|
|
@@ -10,6 +14,14 @@ OpenClaw plugin for [Cortex](https://github.com/ubundi/cortex) long-term memory.
|
|
|
10
14
|
- **Periodic Reflect** — consolidates memories, resolves SUPERSEDES chains, detects contradictions
|
|
11
15
|
- **Resilience** — retry queue with exponential backoff, cold-start detection, latency metrics
|
|
12
16
|
|
|
17
|
+
> **Cortex availability:** Cortex is currently privately hosted and in early testing — it is not yet a public service. API keys are not self-serve; to request access email [matthew@ubundi.co.za](mailto:matthew@ubundi.co.za). A public sign-up is planned for the future.
|
|
18
|
+
|
|
19
|
+
## Prerequisites
|
|
20
|
+
|
|
21
|
+
- Node.js `>=20`
|
|
22
|
+
- [OpenClaw](https://github.com/openclaw/openclaw) with plugin support (`openclaw` peer dependency is `>=0.1.0`)
|
|
23
|
+
- Cortex API key — available on request (see availability note above)
|
|
24
|
+
|
|
13
25
|
## Installation
|
|
14
26
|
|
|
15
27
|
```bash
|
|
@@ -22,6 +34,36 @@ Or link locally for development:
|
|
|
22
34
|
openclaw plugins install -l ./path/to/openclaw-cortex
|
|
23
35
|
```
|
|
24
36
|
|
|
37
|
+
## Quick Start
|
|
38
|
+
|
|
39
|
+
1. Install the plugin:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
openclaw plugins install @ubundi/openclaw-cortex
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
2. Add a minimal plugin config to `openclaw.json`:
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{
|
|
49
|
+
"plugins": {
|
|
50
|
+
"entries": {
|
|
51
|
+
"@ubundi/openclaw-cortex": {
|
|
52
|
+
"enabled": true,
|
|
53
|
+
"config": {
|
|
54
|
+
"apiKey": "${CORTEX_API_KEY}"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
},
|
|
58
|
+
"slots": {
|
|
59
|
+
"memory": "@ubundi/openclaw-cortex"
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
3. Run an agent turn. If configured correctly, recall data is prepended in a `<cortex_memories>` block before the model turn.
|
|
66
|
+
|
|
25
67
|
## Configuration
|
|
26
68
|
|
|
27
69
|
Add to your `openclaw.json`:
|
|
@@ -34,6 +76,7 @@ Add to your `openclaw.json`:
|
|
|
34
76
|
enabled: true,
|
|
35
77
|
config: {
|
|
36
78
|
apiKey: "sk-cortex-...",
|
|
79
|
+
// Cortex hosted API endpoint — provided with your API key. Omit to use the default.
|
|
37
80
|
baseUrl: "https://q5p64iw9c9.execute-api.us-east-1.amazonaws.com/prod",
|
|
38
81
|
autoRecall: true,
|
|
39
82
|
autoCapture: true,
|
|
@@ -67,17 +110,8 @@ Environment variables are supported via `${VAR_NAME}` syntax:
|
|
|
67
110
|
| Option | Type | Default | Description |
|
|
68
111
|
|---|---|---|---|
|
|
69
112
|
| `apiKey` | string | _required_ | Cortex API key |
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
| `autoCapture` | boolean | `true` | Extract facts after agent responses |
|
|
73
|
-
| `recallTopK` | number | `5` | Number of memories to retrieve per turn |
|
|
74
|
-
| `recallTimeoutMs` | number | `500` | Max time to wait for recall (ms) |
|
|
75
|
-
| `recallMode` | string | `"fast"` | Retrieval depth: `fast`, `balanced`, or `full` |
|
|
76
|
-
| `fileSync` | boolean | `true` | Watch MEMORY.md and daily logs |
|
|
77
|
-
| `transcriptSync` | boolean | `true` | Watch and ingest session transcripts |
|
|
78
|
-
| `reflectIntervalMs` | number | `3600000` | Memory consolidation interval (ms). `0` to disable |
|
|
79
|
-
| `recallQueryType` | string | `"combined"` | Retrieval bias: `factual` (entities/facts), `emotional` (feelings/values), or `combined` |
|
|
80
|
-
| `namespace` | string | _(auto)_ | Memory namespace. Auto-derived from workspace directory; set explicitly to share memory across workspaces |
|
|
113
|
+
|
|
114
|
+
All other options are pre-configured with sensible defaults and can be tuned via the OpenClaw plugin config UI.
|
|
81
115
|
|
|
82
116
|
### Recall Modes
|
|
83
117
|
|
|
@@ -145,12 +179,19 @@ Use this to tune `recallTimeoutMs` and `recallMode` for your deployment.
|
|
|
145
179
|
|
|
146
180
|
If both this plugin and the Cortex SKILL.md are active, the `<cortex_memories>` tag in the prepended context signals to the skill that recall has already happened — the agent can skip manual `curl` calls.
|
|
147
181
|
|
|
182
|
+
## Troubleshooting
|
|
183
|
+
|
|
184
|
+
- `apiKey` errors on startup: confirm `config.apiKey` is set and `${CORTEX_API_KEY}` resolves in your environment.
|
|
185
|
+
- Plugin installed but no memory behavior: verify both `"enabled": true` and `"slots.memory": "@ubundi/openclaw-cortex"` in `openclaw.json`.
|
|
186
|
+
- Frequent recall timeouts: increase `recallTimeoutMs` and/or set `recallMode` to `"fast"`.
|
|
187
|
+
- No useful memories returned: ensure prior sessions were captured (`autoCapture`) or file sync is enabled (`fileSync`, `transcriptSync`).
|
|
188
|
+
|
|
148
189
|
## Development
|
|
149
190
|
|
|
150
191
|
```bash
|
|
151
192
|
npm install
|
|
152
193
|
npm run build # TypeScript → dist/
|
|
153
|
-
npm test # Run vitest (
|
|
194
|
+
npm test # Run vitest (150 tests)
|
|
154
195
|
npm run test:watch # Watch mode
|
|
155
196
|
npm run test:integration # Live Cortex API tests (requires CORTEX_API_KEY)
|
|
156
197
|
```
|
|
@@ -24,7 +24,7 @@ export const CortexConfigSchema = z.object({
|
|
|
24
24
|
autoRecall: z.boolean().default(true),
|
|
25
25
|
autoCapture: z.boolean().default(true),
|
|
26
26
|
recallTopK: z.number().int().min(1).max(20).default(5),
|
|
27
|
-
recallTimeoutMs: z.number().int().min(100).max(10000).default(
|
|
27
|
+
recallTimeoutMs: z.number().int().min(100).max(10000).default(500),
|
|
28
28
|
recallMode: RecallMode.default("fast"),
|
|
29
29
|
recallQueryType: RecallQueryType.default("combined"),
|
|
30
30
|
fileSync: z.boolean().default(true),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/core/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAG/D,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AAG5E;;GAEG;AACH,MAAM,QAAQ,GAAG,CAAC;KACf,MAAM,EAAE;KACR,GAAG,CAAC,6BAA6B,CAAC;KAClC,MAAM,CACL,CAAC,GAAG,EAAE,EAAE;IACN,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9C,wDAAwD;IACxD,IACE,MAAM,CAAC,QAAQ,KAAK,OAAO;QAC3B,CAAC,MAAM,CAAC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC,EACpE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,EACD,EAAE,OAAO,EAAE,0DAA0D,EAAE,CACxE,CAAC;AAEJ,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,oBAAoB,CAAC;IAC/C,OAAO,EAAE,QAAQ,CAAC,OAAO,CACvB,6DAA6D,CAC9D;IACD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,
|
|
1
|
+
{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/core/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;AAG/D,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;AAG5E;;GAEG;AACH,MAAM,QAAQ,GAAG,CAAC;KACf,MAAM,EAAE;KACR,GAAG,CAAC,6BAA6B,CAAC;KAClC,MAAM,CACL,CAAC,GAAG,EAAE,EAAE;IACN,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9C,wDAAwD;IACxD,IACE,MAAM,CAAC,QAAQ,KAAK,OAAO;QAC3B,CAAC,MAAM,CAAC,QAAQ,KAAK,WAAW,IAAI,MAAM,CAAC,QAAQ,KAAK,WAAW,CAAC,EACpE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC,EACD,EAAE,OAAO,EAAE,0DAA0D,EAAE,CACxE,CAAC;AAEJ,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,oBAAoB,CAAC;IAC/C,OAAO,EAAE,QAAQ,CAAC,OAAO,CACvB,6DAA6D,CAC9D;IACD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACrC,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACtC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC;IAClE,UAAU,EAAE,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC;IACtC,eAAe,EAAE,eAAe,CAAC,OAAO,CAAC,UAAU,CAAC;IACpD,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACzC,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC7D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;CACjD,CAAC,CAAC;AAIH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS,CAAC,KAAc;QACtB,OAAO,kBAAkB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7C,CAAC;CACF,CAAC"}
|
package/openclaw.plugin.json
CHANGED
|
@@ -2,11 +2,13 @@
|
|
|
2
2
|
"id": "cortex-memory",
|
|
3
3
|
"name": "Cortex Memory",
|
|
4
4
|
"description": "Long-term memory powered by Cortex — Auto-Recall, Auto-Capture, transcript ingestion, periodic consolidation, and background file sync",
|
|
5
|
-
"version": "0.3.
|
|
5
|
+
"version": "0.3.4",
|
|
6
6
|
"kind": "memory",
|
|
7
7
|
"configSchema": {
|
|
8
8
|
"type": "object",
|
|
9
|
-
"required": [
|
|
9
|
+
"required": [
|
|
10
|
+
"apiKey"
|
|
11
|
+
],
|
|
10
12
|
"properties": {
|
|
11
13
|
"apiKey": {
|
|
12
14
|
"type": "string",
|
|
@@ -39,7 +41,11 @@
|
|
|
39
41
|
},
|
|
40
42
|
"recallMode": {
|
|
41
43
|
"type": "string",
|
|
42
|
-
"enum": [
|
|
44
|
+
"enum": [
|
|
45
|
+
"fast",
|
|
46
|
+
"balanced",
|
|
47
|
+
"full"
|
|
48
|
+
],
|
|
43
49
|
"description": "Retrieval depth — fast (BM25 + semantic), balanced (+ light reranking), full (+ graph traversal + reranker)",
|
|
44
50
|
"default": "fast"
|
|
45
51
|
},
|
|
@@ -60,7 +66,11 @@
|
|
|
60
66
|
},
|
|
61
67
|
"recallQueryType": {
|
|
62
68
|
"type": "string",
|
|
63
|
-
"enum": [
|
|
69
|
+
"enum": [
|
|
70
|
+
"factual",
|
|
71
|
+
"emotional",
|
|
72
|
+
"combined"
|
|
73
|
+
],
|
|
64
74
|
"description": "Type of retrieval query — factual (entities/facts), emotional (feelings/values), or combined",
|
|
65
75
|
"default": "combined"
|
|
66
76
|
},
|
package/package.json
CHANGED
|
@@ -1,10 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ubundi/openclaw-cortex",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.4",
|
|
4
4
|
"description": "OpenClaw plugin for Cortex memory — Auto-Recall, Auto-Capture, and file sync",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"types": "./dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"import": "./dist/index.js",
|
|
11
|
+
"types": "./dist/index.d.ts"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=20.0.0"
|
|
16
|
+
},
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "git+https://github.com/Ubundi/openclaw-cortex.git"
|
|
20
|
+
},
|
|
21
|
+
"bugs": {
|
|
22
|
+
"url": "https://github.com/Ubundi/openclaw-cortex/issues"
|
|
23
|
+
},
|
|
24
|
+
"homepage": "https://github.com/Ubundi/openclaw-cortex#readme",
|
|
8
25
|
"openclaw": {
|
|
9
26
|
"extensions": [
|
|
10
27
|
"./dist/index.js"
|
|
@@ -15,11 +32,14 @@
|
|
|
15
32
|
"test": "vitest run",
|
|
16
33
|
"test:watch": "vitest",
|
|
17
34
|
"test:integration": "vitest run -c vitest.integration.config.ts",
|
|
18
|
-
"
|
|
35
|
+
"verify-release": "node scripts/verify-release.mjs",
|
|
36
|
+
"clean": "rm -rf dist",
|
|
37
|
+
"version": "node scripts/sync-version.mjs && git add openclaw.plugin.json"
|
|
19
38
|
},
|
|
20
39
|
"files": [
|
|
21
40
|
"dist",
|
|
22
|
-
"openclaw.plugin.json"
|
|
41
|
+
"openclaw.plugin.json",
|
|
42
|
+
"LICENSE"
|
|
23
43
|
],
|
|
24
44
|
"keywords": [
|
|
25
45
|
"openclaw",
|
|
@@ -40,8 +60,5 @@
|
|
|
40
60
|
"hono": "^4.11.9",
|
|
41
61
|
"typescript": "^5.5.0",
|
|
42
62
|
"vitest": "^2.0.0"
|
|
43
|
-
},
|
|
44
|
-
"optionalDependencies": {
|
|
45
|
-
"hono": "*"
|
|
46
63
|
}
|
|
47
64
|
}
|