memorandum-mcp 0.1.0

package/dist/types.js

@@ -0,0 +1,88 @@
+import safeRegex from 'safe-regex2';
+import { z } from 'zod';
+// ============================================================================
+// Constants
+// ============================================================================
+export const KEY_MAX_LEN = 256;
+export const NAMESPACE_MAX_LEN = 64;
+export const NAMESPACE_REGEX = /^[a-z0-9\-_.]+$/;
+export const DEFAULT_NAMESPACE = 'default';
+export const DEFAULT_LIST_LIMIT = 50;
+export const DEFAULT_SEARCH_LIMIT = 20;
+// ============================================================================
+// Display Schemas (for LLM tool description - all fields optional)
+// ============================================================================
+export const MemoryWriteDisplaySchema = z.object({
+    key: z.string().optional().describe('Unique identifier for the fact (1-256 characters)'),
+    value: z.unknown().optional().describe('The data to store (any JSON-serializable value)'),
+    namespace: z.string().optional().describe(`Namespace to organize facts (default: "${DEFAULT_NAMESPACE}", 1-64 chars, lowercase alphanumeric with -_.)`),
+    ttl_seconds: z.number().optional().describe('Optional time-to-live in seconds (positive integer)'),
+});
+export const MemoryReadDisplaySchema = z.object({
+    key: z.string().optional().describe('The key of the fact to retrieve'),
+    namespace: z.string().optional().describe(`Namespace to read from (default: "${DEFAULT_NAMESPACE}")`),
+});
+export const MemoryManageDisplaySchema = z.object({
+    action: z.string().optional().describe('Action to perform: "delete", "delete_namespace", "list", "search", "namespaces", "export", "import", "sync"'),
+    key: z.string().optional().describe('Key to delete (required for "delete" action)'),
+    namespace: z.string().optional().describe('Namespace to operate on (various actions)'),
+    pattern: z.string().optional().describe('Glob pattern to filter keys, e.g. "server-*" (for "list" action)'),
+    limit: z.number().optional().describe(`Maximum number of results (default: ${DEFAULT_LIST_LIMIT} for list, ${DEFAULT_SEARCH_LIMIT} for search)`),
+    include_values: z.boolean().optional().describe('Include fact values in list results (default: false)'),
+    include_stats: z.boolean().optional().describe('Include memory statistics in list results (default: false)'),
+    query: z.string().optional().describe('Search query string (required for "search" action)'),
+    data: z.string().optional().describe('JSON string to import (required for "import" action)'),
+    merge: z.boolean().optional().describe('Merge imported data with existing facts (default: true, for "import" action)'),
+});
+// ============================================================================
+// Input Schemas (for runtime validation - strict)
+// ============================================================================
+const namespaceField = z
+    .string()
+    .min(1, 'Namespace must not be empty')
+    .max(NAMESPACE_MAX_LEN, `Namespace must not exceed ${NAMESPACE_MAX_LEN} characters`)
+    .regex(NAMESPACE_REGEX, 'Namespace must contain only lowercase letters, numbers, hyphens, underscores, and dots');
+export const MemoryWriteInputSchema = z.strictObject({
+    key: z.string().min(1, 'Key must not be empty').max(KEY_MAX_LEN, `Key must not exceed ${KEY_MAX_LEN} characters`),
+    value: z.unknown(),
+    namespace: namespaceField.default(DEFAULT_NAMESPACE),
+    ttl_seconds: z.number().int('TTL must be an integer').positive('TTL must be positive').optional(),
+});
+export const MemoryReadInputSchema = z.strictObject({
+    key: z.string().min(1, 'Key must not be empty').max(KEY_MAX_LEN, `Key must not exceed ${KEY_MAX_LEN} characters`),
+    namespace: namespaceField.default(DEFAULT_NAMESPACE),
+});
+export const MemoryManageInputSchema = z.discriminatedUnion('action', [
+    z.strictObject({
+        action: z.literal('delete'),
+        key: z.string().min(1).max(KEY_MAX_LEN),
+        namespace: namespaceField.default(DEFAULT_NAMESPACE),
+    }),
+    z.strictObject({
+        action: z.literal('delete_namespace'),
+        namespace: namespaceField,
+    }),
+    z.strictObject({
+        action: z.literal('list'),
+        namespace: namespaceField.optional(),
+        pattern: z.string().optional(),
+        limit: z.number().int().positive().default(DEFAULT_LIST_LIMIT),
+        include_values: z.boolean().default(false),
+        include_stats: z.boolean().default(false),
+    }),
+    z.strictObject({
+        action: z.literal('search'),
+        query: z.string().min(1, 'Search query must not be empty').refine((val) => safeRegex(val), 'Search query contains unsafe regex pattern (potential ReDoS)'),
+        namespace: namespaceField.optional(),
+        limit: z.number().int().positive().default(DEFAULT_SEARCH_LIMIT),
+    }),
+    z.strictObject({ action: z.literal('namespaces') }),
+    z.strictObject({ action: z.literal('export') }),
+    z.strictObject({
+        action: z.literal('import'),
+        data: z.string().min(1, 'Import data must not be empty'),
+        merge: z.boolean().default(true),
+    }),
+    z.strictObject({ action: z.literal('sync') }),
+]);
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/vector-store.d.ts

@@ -0,0 +1,85 @@
+import type { Logger } from 'pino';
+import type { VectorEntry, SearchResult, SearchFilterOptions, EmbeddingFailureRecord } from './semantic-types.js';
+/**
+ * Persisted in-memory vector store that supports cosine-similarity search,
+ * atomic saves, and failure tracking for embedding retries.
+ */
+export declare class VectorStore {
+    private readonly indexPath;
+    private readonly modelId;
+    private dimensions;
+    private readonly logger;
+    private entries;
+    private storedModelId;
+    private failedEmbeddings;
+    private dirty;
+    /**
+     * @param indexPath - File path for the persisted JSON vector index.
+     * @param modelId - Identifier of the embedding model producing the vectors.
+     * @param dimensions - Expected dimensionality of embedding vectors.
+     * @param logger - Pino logger instance.
+     */
+    constructor(indexPath: string, modelId: string, dimensions: number, logger: Logger);
+    /** Loads the vector index from disk, or starts with an empty index if the file is missing or corrupt. */
+    load(): void;
+    /**
+     * Atomically persists the vector index to disk via a temp-file rename.
+     * Skips the write if nothing has changed, and refuses to overwrite a
+     * non-empty file on disk with an empty in-memory index.
+     * @returns True if the file was written, false otherwise.
+     */
+    save(): Promise<boolean>;
+    /**
+     * Inserts or updates a vector entry by id.
+     * @param entry - The vector entry to upsert.
+     */
+    upsert(entry: VectorEntry): void;
+    /**
+     * Removes a vector entry by id.
+     * @param id - The entry identifier.
+     * @returns True if the entry was found and removed.
+     */
+    remove(id: string): boolean;
+    /**
+     * Replaces all entries in the store with the provided array.
+     * @param entries - The new set of vector entries.
+     */
+    rebuild(entries: VectorEntry[]): void;
+    /**
+     * Searches for the most similar entries using cosine similarity.
+     * @param queryVector - The query embedding vector.
+     * @param options - Optional filters and limits for the search.
+     * @returns Matching results sorted by descending similarity score.
+     */
+    query(queryVector: number[], options?: SearchFilterOptions): SearchResult[];
+    /** The number of vector entries currently stored. */
+    get entryCount(): number;
+    /** Returns a read-only view of all stored vector entries. */
+    allEntries(): ReadonlyArray<VectorEntry>;
+    /** Updates the expected embedding dimensions (e.g. after auto-detection). */
+    setDimensions(n: number): void;
+    /** The embedding model id configured for this store. */
+    get currentModelId(): string;
+    /** The model id stored in the persisted index, or null if not yet saved. */
+    get indexModelId(): string | null;
+    /** Returns the current map of failed embedding records. */
+    getFailedEmbeddings(): Record<string, EmbeddingFailureRecord>;
+    /**
+     * Replaces the entire failed-embeddings map (e.g. during reindex reset).
+     * @param records - The new failure records to store.
+     */
+    setFailedEmbeddings(records: Record<string, EmbeddingFailureRecord>): void;
+    /**
+     * Removes a failure record for the given id, if one exists.
+     * @param id - The entry identifier whose failure record should be cleared.
+     */
+    clearFailure(id: string): void;
+    /**
+     * Records or increments a failure for a given entry. Marks it as permanently
+     * "failed" once the retry count reaches maxRetries.
+     * @param id - The entry identifier that failed.
+     * @param error - The error message from the failed attempt.
+     * @param maxRetries - Maximum retries before marking as permanently failed.
+     */
+    recordFailure(id: string, error: string, maxRetries: number): void;
+}

package/dist/vector-store.js

@@ -0,0 +1,241 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { writeFile, rename, mkdir, access } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { VECTOR_INDEX_VERSION, DEFAULT_SEARCH_LIMIT, DEFAULT_SEARCH_THRESHOLD } from './semantic-types.js';
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0, normA = 0, normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom === 0 ? 0 : dot / denom;
+}
+/**
+ * Persisted in-memory vector store that supports cosine-similarity search,
+ * atomic saves, and failure tracking for embedding retries.
+ */
+export class VectorStore {
+    indexPath;
+    modelId;
+    dimensions;
+    logger;
+    entries = [];
+    storedModelId = null;
+    failedEmbeddings = {};
+    dirty = false;
+    /**
+     * @param indexPath - File path for the persisted JSON vector index.
+     * @param modelId - Identifier of the embedding model producing the vectors.
+     * @param dimensions - Expected dimensionality of embedding vectors.
+     * @param logger - Pino logger instance.
+     */
+    constructor(indexPath, modelId, dimensions, logger) {
+        this.indexPath = indexPath;
+        this.modelId = modelId;
+        this.dimensions = dimensions;
+        this.logger = logger;
+    }
+    /** Loads the vector index from disk, or starts with an empty index if the file is missing or corrupt. */
+    load() {
+        if (!existsSync(this.indexPath)) {
+            this.entries = [];
+            this.storedModelId = null;
+            return;
+        }
+        try {
+            const raw = readFileSync(this.indexPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null || !Array.isArray(parsed.entries)) {
+                throw new Error('Invalid vector index structure');
+            }
+            this.entries = parsed.entries;
+            this.storedModelId = parsed.modelId ?? null;
+            const rawFailed = parsed.failedEmbeddings;
+            this.failedEmbeddings = (rawFailed != null && typeof rawFailed === 'object' && !Array.isArray(rawFailed))
+                ? rawFailed : {};
+            this.dirty = false;
+            this.logger.debug({ entries: this.entries.length, modelId: this.storedModelId }, 'Vector index loaded');
+        }
+        catch (err) {
+            this.logger.warn({ error: err instanceof Error ? err.message : String(err) }, 'Failed to parse vector index, starting empty');
+            this.entries = [];
+            this.storedModelId = null;
+        }
+    }
+    /**
+     * Atomically persists the vector index to disk via a temp-file rename.
+     * Skips the write if nothing has changed, and refuses to overwrite a
+     * non-empty file on disk with an empty in-memory index.
+     * @returns True if the file was written, false otherwise.
+     */
+    async save() {
+        if (!this.dirty)
+            return false;
+        if (this.entries.length === 0 && existsSync(this.indexPath)) {
+            try {
+                const diskRaw = readFileSync(this.indexPath, 'utf-8');
+                const diskIndex = JSON.parse(diskRaw);
+                if (diskIndex && Array.isArray(diskIndex.entries) && diskIndex.entries.length > 0) {
+                    this.logger.warn('Skipping vector index save: disk has data but in-memory is empty');
+                    return false;
+                }
+            }
+            catch { /* proceed */ }
+        }
+        const index = {
+            version: VECTOR_INDEX_VERSION,
+            modelId: this.modelId,
+            dimensions: this.dimensions,
+            entries: this.entries,
+            updatedAt: Date.now(),
+            failedEmbeddings: this.failedEmbeddings,
+        };
+        try {
+            const dir = dirname(this.indexPath);
+            try {
+                await access(dir);
+            }
+            catch {
+                await mkdir(dir, { recursive: true });
+            }
+            const data = JSON.stringify(index);
+            const tmpPath = `${this.indexPath}.${process.pid}-${Date.now()}.tmp`;
+            await writeFile(tmpPath, data, 'utf-8');
+            await rename(tmpPath, this.indexPath);
+            this.dirty = false;
+            this.storedModelId = this.modelId;
+            this.logger.debug({ entries: this.entries.length }, 'Vector index saved');
+            return true;
+        }
+        catch (err) {
+            this.logger.error({ error: err instanceof Error ? err.message : String(err) }, 'Failed to save vector index');
+            return false;
+        }
+    }
+    /**
+     * Inserts or updates a vector entry by id.
+     * @param entry - The vector entry to upsert.
+     */
+    upsert(entry) {
+        const idx = this.entries.findIndex((e) => e.id === entry.id);
+        if (idx !== -1) {
+            this.entries[idx] = entry;
+        }
+        else {
+            this.entries.push(entry);
+        }
+        this.dirty = true;
+    }
+    /**
+     * Removes a vector entry by id.
+     * @param id - The entry identifier.
+     * @returns True if the entry was found and removed.
+     */
+    remove(id) {
+        const idx = this.entries.findIndex((e) => e.id === id);
+        if (idx === -1)
+            return false;
+        this.entries.splice(idx, 1);
+        this.dirty = true;
+        return true;
+    }
+    /**
+     * Replaces all entries in the store with the provided array.
+     * @param entries - The new set of vector entries.
+     */
+    rebuild(entries) {
+        this.entries = entries;
+        this.dirty = true;
+    }
+    /**
+     * Searches for the most similar entries using cosine similarity.
+     * @param queryVector - The query embedding vector.
+     * @param options - Optional filters and limits for the search.
+     * @returns Matching results sorted by descending similarity score.
+     */
+    query(queryVector, options) {
+        const limit = options?.limit ?? DEFAULT_SEARCH_LIMIT;
+        const threshold = options?.threshold ?? DEFAULT_SEARCH_THRESHOLD;
+        let candidates = this.entries;
+        if (options?.source === 'facts')
+            candidates = candidates.filter((e) => e.source === 'fact');
+        else if (options?.source === 'documents')
+            candidates = candidates.filter((e) => e.source === 'document');
+        if (options?.namespace !== undefined) {
+            candidates = candidates.filter((e) => e.source === 'fact' && e.metadata.namespace === options.namespace);
+        }
+        if (options?.tag !== undefined) {
+            candidates = candidates.filter((e) => e.source === 'document' && e.metadata.tags.includes(options.tag));
+        }
+        if (options?.topic !== undefined) {
+            candidates = candidates.filter((e) => e.source === 'document' && e.metadata.topic === options.topic);
+        }
+        if (options?.content_type !== undefined) {
+            candidates = candidates.filter((e) => e.source === 'document' && e.metadata.contentType === options.content_type);
+        }
+        const scored = [];
+        for (const entry of candidates) {
+            if (queryVector.length !== entry.vector.length)
+                continue;
+            const score = cosineSimilarity(queryVector, entry.vector);
+            if (score >= threshold) {
+                scored.push({ source: entry.source, id: entry.id, score, metadata: entry.metadata });
+            }
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, limit);
+    }
+    /** The number of vector entries currently stored. */
+    get entryCount() { return this.entries.length; }
+    /** Returns a read-only view of all stored vector entries. */
+    allEntries() { return this.entries; }
+    /** Updates the expected embedding dimensions (e.g. after auto-detection). */
+    setDimensions(n) { this.dimensions = n; }
+    /** The embedding model id configured for this store. */
+    get currentModelId() { return this.modelId; }
+    /** The model id stored in the persisted index, or null if not yet saved. */
+    get indexModelId() { return this.storedModelId; }
+    /** Returns the current map of failed embedding records. */
+    getFailedEmbeddings() { return this.failedEmbeddings; }
+    /**
+     * Replaces the entire failed-embeddings map (e.g. during reindex reset).
+     * @param records - The new failure records to store.
+     */
+    setFailedEmbeddings(records) {
+        this.failedEmbeddings = records;
+        this.dirty = true;
+    }
+    /**
+     * Removes a failure record for the given id, if one exists.
+     * @param id - The entry identifier whose failure record should be cleared.
+     */
+    clearFailure(id) {
+        if (id in this.failedEmbeddings) {
+            delete this.failedEmbeddings[id];
+            this.dirty = true;
+        }
+    }
+    /**
+     * Records or increments a failure for a given entry. Marks it as permanently
+     * "failed" once the retry count reaches maxRetries.
+     * @param id - The entry identifier that failed.
+     * @param error - The error message from the failed attempt.
+     * @param maxRetries - Maximum retries before marking as permanently failed.
+     */
+    recordFailure(id, error, maxRetries) {
+        const existing = this.failedEmbeddings[id];
+        const retries = (existing?.retries ?? 0) + 1;
+        this.failedEmbeddings[id] = {
+            retries,
+            status: retries >= maxRetries ? 'failed' : 'pending',
+            lastError: error,
+            lastAttempt: Date.now(),
+        };
+        this.dirty = true;
+    }
+}
+//# sourceMappingURL=vector-store.js.map

package/dist/vector-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../src/vector-store.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "memorandum-mcp",
+  "version": "0.1.0",
+  "description": "MCP server with memory: facts (short records with LRU expiration) and documents (with metadata and semantic search)",
+  "author": "lionsoftware <33127234+lionsoftware@users.noreply.github.com>",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lionsoftware/memorandum.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "memorandum": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "memory",
+    "semantic-search"
+  ],
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "lru-cache": "^11.2.7",
+    "pino": "^10.3.1",
+    "safe-regex2": "^5.1.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}