heurchain 1.2.1 → 1.4.1
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/CHANGELOG.md +103 -0
- package/package.json +38 -37
- package/server.js +1364 -910
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# HeurChain Changelog
|
|
2
|
+
|
|
3
|
+
## v1.4.1 — 2026-05-07
|
|
4
|
+
|
|
5
|
+
### Architecture
|
|
6
|
+
|
|
7
|
+
- **Briefing worker is pure memory delivery — no inference.** HeurChain is a memory substrate. The briefing worker assembles raw proc entries and session turns; it never calls an LLM. The receiving agent decides whether to surface items, query deeper via `heurchain_search`, or synthesize with its own model.
|
|
8
|
+
- `runCompressor` remains for consolidation cue compression only (background worker, separate concern).
|
|
9
|
+
|
|
10
|
+
### Changes
|
|
11
|
+
|
|
12
|
+
- Removed LLM synthesis path from `generateBriefing()`. Raw proc + session items IS the correct output, not a fallback.
|
|
13
|
+
- Default `BRIEFING_INTERVAL_MS` changed from 6 hours → 24 hours (daily cadence).
|
|
14
|
+
- Added optional webhook push: set proc key `briefing_webhook_url` for an agent and the worker will POST `{ agent, timestamp, items }` to that URL after each briefing generation (fire-and-forget, 10s timeout). Agent's orchestration layer handles the payload independently.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## v1.4.0 — 2026-05-07
|
|
19
|
+
|
|
20
|
+
### New: Ollama-first compressor provider chain
|
|
21
|
+
|
|
22
|
+
- `COMPRESSOR_PROVIDER`: `ollama` (default when `OLLAMA_BASE_URL` is set) | `anthropic` | `none`
|
|
23
|
+
- Ollama default model: `qwen2.5:1.5b` — runs on CPU, ~1 GB RAM, no GPU or external API required
|
|
24
|
+
- `anthropic` provider optional — requires `ANTHROPIC_API_KEY`
|
|
25
|
+
- `none` provider: consolidation still fires, marks keys consolidated, skips cue generation
|
|
26
|
+
- Removes hard dependency on external API for self-hosted deployments
|
|
27
|
+
|
|
28
|
+
### New: Proactive memory briefing worker
|
|
29
|
+
|
|
30
|
+
- `runProactiveBriefings()` runs on `BRIEFING_INTERVAL_MS` schedule (default 24h) plus once 30s after startup
|
|
31
|
+
- Discovers active agents by scanning `proc:agent:*` keys
|
|
32
|
+
- Assembles `"HeurChain: {item}"` reminders from proc memory and recent session buffer turns
|
|
33
|
+
- Caches result at `briefing:{agent}:latest` (Redis, 24h TTL)
|
|
34
|
+
- `/api/session-context` now returns a `briefing` field — pre-generated reminders ready at session start with zero added latency (cache hit path)
|
|
35
|
+
- Per-agent controls via proc keys: `briefing_disabled`, `briefing_interval_ms`, `briefing_instructions`, `briefing_webhook_url`
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## v1.3.0 — 2026-05-07
|
|
40
|
+
|
|
41
|
+
### New: Frictionless REST layer
|
|
42
|
+
|
|
43
|
+
- `GET /api/session-context?agent=X&hint=Y` — token-budgeted payload (proc knobs + last session + top BM25 hits) designed for system-prompt injection via hook at session start. Zero MCP tool calls required.
|
|
44
|
+
- `GET /api/search?q=...` — BM25 search over the full index via plain HTTP. No SSE session, no tool definition overhead.
|
|
45
|
+
- `POST /api/buffer` — fire-and-forget turn capture. Flushes to Redis on 5-min heartbeat or session end. No agent action required.
|
|
46
|
+
- `POST/GET/DELETE /api/proc` — procedural memory tier. Stable agent preferences (coding style, language, patterns) stored with no TTL or decay.
|
|
47
|
+
|
|
48
|
+
### New: Slim MCP profile
|
|
49
|
+
|
|
50
|
+
- Connect with `?profile=slim` on `/sse` to load 14 core tools instead of 29 (~750 token savings on tool definitions per context window).
|
|
51
|
+
- Infrastructure tools (Prometheus, Grafana, Proxmox, Ceph) only load on `?profile=full`.
|
|
52
|
+
|
|
53
|
+
### New: MCP tools
|
|
54
|
+
|
|
55
|
+
- `proc_set` / `proc_get` — read and write procedural memory from within an MCP session.
|
|
56
|
+
|
|
57
|
+
### Fix: BM25 index was Redis-blind
|
|
58
|
+
|
|
59
|
+
- Silent bug in node-redis `scanIterator` caused it to yield key pages (arrays) instead of individual keys. Every `redis.get(array)` call failed silently, so BM25 was built from Obsidian vault files only — Redis keys were never indexed. Fixed via `scanKeys()` normalizer. Index now correctly covers both tiers (465 docs vs 447 before).
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## v1.2.1 — 2026-05-06
|
|
64
|
+
|
|
65
|
+
### Security
|
|
66
|
+
|
|
67
|
+
- Path traversal fix: `validateKey()` now rejects `..` segments, null bytes, and slash characters before resolving vault paths.
|
|
68
|
+
- Bearer token auth (`MCP_AUTH_TOKEN`) enforced on all endpoints. `/health` remains open for healthcheck probes.
|
|
69
|
+
- Grafana tool fails closed when credentials are not configured rather than exposing unauthenticated access.
|
|
70
|
+
|
|
71
|
+
### Fixes
|
|
72
|
+
|
|
73
|
+
- SSE session cap (50) with cleanup on both `req.on("close")` and `res.on("close")` to prevent transport leaks.
|
|
74
|
+
- BM25 rebuild is atomic: `isBuilding` flag + `pendingOps` queue replays writes that arrived during a rebuild onto the fresh index after swap. No silent memory loss during hourly rebuild.
|
|
75
|
+
- `bulkAdd()` for O(N log N) index builds instead of O(N²) per-insert `_recalcStats()` calls.
|
|
76
|
+
- Per-key try/catch in `buildIndex` Redis scan — a single bad key type no longer aborts the entire scan.
|
|
77
|
+
- Tier validation: unknown tier strings fall back to `"all"` instead of returning empty results.
|
|
78
|
+
|
|
79
|
+
### Features
|
|
80
|
+
|
|
81
|
+
- `heurchain_export` — glacier sync: exports Redis longterm-tier entries to Obsidian vault as markdown. Idempotent.
|
|
82
|
+
- `minScore` parameter on `heurchain_search` to filter low-signal results.
|
|
83
|
+
- Namespace isolation: `namespace` parameter scopes search and write operations to an agent-specific key prefix.
|
|
84
|
+
- Session noise filter: suppresses low-signal session metadata keys from BM25 results.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## v1.2.0 — 2026-05-05
|
|
89
|
+
|
|
90
|
+
### Features
|
|
91
|
+
|
|
92
|
+
- Native BM25 search (Okapi BM25, k1=1.5, b=0.75) implemented in-process. Replaced dead broker call to port 3012.
|
|
93
|
+
- Redis integration: `redis-cache` service added to Docker stack; `REDIS_URL` fixed to use Docker service name.
|
|
94
|
+
- `heurchain_search` now indexes all Redis string keys + Obsidian vault `.md` files on startup with hourly rebuild.
|
|
95
|
+
|
|
96
|
+
---
|
|
97
|
+
|
|
98
|
+
## v1.1.0 — initial release
|
|
99
|
+
|
|
100
|
+
- MCP SSE server with 27 tools across cache, vault, search, monitoring, infrastructure, and user context categories.
|
|
101
|
+
- Tiered storage: Redis (longterm) + Obsidian vault (working).
|
|
102
|
+
- nginx gateway for SSE proxying.
|
|
103
|
+
- Ansible role for managed host deployment.
|
package/package.json
CHANGED
|
@@ -1,37 +1,38 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "heurchain",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "MCP (Model Context Protocol) server for HeurChain — tiered agent memory with BM25 search, session lifecycle, and
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
"
|
|
17
|
-
"
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
"
|
|
21
|
-
"
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
-
"
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
"
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
37
|
-
}
|
|
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
|
+
}
|