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