heurchain 1.4.2 → 2.0.0
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 +204 -361
- package/AGENT_ONBOARDING.md +365 -0
- package/CHANGELOG.md +18 -103
- package/LICENSE +21 -0
- package/README.md +100 -413
- package/package.json +38 -38
- package/server.js +0 -1364
package/README.md
CHANGED
|
@@ -1,413 +1,100 @@
|
|
|
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
|
-
### 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
|
|
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 recall them later with hybrid search (BM25 + dense vectors, fused with RRF).
|
|
8
|
+
|
|
9
|
+
> **2.0.0 is a documentation and agent-configuration package.** Since 2.0.0, HeurChain is a
|
|
10
|
+
> self-hosted Go broker (version **0.6.1**) run with Docker Compose or systemd. This package
|
|
11
|
+
> no longer contains a server. It carries the setup guide and the machine-readable files
|
|
12
|
+
> agents use to wire themselves to your broker.
|
|
13
|
+
>
|
|
14
|
+
> The 1.x Node.js server (`server.js`) is deprecated. Its data model differs from the broker;
|
|
15
|
+
> see [Upgrading from 1.x](#upgrading-from-1x).
|
|
16
|
+
|
|
17
|
+
Source, install guide and research: **https://github.com/peterjohannmedina/heurchain**
|
|
18
|
+
|
|
19
|
+
## What's in this package
|
|
20
|
+
|
|
21
|
+
| File | For |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `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 |
|
|
24
|
+
| `AGENT_ONBOARDING.md` | The broker's own agent guide (the same text it serves at `GET /`) |
|
|
25
|
+
| `README.md` | This file |
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
const config = require('heurchain/AGENT_CONFIG.json');
|
|
29
|
+
console.log(config.authentication.headers);
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Run the broker
|
|
33
|
+
|
|
34
|
+
Requirements: Docker Engine with Compose v2.
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
git clone https://github.com/peterjohannmedina/heurchain.git
|
|
38
|
+
cd heurchain
|
|
39
|
+
cp deploy/.env.example deploy/.env # set ADMIN_USER and a long random ADMIN_PASS
|
|
40
|
+
docker compose -f deploy/compose.yaml up -d --build
|
|
41
|
+
docker compose -f deploy/compose.yaml exec ollama ollama pull nomic-embed-text
|
|
42
|
+
curl -s http://127.0.0.1:8080/health
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The stack runs the broker, Redis, Qdrant and Ollama, published on `127.0.0.1` only. The
|
|
46
|
+
full guide (native systemd install, TLS, backups) is
|
|
47
|
+
[docs/install.md](https://github.com/peterjohannmedina/heurchain/blob/master/docs/install.md).
|
|
48
|
+
|
|
49
|
+
Create a tenant and API key (the key is shown once):
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
curl -s -u "$ADMIN_USER:$ADMIN_PASS" -X POST http://127.0.0.1:8080/admin/tenants \
|
|
53
|
+
-H 'Content-Type: application/json' -d '{"name":"My team","email":"me@example.com"}'
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Wire your agent
|
|
57
|
+
|
|
58
|
+
Every request sends two headers: `X-HeurChain-API-Key: <api_key>` and
|
|
59
|
+
`X-HeurChain-Tenant: <tenant_id>`.
|
|
60
|
+
|
|
61
|
+
**MCP (Streamable HTTP)**, for example Claude Code:
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
claude mcp add --transport http heurchain http://127.0.0.1:8080/mcp/sse \
|
|
65
|
+
--header "X-HeurChain-API-Key: $KEY" --header "X-HeurChain-Tenant: $TENANT"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**HTTP**: `POST /store`, `POST /search`, `POST /query`, `POST /session/start`, and so on.
|
|
69
|
+
`GET /openapi.json` on your broker describes every endpoint.
|
|
70
|
+
|
|
71
|
+
**Let the agent set itself up.** Paste this to any agent:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
Read the setup instructions in the heurchain npm package (README.md and
|
|
75
|
+
AGENT_CONFIG.json, https://www.npmjs.com/package/heurchain), then connect to the
|
|
76
|
+
HeurChain broker at http://<your-host>:8080 using the API key and tenant ID I give
|
|
77
|
+
you. Follow the session protocol in AGENT_CONFIG.json: check the manifest and start a
|
|
78
|
+
session at startup, store and search during work, end the session with a summary.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Session protocol (short form)
|
|
82
|
+
|
|
83
|
+
1. `GET /memory/manifest`: see what is already stored before asking the user.
|
|
84
|
+
2. `POST /session/start` with your `agent_id`; pass the returned `session_id` as
|
|
85
|
+
`metadata.session_id` on every store.
|
|
86
|
+
3. `GET /agent/{agent_id}`: recall your recent memories.
|
|
87
|
+
4. During work: `POST /store` for facts and decisions, `POST /search` before asking.
|
|
88
|
+
5. At the end: `POST /session/end`, then store a concise summary.
|
|
89
|
+
|
|
90
|
+
## Upgrading from 1.x
|
|
91
|
+
|
|
92
|
+
1.x was a Node.js server with its own Redis key layout (`doc:*`, `memory:*`, Obsidian/Ori
|
|
93
|
+
vault tiers). Broker 0.6.1 does not read 1.x data in place. Run the new broker alongside
|
|
94
|
+
the old one, with separate Redis instances, and re-store what you want to keep through
|
|
95
|
+
`POST /store`. Keep the 1.x deployment until you have checked the results. The 1.x versions
|
|
96
|
+
stay installable as `heurchain@1`.
|
|
97
|
+
|
|
98
|
+
## License
|
|
99
|
+
|
|
100
|
+
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.0",
|
|
4
|
+
"description": "Setup guide and agent configuration for the self-hosted HeurChain memory broker (0.6.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
|
+
}
|