mcp-memory-bucket 0.7.1 → 0.7.4

package/dist/src/channels/search.js

@@ -0,0 +1,40 @@
+import { distance } from 'fastest-levenshtein';
+/**
+ * Mirrors mcp-tenant-lib's channel-search.ts — duplicated rather than
+ * imported since this package has no other dependency on mcp-tenant-lib.
+ * See that file for the full design rationale behind the stem/typo split.
+ */
+function words(name) {
+    return name.split(/[_-]+/).filter(Boolean);
+}
+function typoScore(a, b) {
+    const maxLen = Math.max(a.length, b.length);
+    if (maxLen === 0)
+        return 1;
+    return 1 - distance(a, b) / maxLen;
+}
+function stemScore(a, b) {
+    const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
+    if (shorter.length < 3 || !longer.startsWith(shorter))
+        return 0;
+    return shorter.length / longer.length;
+}
+function wordScore(query, word) {
+    const stem = stemScore(query, word);
+    if (Math.abs(query.length - word.length) > 2)
+        return stem;
+    return Math.max(stem, typoScore(query, word));
+}
+export function scoreChannelMatch(query, candidate) {
+    const q = query.toLowerCase();
+    const c = candidate.toLowerCase();
+    const whole = Math.max(typoScore(q, c), stemScore(q, c));
+    const perWord = words(c).map((w) => wordScore(q, w));
+    return Math.max(whole, ...perWord, 0);
+}
+export function findChannelMatches(query, candidates, minScore = 0.5) {
+    return candidates
+        .map((name) => ({ name, score: scoreChannelMatch(query, name) }))
+        .filter((m) => m.score >= minScore)
+        .sort((a, b) => b.score - a.score);
+}

package/dist/src/channels/store.js

@@ -0,0 +1,53 @@
+/**
+ * URL-safe slug rule for agent-chosen channel names: letters, digits,
+ * underscore, hyphen only. Mirrors mcp-tenant-lib's isValidChannelName —
+ * duplicated rather than imported since this package has no other
+ * dependency on mcp-tenant-lib and one shared regex isn't worth adding one.
+ */
+export function isValidChannelName(name) {
+    return /^[a-zA-Z0-9_-]+$/.test(name);
+}
+const channels = new Map();
+/** Auto-vivifies on first reference, same as mcp-tenant-lib's getOrCreateTenant. */
+export function getOrCreateChannel(name) {
+    let channel = channels.get(name);
+    if (!channel) {
+        channel = { name, content: '', lastActivityAt: Date.now() };
+        channels.set(name, channel);
+    }
+    return channel;
+}
+export function getChannel(name) {
+    return channels.get(name);
+}
+export function listChannels() {
+    return [...channels.values()];
+}
+function envMs(name, defaultMs) {
+    const raw = process.env[name];
+    if (!raw)
+        return defaultMs;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : defaultMs;
+}
+// Long-lived by design: a cross-agent discussion may span much longer gaps
+// between contributions than a live form-fill session (mcp-tenant-lib's
+// tenants default to a 30-minute idle timeout) — default here is ~24h.
+const MEMORY_CHANNEL_IDLE_TIMEOUT_MS = envMs('MEMORY_CHANNEL_IDLE_TIMEOUT_MS', 24 * 60 * 60 * 1000);
+const MEMORY_CHANNEL_SWEEP_INTERVAL_MS = envMs('MEMORY_CHANNEL_SWEEP_INTERVAL_MS', 30 * 60 * 1000);
+export function startChannelSweep(onSweep) {
+    const sweepInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [name, channel] of channels) {
+            if (now - channel.lastActivityAt > MEMORY_CHANNEL_IDLE_TIMEOUT_MS) {
+                onSweep(name);
+                channels.delete(name);
+            }
+        }
+    }, MEMORY_CHANNEL_SWEEP_INTERVAL_MS);
+    sweepInterval.unref();
+    return sweepInterval;
+}
+// Test-only escape hatch, mirroring how mcp-tenant-lib's tests reach into
+// its module-level `tenants` Map directly (see tenant.ts's `tenants` export).
+export { channels };

package/dist/src/channels/tools.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { getOrCreateChannel, getChannel, listChannels, isValidChannelName } from './store.js';
+import { findChannelMatches } from './search.js';
+export function registerMemoryChannelTools(mcp) {
+    mcp.tool('memory_channel_read', 'Reads a memory channel: ephemeral, in-memory-only text shared live between agent sessions on this server ' +
+        '— distinct from persisted memory_* docs (never on disk, never indexed by search). Empty content if the ' +
+        'channel doesn\'t exist yet — reading never creates one (memory_channel_post does). ' +
+        'IMPORTANT: empty is ambiguous ("nothing posted yet" vs "wrong name" — matching is EXACT, no fuzz). Before ' +
+        'saying a discussion doesn\'t exist, call memory_channel_find or list_memory_channels to check for a ' +
+        'similarly-named channel (e.g. "pets" vs "pet_discussion").', { channel: z.string().describe('Channel name. Letters/digits/underscore/hyphen only.') }, async ({ channel }) => {
+        if (!isValidChannelName(channel)) {
+            return {
+                content: [{ type: 'text', text: `Error: "${channel}" is not a valid channel name — use only letters, digits, underscore, and hyphen.` }],
+                isError: true,
+            };
+        }
+        const existing = getChannel(channel);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ content: existing?.content ?? '', lastActivityAt: existing?.lastActivityAt ?? null }, null, 2) }],
+        };
+    });
+    mcp.tool('memory_channel_post', 'Writes to a memory channel, replacing its content (last-write-wins) — auto-creates it if missing. ' +
+        'Ephemeral, in-memory only: never on disk, never indexed by search, gone on restart or after a long idle ' +
+        'period. This ALWAYS replaces content — "append to a discussion" vs "hand over a fresh summary" is your ' +
+        'choice, not a mode: to preserve history, read first then post the old content plus your addition ' +
+        'concatenated; to hand over cleanly, just post fresh content. Names must match EXACTLY — if continuing an ' +
+        'existing discussion, double-check via memory_channel_find/list_memory_channels first, or a typo silently ' +
+        'starts an unrelated empty channel instead of erroring.', {
+        channel: z.string().describe('Channel name. Letters/digits/underscore/hyphen only.'),
+        content: z.string().describe('The full new content of the channel — replaces whatever was there before.'),
+    }, async ({ channel, content }) => {
+        if (!isValidChannelName(channel)) {
+            return {
+                content: [{ type: 'text', text: `Error: "${channel}" is not a valid channel name — use only letters, digits, underscore, and hyphen.` }],
+                isError: true,
+            };
+        }
+        const ch = getOrCreateChannel(channel);
+        ch.content = content;
+        ch.lastActivityAt = Date.now();
+        return {
+            content: [{ type: 'text', text: `Posted ${content.length} character(s) to channel "${channel}".` }],
+        };
+    });
+    mcp.tool('list_memory_channels', 'Lists every memory channel currently live on this server, with when each was last written or read. Use ' +
+        'this to discover an existing channel by name before calling memory_channel_read/post on it.', {}, async () => {
+        const channels = listChannels().map((c) => ({ name: c.name, lastActivityAt: c.lastActivityAt }));
+        return { content: [{ type: 'text', text: JSON.stringify(channels, null, 2) }] };
+    });
+    mcp.tool('memory_channel_find', 'Fuzzy-searches existing memory channel names for a loose query (e.g. "the pets discussion") instead of ' +
+        'guessing at memory_channel_read/post or eyeballing list_memory_channels yourself. Matches whole-name ' +
+        'similarity (typos) and per-word similarity on underscore/hyphen-split parts (e.g. "pets" matches ' +
+        '"pet_food_memory" via "pet"). Returns ranked {name, score} (0..1, higher better), empty if nothing scores ' +
+        'above threshold. Read-only — does not read or create anything. Call memory_channel_read yourself on the ' +
+        'right result; if scores are close, ask the user to disambiguate rather than guessing.', { query: z.string().describe('Loose/partial channel name or topic to search for, e.g. "pets".') }, async ({ query }) => {
+        const matches = findChannelMatches(query, listChannels().map((c) => c.name));
+        return { content: [{ type: 'text', text: JSON.stringify(matches, null, 2) }] };
+    });
+}

package/dist/src/server.js

@@ -17,6 +17,8 @@ import { registerAttachmentTools } from './attachments/tools.js';
 import { AttachmentRepository } from './attachments/repository.js';
 import { buildWebRouter } from './web/routes.js';
 import { registerUiTool } from './web/ui-tool.js';
+import { registerMemoryChannelTools } from './channels/tools.js';
+import { startChannelSweep } from './channels/store.js';
 // server.ts is rebuilt from `buildMcpServer()` on every /mcp request (see below),
 // so tool schemas (which conditionally include `folder` based on folder count) always
 // reflect the current folders — no restart needed after an add/remove-folder call.
@@ -52,7 +54,7 @@ if (config.skillFolders.length === 0 && config.memoryFolders.length === 0) {
 // this server — surfaced both in serverInfo.description and instructions so
 // clients that expose either to the model can make that association.
 const SERVER_DESCRIPTION = 'Also known as "memory bucket", "mem bucket", or "skill bucket" — if the user refers to this server by any of those names, they mean this one.';
-const SERVER_INSTRUCTIONS = `${SERVER_DESCRIPTION} Exposes skill_* (reusable coding patterns, stored as agentskills.io-standard SKILL.md folders) and memory_* (point-in-time working context — plans, specs, SQL, session summaries — looked up by key) tools, plus shared relocate/bucket_search/bucket_*_folder tools. Use skill_search/memory_search/bucket_search for full-text search over body content (not just metadata) — bucket_search when you don't know which bucket something landed in. Use bucket_list_folders to see what named source directories (folders) are configured before passing a folder argument elsewhere, and bucket_create_folder/bucket_delete_folder to register or unregister one. Most operations have a _bulk_ variant (bulk_get/bulk_create/bulk_update/bulk_delete/bulk_rename, relocate_bulk) that take a list and return per-item success/failure — prefer these over looping single calls when acting on more than one item. A memory doc's key can be changed in place via memory_update(id, key: ...) — no separate rename tool needed. Before calling any *_create/*_update/relocate tool, call skill_get("memory-bucket-authoring") first to learn the exact frontmatter schema — don't guess the shape.`;
+const SERVER_INSTRUCTIONS = `${SERVER_DESCRIPTION} Exposes skill_* (reusable coding patterns, stored as agentskills.io-standard SKILL.md folders) and memory_* (point-in-time working context — plans, specs, SQL, session summaries — looked up by key) tools, plus shared relocate/bucket_search/bucket_*_folder tools. Use skill_search/memory_search/bucket_search for full-text search over body content (not just metadata) — bucket_search when you don't know which bucket something landed in. Use bucket_list_folders to see what named source directories (folders) are configured before passing a folder argument elsewhere, and bucket_create_folder/bucket_delete_folder to register or unregister one. Most operations have a _bulk_ variant (bulk_get/bulk_create/bulk_update/bulk_delete/bulk_rename, relocate_bulk) that take a list and return per-item success/failure — prefer these over looping single calls when acting on more than one item. A memory doc's key can be changed in place via memory_update(id, key: ...) — no separate rename tool needed. Before calling any *_create/*_update/relocate tool, call skill_get("memory-bucket-authoring") first to learn the exact frontmatter schema — don't guess the shape. Also exposes memory_channel_read/memory_channel_post/list_memory_channels — a SEPARATE, ephemeral in-memory layer for live cross-agent coordination (a shared scratchpad/discussion channel by name), never written to disk and never indexed by memory_search/bucket_search; do not confuse these with the persisted memory_* docs above.`;
 function buildMcpServer() {
     const server = new McpServer({ name: 'memory-bucket', version: '0.1.0', description: SERVER_DESCRIPTION }, { capabilities: {}, instructions: SERVER_INSTRUCTIONS });
     registerSkillTools(server, skillRepo);
@@ -62,8 +64,10 @@ function buildMcpServer() {
     registerBucketFolderTools(server, config, skillRepo, memoryRepo, db, skillSpec, memorySpec);
     registerAttachmentTools(server, attachmentRepo);
     registerUiTool(server, PORT);
+    registerMemoryChannelTools(server);
     return server;
 }
+startChannelSweep((name) => console.error(`[memory-bucket] sweeping idle memory channel: ${name}`));
 const app = express();
 app.use(express.json());
 app.use(buildWebRouter(db, config, skillRepo, memoryRepo, skillSpec, memorySpec));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-memory-bucket",
-  "version": "0.7.1",
+  "version": "0.7.4",
   "type": "module",
   "description": "MCP server exposing skill_* (reusable coding patterns) and memory_* (point-in-time working context) tools over a markdown+frontmatter source, cached into SQLite at runtime.",
   "repository": {
@@ -39,6 +39,7 @@
     "better-sqlite3": "^11.8.0",
     "chokidar": "^4.0.0",
     "express": "^4.21.0",
+    "fastest-levenshtein": "^1.0.16",
     "gray-matter": "^4.0.3",
     "lit": "^3.3.3",
     "marked": "^18.0.10",