v1.0.2: Qdrant timeout, webhook warnings, npm metadata, docs polish

- Add configurable Qdrant request timeout (QDRANT_TIMEOUT_MS, default 10s)
- Surface structured store failures as warnings in webhook response
- Expand npm keywords and description for discoverability
- Add brain_consolidate/brain_stats examples and troubleshooting to README
- Add CI step to validate MCP server entrypoint
- Add CHANGELOG.md shipped with npm package
- Align version across package.json and MCP server registration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Skiipy11

.github/workflows/ci.yml

@@ -25,3 +25,8 @@ jobs:
 
       - name: Run tests
         run: cd api && npm test
+
+      - name: Validate MCP server entrypoint
+        run: cd mcp-server && timeout 5 node src/index.js 2>&1 || true
+        env:
+          BRAIN_API_KEY: test-key

api/src/routes/webhook.js

@@ -78,6 +78,7 @@ webhookRouter.post('/n8n', async (req, res) => {
     });
 
     // Store as event in structured database
+    const warnings = [];
     if (isStoreAvailable()) try {
       await createEvent({
         content,
@@ -91,6 +92,7 @@ webhookRouter.post('/n8n', async (req, res) => {
       });
     } catch (e) {
       console.error('[webhook:n8n] Store write failed:', e.message);
+      warnings.push(`Structured store write failed: ${e.message}`);
     }
 
     // If workflow errored, also update status
@@ -104,10 +106,13 @@ webhookRouter.post('/n8n', async (req, res) => {
         });
       } catch (e) {
         console.error('[webhook:n8n] Status update failed:', e.message);
+        warnings.push(`Status update failed: ${e.message}`);
       }
     }
 
-    res.status(201).json({ id: pointId, content });
+    const response = { id: pointId, content };
+    if (warnings.length > 0) response.warnings = warnings;
+    res.status(201).json(response);
   } catch (err) {
     console.error('[webhook:n8n] Error:', err.message);
     res.status(500).json({ error: err.message });

api/src/services/qdrant.js

@@ -8,16 +8,29 @@ const COLLECTION = 'shared_memories';
 const DECAY_FACTOR = parseFloat(process.env.DECAY_FACTOR) || 0.98;
 const DECAY_TYPES = ['fact', 'status']; // events and decisions are historical — don't decay
 
+const QDRANT_TIMEOUT_MS = parseInt(process.env.QDRANT_TIMEOUT_MS) || 10000;
+
 async function qdrantRequest(path, options = {}) {
   const headers = { 'Content-Type': 'application/json' };
   if (QDRANT_API_KEY) headers['api-key'] = QDRANT_API_KEY;
 
-  const res = await fetch(`${QDRANT_URL}${path}`, { ...options, headers: { ...headers, ...options.headers } });
-  if (!res.ok) {
-    const body = await res.text();
-    throw new Error(`Qdrant ${options.method || 'GET'} ${path} failed: ${res.status} ${body}`);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), QDRANT_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${QDRANT_URL}${path}`, { ...options, headers: { ...headers, ...options.headers }, signal: controller.signal });
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Qdrant ${options.method || 'GET'} ${path} failed: ${res.status} ${body}`);
+    }
+    return res.json();
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      throw new Error(`Qdrant request timed out after ${QDRANT_TIMEOUT_MS}ms: ${options.method || 'GET'} ${path}`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeout);
   }
-  return res.json();
 }
 
 export async function initQdrant() {

mcp-server/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 1.0.2
+
+- Expanded npm keywords for better discoverability
+- Improved package description
+- Added Qdrant request timeout (default 10s, configurable via `QDRANT_TIMEOUT_MS`)
+- Webhook now surfaces structured store warnings instead of silently swallowing errors
+- Added troubleshooting section to README
+- Added `brain_consolidate` and `brain_stats` usage examples to README
+- CI now validates MCP server entrypoint
+- Version alignment between package.json and MCP server registration
+
+## 1.0.1
+
+- Initial npm publish with README
+
+## 1.0.0
+
+- Initial release

mcp-server/README.md

@@ -96,6 +96,43 @@ Stores a fact that any other agent (n8n, OpenClaw, Cursor) can retrieve later.
 | `status` | Update-in-place by `subject` | Current state of a system or workflow |
 | `decision` | Append-only | Choices made and why |
 
+## More Usage Examples
+
+Check memory health:
+
+```
+brain_stats
+```
+
+Returns total count, active vs superseded, consolidated, and breakdown by type.
+
+Trigger memory consolidation:
+
+```
+brain_consolidate action="run"
+```
+
+An LLM analyzes unconsolidated memories — merging duplicates, flagging contradictions, discovering connections, and generating insights.
+
+Check consolidation status:
+
+```
+brain_consolidate action="status"
+```
+
+Returns whether consolidation is running, when it last ran, and which LLM is configured.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `BRAIN_API_KEY environment variable is required` | Set `BRAIN_API_KEY` in your MCP config `env` block |
+| `API ... 401 Unauthorized` | API key doesn't match the one in your Memory API `.env` |
+| `API ... ECONNREFUSED` | Memory API isn't running — run `docker compose up -d` |
+| `fetch failed` / timeout | Check `BRAIN_API_URL` points to the correct host and port |
+| Tool calls return empty results | Verify Qdrant is running and has data — use `brain_stats` to check |
+| `Qdrant request timed out` | Qdrant is slow or unreachable — check connectivity, increase `QDRANT_TIMEOUT_MS` |
+
 ## Full Documentation
 
 See the [main repository](https://github.com/ZenSystemAI/multi-agent-memory) for the complete API reference, adapter docs (Bash CLI, n8n, OpenClaw), deployment guide, and architecture overview.

mcp-server/package.json

@@ -1,26 +1,38 @@
 {
   "name": "@zensystemai/multi-agent-memory-mcp",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
-  "description": "MCP server for Multi-Agent Memory - cross-agent persistent memory system",
+  "description": "Persistent semantic memory across AI agents — credential scrubbing, auto-consolidation, multi-backend storage (Qdrant + SQLite/Postgres/Baserow)",
   "main": "src/index.js",
   "bin": {
     "multi-agent-memory-mcp": "src/index.js"
   },
   "files": [
-    "src/"
+    "src/",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "start": "node src/index.js"
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "memory",
     "ai",
     "agent",
     "multi-agent",
-    "llm"
+    "llm",
+    "semantic-search",
+    "persistent-memory",
+    "cross-agent",
+    "knowledge-base",
+    "qdrant",
+    "embeddings",
+    "credential-scrubbing"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "author": "ZenSystem",
   "license": "MIT",
   "repository": {

mcp-server/src/index.js

@@ -36,7 +36,7 @@ async function apiRequest(path, options = {}) {
 }
 
 const server = new Server(
-  { name: 'shared-brain', version: '1.0.0' },
+  { name: 'shared-brain', version: '1.0.2' },
   { capabilities: { tools: {} } }
 );