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