heurchain 1.2.0 → 1.3.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/server.js CHANGED
@@ -13,10 +13,76 @@ app.use(cors());
13
13
  const redis = createClient({ url: process.env.REDIS_URL || "redis://localhost:6379" });
14
14
  redis.on("error", (err) => console.error("Redis error:", err));
15
15
 
16
- const OBSIDIAN_VAULT_PATH = process.env.OBSIDIAN_VAULT_PATH || "/opt/obsidian-vault";
16
+ const OBSIDIAN_VAULT_PATH = path.resolve(process.env.OBSIDIAN_VAULT_PATH || "/opt/obsidian-vault");
17
+ const VAULT_ROOT = OBSIDIAN_VAULT_PATH + path.sep;
18
+
19
+ const BUFFER_CAPACITY = parseInt(process.env.BUFFER_CAPACITY, 10) || 50;
20
+ const BUFFER_FLUSH_MS = parseInt(process.env.BUFFER_FLUSH_MS, 10) || 5 * 60 * 1000; // 5 min
21
+ const SESSION_CONTEXT_TOKENS = parseInt(process.env.SESSION_CONTEXT_TOKENS, 10) || 400;
22
+ const PROC_KEY_RE = /^[a-zA-Z0-9_\-\.]+$/; // safe proc key segment
23
+
24
+ // node-redis scanIterator yields pages (arrays) in some versions and individual
25
+ // keys in others. scanKeys normalizes to individual key strings in all cases.
26
+ async function* scanKeys(pattern, type) {
27
+ const opts = { MATCH: pattern, COUNT: 200 };
28
+ if (type) opts.TYPE = type;
29
+ for await (const item of redis.scanIterator(opts)) {
30
+ if (Array.isArray(item)) { for (const k of item) yield k; }
31
+ else yield item;
32
+ }
33
+ }
17
34
 
18
35
  // ---------------------------------------------------------------------------
19
- // BM25 Index
36
+ // Auth middleware — set MCP_AUTH_TOKEN env var to enforce bearer token auth.
37
+ // If unset, access is unrestricted (warn loudly).
38
+ // ---------------------------------------------------------------------------
39
+
40
+ const MCP_AUTH_TOKEN = process.env.MCP_AUTH_TOKEN || "";
41
+ if (!MCP_AUTH_TOKEN) {
42
+ console.warn("⚠️ SECURITY WARNING: MCP_AUTH_TOKEN is not set. All endpoints are unauthenticated. Set this env var to a secret token.");
43
+ }
44
+
45
+ function requireAuth(req, res, next) {
46
+ if (!MCP_AUTH_TOKEN) return next(); // auth disabled — allow (warned at startup)
47
+ const auth = req.headers.authorization || "";
48
+ if (!auth.startsWith("Bearer ") || auth.slice(7) !== MCP_AUTH_TOKEN) {
49
+ return res.status(401).json({ error: "Unauthorized" });
50
+ }
51
+ next();
52
+ }
53
+
54
+ // ---------------------------------------------------------------------------
55
+ // Key validation & path resolution — #1 path traversal fix
56
+ // ---------------------------------------------------------------------------
57
+
58
+ const SAFE_KEY_SEGMENT = /^[a-zA-Z0-9_\-\.]+$/;
59
+
60
+ function validateKey(key) {
61
+ if (typeof key !== "string" || key.length === 0 || key.length > 512)
62
+ throw new Error("invalid key: must be a non-empty string ≤ 512 chars");
63
+ if (/[\\/\x00]/.test(key))
64
+ throw new Error("invalid key: contains illegal characters");
65
+ const segments = key.split(":");
66
+ for (const seg of segments) {
67
+ if (seg === "" || seg === "." || seg === "..")
68
+ throw new Error("invalid key: empty or dot segment");
69
+ if (!SAFE_KEY_SEGMENT.test(seg))
70
+ throw new Error(`invalid key: segment '${seg}' contains illegal characters`);
71
+ }
72
+ }
73
+
74
+ function keyToObsidianPath(key) {
75
+ validateKey(key);
76
+ const relative = key.replace(/:/g, path.sep) + ".md";
77
+ const resolved = path.resolve(OBSIDIAN_VAULT_PATH, relative);
78
+ if (resolved !== OBSIDIAN_VAULT_PATH && !resolved.startsWith(VAULT_ROOT))
79
+ throw new Error("invalid key: path escapes vault");
80
+ return resolved;
81
+ }
82
+
83
+ // ---------------------------------------------------------------------------
84
+ // BM25 Index — fixes: drop tokens array (#13), O(N²) rebuild (#5),
85
+ // pending-ops queue to survive rebuild (#4), tier validation (#15)
20
86
  // ---------------------------------------------------------------------------
21
87
 
22
88
  const STOPWORDS = new Set([
@@ -30,8 +96,9 @@ const STOPWORDS = new Set([
30
96
  "if","up","out","about","into","through","over","after","before","between"
31
97
  ]);
32
98
 
33
- // Low-signal session metadata patterns — excluded from search by default
34
- const NOISE_KEY_PATTERNS = [/session-summary/, /agent-end/, /heartbeat/];
99
+ const VALID_TIERS = new Set(["all", "longterm", "working"]);
100
+
101
+ const NOISE_KEY_PATTERNS = [/session-summary/, /agent-end/, /heartbeat/];
35
102
  const NOISE_CONTENT_PATTERNS = [
36
103
  /^\d+ user turns,\s*\d+ total messages/i,
37
104
  /^openclaw session on [a-z0-9-]+:/i,
@@ -40,16 +107,16 @@ const NOISE_CONTENT_PATTERNS = [
40
107
 
41
108
  function isSessionNoise(key, content) {
42
109
  if (NOISE_KEY_PATTERNS.some(p => p.test(key))) return true;
43
- const trimmed = (content || "").trim();
44
- return NOISE_CONTENT_PATTERNS.some(p => p.test(trimmed));
110
+ return NOISE_CONTENT_PATTERNS.some(p => p.test((content || "").trim()));
45
111
  }
46
112
 
47
113
  class BM25Index {
48
114
  constructor(k1 = 1.5, b = 0.75) {
49
115
  this.k1 = k1;
50
116
  this.b = b;
51
- this.docs = new Map(); // key -> { tf, tokens, content, tier, updatedAt }
52
- this.df = new Map(); // term -> document frequency count
117
+ // doc entry: { tf: Map<term,count>, dl: number, content: string, tier: string, updatedAt: string|null }
118
+ this.docs = new Map();
119
+ this.df = new Map(); // term -> document frequency
53
120
  this.avgLen = 0;
54
121
  this.N = 0;
55
122
  }
@@ -62,16 +129,30 @@ class BM25Index {
62
129
  .filter(t => t.length > 1 && !STOPWORDS.has(t));
63
130
  }
64
131
 
132
+ // Single-doc add — used for incremental updates; calls _recalcStats each time
65
133
  add(key, content, tier, updatedAt) {
66
134
  if (this.docs.has(key)) this._removeFromIndex(key);
67
135
  const tokens = this.tokenize(content);
68
136
  const tf = new Map();
69
137
  for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
70
- this.docs.set(key, { tf, tokens, content, tier, updatedAt });
138
+ this.docs.set(key, { tf, dl: tokens.length, content, tier, updatedAt });
71
139
  for (const term of tf.keys()) this.df.set(term, (this.df.get(term) || 0) + 1);
72
140
  this._recalcStats();
73
141
  }
74
142
 
143
+ // Bulk add — O(N log N) instead of O(N²); calls _recalcStats once at end
144
+ bulkAdd(entries) {
145
+ for (const { key, content, tier, updatedAt } of entries) {
146
+ if (this.docs.has(key)) this._removeFromIndex(key);
147
+ const tokens = this.tokenize(content);
148
+ const tf = new Map();
149
+ for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
150
+ this.docs.set(key, { tf, dl: tokens.length, content, tier, updatedAt });
151
+ for (const term of tf.keys()) this.df.set(term, (this.df.get(term) || 0) + 1);
152
+ }
153
+ this._recalcStats();
154
+ }
155
+
75
156
  remove(key) {
76
157
  if (!this.docs.has(key)) return;
77
158
  this._removeFromIndex(key);
@@ -82,9 +163,9 @@ class BM25Index {
82
163
  const doc = this.docs.get(key);
83
164
  if (!doc) return;
84
165
  for (const term of doc.tf.keys()) {
85
- const count = this.df.get(term) || 0;
86
- if (count <= 1) this.df.delete(term);
87
- else this.df.set(term, count - 1);
166
+ const c = this.df.get(term) || 0;
167
+ if (c <= 1) this.df.delete(term);
168
+ else this.df.set(term, c - 1);
88
169
  }
89
170
  this.docs.delete(key);
90
171
  }
@@ -93,41 +174,40 @@ class BM25Index {
93
174
  this.N = this.docs.size;
94
175
  if (this.N === 0) { this.avgLen = 0; return; }
95
176
  let total = 0;
96
- for (const doc of this.docs.values()) total += doc.tokens.length;
177
+ for (const doc of this.docs.values()) total += doc.dl;
97
178
  this.avgLen = total / this.N;
98
179
  }
99
180
 
100
181
  _scoreDoc(queryTokens, docKey) {
101
182
  const doc = this.docs.get(docKey);
102
183
  if (!doc) return 0;
103
- const dl = doc.tokens.length;
104
- const lenNorm = this.avgLen > 0 ? dl / this.avgLen : 1;
184
+ const lenNorm = this.avgLen > 0 ? doc.dl / this.avgLen : 1;
105
185
  let score = 0;
106
186
  for (const term of queryTokens) {
107
187
  const tf = doc.tf.get(term) || 0;
108
188
  if (tf === 0) continue;
109
- const df = this.df.get(term) || 0;
189
+ const df = this.df.get(term) || 0;
110
190
  const idf = Math.log((this.N - df + 0.5) / (df + 0.5) + 1);
111
- const tfNorm = (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * lenNorm));
112
- score += idf * tfNorm;
191
+ const tfn = (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * lenNorm));
192
+ score += idf * tfn;
113
193
  }
114
194
  return score;
115
195
  }
116
196
 
117
197
  search(query, { limit = 10, tier = "all", minScore = 0, noiseFilter = true, namespace = null } = {}) {
198
+ const safeTier = VALID_TIERS.has(tier) ? tier : "all";
199
+ const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? Math.floor(limit) : 10, 50));
118
200
  const queryTokens = this.tokenize(query);
119
201
  if (queryTokens.length === 0) return [];
120
202
  const results = [];
121
203
  for (const [key, doc] of this.docs.entries()) {
122
- if (tier !== "all" && doc.tier !== tier) continue;
204
+ if (safeTier !== "all" && doc.tier !== safeTier) continue;
123
205
  if (namespace && !key.startsWith(namespace + ":")) continue;
124
206
  if (noiseFilter && isSessionNoise(key, doc.content)) continue;
125
207
  const score = this._scoreDoc(queryTokens, key);
126
- if (score > minScore) {
127
- results.push({ key, score, tier: doc.tier, content: doc.content, updated_at: doc.updatedAt });
128
- }
208
+ if (score > minScore) results.push({ key, score, tier: doc.tier, content: doc.content, updated_at: doc.updatedAt });
129
209
  }
130
- return results.sort((a, b) => b.score - a.score).slice(0, limit);
210
+ return results.sort((a, b) => b.score - a.score).slice(0, safeLimit);
131
211
  }
132
212
 
133
213
  get size() { return this.N; }
@@ -136,20 +216,90 @@ class BM25Index {
136
216
  const bm25 = new BM25Index();
137
217
 
138
218
  // ---------------------------------------------------------------------------
139
- // Index Build & Maintenance
219
+ // Session buffer — ambient turn capture without explicit agent store calls.
220
+ // Agents POST to /api/buffer fire-and-forget; buffer auto-flushes to Redis.
221
+ // ---------------------------------------------------------------------------
222
+
223
+ const sessionBuffers = new Map(); // session_id -> [{ role, content, agent, ts }]
224
+
225
+ async function flushBuffer(sessionId) {
226
+ const buf = sessionBuffers.get(sessionId);
227
+ if (!buf || buf.length === 0) return;
228
+ const key = `session:${sessionId}:buffer`;
229
+ try {
230
+ const existing = await redis.get(key);
231
+ const prev = existing ? JSON.parse(existing) : [];
232
+ await redis.setEx(key, 7 * 24 * 60 * 60, JSON.stringify([...prev, ...buf]));
233
+ sessionBuffers.set(sessionId, []);
234
+ } catch (e) {
235
+ console.error(`Buffer flush error session ${sessionId}:`, e.message);
236
+ }
237
+ }
238
+
239
+ function bufferAppend(sessionId, agentName, role, content) {
240
+ if (!sessionBuffers.has(sessionId)) sessionBuffers.set(sessionId, []);
241
+ const buf = sessionBuffers.get(sessionId);
242
+ buf.push({ role: role || "user", content, agent: agentName || "unknown", ts: new Date().toISOString() });
243
+ if (buf.length >= BUFFER_CAPACITY) flushBuffer(sessionId).catch(() => {});
244
+ }
245
+
246
+ // ---------------------------------------------------------------------------
247
+ // Procedural memory — stable agent preferences/style knobs, no TTL/decay.
248
+ // Redis namespace: proc:agent:{name}:{key}
249
+ // ---------------------------------------------------------------------------
250
+
251
+ function procKey(agentName, key) {
252
+ if (!PROC_KEY_RE.test(agentName)) throw new Error("invalid agent_name");
253
+ if (!PROC_KEY_RE.test(key)) throw new Error("invalid proc key");
254
+ return `proc:agent:${agentName}:${key}`;
255
+ }
256
+
257
+ async function procGet(agentName) {
258
+ const prefix = `proc:agent:${agentName}:`;
259
+ const result = {};
260
+ for await (const k of scanKeys(`${prefix}*`, "string")) {
261
+ const val = await redis.get(k);
262
+ if (!val) continue;
263
+ const shortKey = k.slice(prefix.length);
264
+ try { result[shortKey] = JSON.parse(val); } catch { result[shortKey] = val; }
265
+ }
266
+ return result;
267
+ }
268
+
269
+ // Pending-ops queue: writes/removes that occur during a rebuild are applied
270
+ // after the swap so they aren't silently discarded — fix #4
271
+ let isBuilding = false;
272
+ const pendingOps = [];
273
+
274
+ function indexAdd(key, content, tier, updatedAt) {
275
+ bm25.add(key, content, tier, updatedAt); // update live index for immediate search
276
+ if (isBuilding) pendingOps.push({ op: "add", key, content, tier, updatedAt });
277
+ }
278
+
279
+ function indexRemove(key) {
280
+ bm25.remove(key);
281
+ if (isBuilding) pendingOps.push({ op: "remove", key });
282
+ }
283
+
284
+ // ---------------------------------------------------------------------------
285
+ // Index build
140
286
  // ---------------------------------------------------------------------------
141
287
 
142
288
  async function buildIndex() {
143
- const freshIndex = new BM25Index();
289
+ if (isBuilding) return; // skip if already running
290
+ isBuilding = true;
291
+ pendingOps.length = 0;
292
+
293
+ const entries = [];
144
294
 
145
- // Scan all Redis keys
146
- let redisCount = 0;
295
+ // Scan Redis — scanKeys normalizes page/individual yields from scanIterator
147
296
  try {
148
- for await (const key of redis.scanIterator({ MATCH: "*", COUNT: 200 })) {
149
- const val = await redis.get(key);
150
- if (val) {
151
- freshIndex.add(key, val, "longterm", null);
152
- redisCount++;
297
+ for await (const key of scanKeys("*", "string")) {
298
+ try {
299
+ const val = await redis.get(key);
300
+ if (val) entries.push({ key, content: val, tier: "longterm", updatedAt: null });
301
+ } catch (e) {
302
+ console.warn(`Index build — skipping key '${key}': ${e.message}`);
153
303
  }
154
304
  }
155
305
  } catch (e) {
@@ -157,22 +307,20 @@ async function buildIndex() {
157
307
  }
158
308
 
159
309
  // Walk Obsidian vault
160
- let vaultCount = 0;
161
310
  async function walk(dir) {
162
- let entries;
163
- try { entries = await fs.readdir(dir, { withFileTypes: true }); }
311
+ let items;
312
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
164
313
  catch (e) { if (e.code === "ENOENT") return; throw e; }
165
- for (const entry of entries) {
314
+ for (const entry of items) {
166
315
  const fullPath = path.join(dir, entry.name);
167
316
  if (entry.isDirectory()) { await walk(fullPath); continue; }
168
317
  if (!entry.name.endsWith(".md")) continue;
169
318
  try {
170
319
  const content = await fs.readFile(fullPath, "utf-8");
171
- const stat = await fs.stat(fullPath);
320
+ const stat = await fs.stat(fullPath);
172
321
  const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
173
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
174
- freshIndex.add(key, content, "working", stat.mtime.toISOString());
175
- vaultCount++;
322
+ const key = relative.replace(/\//g, ":").replace(/\\/, ":").replace(/\.md$/, "");
323
+ entries.push({ key, content, tier: "working", updatedAt: stat.mtime.toISOString() });
176
324
  } catch (e) {
177
325
  console.error("Index build — vault read error:", fullPath, e.message);
178
326
  }
@@ -180,35 +328,41 @@ async function buildIndex() {
180
328
  }
181
329
  await walk(OBSIDIAN_VAULT_PATH);
182
330
 
183
- // Swap in new index atomically
184
- bm25.docs = freshIndex.docs;
185
- bm25.df = freshIndex.df;
186
- bm25.avgLen = freshIndex.avgLen;
187
- bm25.N = freshIndex.N;
331
+ // Build fresh index in bulk — O(N log N), no event-loop stall per doc
332
+ const fresh = new BM25Index();
333
+ fresh.bulkAdd(entries);
334
+
335
+ // Atomic field swap
336
+ bm25.docs = fresh.docs;
337
+ bm25.df = fresh.df;
338
+ bm25.avgLen = fresh.avgLen;
339
+ bm25.N = fresh.N;
188
340
 
189
- console.log(`BM25 index built: ${redisCount} Redis keys + ${vaultCount} vault files = ${bm25.size} docs`);
341
+ // Re-apply writes/removes that occurred during the build
342
+ for (const op of pendingOps) {
343
+ if (op.op === "add") bm25.add(op.key, op.content, op.tier, op.updatedAt);
344
+ else if (op.op === "remove") bm25.remove(op.key);
345
+ }
346
+ pendingOps.length = 0;
347
+ isBuilding = false;
348
+
349
+ console.log(`BM25 index built: ${bm25.size} docs (${entries.length} total entries scanned)`);
190
350
  }
191
351
 
192
352
  // ---------------------------------------------------------------------------
193
- // Obsidian Vault Helpers
353
+ // Obsidian vault helpers
194
354
  // ---------------------------------------------------------------------------
195
355
 
196
- function keyToObsidianPath(key) {
197
- const relativePath = key.replace(/:/g, "/") + ".md";
198
- return path.join(OBSIDIAN_VAULT_PATH, relativePath);
199
- }
200
-
201
356
  async function saveToObsidian(key, content, metadata) {
202
- const filePath = keyToObsidianPath(key);
357
+ const filePath = keyToObsidianPath(key); // throws on bad key
203
358
  await fs.mkdir(path.dirname(filePath), { recursive: true });
204
359
  let output = content;
205
360
  if (metadata && Object.keys(metadata).length > 0) {
206
- const frontmatter = ["---"];
207
- for (const [k, v] of Object.entries(metadata)) {
208
- frontmatter.push(`${k}: ${Array.isArray(v) ? `[${v.join(", ")}]` : v}`);
209
- }
210
- frontmatter.push("---", "");
211
- output = frontmatter.join("\n") + content;
361
+ const lines = ["---"];
362
+ for (const [k, v] of Object.entries(metadata))
363
+ lines.push(`${k}: ${Array.isArray(v) ? `[${v.join(", ")}]` : v}`);
364
+ lines.push("---", "");
365
+ output = lines.join("\n") + content;
212
366
  }
213
367
  await fs.writeFile(filePath, output, "utf-8");
214
368
  return filePath;
@@ -226,72 +380,74 @@ async function deleteFromObsidian(key) {
226
380
  catch (e) { if (e.code === "ENOENT") return false; throw e; }
227
381
  }
228
382
 
229
- async function searchObsidian(query) {
383
+ async function searchObsidian(query, namespace) {
230
384
  const results = [];
231
385
  async function walk(dir) {
232
- const entries = await fs.readdir(dir, { withFileTypes: true });
233
- for (const entry of entries) {
386
+ let items;
387
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
388
+ catch (e) { if (e.code === "ENOENT") return; throw e; }
389
+ for (const entry of items) {
234
390
  const fullPath = path.join(dir, entry.name);
235
391
  if (entry.isDirectory()) { await walk(fullPath); continue; }
236
392
  if (!entry.name.endsWith(".md")) continue;
237
393
  const content = await fs.readFile(fullPath, "utf-8");
238
- if (content.toLowerCase().includes(query.toLowerCase())) {
239
- const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
240
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
241
- results.push({ key, content, path: relative });
242
- }
394
+ if (!content.toLowerCase().includes(query.toLowerCase())) continue;
395
+ const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
396
+ const key = relative.replace(/[\\/]/g, ":").replace(/\.md$/, "");
397
+ if (namespace && !key.startsWith(namespace + ":")) continue;
398
+ results.push({ key, content, path: relative });
243
399
  }
244
400
  }
245
- try { await walk(OBSIDIAN_VAULT_PATH); }
246
- catch (e) { if (e.code !== "ENOENT") throw e; }
401
+ await walk(OBSIDIAN_VAULT_PATH);
247
402
  return results;
248
403
  }
249
404
 
250
405
  async function listObsidian(prefix) {
251
406
  const results = [];
252
407
  async function walk(dir) {
253
- const entries = await fs.readdir(dir, { withFileTypes: true });
254
- for (const entry of entries) {
408
+ let items;
409
+ try { items = await fs.readdir(dir, { withFileTypes: true }); }
410
+ catch (e) { if (e.code === "ENOENT") return; throw e; }
411
+ for (const entry of items) {
255
412
  const fullPath = path.join(dir, entry.name);
256
413
  if (entry.isDirectory()) { await walk(fullPath); continue; }
257
414
  if (!entry.name.endsWith(".md")) continue;
258
415
  const relative = path.relative(OBSIDIAN_VAULT_PATH, fullPath);
259
- const key = relative.replace(/\//g, ":").replace(/\.md$/, "");
416
+ const key = relative.replace(/[\\/]/g, ":").replace(/\.md$/, "");
260
417
  if (!prefix || key.startsWith(prefix)) results.push({ key, path: relative });
261
418
  }
262
419
  }
263
- try { await walk(OBSIDIAN_VAULT_PATH); }
264
- catch (e) { if (e.code !== "ENOENT") throw e; }
420
+ await walk(OBSIDIAN_VAULT_PATH);
265
421
  return results;
266
422
  }
267
423
 
268
424
  // ---------------------------------------------------------------------------
269
- // MCP Server Factory
425
+ // MCP server factory
270
426
  // ---------------------------------------------------------------------------
271
427
 
272
- function createMcpServerInstance() {
273
- const server = new McpServer({
274
- name: "heurchain-mcp",
275
- version: "1.2.0"
276
- });
428
+ function createMcpServerInstance(profile = "full") {
429
+ const server = new McpServer({ name: "heurchain-mcp", version: "1.3.0" });
277
430
 
278
431
  // --- Cache Tools ---
279
432
 
280
433
  server.tool("cache_set", "Store a key-value pair in Redis (longterm tier). Optionally scope to a namespace.", {
281
- key: z.string().describe("Cache key"),
282
- value: z.string().describe("Value to cache"),
283
- ttl: z.number().optional().describe("Time-to-live in seconds"),
434
+ key: z.string().describe("Cache key"),
435
+ value: z.string().describe("Value to cache"),
436
+ ttl: z.number().optional().describe("Time-to-live in seconds"),
284
437
  namespace: z.string().optional().describe("Optional namespace prefix, e.g. 'agent-hermes'. Key becomes namespace:key.")
285
438
  }, async ({ key, value, ttl, namespace }) => {
286
439
  const fullKey = namespace ? `${namespace}:${key}` : key;
440
+ try { validateKey(fullKey); } catch (e) {
441
+ return { content: [{ type: "text", text: JSON.stringify({ cached: false, error: e.message }) }] };
442
+ }
287
443
  if (ttl) await redis.setEx(fullKey, ttl, value);
288
444
  else await redis.set(fullKey, value);
289
- bm25.add(fullKey, value, "longterm", new Date().toISOString());
445
+ indexAdd(fullKey, value, "longterm", new Date().toISOString());
290
446
  return { content: [{ type: "text", text: JSON.stringify({ cached: true, key: fullKey }) }] };
291
447
  });
292
448
 
293
449
  server.tool("cache_get", "Retrieve a cached value from Redis by key", {
294
- key: z.string().describe("Cache key to retrieve"),
450
+ key: z.string().describe("Cache key to retrieve"),
295
451
  namespace: z.string().optional().describe("Namespace prefix used when storing")
296
452
  }, async ({ key, namespace }) => {
297
453
  const fullKey = namespace ? `${namespace}:${key}` : key;
@@ -301,12 +457,12 @@ function createMcpServerInstance() {
301
457
  });
302
458
 
303
459
  server.tool("cache_delete", "Delete a cached key from Redis", {
304
- key: z.string().describe("Cache key to delete"),
460
+ key: z.string().describe("Cache key to delete"),
305
461
  namespace: z.string().optional().describe("Namespace prefix used when storing")
306
462
  }, async ({ key, namespace }) => {
307
463
  const fullKey = namespace ? `${namespace}:${key}` : key;
308
464
  const deleted = await redis.del(fullKey);
309
- bm25.remove(fullKey);
465
+ indexRemove(fullKey);
310
466
  return { content: [{ type: "text", text: JSON.stringify({ deleted: deleted > 0, key: fullKey }) }] };
311
467
  });
312
468
 
@@ -319,41 +475,36 @@ function createMcpServerInstance() {
319
475
  const redisOk = redis.isReady;
320
476
  let obsidianOk = false;
321
477
  try { await fs.access(OBSIDIAN_VAULT_PATH); obsidianOk = true; } catch {}
322
- return {
323
- content: [{
324
- type: "text",
325
- text: JSON.stringify({
326
- status: (redisOk && obsidianOk) ? "healthy" : "degraded",
327
- redis: redisOk,
328
- obsidian: obsidianOk,
329
- vault_path: OBSIDIAN_VAULT_PATH,
330
- bm25_docs: bm25.size,
331
- uptime: process.uptime()
332
- })
333
- }]
334
- };
335
- });
336
-
337
- // --- Obsidian Vault Tools (Working Tier / Human-Readable Glacier) ---
338
-
339
- server.tool("obsidian_write_note", "Write a markdown note to the Obsidian vault (working tier — human-readable glacier). Key colons become folder separators.", {
340
- key: z.string().describe("Note key (e.g. doc:proxmox:setup)"),
341
- content: z.string().describe("Markdown body"),
342
- metadata: z.record(z.string()).optional().describe("Optional frontmatter metadata"),
478
+ return { content: [{ type: "text", text: JSON.stringify({
479
+ status: (redisOk && obsidianOk) ? "healthy" : "degraded",
480
+ redis: redisOk, obsidian: obsidianOk,
481
+ vault_path: OBSIDIAN_VAULT_PATH,
482
+ bm25_docs: bm25.size,
483
+ uptime: process.uptime()
484
+ }) }] };
485
+ });
486
+
487
+ // --- Obsidian Vault Tools ---
488
+
489
+ server.tool("obsidian_write_note", "Write a markdown note to the Obsidian vault (working tier). Key colons become folder separators.", {
490
+ key: z.string().describe("Note key (e.g. doc:proxmox:setup)"),
491
+ content: z.string().describe("Markdown body"),
492
+ metadata: z.record(z.string()).optional().describe("Optional frontmatter metadata"),
343
493
  namespace: z.string().optional().describe("Optional namespace prefix")
344
494
  }, async ({ key, content, metadata, namespace }) => {
345
495
  const fullKey = namespace ? `${namespace}:${key}` : key;
346
496
  try {
347
497
  const filePath = await saveToObsidian(fullKey, content, metadata);
348
- bm25.add(fullKey, content, "working", new Date().toISOString());
498
+ indexAdd(fullKey, content, "working", new Date().toISOString());
349
499
  return { content: [{ type: "text", text: JSON.stringify({ stored: true, key: fullKey, path: filePath, tier: "working" }) }] };
350
500
  } catch (e) {
351
- return { content: [{ type: "text", text: JSON.stringify({ stored: false, key: fullKey, error: e.message }) }] };
501
+ console.error(`obsidian_write_note error for key '${fullKey}':`, e);
502
+ return { content: [{ type: "text", text: JSON.stringify({ stored: false, key: fullKey, error: e.message.startsWith("invalid key") ? e.message : "write failed" }) }] };
352
503
  }
353
504
  });
354
505
 
355
506
  server.tool("obsidian_read_note", "Read a markdown note from the Obsidian vault by key", {
356
- key: z.string().describe("Note key"),
507
+ key: z.string().describe("Note key"),
357
508
  namespace: z.string().optional().describe("Namespace prefix used when storing")
358
509
  }, async ({ key, namespace }) => {
359
510
  const fullKey = namespace ? `${namespace}:${key}` : key;
@@ -362,39 +513,41 @@ function createMcpServerInstance() {
362
513
  if (content === null) return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey }) }] };
363
514
  return { content: [{ type: "text", text: JSON.stringify({ found: true, key: fullKey, content }) }] };
364
515
  } catch (e) {
365
- return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey, error: e.message }) }] };
516
+ console.error(`obsidian_read_note error for key '${fullKey}':`, e);
517
+ return { content: [{ type: "text", text: JSON.stringify({ found: false, key: fullKey, error: e.message.startsWith("invalid key") ? e.message : "read failed" }) }] };
366
518
  }
367
519
  });
368
520
 
369
521
  server.tool("obsidian_delete_note", "Delete a markdown note from the Obsidian vault by key", {
370
- key: z.string().describe("Note key to delete"),
522
+ key: z.string().describe("Note key to delete"),
371
523
  namespace: z.string().optional().describe("Namespace prefix used when storing")
372
524
  }, async ({ key, namespace }) => {
373
525
  const fullKey = namespace ? `${namespace}:${key}` : key;
374
526
  try {
375
527
  const deleted = await deleteFromObsidian(fullKey);
376
- bm25.remove(fullKey);
528
+ indexRemove(fullKey);
377
529
  return { content: [{ type: "text", text: JSON.stringify({ deleted, key: fullKey }) }] };
378
530
  } catch (e) {
379
- return { content: [{ type: "text", text: JSON.stringify({ deleted: false, key: fullKey, error: e.message }) }] };
531
+ console.error(`obsidian_delete_note error for key '${fullKey}':`, e);
532
+ return { content: [{ type: "text", text: JSON.stringify({ deleted: false, key: fullKey, error: e.message.startsWith("invalid key") ? e.message : "delete failed" }) }] };
380
533
  }
381
534
  });
382
535
 
383
- server.tool("obsidian_search_notes", "Search markdown notes in the Obsidian vault by keyword (substring match, vault only). Prefer heurchain_search for ranked results across all tiers.", {
384
- query: z.string().describe("Search term"),
385
- limit: z.number().optional().describe("Max results").default(10),
536
+ server.tool("obsidian_search_notes", "Search markdown notes in the Obsidian vault by keyword (substring, vault only). Prefer heurchain_search for ranked results across all tiers.", {
537
+ query: z.string().describe("Search term"),
538
+ limit: z.number().optional().describe("Max results (1–100, default 10)").default(10),
386
539
  namespace: z.string().optional().describe("Restrict to a namespace prefix")
387
540
  }, async ({ query, limit, namespace }) => {
541
+ const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? Math.floor(limit) : 10, 100));
388
542
  try {
389
- let results = await searchObsidian(query);
390
- if (namespace) results = results.filter(r => r.key.startsWith(namespace + ":"));
391
- const sliced = results.slice(0, limit);
543
+ const results = await searchObsidian(query, namespace || null);
392
544
  return { content: [{ type: "text", text: JSON.stringify({
393
545
  count: results.length,
394
- results: sliced.map(r => ({ key: r.key, preview: r.content.substring(0, 200) }))
546
+ results: results.slice(0, safeLimit).map(r => ({ key: r.key, preview: r.content.substring(0, 200) }))
395
547
  }) }] };
396
548
  } catch (e) {
397
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
549
+ console.error("obsidian_search_notes error:", e);
550
+ return { content: [{ type: "text", text: JSON.stringify({ error: "search failed" }) }] };
398
551
  }
399
552
  });
400
553
 
@@ -405,20 +558,21 @@ function createMcpServerInstance() {
405
558
  const results = await listObsidian(prefix);
406
559
  return { content: [{ type: "text", text: JSON.stringify({ count: results.length, notes: results }) }] };
407
560
  } catch (e) {
408
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
561
+ console.error("obsidian_list_notes error:", e);
562
+ return { content: [{ type: "text", text: JSON.stringify({ error: "list failed" }) }] };
409
563
  }
410
564
  });
411
565
 
412
- // --- HeurChain BM25 Search (native, in-process) ---
566
+ // --- HeurChain BM25 Search ---
413
567
 
414
568
  server.tool("heurchain_search",
415
- "Search the full knowledge base using HeurChain's native BM25 ranked index. Covers all Redis keys (longterm tier) and Obsidian vault files (working tier) with relevance scoring. Preferred over obsidian_search_notes.", {
416
- query: z.string().describe("Search query"),
417
- limit: z.number().optional().describe("Max results (default 10, max 50)").default(10),
418
- tier: z.string().optional().describe("'all' | 'longterm' | 'working' (default: all)").default("all"),
419
- minScore: z.number().optional().describe("Minimum BM25 score threshold (default 0 = all results; try 0.5 to cut noise)").default(0),
420
- noiseFilter: z.boolean().optional().describe("Skip low-signal session metadata entries (default true)").default(true),
421
- namespace: z.string().optional().describe("Restrict search to a namespace, e.g. 'agent-hermes'")
569
+ "Search the full knowledge base using HeurChain's native BM25 ranked index. Covers all Redis keys (longterm) and Obsidian vault files (working). Preferred over obsidian_search_notes.", {
570
+ query: z.string().describe("Search query"),
571
+ limit: z.number().optional().describe("Max results (default 10, max 50)").default(10),
572
+ tier: z.string().optional().describe("'all' | 'longterm' | 'working' (default: all)").default("all"),
573
+ minScore: z.number().optional().describe("Minimum BM25 score (default 0; try 0.5 to reduce noise)").default(0),
574
+ noiseFilter: z.boolean().optional().describe("Skip low-signal session metadata (default true)").default(true),
575
+ namespace: z.string().optional().describe("Restrict to a namespace, e.g. 'agent-hermes'")
422
576
  }, async ({ query, limit, tier, minScore, noiseFilter, namespace }) => {
423
577
  try {
424
578
  const results = bm25.search(query, {
@@ -440,20 +594,23 @@ function createMcpServerInstance() {
440
594
  }))
441
595
  }) }] };
442
596
  } catch (e) {
443
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
597
+ console.error("heurchain_search error:", e);
598
+ return { content: [{ type: "text", text: JSON.stringify({ error: "search failed" }) }] };
444
599
  }
445
600
  });
446
601
 
447
602
  // --- heurchain_export (Glacier Sync) ---
448
603
 
449
604
  server.tool("heurchain_export",
450
- "Export Redis longterm-tier entries to Obsidian vault markdown files. Makes the Redis knowledge base human-readable and browsable. Idempotent — safe to run repeatedly.", {
451
- prefix: z.string().optional().describe("Only export keys matching this prefix (e.g. 'doc:', 'memory:'). Defaults to all keys."),
605
+ "Export Redis longterm-tier entries to Obsidian vault markdown files. Makes the Redis knowledge base human-readable. Idempotent — safe to run repeatedly.", {
606
+ prefix: z.string().optional().describe("Only export keys matching this prefix (e.g. 'doc:'). Defaults to all keys."),
452
607
  overwrite: z.boolean().optional().describe("Overwrite existing vault files (default false — skip if file exists)").default(false)
453
608
  }, async ({ prefix, overwrite }) => {
454
609
  let exported = 0, skipped = 0, errors = 0;
455
610
  try {
456
- for await (const key of redis.scanIterator({ MATCH: prefix ? `${prefix}*` : "*", COUNT: 100 })) {
611
+ for await (const key of scanKeys(prefix ? `${prefix}*` : "*", "string")) {
612
+ // skip keys that would fail path validation
613
+ try { validateKey(key); } catch { skipped++; continue; }
457
614
  const val = await redis.get(key);
458
615
  if (!val) continue;
459
616
  const filePath = keyToObsidianPath(key);
@@ -462,21 +619,58 @@ function createMcpServerInstance() {
462
619
  }
463
620
  try {
464
621
  await fs.mkdir(path.dirname(filePath), { recursive: true });
465
- const header = `---\nkey: ${key}\nexported_at: ${new Date().toISOString()}\nsource: redis-longterm\n---\n\n`;
622
+ // avoid double-frontmatter if the Redis value already starts with ---
623
+ const hasFrontmatter = val.trimStart().startsWith("---");
624
+ const header = hasFrontmatter
625
+ ? `<!-- exported: key=${key} at ${new Date().toISOString()} -->\n\n`
626
+ : `---\nkey: ${key}\nexported_at: ${new Date().toISOString()}\nsource: redis-longterm\n---\n\n`;
466
627
  await fs.writeFile(filePath, header + val, "utf-8");
467
- bm25.add(key, val, "longterm", new Date().toISOString());
628
+ indexAdd(key, val, "longterm", new Date().toISOString());
468
629
  exported++;
469
630
  } catch (e) {
470
- console.error(`heurchain_export: failed to write ${key}:`, e.message);
631
+ console.error(`heurchain_export: failed to write '${key}':`, e.message);
471
632
  errors++;
472
633
  }
473
634
  }
474
635
  return { content: [{ type: "text", text: JSON.stringify({ exported, skipped, errors, vault_path: OBSIDIAN_VAULT_PATH }) }] };
475
636
  } catch (e) {
476
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message, exported, skipped, errors }) }] };
637
+ console.error("heurchain_export error:", e);
638
+ return { content: [{ type: "text", text: JSON.stringify({ error: "export failed", exported, skipped, errors }) }] };
477
639
  }
478
640
  });
479
641
 
642
+ // --- Procedural Memory Tools ---
643
+
644
+ server.tool("proc_set",
645
+ "Store a stable agent preference or style knob in procedural memory. These persist indefinitely across sessions — no TTL, no decay. Use for learned behaviors, coding style, user preferences.", {
646
+ agent_name: z.string().describe("Agent identifier (e.g. 'claude-code', 'hermes')"),
647
+ key: z.string().describe("Preference name (alphanumeric, hyphens, underscores — e.g. 'coding_style')"),
648
+ value: z.string().describe("Preference value")
649
+ }, async ({ agent_name, key, value }) => {
650
+ try {
651
+ const rk = procKey(agent_name, key);
652
+ await redis.set(rk, value);
653
+ return { content: [{ type: "text", text: JSON.stringify({ stored: true, key: rk }) }] };
654
+ } catch (e) {
655
+ return { content: [{ type: "text", text: JSON.stringify({ stored: false, error: e.message }) }] };
656
+ }
657
+ });
658
+
659
+ server.tool("proc_get",
660
+ "Read all procedural memory knobs for an agent as compact JSON. Call once at session start and inject into system prompt — zero tool calls needed during the session.", {
661
+ agent_name: z.string().describe("Agent identifier")
662
+ }, async ({ agent_name }) => {
663
+ try {
664
+ const result = await procGet(agent_name);
665
+ return { content: [{ type: "text", text: JSON.stringify(result) }] };
666
+ } catch (e) {
667
+ return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
668
+ }
669
+ });
670
+
671
+ // --- Infrastructure Tools (full profile only) ---
672
+ if (profile === "full") {
673
+
480
674
  // --- Prometheus Monitoring Tools ---
481
675
 
482
676
  server.tool("prometheus_get_targets", "Returns the status of all targets Prometheus is currently scraping", {}, async () => {
@@ -489,7 +683,7 @@ function createMcpServerInstance() {
489
683
  }));
490
684
  return { content: [{ type: "text", text: JSON.stringify({ targets }) }] };
491
685
  } catch (e) {
492
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
686
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
493
687
  }
494
688
  });
495
689
 
@@ -500,7 +694,7 @@ function createMcpServerInstance() {
500
694
  const data = await response.json();
501
695
  return { content: [{ type: "text", text: JSON.stringify({ alerts: data.data.alerts }) }] };
502
696
  } catch (e) {
503
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
697
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
504
698
  }
505
699
  });
506
700
 
@@ -513,60 +707,68 @@ function createMcpServerInstance() {
513
707
  const data = await response.json();
514
708
  return { content: [{ type: "text", text: JSON.stringify(data.data) }] };
515
709
  } catch (e) {
516
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
710
+ return { content: [{ type: "text", text: JSON.stringify({ error: "request failed" }) }] };
517
711
  }
518
712
  });
519
713
 
520
- // --- Grafana Monitoring Tools ---
714
+ // --- Grafana Monitoring Tools — fail closed if creds not configured (#6) ---
715
+
716
+ const grafanaUser = process.env.GRAFANA_USER;
717
+ const grafanaPass = process.env.GRAFANA_PASSWORD;
718
+ const grafanaAuth = (grafanaUser && grafanaPass)
719
+ ? "Basic " + Buffer.from(`${grafanaUser}:${grafanaPass}`).toString("base64")
720
+ : null;
521
721
 
522
- const grafanaAuth = "Basic " + Buffer.from(`${process.env.GRAFANA_USER || "admin"}:${process.env.GRAFANA_PASSWORD || "admin"}`).toString("base64");
722
+ function grafanaHeaders() {
723
+ if (!grafanaAuth) throw new Error("Grafana credentials not configured (GRAFANA_USER / GRAFANA_PASSWORD not set)");
724
+ return { "Authorization": grafanaAuth };
725
+ }
523
726
 
524
727
  server.tool("grafana_get_health", "Check the health status of the Grafana server", {}, async () => {
525
728
  try {
526
- const response = await fetch("http://grafana:3000/api/health", { headers: { "Authorization": grafanaAuth } });
729
+ const response = await fetch("http://grafana:3000/api/health", { headers: grafanaHeaders() });
527
730
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
528
731
  return { content: [{ type: "text", text: JSON.stringify(await response.json()) }] };
529
732
  } catch (e) {
530
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
733
+ return { content: [{ type: "text", text: JSON.stringify({ error: e.message.includes("credentials") ? e.message : "request failed" }) }] };
531
734
  }
532
735
  });
533
736
 
534
737
  server.tool("grafana_list_dashboards", "List all available dashboards in Grafana", {}, async () => {
535
738
  try {
536
- const response = await fetch("http://grafana:3000/api/search?type=dash-db", { headers: { "Authorization": grafanaAuth } });
739
+ const response = await fetch("http://grafana:3000/api/search?type=dash-db", { headers: grafanaHeaders() });
537
740
  if (!response.ok) return { content: [{ type: "text", text: JSON.stringify({ error: `HTTP ${response.status}` }) }] };
538
741
  const dashboards = await response.json();
539
742
  return { content: [{ type: "text", text: JSON.stringify({ dashboards: dashboards.map(d => ({ title: d.title, url: d.url })) }) }] };
540
743
  } catch (e) {
541
- return { content: [{ type: "text", text: JSON.stringify({ error: e.message }) }] };
744
+ return { content: [{ type: "text", text: JSON.stringify({ error: e.message.includes("credentials") ? e.message : "request failed" }) }] };
542
745
  }
543
746
  });
544
747
 
545
- // --- Proxmox Documentation Tools (Redis-backed) ---
748
+ // --- Proxmox Documentation Tools ---
546
749
 
547
750
  async function searchDocs(keyPattern, contentFilter) {
548
751
  const keys = [];
549
- for await (const key of redis.scanIterator({ MATCH: keyPattern, COUNT: 100 })) keys.push(key);
752
+ for await (const key of scanKeys(keyPattern, "string")) keys.push(key);
550
753
  if (keys.length === 0) return [];
551
754
  const results = [];
552
755
  for (const key of keys) {
553
756
  const val = await redis.get(key);
554
- if (val && (!contentFilter || val.toLowerCase().includes(contentFilter.toLowerCase()))) {
757
+ if (val && (!contentFilter || val.toLowerCase().includes(contentFilter.toLowerCase())))
555
758
  results.push({ key, content: val });
556
- }
557
759
  }
558
760
  return results;
559
761
  }
560
762
 
561
763
  server.tool("proxmox_get_cluster_status", "Retrieve the Proxmox cluster status document from the knowledge base", {}, async () => {
562
764
  const results = await searchDocs("doc:proxmox:cluster-status*", null);
563
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No cluster status document found. Store one with key 'doc:proxmox:cluster-status' using cache_set." }) }] };
765
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No cluster status document found. Store one with key 'doc:proxmox:cluster-status' using cache_set." }) }] };
564
766
  return { content: [{ type: "text", text: results[0].content }] };
565
767
  });
566
768
 
567
769
  server.tool("proxmox_list_nodes", "List all Proxmox nodes documented in the knowledge base", {}, async () => {
568
770
  const results = await searchDocs("doc:proxmox:node:*", null);
569
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No node documents found. Store them with keys like 'doc:proxmox:node:pver430' using cache_set." }) }] };
771
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No node documents found." }) }] };
570
772
  return { content: [{ type: "text", text: JSON.stringify({ nodes: results.map(r => ({ key: r.key, title: r.key.split(":").pop() })) }) }] };
571
773
  });
572
774
 
@@ -574,33 +776,33 @@ function createMcpServerInstance() {
574
776
  vm_id_or_name: z.string().describe("VM ID or name to search for")
575
777
  }, async ({ vm_id_or_name }) => {
576
778
  let results = await searchDocs("doc:proxmox:vm:*", vm_id_or_name);
577
- if (results.length === 0) results = await searchDocs("doc:proxmox:ct:*", vm_id_or_name);
578
- if (results.length === 0) results = await searchDocs("doc:proxmox:*", vm_id_or_name);
579
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: `No VM or CT found matching "${vm_id_or_name}".` }) }] };
779
+ if (!results.length) results = await searchDocs("doc:proxmox:ct:*", vm_id_or_name);
780
+ if (!results.length) results = await searchDocs("doc:proxmox:*", vm_id_or_name);
781
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: `No VM or CT found matching "${vm_id_or_name}".` }) }] };
580
782
  return { content: [{ type: "text", text: results[0].content }] };
581
783
  });
582
784
 
583
- // --- Ceph Documentation Tools (Redis-backed) ---
785
+ // --- Ceph Documentation Tools ---
584
786
 
585
787
  server.tool("ceph_get_health_status", "Retrieve the latest Ceph cluster health status from the knowledge base", {}, async () => {
586
788
  const results = await searchDocs("doc:ceph:cluster-status*", null);
587
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No Ceph status document found. Store one with key 'doc:ceph:cluster-status' using cache_set." }) }] };
789
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No Ceph status document found." }) }] };
588
790
  return { content: [{ type: "text", text: results[0].content }] };
589
791
  });
590
792
 
591
793
  server.tool("ceph_list_osd_notes", "List all Ceph OSD documentation notes from the knowledge base", {}, async () => {
592
794
  const results = await searchDocs("doc:ceph:osd:*", null);
593
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: "No OSD documents found. Store them with keys like 'doc:ceph:osd:0' using cache_set." }) }] };
795
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: "No OSD documents found." }) }] };
594
796
  return { content: [{ type: "text", text: JSON.stringify({ osd_notes: results.map(r => r.key) }) }] };
595
797
  });
596
798
 
597
- // --- Network Documentation Tools (Redis-backed) ---
799
+ // --- Network Documentation Tools ---
598
800
 
599
801
  server.tool("network_search_docs", "Search across network and infrastructure documentation in the knowledge base", {
600
802
  search_query: z.string().describe("Search query to find relevant documentation")
601
803
  }, async ({ search_query }) => {
602
804
  const results = [...await searchDocs("doc:network:*", search_query), ...await searchDocs("doc:infrastructure:*", search_query)];
603
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ status: "No relevant documents found." }) }] };
805
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ status: "No relevant documents found." }) }] };
604
806
  return { content: [{ type: "text", text: JSON.stringify({ results: results.slice(0, 5).map(r => ({ key: r.key, preview: r.content.substring(0, 200) })) }) }] };
605
807
  });
606
808
 
@@ -608,13 +810,13 @@ function createMcpServerInstance() {
608
810
  topic: z.string().describe("Runbook topic to search for")
609
811
  }, async ({ topic }) => {
610
812
  const results = await searchDocs("doc:runbook:*", topic);
611
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ error: `No runbook found for topic: "${topic}". Store runbooks with keys like 'doc:runbook:topic-name' using cache_set.` }) }] };
813
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ error: `No runbook found for topic: "${topic}".` }) }] };
612
814
  return { content: [{ type: "text", text: results[0].content }] };
613
815
  });
614
816
 
615
- // --- User Context Tools (Redis-backed) ---
817
+ // --- User Context Tools ---
616
818
 
617
- const USER_HISTORY_TTL = 90 * 24 * 60 * 60; // 90 days
819
+ const USER_HISTORY_TTL = 90 * 24 * 60 * 60;
618
820
 
619
821
  server.tool("user_context_add_entry", "Add an entry to a user's daily interaction history log", {
620
822
  user_id: z.string().describe("User identifier"),
@@ -624,53 +826,75 @@ function createMcpServerInstance() {
624
826
  const key = `doc:users:${user_id}:history:${today}`;
625
827
  let existing = await redis.get(key);
626
828
  if (!existing) existing = `## User History for ${user_id} - ${today}\n\n`;
627
- const timestamp = new Date().toLocaleTimeString();
628
- const entry = `**[${timestamp}]**\n${content}\n\n---\n\n`;
829
+ const entry = `**[${new Date().toLocaleTimeString()}]**\n${content}\n\n---\n\n`;
629
830
  const updated = existing + entry;
630
831
  await redis.setEx(key, USER_HISTORY_TTL, updated);
631
- bm25.add(key, updated, "longterm", new Date().toISOString());
632
- return { content: [{ type: "text", text: JSON.stringify({ success: true, key, entry_added: entry }) }] };
832
+ indexAdd(key, updated, "longterm", new Date().toISOString());
833
+ return { content: [{ type: "text", text: JSON.stringify({ success: true, key }) }] };
633
834
  });
634
835
 
635
836
  server.tool("user_context_get_history", "Retrieve the full interaction history for a user on a specific date", {
636
837
  user_id: z.string().describe("User identifier"),
637
- date: z.string().describe("Date in YYYY-MM-DD format")
838
+ date: z.string().describe("Date in YYYY-MM-DD format")
638
839
  }, async ({ user_id, date }) => {
639
840
  const key = `doc:users:${user_id}:history:${date}`;
640
841
  const val = await redis.get(key);
641
- if (!val) return { content: [{ type: "text", text: JSON.stringify({ status: "Not Found", message: `No history found for user '${user_id}' on date '${date}'.` }) }] };
842
+ if (!val) return { content: [{ type: "text", text: JSON.stringify({ status: "Not Found", message: `No history for user '${user_id}' on '${date}'.` }) }] };
642
843
  return { content: [{ type: "text", text: JSON.stringify({ user_id, date, history: val }) }] };
643
844
  });
644
845
 
645
846
  server.tool("user_context_search_history", "Search across all of a user's history documents by keyword", {
646
847
  user_id: z.string().describe("User identifier"),
647
- query: z.string().describe("Search query")
848
+ query: z.string().describe("Search query")
648
849
  }, async ({ user_id, query }) => {
649
850
  const results = await searchDocs(`doc:users:${user_id}:history:*`, query);
650
- if (results.length === 0) return { content: [{ type: "text", text: JSON.stringify({ status: "No matches found." }) }] };
851
+ if (!results.length) return { content: [{ type: "text", text: JSON.stringify({ status: "No matches found." }) }] };
651
852
  return { content: [{ type: "text", text: JSON.stringify({
652
853
  results: results.map(r => ({ date: r.key.split(":").pop(), match_preview: r.content.substring(0, 200) + "..." }))
653
854
  }) }] };
654
855
  });
655
856
 
857
+ } // end profile === "full"
858
+
656
859
  return server;
657
860
  }
658
861
 
659
862
  // ---------------------------------------------------------------------------
660
- // SSE Transport
863
+ // SSE transport — fix #3: max session cap + cleanup on error/close
661
864
  // ---------------------------------------------------------------------------
662
865
 
866
+ const MAX_SESSIONS = 50;
663
867
  const transports = {};
664
868
 
665
- app.get("/sse", async (req, res) => {
869
+ app.get("/sse", requireAuth, async (req, res) => {
870
+ if (Object.keys(transports).length >= MAX_SESSIONS) {
871
+ return res.status(503).json({ error: "Max concurrent sessions reached" });
872
+ }
873
+ const profile = req.query.profile === "slim" ? "slim" : "full";
666
874
  const transport = new SSEServerTransport("/messages", res);
667
- const mcpServer = createMcpServerInstance();
668
- transports[transport.sessionId] = { transport, server: mcpServer };
669
- res.on("close", () => { mcpServer.close(); delete transports[transport.sessionId]; });
670
- await mcpServer.connect(transport);
875
+ const mcpServer = createMcpServerInstance(profile);
876
+ const sessionId = transport.sessionId;
877
+ transports[sessionId] = { transport, server: mcpServer };
878
+
879
+ const cleanup = () => {
880
+ if (!transports[sessionId]) return;
881
+ mcpServer.close().catch(() => {});
882
+ delete transports[sessionId];
883
+ };
884
+
885
+ res.on("close", cleanup);
886
+ req.on("close", cleanup);
887
+
888
+ try {
889
+ await mcpServer.connect(transport);
890
+ } catch (e) {
891
+ cleanup();
892
+ console.error("SSE connect error:", e.message);
893
+ if (!res.headersSent) res.status(500).json({ error: "Connection failed" });
894
+ }
671
895
  });
672
896
 
673
- app.post("/messages", async (req, res) => {
897
+ app.post("/messages", requireAuth, async (req, res) => {
674
898
  const sessionId = req.query.sessionId;
675
899
  const entry = transports[sessionId];
676
900
  if (entry) await entry.transport.handlePostMessage(req, res);
@@ -678,7 +902,7 @@ app.post("/messages", async (req, res) => {
678
902
  });
679
903
 
680
904
  // ---------------------------------------------------------------------------
681
- // REST API (backwards compatibility)
905
+ // REST API (backwards compatibility) — all routes require auth except /health
682
906
  // ---------------------------------------------------------------------------
683
907
 
684
908
  const jsonParser = express.json();
@@ -689,89 +913,235 @@ app.get("/health", async (req, res) => {
689
913
  try { await fs.access(OBSIDIAN_VAULT_PATH); obsidianOk = true; } catch {}
690
914
  res.json({
691
915
  status: (redisOk && obsidianOk) ? "healthy" : "degraded",
692
- redis: redisOk,
693
- obsidian: obsidianOk,
916
+ redis: redisOk, obsidian: obsidianOk,
694
917
  vault_path: OBSIDIAN_VAULT_PATH,
695
918
  bm25_docs: bm25.size,
696
919
  uptime: process.uptime()
697
920
  });
698
921
  });
699
922
 
700
- app.get("/api/tools", (req, res) => {
701
- res.json({ tools: [
923
+ app.get("/api/tools", requireAuth, (req, res) => {
924
+ const profile = req.query.profile === "slim" ? "slim" : "full";
925
+ const core = [
702
926
  "cache_set", "cache_get", "cache_delete", "redis_stats", "health_check",
703
927
  "obsidian_write_note", "obsidian_read_note", "obsidian_delete_note",
704
928
  "obsidian_search_notes", "obsidian_list_notes",
705
929
  "heurchain_search", "heurchain_export",
930
+ "proc_set", "proc_get"
931
+ ];
932
+ const infra = [
706
933
  "prometheus_get_targets", "prometheus_get_alerts", "prometheus_query",
707
934
  "grafana_get_health", "grafana_list_dashboards",
708
935
  "proxmox_get_cluster_status", "proxmox_list_nodes", "proxmox_find_vm",
709
936
  "ceph_get_health_status", "ceph_list_osd_notes",
710
937
  "network_search_docs", "network_get_runbook",
711
938
  "user_context_add_entry", "user_context_get_history", "user_context_search_history"
712
- ]});
939
+ ];
940
+ res.json({
941
+ profile,
942
+ tools: profile === "slim" ? core : [...core, ...infra],
943
+ rest: ["/api/search", "/api/buffer", "/api/proc", "/api/session-context"]
944
+ });
713
945
  });
714
946
 
715
- app.post("/api/cache", jsonParser, async (req, res) => {
947
+ app.post("/api/cache", requireAuth, jsonParser, async (req, res) => {
716
948
  const { key, value, ttl } = req.body;
717
949
  if (ttl) await redis.setEx(key, ttl, JSON.stringify(value));
718
950
  else await redis.set(key, JSON.stringify(value));
719
951
  res.json({ cached: true });
720
952
  });
721
953
 
722
- app.get("/api/cache/:key", async (req, res) => {
954
+ app.get("/api/cache/:key", requireAuth, async (req, res) => {
723
955
  const val = await redis.get(req.params.key);
724
956
  if (val) res.json({ hit: true, data: JSON.parse(val) });
725
957
  else res.json({ hit: false });
726
958
  });
727
959
 
728
- app.get("/api/stats", async (req, res) => {
960
+ app.get("/api/stats", requireAuth, async (req, res) => {
729
961
  const info = await redis.info("stats");
730
962
  res.json({ redis_info: info, bm25_docs: bm25.size });
731
963
  });
732
964
 
733
- // --- Obsidian REST Endpoints ---
734
-
735
- app.get("/api/obsidian/notes", async (req, res) => {
965
+ app.get("/api/obsidian/notes", requireAuth, async (req, res) => {
736
966
  const { key, prefix } = req.query;
737
967
  if (key) {
738
- const content = await readFromObsidian(key);
739
- if (content === null) return res.status(404).json({ found: false, key });
740
- return res.json({ found: true, key, content });
968
+ try {
969
+ const content = await readFromObsidian(key);
970
+ if (content === null) return res.status(404).json({ found: false, key });
971
+ return res.json({ found: true, key, content });
972
+ } catch (e) {
973
+ return res.status(400).json({ error: e.message.startsWith("invalid key") ? e.message : "read failed" });
974
+ }
741
975
  }
742
976
  const notes = await listObsidian(prefix);
743
977
  res.json({ count: notes.length, notes });
744
978
  });
745
979
 
746
- app.post("/api/obsidian/notes", jsonParser, async (req, res) => {
980
+ app.post("/api/obsidian/notes", requireAuth, jsonParser, async (req, res) => {
747
981
  const { key, content, metadata } = req.body;
748
982
  if (!key || content === undefined) return res.status(400).json({ error: "key and content required" });
749
983
  try {
750
984
  const filePath = await saveToObsidian(key, content, metadata);
751
985
  res.json({ stored: true, key, path: filePath });
752
986
  } catch (e) {
753
- res.status(500).json({ stored: false, error: e.message });
987
+ res.status(e.message.startsWith("invalid key") ? 400 : 500)
988
+ .json({ error: e.message.startsWith("invalid key") ? e.message : "write failed" });
754
989
  }
755
990
  });
756
991
 
757
- app.delete("/api/obsidian/notes", async (req, res) => {
992
+ app.delete("/api/obsidian/notes", requireAuth, async (req, res) => {
758
993
  const { key } = req.query;
759
994
  if (!key) return res.status(400).json({ error: "key required" });
760
- const deleted = await deleteFromObsidian(key);
761
- res.json({ deleted, key });
995
+ try {
996
+ const deleted = await deleteFromObsidian(key);
997
+ res.json({ deleted, key });
998
+ } catch (e) {
999
+ res.status(400).json({ error: e.message.startsWith("invalid key") ? e.message : "delete failed" });
1000
+ }
762
1001
  });
763
1002
 
764
- app.get("/api/obsidian/search", async (req, res) => {
1003
+ app.get("/api/obsidian/search", requireAuth, async (req, res) => {
765
1004
  const { q, limit } = req.query;
766
1005
  if (!q) return res.status(400).json({ error: "q required" });
767
- const results = await searchObsidian(q);
768
- const max = parseInt(limit) || 10;
1006
+ const max = Math.max(1, Math.min(parseInt(limit) || 10, 100));
1007
+ const results = await searchObsidian(q, null);
1008
+ res.json({ count: results.length, results: results.slice(0, max).map(r => ({ key: r.key, path: r.path, preview: r.content.substring(0, 200) })) });
1009
+ });
1010
+
1011
+ // ---------------------------------------------------------------------------
1012
+ // BM25 search REST — frictionless recall via curl/hook, no MCP tool overhead
1013
+ // ---------------------------------------------------------------------------
1014
+
1015
+ app.get("/api/search", requireAuth, async (req, res) => {
1016
+ const { q, limit, tier, minScore, namespace } = req.query;
1017
+ if (!q) return res.status(400).json({ error: "q required" });
1018
+ const results = bm25.search(q, {
1019
+ limit: Math.min(parseInt(limit) || 10, 50),
1020
+ tier: tier || "all",
1021
+ minScore: parseFloat(minScore) || 0,
1022
+ noiseFilter: true,
1023
+ namespace: namespace || null
1024
+ });
769
1025
  res.json({
770
1026
  count: results.length,
771
- results: results.slice(0, max).map(r => ({ key: r.key, path: r.path, preview: r.content.substring(0, 200) }))
1027
+ index_size: bm25.size,
1028
+ results: results.map(r => ({
1029
+ key: r.key,
1030
+ score: Math.round(r.score * 1000) / 1000,
1031
+ tier: r.tier,
1032
+ preview: (r.content || "").substring(0, 300)
1033
+ }))
772
1034
  });
773
1035
  });
774
1036
 
1037
+ // ---------------------------------------------------------------------------
1038
+ // Session buffer — ambient turn capture, POST fire-and-forget from agent hook
1039
+ // ---------------------------------------------------------------------------
1040
+
1041
+ app.post("/api/buffer", requireAuth, jsonParser, async (req, res) => {
1042
+ const { session_id, agent_name, role, content } = req.body;
1043
+ if (!session_id || !content) return res.status(400).json({ error: "session_id and content required" });
1044
+ bufferAppend(session_id, agent_name, role, content);
1045
+ res.json({ buffered: true, session_id });
1046
+ });
1047
+
1048
+ app.post("/api/buffer/flush", requireAuth, jsonParser, async (req, res) => {
1049
+ const { session_id } = req.body;
1050
+ if (!session_id) return res.status(400).json({ error: "session_id required" });
1051
+ await flushBuffer(session_id);
1052
+ res.json({ flushed: true, session_id });
1053
+ });
1054
+
1055
+ // ---------------------------------------------------------------------------
1056
+ // Procedural memory REST — stable agent preference knobs, no TTL
1057
+ // ---------------------------------------------------------------------------
1058
+
1059
+ app.post("/api/proc", requireAuth, jsonParser, async (req, res) => {
1060
+ const { agent_name, key, value } = req.body;
1061
+ if (!agent_name || !key || value === undefined) return res.status(400).json({ error: "agent_name, key, value required" });
1062
+ try {
1063
+ const rk = procKey(agent_name, key);
1064
+ await redis.set(rk, typeof value === "string" ? value : JSON.stringify(value));
1065
+ res.json({ stored: true, key: rk });
1066
+ } catch (e) {
1067
+ res.status(400).json({ error: e.message });
1068
+ }
1069
+ });
1070
+
1071
+ app.get("/api/proc/:agent", requireAuth, async (req, res) => {
1072
+ try {
1073
+ if (!PROC_KEY_RE.test(req.params.agent)) return res.status(400).json({ error: "invalid agent name" });
1074
+ res.json(await procGet(req.params.agent));
1075
+ } catch (e) {
1076
+ res.status(500).json({ error: "proc read failed" });
1077
+ }
1078
+ });
1079
+
1080
+ app.delete("/api/proc/:agent/:key", requireAuth, async (req, res) => {
1081
+ try {
1082
+ const rk = procKey(req.params.agent, req.params.key);
1083
+ const deleted = await redis.del(rk);
1084
+ res.json({ deleted: deleted > 0, key: rk });
1085
+ } catch (e) {
1086
+ res.status(400).json({ error: e.message });
1087
+ }
1088
+ });
1089
+
1090
+ // ---------------------------------------------------------------------------
1091
+ // Session-context injection — compact recall for system-prompt injection.
1092
+ // Returns proc knobs + last session summary + top BM25 hits, hard-capped at
1093
+ // SESSION_CONTEXT_TOKENS (~400 tokens). Call via hook at session start;
1094
+ // inject the JSON into system prompt. Zero MCP tool overhead.
1095
+ // ---------------------------------------------------------------------------
1096
+
1097
+ app.get("/api/session-context", requireAuth, async (req, res) => {
1098
+ const { agent, hint } = req.query;
1099
+ if (!agent) return res.status(400).json({ error: "agent required" });
1100
+ if (!PROC_KEY_RE.test(agent)) return res.status(400).json({ error: "invalid agent name" });
1101
+
1102
+ // 1. Procedural knobs
1103
+ let proc = {};
1104
+ try { proc = await procGet(agent); } catch {}
1105
+
1106
+ // 2. Last session summary — scan for most recent buffer entry or session record
1107
+ let last_session = null;
1108
+ try {
1109
+ const candidates = [];
1110
+ for await (const k of scanKeys("session:*:buffer", "string")) {
1111
+ const raw = await redis.get(k);
1112
+ if (!raw) continue;
1113
+ try {
1114
+ const turns = JSON.parse(raw);
1115
+ const agentTurns = turns.filter(t => t.agent === agent);
1116
+ if (agentTurns.length === 0) continue;
1117
+ const last = agentTurns[agentTurns.length - 1];
1118
+ candidates.push({ ts: last.ts, summary: last.content.substring(0, 200) });
1119
+ } catch {}
1120
+ }
1121
+ if (candidates.length > 0) {
1122
+ candidates.sort((a, b) => b.ts.localeCompare(a.ts));
1123
+ last_session = candidates[0].summary;
1124
+ }
1125
+ } catch {}
1126
+
1127
+ // 3. BM25 relevant results, token-budgeted
1128
+ let relevant = [];
1129
+ if (hint) {
1130
+ try {
1131
+ const hits = bm25.search(hint, { limit: 15, minScore: 0.5, noiseFilter: true });
1132
+ let budget = SESSION_CONTEXT_TOKENS - JSON.stringify(proc).length / 4 - 50;
1133
+ for (const r of hits) {
1134
+ const excerpt = (r.content || "").substring(0, 200);
1135
+ budget -= Math.ceil((r.key.length + excerpt.length) / 4);
1136
+ if (budget < 0) break;
1137
+ relevant.push({ key: r.key, score: Math.round(r.score * 100) / 100, excerpt });
1138
+ }
1139
+ } catch {}
1140
+ }
1141
+
1142
+ res.json({ proc, last_session, relevant });
1143
+ });
1144
+
775
1145
  // ---------------------------------------------------------------------------
776
1146
  // Startup
777
1147
  // ---------------------------------------------------------------------------
@@ -779,8 +1149,13 @@ app.get("/api/obsidian/search", async (req, res) => {
779
1149
  (async () => {
780
1150
  await redis.connect();
781
1151
  await buildIndex();
782
- // Rebuild index hourly to catch external writes
783
- setInterval(buildIndex, 60 * 60 * 1000);
1152
+ setInterval(buildIndex, 60 * 60 * 1000); // hourly BM25 rebuild
1153
+ // Flush all active session buffers on heartbeat
1154
+ setInterval(async () => {
1155
+ for (const sessionId of sessionBuffers.keys()) {
1156
+ await flushBuffer(sessionId).catch(() => {});
1157
+ }
1158
+ }, BUFFER_FLUSH_MS);
784
1159
  const port = parseInt(process.env.MCP_PORT, 10) || 3010;
785
- app.listen(port, () => console.log(`HeurChain MCP v1.2.0 listening on port ${port} — ${bm25.size} docs indexed`));
1160
+ app.listen(port, () => console.log(`HeurChain MCP v1.3.0 listening on port ${port} — ${bm25.size} docs indexed`));
786
1161
  })();