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 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"
@@ -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": "Increment a memory item's retrieval weight. Call after a human confirms a stored fact is correct.",
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": "Flush working memory: consolidate hot vectors into the durable vault for this tenant. Call at the end of a long session to persist accumulated memories.",
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
+ }
@@ -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
 
@@ -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
- Deletes items tagged `conversation` (or a custom tag set you specify). Use at
256
- session end to prune conversational chaff before it pollutes future retrieval.
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: 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.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",