heurchain 1.4.2 → 2.0.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 +195 -361
- package/AGENT_ONBOARDING.md +365 -0
- package/CHANGELOG.md +31 -103
- package/LICENSE +21 -0
- package/README.md +127 -413
- package/package.json +38 -38
- package/server.js +0 -1364
package/README.md
CHANGED
|
@@ -1,413 +1,127 @@
|
|
|
1
|
-
# HeurChain
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
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
|
-
|
|
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
|
-
### 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
|
|
1
|
+
# HeurChain
|
|
2
|
+
|
|
3
|
+
**One memory system for every AI agent you run, on your own infrastructure.**
|
|
4
|
+
|
|
5
|
+
HeurChain is a persistent memory broker for AI agents. Claude Code, Codex, Gemini, local
|
|
6
|
+
models and any HTTP or MCP client share one store. They write facts, decisions and session
|
|
7
|
+
summaries, and later recall them with hybrid search: keyword (BM25) and meaning (dense
|
|
8
|
+
vectors), fused into one ranking.
|
|
9
|
+
|
|
10
|
+
> ### This package is the agent kit, not the server
|
|
11
|
+
>
|
|
12
|
+
> `npm install heurchain` gives you the files agents use to connect to a HeurChain broker:
|
|
13
|
+
> `AGENT_CONFIG.json` (a machine-readable manifest of the API, MCP tools and session
|
|
14
|
+
> protocol) and `AGENT_ONBOARDING.md`. **It does not run anything.**
|
|
15
|
+
>
|
|
16
|
+
> **To run HeurChain**, clone the GitHub repository and start it with Docker Compose. That
|
|
17
|
+
> repository is the complete self-hosted package: the Go broker 0.6.1-oss.1, Redis, Qdrant and an
|
|
18
|
+
> embedding model. See [Run the broker](#run-the-broker) below.
|
|
19
|
+
>
|
|
20
|
+
> Versions 1.x were a Node.js server. They are deprecated and still installable as
|
|
21
|
+
> `heurchain@1`; see [Upgrading from 1.x](#upgrading-from-1x).
|
|
22
|
+
|
|
23
|
+
Source and install guide: **https://github.com/peterjohannmedina/heurchain**
|
|
24
|
+
|
|
25
|
+
## How it works
|
|
26
|
+
|
|
27
|
+

|
|
28
|
+
|
|
29
|
+
The broker is one Go binary on one port. Agents reach it over **MCP** or **HTTP + JSON**,
|
|
30
|
+
and every request carries an API key and a tenant ID (one tenant per person, team or
|
|
31
|
+
project). Redis holds the memory records and the keyword index, Qdrant holds the vectors, an
|
|
32
|
+
embedder (Ollama or any OpenAI-compatible API) turns text into vectors, and a SQLite file
|
|
33
|
+
holds tenants, keys and the audit log. All of it runs on your machine.
|
|
34
|
+
|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
- **Store**: embed the text, save the record in Redis, index it for keywords (Redis) and for
|
|
38
|
+
meaning (Qdrant).
|
|
39
|
+
- **Recall**: search both indexes and fuse the two rankings with reciprocal rank fusion, so
|
|
40
|
+
memories that match on exact words and on meaning come first.
|
|
41
|
+
- **Lifecycle**: memories that go unused fade; a background worker can move them into a
|
|
42
|
+
vault that is kept and exportable but no longer searched (off until you enable it).
|
|
43
|
+
|
|
44
|
+
## Run the broker
|
|
45
|
+
|
|
46
|
+
Requirements: Docker Engine with Compose v2.
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
git clone https://github.com/peterjohannmedina/heurchain.git
|
|
50
|
+
cd heurchain
|
|
51
|
+
cp deploy/.env.example deploy/.env # set ADMIN_USER and a long random ADMIN_PASS
|
|
52
|
+
docker compose -f deploy/compose.yaml up -d --build
|
|
53
|
+
docker compose -f deploy/compose.yaml exec ollama ollama pull nomic-embed-text
|
|
54
|
+
curl -s http://127.0.0.1:8080/health
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The stack runs the broker, Redis, Qdrant and Ollama, published on `127.0.0.1` only. These
|
|
58
|
+
steps are tested end to end on every broker or deploy change. The full guide (native
|
|
59
|
+
systemd install, TLS, backups) is
|
|
60
|
+
[docs/install.md](https://github.com/peterjohannmedina/heurchain/blob/master/docs/install.md).
|
|
61
|
+
|
|
62
|
+
Create a tenant and API key (the key is shown once):
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
curl -s -u "$ADMIN_USER:$ADMIN_PASS" -X POST http://127.0.0.1:8080/admin/tenants \
|
|
66
|
+
-H 'Content-Type: application/json' -d '{"name":"My team","email":"me@example.com"}'
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Wire your agent
|
|
70
|
+
|
|
71
|
+
Every request sends two headers: `X-HeurChain-API-Key: <api_key>` and
|
|
72
|
+
`X-HeurChain-Tenant: <tenant_id>`.
|
|
73
|
+
|
|
74
|
+
**MCP (Streamable HTTP)**, for example Claude Code:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
claude mcp add --transport http heurchain http://127.0.0.1:8080/mcp/sse \
|
|
78
|
+
--header "X-HeurChain-API-Key: $KEY" --header "X-HeurChain-Tenant: $TENANT"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**HTTP**: `POST /store`, `POST /search`, `POST /query`, `POST /session/start`, and so on.
|
|
82
|
+
`GET /openapi.json` on your broker describes every endpoint.
|
|
83
|
+
|
|
84
|
+
**Let the agent set itself up.** Paste this to any agent:
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
Read the setup instructions in the heurchain npm package (README.md and
|
|
88
|
+
AGENT_CONFIG.json, https://www.npmjs.com/package/heurchain), then connect to the
|
|
89
|
+
HeurChain broker at http://<your-host>:8080 using the API key and tenant ID I give
|
|
90
|
+
you. Follow the session protocol in AGENT_CONFIG.json.
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Session protocol
|
|
94
|
+
|
|
95
|
+

|
|
96
|
+
|
|
97
|
+
1. `GET /memory/manifest`: see what is already stored before asking the user.
|
|
98
|
+
2. `POST /session/start` with your `agent_id`; pass the returned `session_id` as
|
|
99
|
+
`metadata.session_id` on every store.
|
|
100
|
+
3. `GET /agent/{agent_id}`: recall your recent memories.
|
|
101
|
+
4. During work: `POST /search` before asking, `POST /store` for facts and decisions.
|
|
102
|
+
5. At the end: `POST /session/end`, then store a concise summary.
|
|
103
|
+
|
|
104
|
+
## What's in this package
|
|
105
|
+
|
|
106
|
+
| File | For |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `AGENT_CONFIG.json` | Machine-readable manifest: auth headers, MCP and HTTP connection, session protocol, every HTTP operation and MCP tool of broker 0.6.1-oss.1 |
|
|
109
|
+
| `AGENT_ONBOARDING.md` | The broker's own agent guide (the same text it serves at `GET /`) |
|
|
110
|
+
| `README.md` | This file |
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
const config = require('heurchain/AGENT_CONFIG.json');
|
|
114
|
+
console.log(config.authentication.headers);
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Upgrading from 1.x
|
|
118
|
+
|
|
119
|
+
1.x was a Node.js server with its own Redis key layout (`doc:*`, `memory:*`, Obsidian/Ori
|
|
120
|
+
vault tiers). Broker 0.6.1 does not read 1.x data in place. Run the new broker alongside
|
|
121
|
+
the old one, with separate Redis instances, and re-store what you want to keep through
|
|
122
|
+
`POST /store`. Keep the 1.x deployment until you have checked the results. The 1.x versions
|
|
123
|
+
stay installable as `heurchain@1`.
|
|
124
|
+
|
|
125
|
+
## License
|
|
126
|
+
|
|
127
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,38 +1,38 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "heurchain",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "
|
|
5
|
-
"
|
|
6
|
-
|
|
7
|
-
"
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
"
|
|
12
|
-
"
|
|
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
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "heurchain",
|
|
3
|
+
"version": "2.0.2",
|
|
4
|
+
"description": "Setup guide and agent configuration for the self-hosted HeurChain memory broker (0.6.1-oss.1): persistent, hybrid-search memory shared by every AI agent over MCP or HTTP",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"mcp",
|
|
7
|
+
"heurchain",
|
|
8
|
+
"agent-memory",
|
|
9
|
+
"llm",
|
|
10
|
+
"ai",
|
|
11
|
+
"model-context-protocol",
|
|
12
|
+
"bm25",
|
|
13
|
+
"rag",
|
|
14
|
+
"self-hosted",
|
|
15
|
+
"claude"
|
|
16
|
+
],
|
|
17
|
+
"homepage": "https://github.com/peterjohannmedina/heurchain#readme",
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/peterjohannmedina/heurchain.git",
|
|
21
|
+
"directory": "npm"
|
|
22
|
+
},
|
|
23
|
+
"bugs": {
|
|
24
|
+
"url": "https://github.com/peterjohannmedina/heurchain/issues"
|
|
25
|
+
},
|
|
26
|
+
"license": "MIT",
|
|
27
|
+
"author": "HeurChain <info@heurchain.com>",
|
|
28
|
+
"files": [
|
|
29
|
+
"AGENT_CONFIG.json",
|
|
30
|
+
"AGENT_ONBOARDING.md",
|
|
31
|
+
"CHANGELOG.md"
|
|
32
|
+
],
|
|
33
|
+
"exports": {
|
|
34
|
+
"./AGENT_CONFIG.json": "./AGENT_CONFIG.json",
|
|
35
|
+
"./AGENT_ONBOARDING.md": "./AGENT_ONBOARDING.md",
|
|
36
|
+
"./package.json": "./package.json"
|
|
37
|
+
}
|
|
38
|
+
}
|