heurchain 1.4.1 → 1.4.2
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/AGENT_CONFIG.json +361 -361
- package/CHANGELOG.md +103 -103
- package/README.md +413 -390
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,390 +1,413 @@
|
|
|
1
|
-
# HeurChain
|
|
2
|
-
|
|
3
|
-
> **HeurChain** — short for **Heuristic Chaining** — describes the core design principle: knowledge is not stored in isolation but chained through heuristic reasoning, so that each piece of stored information reinforces and contextualizes what came before. The result is a memory system that improves its own recall accuracy over time, across every agent that writes to it.
|
|
4
|
-
|
|
5
|
-
**One memory system. Every AI agent. Simultaneously.**
|
|
6
|
-
|
|
7
|
-
HeurChain is a universal persistent memory layer for AI agents. Claude Code, Kimi, Hermes, OpenClaw, ChatGPT, and any HTTP or MCP client share the same tiered knowledge store — BM25-ranked search, session continuity, and automatic tier promotion — without any agent-specific configuration beyond a URL and an interface choice.
|
|
8
|
-
|
|
9
|
-
[](https://www.npmjs.com/package/heurchain)
|
|
10
|
-
[](LICENSE)
|
|
11
|
-
[](https://nodejs.org)
|
|
12
|
-
[](https://docs.docker.com/compose/)
|
|
13
|
-
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
##
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
|
21
|
-
|
|
22
|
-
| **
|
|
23
|
-
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
###
|
|
67
|
-
|
|
68
|
-
```bash
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
| `
|
|
301
|
-
| `
|
|
302
|
-
| `
|
|
303
|
-
| `
|
|
304
|
-
| `
|
|
305
|
-
| `
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
|
322
|
-
|
|
323
|
-
|
|
|
324
|
-
|
|
|
325
|
-
|
|
|
326
|
-
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
|
339
|
-
|
|
340
|
-
|
|
|
341
|
-
|
|
|
342
|
-
|
|
|
343
|
-
|
|
|
344
|
-
|
|
|
345
|
-
|
|
|
346
|
-
|
|
|
347
|
-
|
|
|
348
|
-
|
|
|
349
|
-
|
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
1
|
+
# HeurChain
|
|
2
|
+
|
|
3
|
+
> **HeurChain** — short for **Heuristic Chaining** — describes the core design principle: knowledge is not stored in isolation but chained through heuristic reasoning, so that each piece of stored information reinforces and contextualizes what came before. The result is a memory system that improves its own recall accuracy over time, across every agent that writes to it.
|
|
4
|
+
|
|
5
|
+
**One memory system. Every AI agent. Simultaneously.**
|
|
6
|
+
|
|
7
|
+
HeurChain is a universal persistent memory layer for AI agents. Claude Code, Kimi, Hermes, OpenClaw, ChatGPT, and any HTTP or MCP client share the same tiered knowledge store — BM25-ranked search, session continuity, and automatic tier promotion — without any agent-specific configuration beyond a URL and an interface choice.
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/heurchain)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](https://nodejs.org)
|
|
12
|
+
[](https://docs.docker.com/compose/)
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Wiring your agent — where to look
|
|
17
|
+
|
|
18
|
+
You don't need to manually configure every option. Point your agent at either of these resources and it can read its own wiring instructions and self-configure:
|
|
19
|
+
|
|
20
|
+
| Resource | Where | What it contains |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| **This README** | `https://www.npmjs.com/package/heurchain` | Complete setup, per-agent wiring snippets, API reference, session protocol |
|
|
23
|
+
| **`AGENT_CONFIG.json`** | Bundled inside the npm package at install time | Machine-readable session lifecycle and tool catalog — designed for programmatic bootstrapping |
|
|
24
|
+
|
|
25
|
+
**Paste this prompt to any agent to get it started:**
|
|
26
|
+
|
|
27
|
+
```
|
|
28
|
+
Read the setup instructions at https://www.npmjs.com/package/heurchain,
|
|
29
|
+
then wire yourself to the HeurChain instance at http://<your-host>.
|
|
30
|
+
Follow the session protocol in the README (or in AGENT_CONFIG.json if you
|
|
31
|
+
have the npm package): start a session on startup, use /agent/store and
|
|
32
|
+
/search during work, end with a summary on shutdown.
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The agent will find its protocol section (MCP SSE or HTTP REST), wire itself, and start using the session lifecycle. No manual configuration needed beyond the host URL.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Tested agents
|
|
40
|
+
|
|
41
|
+
| Agent | Protocol | Status |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| **Claude Code** | MCP SSE via nginx | ✓ Connected |
|
|
44
|
+
| **Kimi (Moonshot)** | MCP SSE via nginx | ✓ Connected — full read/write confirmed |
|
|
45
|
+
| **Hermes** | HTTP REST direct to broker | ✓ Connected — all 12 endpoints verified |
|
|
46
|
+
| **OpenClaw** | HTTP REST direct to broker | ✓ Connected — session lifecycle, BM25, persist flag |
|
|
47
|
+
| **ChatGPT / GPT Actions** | HTTP REST via nginx | ✓ Compatible |
|
|
48
|
+
| **Any HTTP client** | REST — no auth required | ✓ Compatible |
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Architecture
|
|
53
|
+
|
|
54
|
+
<img src="https://mermaid.ink/img/Zmxvd2NoYXJ0IFRECiAgICBzdWJncmFwaCBBR0VOVFMgWyJBbnkgQUkgQWdlbnQiXQogICAgICAgIEExWyJDbGF1ZGUgQ29kZSAvIEtpbWkKTUNQIFNTRSBjbGllbnQiXQogICAgICAgIEEyWyJPcGVuQ2xhdyAvIEhlcm1lcyAvIENoYXRHUFQKSFRUUCBjbGllbnQiXQogICAgZW5kCiAgICBzdWJncmFwaCBJRkFDRSBbIkludGVyZmFjZSBMYXllciJdCiAgICAgICAgTlsibmdpbnggOjgwClNTRSBnYXRld2F5Il0KICAgICAgICBNWyJoZXVyY2hhaW4tbWNwIDozMDEwCjI2IE1DUCB0b29scyJdCiAgICBlbmQKICAgIHN1YmdyYXBoIEJST0tFUiBbIkhldXJDaGFpbiBCcm9rZXIgOjMwMTIiXQogICAgICAgIFNNWyJTZXNzaW9uIE1hbmFnZXIKYWdlbnQgbmFtZXNwYWNpbmciXQogICAgICAgIFRSWyJUaWVyIFJvdXRlcgprZXkgcHJlZml4IHJvdXRpbmciXQogICAgICAgIEJNWyJCTTI1IEluZGV4CmluLW1lbW9yeSBzZWFyY2giXQogICAgZW5kCiAgICBzdWJncmFwaCBTVE9SRSBbIlN0b3JhZ2UgTGF5ZXIiXQogICAgICAgIFdbIk9yaSBWYXVsdApXb3JraW5nIFRpZXIKNy1kYXkgYXV0by1wcm9tb3RlIl0KICAgICAgICBSWygiUmVkaXMKTG9uZ3Rlcm0gVGllciIpXQogICAgICAgIE9bIk9ic2lkaWFuIFZhdWx0Ck1hcmtkb3duIG1pcnJvciJdCiAgICBlbmQKICAgIEExIC0tPnxNQ1AgU1NFfCBOCiAgICBBMiAtLT58SFRUUCBSRVNUfCBCUk9LRVIKICAgIE4gLS0+IE0KICAgIE0gLS0+IEJST0tFUgogICAgQlJPS0VSIC0tPiBTTSAtLT4gVFIKICAgIEJST0tFUiA8LS0+fHNjb3JlL2luZGV4fCBCTQogICAgVFIgLS0+fG1lbW9yeTogcHJlZml4fCBXCiAgICBUUiAtLT58ZG9jOiBrbm93bGVkZ2U6IHNlc3Npb246fCBSCiAgICBSIC0tPnxhdXRvLW1pcnJvcnwgTwogICAgQk0gPC0tPnxTQ0FOfCBSCiAgICBCTSA8LS0+fGdsb2IgbWR8IFcKICAgIFcgLS0+fGNvbnNvbGlkYXRpb24gNyBkYXlzfCBS" alt="HeurChain Architecture" width="100%" />
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## Data flow — Prompt to Memory to Recall
|
|
59
|
+
|
|
60
|
+
<img src="https://mermaid.ink/img/Zmxvd2NoYXJ0IFRECiAgICBzdWJncmFwaCBTVE9SRSBbIlNUT1JFIOKAlCBQcm9tcHQgdG8gTWVtb3J5Il0KICAgICAgICBkaXJlY3Rpb24gVEIKICAgICAgICBBKFtBZ2VudF0pIC0tPiBTU1siUE9TVCAvc2Vzc2lvbi9zdGFydCJdCiAgICAgICAgU1MgLS0+IFNJRFsic2Vzc2lvbl9pZCByZXR1cm5lZCJdCiAgICAgICAgU0lEIC0tPiBBU1siUE9TVCAvYWdlbnQvc3RvcmUKa2V5IMK3IGNvbnRlbnQgwrcgcGVyc2lzdCJdCiAgICAgICAgQVMgLS0+IFRSeyJUaWVyIFJvdXRlcgpjbGFzc2lmeV90aWVyIn0KICAgICAgICBUUiAtLT58Im1lbW9yeTogcHJlZml4InwgV1JbIk9yaSBWYXVsdApXb3JraW5nIFRpZXIKNy1kYXkgYXV0by1wcm9tb3RlIl0KICAgICAgICBUUiAtLT58ImRvYzoga25vd2xlZGdlOgpwZXJzaXN0PXRydWUifCBSRFsoIlJlZGlzCkxvbmd0ZXJtIildCiAgICAgICAgUkQgLS0+IEJNWyJCTTI1IEluZGV4IHVwZGF0ZWQiXQogICAgICAgIEFTIC0tPiBTRVsiUE9TVCAvc2Vzc2lvbi9lbmQKc3VtbWFyeSJdCiAgICAgICAgU0UgLS0+IFJECiAgICBlbmQKCiAgICBzdWJncmFwaCBSRUNBTEwgWyJSRUNBTEwg4oCUIE1lbW9yeSB0byBSZXNwb25zZSJdCiAgICAgICAgZGlyZWN0aW9uIFRCCiAgICAgICAgUjFbIkdFVCAvYWdlbnQvbmFtZS9yZWNhbGwiXSAtLT4gUldbIk9yaSBWYXVsdAp3b3JraW5nIGVudHJpZXMiXQogICAgICAgIFIxIC0tPiBSTFsoIlJlZGlzCmxvbmd0ZXJtIGVudHJpZXMiKV0KICAgICAgICBSVyAmIFJMIC0tPiBSUihbIkZ1bGwgY29udGV4dApyZXR1cm5lZCB0byBhZ2VudCJdKQogICAgICAgIFIyWyJHRVQgL3NlYXJjaD9xPXF1ZXJ5Il0gLS0+IEJNU1siQk0yNQpTY29yZSBhbGwgZG9jcyJdCiAgICAgICAgQk1TIC0tPiBSUyhbIlJhbmtlZCByZXN1bHRzCnJldHVybmVkIHRvIGFnZW50Il0pCiAgICBlbmQ" alt="HeurChain Data Flow — Store and Recall" width="100%" />
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## Install — one line
|
|
65
|
+
|
|
66
|
+
### Docker standalone (full stack — recommended)
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# Clone and start
|
|
70
|
+
git clone <repo-url> heurchain && cd heurchain/docker
|
|
71
|
+
cp .env.example .env
|
|
72
|
+
docker compose -f docker-compose.standalone.yml up -d --build
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Four containers start in dependency order:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
heurchain-redis → heurchain-broker → heurchain-mcp → heurchain-nginx
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Verify:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
curl http://localhost:3012/health # broker — Redis + vault status
|
|
85
|
+
curl http://localhost:3010/health # MCP server
|
|
86
|
+
curl http://localhost/ # nginx gateway (SSE entry point)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### npm (MCP server only — requires a running broker)
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm install heurchain
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
The npm package ships `server.js` and `AGENT_CONFIG.json`. The broker (FastAPI + Redis) must be running separately — use Docker standalone or the Ansible role for a managed host.
|
|
96
|
+
|
|
97
|
+
---
|
|
98
|
+
|
|
99
|
+
## Agent wiring
|
|
100
|
+
|
|
101
|
+
### Claude Code
|
|
102
|
+
|
|
103
|
+
Add to your project's `.mcp.json`:
|
|
104
|
+
|
|
105
|
+
```json
|
|
106
|
+
{
|
|
107
|
+
"mcpServers": {
|
|
108
|
+
"heurchain": {
|
|
109
|
+
"type": "sse",
|
|
110
|
+
"url": "http://<your-host>/sse"
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Enable in `.claude/settings.local.json`:
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"enabledMcpjsonServers": ["heurchain"]
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Restart Claude Code. Confirm with `claude mcp list` — you should see `heurchain: ✓ Connected`.
|
|
125
|
+
|
|
126
|
+
All 26 tools are then available in-context. Use `heurchain_search` for knowledge base queries (BM25 ranked). Use `cache_set` / `cache_get` for direct Redis access.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
### Kimi (Moonshot) and other MCP SSE clients
|
|
131
|
+
|
|
132
|
+
Same as Claude Code — point at the nginx gateway SSE endpoint:
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
http://<your-host>/sse
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Kimi confirmed: full read/write, all tools available including `heurchain_search`, `obsidian_write_note`, `user_context_add_entry`, Prometheus, Grafana, Proxmox, and Ceph tools.
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
### OpenClaw
|
|
143
|
+
|
|
144
|
+
Add to your OpenClaw agent config or environment:
|
|
145
|
+
|
|
146
|
+
```env
|
|
147
|
+
HEURCHAIN_URL=http://<your-host>:3012
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Use direct REST calls to the broker. No SSE required. OpenClaw agents confirmed: session start/end, `/agent/store` with persist flag, BM25 search, full session recall all working.
|
|
151
|
+
|
|
152
|
+
```javascript
|
|
153
|
+
// Start a session
|
|
154
|
+
const { session_id } = await fetch(`${HEURCHAIN_URL}/session/start`, {
|
|
155
|
+
method: 'POST',
|
|
156
|
+
headers: { 'Content-Type': 'application/json' },
|
|
157
|
+
body: JSON.stringify({ agent_name: 'openclaw', metadata: { task: 'current task' } })
|
|
158
|
+
}).then(r => r.json());
|
|
159
|
+
|
|
160
|
+
// Store with persistence
|
|
161
|
+
await fetch(`${HEURCHAIN_URL}/agent/store`, {
|
|
162
|
+
method: 'POST',
|
|
163
|
+
headers: { 'Content-Type': 'application/json' },
|
|
164
|
+
body: JSON.stringify({
|
|
165
|
+
agent_name: 'openclaw', session_id,
|
|
166
|
+
key: 'task_result', content: '...', persist: true
|
|
167
|
+
})
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
// BM25 search
|
|
171
|
+
const { results } = await fetch(`${HEURCHAIN_URL}/search?q=campaign+status&limit=10`).then(r => r.json());
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
### Hermes / Ori-Mnemos
|
|
177
|
+
|
|
178
|
+
Direct HTTP to the broker. Hermes confirmed all 12 endpoints, Swagger UI at `/docs`, OpenAPI spec at `/openapi.json`.
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
import httpx
|
|
182
|
+
|
|
183
|
+
BASE = "http://<your-host>:3012"
|
|
184
|
+
|
|
185
|
+
# Session lifecycle
|
|
186
|
+
session = httpx.post(f"{BASE}/session/start", json={"agent_name": "hermes"}).json()
|
|
187
|
+
session_id = session["session_id"]
|
|
188
|
+
|
|
189
|
+
# Store working memory
|
|
190
|
+
httpx.post(f"{BASE}/agent/store", json={
|
|
191
|
+
"agent_name": "hermes", "session_id": session_id,
|
|
192
|
+
"key": "embedding_notes", "content": "...", "persist": False
|
|
193
|
+
})
|
|
194
|
+
|
|
195
|
+
# Recall prior context
|
|
196
|
+
context = httpx.get(f"{BASE}/agent/hermes/recall").json()
|
|
197
|
+
|
|
198
|
+
# End session
|
|
199
|
+
httpx.post(f"{BASE}/session/end", json={"session_id": session_id, "summary": "..."})
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
### ChatGPT / GPT Actions
|
|
205
|
+
|
|
206
|
+
Point GPT Actions at the nginx gateway. The broker speaks plain JSON — no special headers required.
|
|
207
|
+
|
|
208
|
+
```yaml
|
|
209
|
+
openapi: 3.1.0
|
|
210
|
+
info:
|
|
211
|
+
title: HeurChain Memory API
|
|
212
|
+
version: 2.0.0
|
|
213
|
+
servers:
|
|
214
|
+
- url: http://<your-host>
|
|
215
|
+
paths:
|
|
216
|
+
/search:
|
|
217
|
+
get:
|
|
218
|
+
operationId: searchMemory
|
|
219
|
+
parameters:
|
|
220
|
+
- name: q
|
|
221
|
+
in: query
|
|
222
|
+
required: true
|
|
223
|
+
schema: { type: string }
|
|
224
|
+
- name: limit
|
|
225
|
+
in: query
|
|
226
|
+
schema: { type: integer, default: 10 }
|
|
227
|
+
/store:
|
|
228
|
+
post:
|
|
229
|
+
operationId: storeMemory
|
|
230
|
+
requestBody:
|
|
231
|
+
content:
|
|
232
|
+
application/json:
|
|
233
|
+
schema:
|
|
234
|
+
type: object
|
|
235
|
+
required: [key, content]
|
|
236
|
+
properties:
|
|
237
|
+
key: { type: string }
|
|
238
|
+
content: { type: string }
|
|
239
|
+
tier: { type: string, enum: [auto, working, longterm] }
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
### Generic HTTP (PowerShell, curl, any client)
|
|
245
|
+
|
|
246
|
+
```powershell
|
|
247
|
+
# Store
|
|
248
|
+
Invoke-RestMethod -Method POST -Uri "http://<host>:3012/store" `
|
|
249
|
+
-ContentType "application/json" `
|
|
250
|
+
-Body '{"key":"doc:myapp:notes","content":"hello world","tier":"longterm"}'
|
|
251
|
+
|
|
252
|
+
# Search
|
|
253
|
+
Invoke-RestMethod "http://<host>:3012/search?q=hello&limit=5"
|
|
254
|
+
|
|
255
|
+
# Start session
|
|
256
|
+
$s = Invoke-RestMethod -Method POST -Uri "http://<host>:3012/session/start" `
|
|
257
|
+
-ContentType "application/json" -Body '{"agent_name":"ps-agent"}'
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
```bash
|
|
261
|
+
# curl
|
|
262
|
+
curl -X POST http://<host>:3012/store \
|
|
263
|
+
-H "Content-Type: application/json" \
|
|
264
|
+
-d '{"key":"doc:myapp:notes","content":"hello world"}'
|
|
265
|
+
|
|
266
|
+
curl "http://<host>:3012/search?q=hello&limit=5"
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Session protocol
|
|
272
|
+
|
|
273
|
+
Every agent interaction should follow this lifecycle. Read `AGENT_CONFIG.json` (bundled with the npm package) for the full machine-readable version.
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
Startup
|
|
277
|
+
1. POST /session/start → {session_id}
|
|
278
|
+
2. GET /agent/{name}/recall → restore prior context
|
|
279
|
+
3. GET /health → verify backends before starting work
|
|
280
|
+
|
|
281
|
+
During work
|
|
282
|
+
• POST /agent/store persist=false → scratch notes (working tier)
|
|
283
|
+
• POST /agent/store persist=true → durable findings (both tiers)
|
|
284
|
+
• GET /search?q= → query knowledge base before answering
|
|
285
|
+
|
|
286
|
+
Shutdown
|
|
287
|
+
1. Persist key findings with persist=true
|
|
288
|
+
2. POST /session/end {session_id, summary} → summary is searchable in future sessions
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## API reference
|
|
294
|
+
|
|
295
|
+
All endpoints are on the broker at `:3012`. No authentication required.
|
|
296
|
+
|
|
297
|
+
| Method | Path | Description |
|
|
298
|
+
|---|---|---|
|
|
299
|
+
| `GET` | `/health` | Redis, Ori vault, Obsidian vault status |
|
|
300
|
+
| `GET` | `/docs` | Swagger UI |
|
|
301
|
+
| `GET` | `/openapi.json` | OpenAPI 3.1 spec |
|
|
302
|
+
| `POST` | `/store` | Store memory with auto tier routing |
|
|
303
|
+
| `GET` | `/get?key=&tier=` | Get by exact key (all/longterm/working) |
|
|
304
|
+
| `GET` | `/search?q=&limit=&tier=` | BM25 ranked search across all tiers |
|
|
305
|
+
| `GET` | `/keys?prefix=` | List Redis keys by prefix |
|
|
306
|
+
| `POST` | `/promote?key=&new_key=` | Promote working-tier entry to longterm Redis |
|
|
307
|
+
| `POST` | `/session/start` | Start agent session → `{session_id}` |
|
|
308
|
+
| `POST` | `/session/end` | End session, attach summary |
|
|
309
|
+
| `GET` | `/session/{id}` | Session metadata |
|
|
310
|
+
| `GET` | `/session/{id}/context` | All memory stored under a session |
|
|
311
|
+
| `GET` | `/agent/{name}/sessions` | All sessions for an agent, newest first |
|
|
312
|
+
| `GET` | `/agent/{name}/recall` | Full context of most recent session |
|
|
313
|
+
| `POST` | `/agent/store` | Store with automatic `agent_name + session_id` namespacing |
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## Key schema and tier routing
|
|
318
|
+
|
|
319
|
+
Keys determine which storage tier receives the write. Tier routing is automatic when `tier=auto` (default).
|
|
320
|
+
|
|
321
|
+
| Key pattern | Tier | Purpose |
|
|
322
|
+
|---|---|---|
|
|
323
|
+
| `memory:agent:{name}:{sid}:{key}` | working | Session-scoped scratch space |
|
|
324
|
+
| `doc:agent:{name}:{key}` | longterm | Agent persistent documents |
|
|
325
|
+
| `doc:{domain}:{topic}` | longterm | Shared reference documents |
|
|
326
|
+
| `knowledge:{domain}:{key}` | longterm | Shared knowledge base |
|
|
327
|
+
| `session:{id}` | longterm | Session metadata (auto-managed) |
|
|
328
|
+
| `agent:{name}:sessions` | Redis SET | Session registry (auto-managed) |
|
|
329
|
+
|
|
330
|
+
Always namespace your agent's own keys with your `agent_name` to prevent collisions with other agents.
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## MCP tool reference
|
|
335
|
+
|
|
336
|
+
Available when connected via SSE (Claude Code, Kimi, any MCP client):
|
|
337
|
+
|
|
338
|
+
| Category | Tools |
|
|
339
|
+
|---|---|
|
|
340
|
+
| Cache | `cache_set`, `cache_get`, `cache_delete`, `redis_stats` |
|
|
341
|
+
| Search | `heurchain_search` ← **preferred** (BM25 ranked), `obsidian_search_notes` (fallback) |
|
|
342
|
+
| Vault | `obsidian_write_note`, `obsidian_read_note`, `obsidian_delete_note`, `obsidian_list_notes` |
|
|
343
|
+
| Monitoring | `prometheus_query`, `prometheus_get_targets`, `prometheus_get_alerts` |
|
|
344
|
+
| Grafana | `grafana_get_health`, `grafana_list_dashboards` |
|
|
345
|
+
| Infrastructure | `proxmox_get_cluster_status`, `proxmox_list_nodes`, `proxmox_find_vm` |
|
|
346
|
+
| Ceph | `ceph_get_health_status`, `ceph_list_osd_notes` |
|
|
347
|
+
| Network | `network_search_docs`, `network_get_runbook` |
|
|
348
|
+
| User context | `user_context_add_entry`, `user_context_get_history`, `user_context_search_history` |
|
|
349
|
+
| Health | `health_check` |
|
|
350
|
+
|
|
351
|
+
Use `heurchain_search` over `obsidian_search_notes` for any knowledge base query — it runs BM25 over the full Redis keyspace (460+ keys), not just filesystem markdown files.
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## Configuration
|
|
356
|
+
|
|
357
|
+
Set via `.env` (Docker standalone) or Ansible inventory (managed host).
|
|
358
|
+
|
|
359
|
+
| Variable | Default | Description |
|
|
360
|
+
|---|---|---|
|
|
361
|
+
| `REDIS_HOST` | `localhost` | Redis hostname |
|
|
362
|
+
| `REDIS_PORT` | `6379` | Redis port |
|
|
363
|
+
| `MEMORY_BROKER_PORT` | `3012` | Broker listen port |
|
|
364
|
+
| `MCP_PORT` | `3010` | MCP server listen port |
|
|
365
|
+
| `NGINX_PORT` | `80` | Host-side nginx port (SSE entry point) |
|
|
366
|
+
| `HEURCHAIN_PORT` | `3012` | Host-side broker port |
|
|
367
|
+
| `OBSIDIAN_VAULT_PATH` | `./data/obsidian-vault` | Markdown vault root |
|
|
368
|
+
| `ORI_VAULT_PATH` | `./data/ori-vault` | Working tier markdown directory |
|
|
369
|
+
| `GRAFANA_USER` | `admin` | Grafana auth for MCP monitoring tools |
|
|
370
|
+
| `GRAFANA_PASSWORD` | `admin` | Grafana auth for MCP monitoring tools |
|
|
371
|
+
| `OLLAMA_URL` | `http://host.docker.internal:11434` | Ollama for consolidation worker |
|
|
372
|
+
| `CONSOLIDATE_AGE_DAYS` | `7` | Age threshold before working-tier auto-promotes to longterm |
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## Deployment
|
|
377
|
+
|
|
378
|
+
### Ansible (production — managed Linux host)
|
|
379
|
+
|
|
380
|
+
Provisions the full stack: system Redis, HeurChain broker (systemd service), Docker MCP stack, Prometheus + Grafana monitoring.
|
|
381
|
+
|
|
382
|
+
```bash
|
|
383
|
+
# 1. Fill in inventory
|
|
384
|
+
cp inventory.yml.example inventory.yml
|
|
385
|
+
vim inventory.yml
|
|
386
|
+
|
|
387
|
+
# 2. Deploy everything
|
|
388
|
+
ansible-playbook playbook.yml
|
|
389
|
+
|
|
390
|
+
# 3. Selective re-deploys
|
|
391
|
+
ansible-playbook playbook.yml --tags heurchain # broker only
|
|
392
|
+
ansible-playbook playbook.yml --tags docker # MCP + nginx stack only
|
|
393
|
+
ansible-playbook playbook.yml --tags system-redis # Redis config only
|
|
394
|
+
ansible-playbook playbook.yml --tags monitoring # Prometheus + Grafana only
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Role order: `system-prereqs` → `obsidian-vault` → `system-redis` → `heurchain` → `docker-stack` → `monitoring`
|
|
398
|
+
|
|
399
|
+
### Docker standalone (development / unmanaged hosts)
|
|
400
|
+
|
|
401
|
+
```bash
|
|
402
|
+
cd docker/
|
|
403
|
+
cp .env.example .env
|
|
404
|
+
docker compose -f docker-compose.standalone.yml up -d --build
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Requires Docker Compose v2 (`docker compose` plugin or `docker-compose >= 2.x`).
|
|
408
|
+
|
|
409
|
+
---
|
|
410
|
+
|
|
411
|
+
## License
|
|
412
|
+
|
|
413
|
+
MIT
|