heurchain 2.0.0 → 2.0.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.
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.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"
@@ -201,4 +192,4 @@
201
192
  "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
193
  "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
194
  }
204
- }
195
+ }
@@ -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, encrypted silos or previously returned client context.
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
- Non-silo /store now projects into both indexes. HTTP 200 with indexed=true
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. Silo storage retains its encrypted path.
157
+ There is no background retry queue.
158
158
 
159
159
  ---
160
160
 
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: they write facts, decisions and session
7
- summaries, and recall them later with hybrid search (BM25 + dense vectors, fused with RRF).
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
- > **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.
10
+ > ### This package is the agent kit, not the server
13
11
  >
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).
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, install guide and research: **https://github.com/peterjohannmedina/heurchain**
23
+ Source and install guide: **https://github.com/peterjohannmedina/heurchain**
18
24
 
19
- ## What's in this package
25
+ ## How it works
20
26
 
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 |
27
+ ![HeurChain architecture](https://raw.githubusercontent.com/peterjohannmedina/heurchain/master/docs/diagrams/architecture.svg)
26
28
 
27
- ```js
28
- const config = require('heurchain/AGENT_CONFIG.json');
29
- console.log(config.authentication.headers);
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
+ ![Store, recall and lifecycle](https://raw.githubusercontent.com/peterjohannmedina/heurchain/master/docs/diagrams/dataflow.svg)
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. The
46
- full guide (native systemd install, TLS, backups) is
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: check the manifest and start a
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 (short form)
93
+ ## Session protocol
94
+
95
+ ![Agent session protocol](https://raw.githubusercontent.com/peterjohannmedina/heurchain/master/docs/diagrams/session.svg)
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 /store` for facts and decisions, `POST /search` before asking.
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.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.2",
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",