@ubundi/openclaw-cortex 0.3.3 → 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 +1 -1
- package/README.md +54 -13
- package/openclaw.plugin.json +1 -1
- package/package.json +1 -1
package/LICENSE
CHANGED
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
|
```
|
package/openclaw.plugin.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
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",
|