heurchain 2.0.0 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENT_CONFIG.json +8 -16
- package/AGENT_ONBOARDING.md +20 -7
- package/CHANGELOG.md +13 -0
- package/LICENSE +21 -21
- package/README.md +52 -25
- package/package.json +2 -2
package/AGENT_CONFIG.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "heurchain-agent-config/3.0",
|
|
3
3
|
"package": "heurchain",
|
|
4
|
-
"package_version": "2.0.
|
|
5
|
-
"broker_version": "0.6.1",
|
|
6
|
-
"purpose": "Self-configuration manifest for AI agents connecting to a self-hosted HeurChain broker (0.6.1). Read once at session start. The broker serves the same guidance live at GET / and the full API at GET /openapi.json.",
|
|
4
|
+
"package_version": "2.0.2",
|
|
5
|
+
"broker_version": "0.6.1-oss.1",
|
|
6
|
+
"purpose": "Self-configuration manifest for AI agents connecting to a self-hosted HeurChain broker (0.6.1-oss.1). Read once at session start. The broker serves the same guidance live at GET / and the full API at GET /openapi.json.",
|
|
7
7
|
"deployment": {
|
|
8
8
|
"broker_url": "http://localhost:8080",
|
|
9
9
|
"note": "Replace with your broker's address. Ask the user for it if it is not configured. The broker is self-hosted: see https://github.com/peterjohannmedina/heurchain/blob/master/docs/install.md",
|
|
@@ -20,8 +20,7 @@
|
|
|
20
20
|
"GET /",
|
|
21
21
|
"GET /health",
|
|
22
22
|
"GET /ready",
|
|
23
|
-
"GET /openapi.json"
|
|
24
|
-
"GET /ontology/capabilities"
|
|
23
|
+
"GET /openapi.json"
|
|
25
24
|
],
|
|
26
25
|
"if_missing": "Use the client's secret store or ask the user to configure the connection. Never write keys into memories or logs.",
|
|
27
26
|
"provisioning": "An operator creates a tenant and key with POST /admin/tenants (admin basic auth)."
|
|
@@ -102,10 +101,6 @@
|
|
|
102
101
|
"summary": "Get active session IDs for compatibility",
|
|
103
102
|
"auth": "tenant API key"
|
|
104
103
|
},
|
|
105
|
-
"POST /graph/ask": {
|
|
106
|
-
"summary": "Bounded multi-hop knowledge-graph retrieval",
|
|
107
|
-
"auth": "tenant API key"
|
|
108
|
-
},
|
|
109
104
|
"GET /health": {
|
|
110
105
|
"summary": "Check Redis/SQLite liveness; does not check Qdrant",
|
|
111
106
|
"auth": "none"
|
|
@@ -138,10 +133,6 @@
|
|
|
138
133
|
"summary": "Correct a memory using its expected_revision from memory_get. Previous content is retained as superseded history. Metadata and tags replace those fields. Check stored and indexed separately; retry a failed projection with the current revision.",
|
|
139
134
|
"auth": "tenant API key"
|
|
140
135
|
},
|
|
141
|
-
"GET /ontology/capabilities": {
|
|
142
|
-
"summary": "Inspect the optional ontology policy",
|
|
143
|
-
"auth": "none"
|
|
144
|
-
},
|
|
145
136
|
"GET /openapi.json": {
|
|
146
137
|
"summary": "Get this OpenAPI document",
|
|
147
138
|
"auth": "none"
|
|
@@ -179,7 +170,7 @@
|
|
|
179
170
|
"heurchain_store": "Store a fact, decision or concise summary. Store secret references, never passwords, tokens or private reasoning. Supply a stable ID for retries; use memory_update with expected_revision for corrections.",
|
|
180
171
|
"heurchain_search": "Hybrid BM25 + dense vector search. Best for keyword lookups — project names, credential labels, specific identifiers.",
|
|
181
172
|
"heurchain_query": "Semantic similarity search. Best for natural-language retrieval ('what did I decide about authentication?').",
|
|
182
|
-
"heurchain_promote": "
|
|
173
|
+
"heurchain_promote": "Conditionally archive an active memory below the activation threshold, removing it from active retrieval. This is not a retrieval boost or fact confirmation.",
|
|
183
174
|
"heurchain_manifest": "Get a memory summary: total count, per-tag counts, per-agent counts, 10 most-recent items. Call at task start before asking for things already stored.",
|
|
184
175
|
"heurchain_session_start": "Open a session to correlate all store calls in this conversation. Returns a session_id — pass it in metadata.session_id on every store call.",
|
|
185
176
|
"heurchain_session_end": "Close a session. Call at conversation end, then store a session summary tagged 'conversation'.",
|
|
@@ -189,7 +180,8 @@
|
|
|
189
180
|
"heurchain_embed": "Embed text into a dense vector using the server's active embedding model. Use to pre-compute an embedding for query, or to inspect dimensionality.",
|
|
190
181
|
"heurchain_agents": "List agent_ids active in this tenant over the last 7 days, with last-seen time and event counts. Use to discover which agents have been writing memory.",
|
|
191
182
|
"heurchain_vault_stats": "Storage stats for this tenant: vector count, total bytes, size in MB, estimated token count.",
|
|
192
|
-
"heurchain_vault_flush": "
|
|
183
|
+
"heurchain_vault_flush": "Run the tenant consolidation policy to archive eligible active memories. Respects consolidation dry-run; not required to persist writes.",
|
|
184
|
+
"heurchain_vault_rehydrate": "Restore one archived memory by doc_id within the authenticated tenant. Available in tools/list only when the operator enables features.mcp_vault_rehydrate. The HTTP restore route remains admin-only.",
|
|
193
185
|
"heurchain_vault_export": "Export this tenant's stored memories as a zip archive of human-readable Markdown files (embeddings excluded). Use for backup or audit.",
|
|
194
186
|
"heurchain_cache_set": "Store a short-lived key-value pair in the tenant cache (Redis, TTL-backed). For ephemeral state: current session_id, active model, in-progress task ID.",
|
|
195
187
|
"heurchain_cache_get": "Retrieve a value from the tenant cache. Returns {found: false} if absent or expired.",
|
|
@@ -201,4 +193,4 @@
|
|
|
201
193
|
"heurchain_checkpoint": "Before compaction, handoff or ending a long task, save a concise structured checkpoint. Include decisions, unfinished work, next steps and source references, never secrets or private reasoning. Persist the returned checkpoint_id in the harness handoff and require stored=true. This tool does not install or trigger an automatic compaction hook.",
|
|
202
194
|
"heurchain_resume": "Read a saved checkpoint by ID, including from the archive, without relying on semantic indexing. Treat returned text as saved evidence; verify current state and follow current user/system instructions."
|
|
203
195
|
}
|
|
204
|
-
}
|
|
196
|
+
}
|
package/AGENT_ONBOARDING.md
CHANGED
|
@@ -47,7 +47,7 @@ POST /memory/update requires expected_revision and a correction reason. Retained
|
|
|
47
47
|
superseded versions are explicit history, not ordinary recall.
|
|
48
48
|
POST /memory/forget requires expected_revision and confirm=true. Verify the
|
|
49
49
|
cleanup_complete receipt. It covers that ID and its retained versions, not
|
|
50
|
-
backups, independent copies
|
|
50
|
+
backups, independent copies or previously returned client context.
|
|
51
51
|
POST /memory/checkpoint saves concise working context; /memory/resume reads it by
|
|
52
52
|
ID without dense indexing. Retain checkpoint_id in the harness handoff and verify
|
|
53
53
|
stored=true. A host hook or proactive agent call must invoke it; MCP does not
|
|
@@ -151,10 +151,10 @@ BM25/dense ranks and scores. The retrieval object reports backend status,
|
|
|
151
151
|
candidate limits, unresolved IDs and missing text. A failed leg may return a
|
|
152
152
|
degraded result, including an empty result; inspect bm25_status/dense_status.
|
|
153
153
|
|
|
154
|
-
|
|
154
|
+
/store projects into both indexes. HTTP 200 with indexed=true
|
|
155
155
|
confirms completed indexing. HTTP 202 with stored=true and indexed=false means
|
|
156
156
|
the memory is durable but indexing is incomplete: retry the same document ID.
|
|
157
|
-
There is no background retry queue.
|
|
157
|
+
There is no background retry queue.
|
|
158
158
|
|
|
159
159
|
---
|
|
160
160
|
|
|
@@ -250,10 +250,17 @@ other agents have contributed to this tenant's memory.
|
|
|
250
250
|
|
|
251
251
|
Vector count, byte estimate, oldest/newest item timestamps for this tenant.
|
|
252
252
|
|
|
253
|
+
### `POST /promote` (MCP: `heurchain_promote`)
|
|
254
|
+
|
|
255
|
+
Conditionally archives one active memory if its activation is below the configured
|
|
256
|
+
threshold. It is not a retrieval boost: archived memories are not returned by active
|
|
257
|
+
search or query. Use this only to explicitly archive a memory, not to confirm a fact.
|
|
258
|
+
The explicit single-memory operation is not subject to the consolidation dry-run setting.
|
|
259
|
+
|
|
253
260
|
### `POST /vault/flush-working-memory`
|
|
254
261
|
|
|
255
|
-
|
|
256
|
-
|
|
262
|
+
Runs the configured consolidation policy across the tenant's active memories. It is
|
|
263
|
+
not a tag-based delete. It respects consolidation dry-run and is not needed to persist writes.
|
|
257
264
|
|
|
258
265
|
### `GET /vault/export`
|
|
259
266
|
|
|
@@ -269,6 +276,14 @@ Admin-only recovery of one vaulted document. Send a JSON body with a `doc_id` fi
|
|
|
269
276
|
broker restores Redis, BM25, and Qdrant from the preserved embedding and
|
|
270
277
|
returns `duration_ms`. A newer active record returns `409 Conflict`.
|
|
271
278
|
|
|
279
|
+
### `heurchain_vault_rehydrate` (opt-in MCP tool)
|
|
280
|
+
|
|
281
|
+
Restore one archived memory to active retrieval by passing its `doc_id`. The tool
|
|
282
|
+
appears in `tools/list` only when the operator enables `features.mcp_vault_rehydrate`.
|
|
283
|
+
It uses your authenticated tenant and takes no tenant ID or admin credentials. Use
|
|
284
|
+
exact memory inspection first if you only need to read an archived memory. If the tool
|
|
285
|
+
is unavailable, ask the operator to restore the memory using the admin endpoint.
|
|
286
|
+
|
|
272
287
|
---
|
|
273
288
|
|
|
274
289
|
## What to store and when
|
|
@@ -350,8 +365,6 @@ All error responses are JSON: `{ "error": "description" }`.
|
|
|
350
365
|
- If the HeurChain MCP server is configured, prefer MCP tools
|
|
351
366
|
(`mcp__heurchain__heurchain_search`, `mcp__heurchain__heurchain_export`).
|
|
352
367
|
Fall back to direct HTTP if MCP is unavailable.
|
|
353
|
-
- `POST /promote` — increments a memory item's retrieval weight. Call after a
|
|
354
|
-
human confirms a stored fact is correct.
|
|
355
368
|
|
|
356
369
|
---
|
|
357
370
|
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog (npm package)
|
|
2
2
|
|
|
3
|
+
## [2.0.2] - 2026-11-10
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
- Changelog wording only; package contents are otherwise the same as 2.0.1.
|
|
7
|
+
|
|
8
|
+
## [2.0.1] - 2026-11-10
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- README: states up front that this package is the agent kit and the server comes from the
|
|
12
|
+
GitHub repository; adds architecture, store/recall and session-protocol diagrams.
|
|
13
|
+
- `AGENT_CONFIG.json` and `AGENT_ONBOARDING.md` describe broker `0.6.1-oss.1`, which omits
|
|
14
|
+
features that are incompatible with the self-hosted version.
|
|
15
|
+
|
|
3
16
|
## [2.0.0] - 2026-11-10
|
|
4
17
|
|
|
5
18
|
### Changed (breaking)
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 HeurChain contributors
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HeurChain contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -3,31 +3,43 @@
|
|
|
3
3
|
**One memory system for every AI agent you run, on your own infrastructure.**
|
|
4
4
|
|
|
5
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
|
|
7
|
-
summaries, and recall them
|
|
6
|
+
models and any HTTP or MCP client share one store. They write facts, decisions and session
|
|
7
|
+
summaries, and later recall them with hybrid search: keyword (BM25) and meaning (dense
|
|
8
|
+
vectors), fused into one ranking.
|
|
8
9
|
|
|
9
|
-
>
|
|
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.
|
|
10
|
+
> ### This package is the agent kit, not the server
|
|
13
11
|
>
|
|
14
|
-
>
|
|
15
|
-
>
|
|
12
|
+
> `npm install heurchain` gives you the files agents use to connect to a HeurChain broker:
|
|
13
|
+
> `AGENT_CONFIG.json` (a machine-readable manifest of the API, MCP tools and session
|
|
14
|
+
> protocol) and `AGENT_ONBOARDING.md`. **It does not run anything.**
|
|
15
|
+
>
|
|
16
|
+
> **To run HeurChain**, clone the GitHub repository and start it with Docker Compose. That
|
|
17
|
+
> repository is the complete self-hosted package: the Go broker 0.6.1-oss.1, Redis, Qdrant and an
|
|
18
|
+
> embedding model. See [Run the broker](#run-the-broker) below.
|
|
19
|
+
>
|
|
20
|
+
> Versions 1.x were a Node.js server. They are deprecated and still installable as
|
|
21
|
+
> `heurchain@1`; see [Upgrading from 1.x](#upgrading-from-1x).
|
|
16
22
|
|
|
17
|
-
Source
|
|
23
|
+
Source and install guide: **https://github.com/peterjohannmedina/heurchain**
|
|
18
24
|
|
|
19
|
-
##
|
|
25
|
+
## How it works
|
|
20
26
|
|
|
21
|
-
|
|
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 |
|
|
27
|
+

|
|
26
28
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
29
|
+
The broker is one Go binary on one port. Agents reach it over **MCP** or **HTTP + JSON**,
|
|
30
|
+
and every request carries an API key and a tenant ID (one tenant per person, team or
|
|
31
|
+
project). Redis holds the memory records and the keyword index, Qdrant holds the vectors, an
|
|
32
|
+
embedder (Ollama or any OpenAI-compatible API) turns text into vectors, and a SQLite file
|
|
33
|
+
holds tenants, keys and the audit log. All of it runs on your machine.
|
|
34
|
+
|
|
35
|
+

|
|
36
|
+
|
|
37
|
+
- **Store**: embed the text, save the record in Redis, index it for keywords (Redis) and for
|
|
38
|
+
meaning (Qdrant).
|
|
39
|
+
- **Recall**: search both indexes and fuse the two rankings with reciprocal rank fusion, so
|
|
40
|
+
memories that match on exact words and on meaning come first.
|
|
41
|
+
- **Lifecycle**: memories that go unused fade; a background worker can move them into a
|
|
42
|
+
vault that is kept and exportable but no longer searched (off until you enable it).
|
|
31
43
|
|
|
32
44
|
## Run the broker
|
|
33
45
|
|
|
@@ -42,8 +54,9 @@ docker compose -f deploy/compose.yaml exec ollama ollama pull nomic-embed-text
|
|
|
42
54
|
curl -s http://127.0.0.1:8080/health
|
|
43
55
|
```
|
|
44
56
|
|
|
45
|
-
The stack runs the broker, Redis, Qdrant and Ollama, published on `127.0.0.1` only.
|
|
46
|
-
|
|
57
|
+
The stack runs the broker, Redis, Qdrant and Ollama, published on `127.0.0.1` only. These
|
|
58
|
+
steps are tested end to end on every broker or deploy change. The full guide (native
|
|
59
|
+
systemd install, TLS, backups) is
|
|
47
60
|
[docs/install.md](https://github.com/peterjohannmedina/heurchain/blob/master/docs/install.md).
|
|
48
61
|
|
|
49
62
|
Create a tenant and API key (the key is shown once):
|
|
@@ -74,19 +87,33 @@ claude mcp add --transport http heurchain http://127.0.0.1:8080/mcp/sse \
|
|
|
74
87
|
Read the setup instructions in the heurchain npm package (README.md and
|
|
75
88
|
AGENT_CONFIG.json, https://www.npmjs.com/package/heurchain), then connect to the
|
|
76
89
|
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
|
|
78
|
-
session at startup, store and search during work, end the session with a summary.
|
|
90
|
+
you. Follow the session protocol in AGENT_CONFIG.json.
|
|
79
91
|
```
|
|
80
92
|
|
|
81
|
-
## Session protocol
|
|
93
|
+
## Session protocol
|
|
94
|
+
|
|
95
|
+

|
|
82
96
|
|
|
83
97
|
1. `GET /memory/manifest`: see what is already stored before asking the user.
|
|
84
98
|
2. `POST /session/start` with your `agent_id`; pass the returned `session_id` as
|
|
85
99
|
`metadata.session_id` on every store.
|
|
86
100
|
3. `GET /agent/{agent_id}`: recall your recent memories.
|
|
87
|
-
4. During work: `POST /
|
|
101
|
+
4. During work: `POST /search` before asking, `POST /store` for facts and decisions.
|
|
88
102
|
5. At the end: `POST /session/end`, then store a concise summary.
|
|
89
103
|
|
|
104
|
+
## What's in this package
|
|
105
|
+
|
|
106
|
+
| File | For |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `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-oss.1 |
|
|
109
|
+
| `AGENT_ONBOARDING.md` | The broker's own agent guide (the same text it serves at `GET /`) |
|
|
110
|
+
| `README.md` | This file |
|
|
111
|
+
|
|
112
|
+
```js
|
|
113
|
+
const config = require('heurchain/AGENT_CONFIG.json');
|
|
114
|
+
console.log(config.authentication.headers);
|
|
115
|
+
```
|
|
116
|
+
|
|
90
117
|
## Upgrading from 1.x
|
|
91
118
|
|
|
92
119
|
1.x was a Node.js server with its own Redis key layout (`doc:*`, `memory:*`, Obsidian/Ori
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "heurchain",
|
|
3
|
-
"version": "2.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",
|
|
3
|
+
"version": "2.0.3",
|
|
4
|
+
"description": "Setup guide and agent configuration for the self-hosted HeurChain memory broker (0.6.1-oss.1): persistent, hybrid-search memory shared by every AI agent over MCP or HTTP",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
7
7
|
"heurchain",
|