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/README.md CHANGED
@@ -1,413 +1,100 @@
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
- [![npm version](https://img.shields.io/npm/v/heurchain)](https://www.npmjs.com/package/heurchain)
10
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
11
- [![Node ≥ 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
12
- [![Docker](https://img.shields.io/badge/docker-compose%20v2-blue)](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
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": "1.4.2",
4
- "description": "MCP (Model Context Protocol) server for HeurChain — tiered agent memory with BM25 search, session lifecycle, procedural memory, ambient capture, and frictionless session-context injection",
5
- "main": "server.js",
6
- "scripts": {
7
- "start": "node server.js"
8
- },
9
- "author": "Peter Medina <peter@carlssoncreative.com>",
10
- "files": [
11
- "server.js",
12
- "AGENT_CONFIG.json",
13
- "CHANGELOG.md"
14
- ],
15
- "keywords": [
16
- "mcp",
17
- "heurchain",
18
- "agent-memory",
19
- "llm",
20
- "ai",
21
- "model-context-protocol",
22
- "bm25",
23
- "redis",
24
- "claude",
25
- "anthropic"
26
- ],
27
- "license": "MIT",
28
- "engines": {
29
- "node": ">=22"
30
- },
31
- "dependencies": {
32
- "express": "^5.1.0",
33
- "redis": "^5.0.0",
34
- "cors": "^2.8.5",
35
- "@modelcontextprotocol/sdk": "^1.17.0",
36
- "zod": "^3.25.0"
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
+ }