heurchain 1.4.1 → 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,389 +1,99 @@
1
1
  # HeurChain
2
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.
3
+ **One memory system for every AI agent you run, on your own infrastructure.**
4
4
 
5
- **One memory system. Every AI agent. Simultaneously.**
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).
6
8
 
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.
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).
8
16
 
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/)
17
+ Source, install guide and research: **https://github.com/peterjohannmedina/heurchain**
13
18
 
14
- ---
19
+ ## What's in this package
15
20
 
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
- });
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 |
146
26
 
147
- // BM25 search
148
- const { results } = await fetch(`${HEURCHAIN_URL}/search?q=campaign+status&limit=10`).then(r => r.json());
27
+ ```js
28
+ const config = require('heurchain/AGENT_CONFIG.json');
29
+ console.log(config.authentication.headers);
149
30
  ```
150
31
 
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
32
+ ## Run the broker
159
33
 
160
- BASE = "http://<your-host>:3012"
34
+ Requirements: Docker Engine with Compose v2.
161
35
 
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": "..."})
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
177
43
  ```
178
44
 
179
- ---
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).
180
48
 
181
- ### ChatGPT / GPT Actions
49
+ Create a tenant and API key (the key is shown once):
182
50
 
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] }
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"}'
217
54
  ```
218
55
 
219
- ---
220
-
221
- ### Generic HTTP (PowerShell, curl, any client)
56
+ ## Wire your agent
222
57
 
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"}'
58
+ Every request sends two headers: `X-HeurChain-API-Key: <api_key>` and
59
+ `X-HeurChain-Tenant: <tenant_id>`.
228
60
 
229
- # Search
230
- Invoke-RestMethod "http://<host>:3012/search?q=hello&limit=5"
61
+ **MCP (Streamable HTTP)**, for example Claude Code:
231
62
 
232
- # Start session
233
- $s = Invoke-RestMethod -Method POST -Uri "http://<host>:3012/session/start" `
234
- -ContentType "application/json" -Body '{"agent_name":"ps-agent"}'
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"
235
66
  ```
236
67
 
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"}'
68
+ **HTTP**: `POST /store`, `POST /search`, `POST /query`, `POST /session/start`, and so on.
69
+ `GET /openapi.json` on your broker describes every endpoint.
242
70
 
243
- curl "http://<host>:3012/search?q=hello&limit=5"
244
- ```
71
+ **Let the agent set itself up.** Paste this to any agent:
245
72
 
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
73
  ```
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
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.
372
79
  ```
373
80
 
374
- Role order: `system-prereqs` → `obsidian-vault` → `system-redis` → `heurchain` → `docker-stack` → `monitoring`
81
+ ## Session protocol (short form)
375
82
 
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
- ```
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.
383
89
 
384
- Requires Docker Compose v2 (`docker compose` plugin or `docker-compose >= 2.x`).
90
+ ## Upgrading from 1.x
385
91
 
386
- ---
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`.
387
97
 
388
98
  ## License
389
99
 
package/package.json CHANGED
@@ -1,38 +1,38 @@
1
- {
2
- "name": "heurchain",
3
- "version": "1.4.1",
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
+ }