memorandum-mcp 0.1.0

package/dist/semantic-tools.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+import { toMcpErrorResponse } from './errors.js';
+const SemanticSearchDisplaySchema = z.object({
+    query: z.string().optional().describe('Search query in natural language'),
+    source: z.string().optional().describe('Filter by source: all (default), documents, facts'),
+    limit: z.number().optional().describe('Maximum results (default: 10)'),
+    threshold: z.number().optional().describe('Minimum relevance threshold 0.0-1.0 (default: 0.3)'),
+    namespace: z.string().optional().describe('Filter by namespace (facts only)'),
+    tag: z.string().optional().describe('Filter by tag (documents only)'),
+    topic: z.string().optional().describe('Filter by topic (documents only)'),
+    content_type: z.string().optional().describe('Filter by content type (documents only)'),
+});
+const SemanticReindexDisplaySchema = z.object({
+    source: z.string().optional().describe('What to reindex: all (default), documents, facts'),
+});
+const SemanticSearchInputSchema = z.strictObject({
+    query: z.string().min(1).max(1000),
+    source: z.enum(['all', 'documents', 'facts']).default('all'),
+    limit: z.number().int().min(1).max(100).default(10),
+    threshold: z.number().min(0).max(1).default(0.3),
+    namespace: z.string().optional(),
+    tag: z.string().optional(),
+    topic: z.string().optional(),
+    content_type: z.string().optional(),
+});
+const SemanticReindexInputSchema = z.strictObject({
+    source: z.enum(['all', 'documents', 'facts']).default('all'),
+});
+/**
+ * Registers semantic_search and semantic_reindex tools on the MCP server.
+ * @param server - The MCP server instance to register tools on.
+ * @param semanticIndex - The semantic index used for embedding-based search and reindexing.
+ * @param _logger - Logger instance (reserved for future use).
+ */
+export function registerSemanticTools(server, semanticIndex, _logger) {
+    server.registerTool('semantic_search', {
+        title: 'Semantic Search',
+        description: 'Search documents and facts by meaning using natural language queries. Returns ranked results with relevance scores.',
+        inputSchema: SemanticSearchDisplaySchema,
+    }, async (rawInput) => {
+        try {
+            const input = SemanticSearchInputSchema.parse(rawInput);
+            const result = await semanticIndex.search(input.query, {
+                source: input.source, limit: input.limit, threshold: input.threshold,
+                namespace: input.namespace, tag: input.tag, topic: input.topic, content_type: input.content_type,
+            });
+            const output = { status: result.status, hint: result.hint, results: result.results, total: result.total, query: input.query };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            return toMcpErrorResponse(error);
+        }
+    });
+    server.registerTool('semantic_reindex', {
+        title: 'Semantic Reindex',
+        description: 'Rebuild the semantic search index for all documents and/or facts.',
+        inputSchema: SemanticReindexDisplaySchema,
+    }, async (rawInput) => {
+        try {
+            const input = SemanticReindexInputSchema.parse(rawInput);
+            const result = await semanticIndex.reindex(input.source);
+            const output = {
+                success: true,
+                indexed: { facts: result.facts, documents: result.documents, total: result.total },
+                skipped: result.skipped, duration_ms: result.duration_ms, model: semanticIndex.modelId,
+            };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(output) }],
+                structuredContent: output,
+            };
+        }
+        catch (error) {
+            return toMcpErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=semantic-tools.js.map

package/dist/semantic-tools.js.map

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

package/dist/semantic-types.d.ts

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+export declare const VECTOR_INDEX_VERSION = 2;
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+export declare const DEFAULT_SEARCH_THRESHOLD = 0.3;
+export declare const FACT_ID_PREFIX = "fact:";
+export declare const DOC_ID_PREFIX = "doc:";
+export declare const IndexStatusEnum: z.ZodEnum<{
+    ready: "ready";
+    empty: "empty";
+    stale_model: "stale_model";
+    partial: "partial";
+    model_loading: "model_loading";
+    model_unavailable: "model_unavailable";
+}>;
+export type IndexStatus = z.infer<typeof IndexStatusEnum>;
+export declare const INDEX_STATUS_HINTS: Record<IndexStatus, string | undefined>;
+export declare const FactVectorMetadataSchema: z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    preview: z.ZodString;
+}, z.core.$strip>;
+export declare const DocumentVectorMetadataSchema: z.ZodObject<{
+    documentId: z.ZodString;
+    title: z.ZodString;
+    topic: z.ZodOptional<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    contentType: z.ZodString;
+}, z.core.$strip>;
+export declare const VectorMetadataSchema: z.ZodUnion<readonly [z.ZodObject<{
+    key: z.ZodString;
+    namespace: z.ZodString;
+    preview: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    documentId: z.ZodString;
+    title: z.ZodString;
+    topic: z.ZodOptional<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    contentType: z.ZodString;
+}, z.core.$strip>]>;
+export type FactVectorMetadata = z.infer<typeof FactVectorMetadataSchema>;
+export type DocumentVectorMetadata = z.infer<typeof DocumentVectorMetadataSchema>;
+export type VectorMetadata = z.infer<typeof VectorMetadataSchema>;
+export declare const VectorEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    vector: z.ZodArray<z.ZodNumber>;
+    source: z.ZodEnum<{
+        fact: "fact";
+        document: "document";
+    }>;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        key: z.ZodString;
+        namespace: z.ZodString;
+        preview: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        documentId: z.ZodString;
+        title: z.ZodString;
+        topic: z.ZodOptional<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        contentType: z.ZodString;
+    }, z.core.$strip>]>;
+    indexedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type VectorEntry = z.infer<typeof VectorEntrySchema>;
+export declare const EmbeddingFailureRecordSchema: z.ZodObject<{
+    retries: z.ZodNumber;
+    status: z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+    }>;
+    lastError: z.ZodOptional<z.ZodString>;
+    lastAttempt: z.ZodNumber;
+}, z.core.$strip>;
+export type EmbeddingFailureRecord = z.infer<typeof EmbeddingFailureRecordSchema>;
+export declare const EmbeddingQueueItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    source: z.ZodEnum<{
+        fact: "fact";
+        document: "document";
+    }>;
+    textToEmbed: z.ZodString;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        key: z.ZodString;
+        namespace: z.ZodString;
+        preview: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        documentId: z.ZodString;
+        title: z.ZodString;
+        topic: z.ZodOptional<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        contentType: z.ZodString;
+    }, z.core.$strip>]>;
+    enqueuedAt: z.ZodNumber;
+}, z.core.$strip>;
+export type EmbeddingQueueItem = z.infer<typeof EmbeddingQueueItemSchema>;
+export declare const VectorIndexSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    modelId: z.ZodString;
+    dimensions: z.ZodNumber;
+    entries: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        vector: z.ZodArray<z.ZodNumber>;
+        source: z.ZodEnum<{
+            fact: "fact";
+            document: "document";
+        }>;
+        metadata: z.ZodUnion<readonly [z.ZodObject<{
+            key: z.ZodString;
+            namespace: z.ZodString;
+            preview: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            documentId: z.ZodString;
+            title: z.ZodString;
+            topic: z.ZodOptional<z.ZodString>;
+            tags: z.ZodArray<z.ZodString>;
+            contentType: z.ZodString;
+        }, z.core.$strip>]>;
+        indexedAt: z.ZodNumber;
+    }, z.core.$strip>>;
+    updatedAt: z.ZodNumber;
+    failedEmbeddings: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        retries: z.ZodNumber;
+        status: z.ZodEnum<{
+            pending: "pending";
+            failed: "failed";
+        }>;
+        lastError: z.ZodOptional<z.ZodString>;
+        lastAttempt: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type VectorIndex = z.infer<typeof VectorIndexSchema>;
+export declare const SearchResultSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        fact: "fact";
+        document: "document";
+    }>;
+    id: z.ZodString;
+    score: z.ZodNumber;
+    metadata: z.ZodUnion<readonly [z.ZodObject<{
+        key: z.ZodString;
+        namespace: z.ZodString;
+        preview: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        documentId: z.ZodString;
+        title: z.ZodString;
+        topic: z.ZodOptional<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        contentType: z.ZodString;
+    }, z.core.$strip>]>;
+}, z.core.$strip>;
+export type SearchResult = z.infer<typeof SearchResultSchema>;
+export interface SearchFilterOptions {
+    source?: 'all' | 'documents' | 'facts';
+    namespace?: string;
+    tag?: string;
+    topic?: string;
+    content_type?: string;
+    limit?: number;
+    threshold?: number;
+}
+export declare function makeFactVectorId(namespace: string, key: string): string;
+export declare function makeDocVectorId(documentId: string): string;

package/dist/semantic-types.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+// ============================================================================
+// Constants
+// ============================================================================
+export const VECTOR_INDEX_VERSION = 2;
+export const DEFAULT_SEARCH_LIMIT = 10;
+export const DEFAULT_SEARCH_THRESHOLD = 0.3;
+export const FACT_ID_PREFIX = 'fact:';
+export const DOC_ID_PREFIX = 'doc:';
+// ============================================================================
+// Index Status
+// ============================================================================
+export const IndexStatusEnum = z.enum([
+    'ready', 'empty', 'stale_model', 'partial', 'model_loading', 'model_unavailable',
+]);
+export const INDEX_STATUS_HINTS = {
+    ready: undefined,
+    empty: 'Index is empty. Call semantic_reindex to index existing data.',
+    stale_model: 'Model has changed. Call semantic_reindex to re-index with the new model.',
+    partial: 'Index is incomplete. Call semantic_reindex for full indexing.',
+    model_loading: 'Model is loading, retry in a few seconds.',
+    model_unavailable: 'Embedding model could not be loaded. Run semantic_reindex to attempt repair, or use text-based search via memory_manage.',
+};
+// ============================================================================
+// Vector Metadata
+// ============================================================================
+export const FactVectorMetadataSchema = z.object({
+    key: z.string(),
+    namespace: z.string(),
+    preview: z.string(),
+});
+export const DocumentVectorMetadataSchema = z.object({
+    documentId: z.string(),
+    title: z.string(),
+    topic: z.string().optional(),
+    tags: z.array(z.string()),
+    contentType: z.string(),
+});
+export const VectorMetadataSchema = z.union([
+    FactVectorMetadataSchema,
+    DocumentVectorMetadataSchema,
+]);
+// ============================================================================
+// Vector Entry
+// ============================================================================
+export const VectorEntrySchema = z.object({
+    id: z.string(),
+    vector: z.array(z.number()),
+    source: z.enum(['fact', 'document']),
+    metadata: VectorMetadataSchema,
+    indexedAt: z.number(),
+});
+// ============================================================================
+// Embedding Failure Record
+// ============================================================================
+export const EmbeddingFailureRecordSchema = z.object({
+    retries: z.number().int().nonnegative(),
+    status: z.enum(['pending', 'failed']),
+    lastError: z.string().optional(),
+    lastAttempt: z.number(),
+});
+// ============================================================================
+// Embedding Queue Item
+// ============================================================================
+export const EmbeddingQueueItemSchema = z.object({
+    id: z.string(),
+    source: z.enum(['fact', 'document']),
+    textToEmbed: z.string(),
+    metadata: VectorMetadataSchema,
+    enqueuedAt: z.number(),
+});
+// ============================================================================
+// Vector Index (persisted to disk)
+// ============================================================================
+export const VectorIndexSchema = z.object({
+    version: z.number(),
+    modelId: z.string(),
+    dimensions: z.number(),
+    entries: z.array(VectorEntrySchema),
+    updatedAt: z.number(),
+    failedEmbeddings: z.record(z.string(), EmbeddingFailureRecordSchema).default({}),
+});
+// ============================================================================
+// Search Result
+// ============================================================================
+export const SearchResultSchema = z.object({
+    source: z.enum(['fact', 'document']),
+    id: z.string(),
+    score: z.number(),
+    metadata: VectorMetadataSchema,
+});
+// ============================================================================
+// Helper: Compose vector entry ID
+// ============================================================================
+export function makeFactVectorId(namespace, key) {
+    return `${FACT_ID_PREFIX}${namespace}\0${key}`;
+}
+export function makeDocVectorId(documentId) {
+    return `${DOC_ID_PREFIX}${documentId}`;
+}
+//# sourceMappingURL=semantic-types.js.map

package/dist/semantic-types.js.map

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

package/dist/store.d.ts

@@ -0,0 +1,130 @@
+import type { Logger } from 'pino';
+import type { Config, ResolvedPaths } from './config.js';
+import type { FactMetadata, NamespaceInfo, MemoryStats } from './types.js';
+import type { SemanticIndex } from './semantic-index.js';
+/**
+ * LRU-backed in-memory fact store with namespacing, TTL support,
+ * optional semantic indexing, and JSON file persistence.
+ */
+export declare class MemoryStore {
+    private readonly cache;
+    private readonly config;
+    private readonly storagePath;
+    private readonly logger;
+    private semanticIndex;
+    private dirty;
+    lastSavedAt: number | null;
+    constructor(config: Config, paths: ResolvedPaths, logger: Logger);
+    /** Attaches a semantic index for embedding-based fact retrieval. */
+    setSemanticIndex(index: SemanticIndex): void;
+    /**
+     * Creates a composite cache key by joining namespace and key with a null byte.
+     * @param namespace - The namespace portion of the key.
+     * @param key - The fact key within the namespace.
+     * @returns The composite key string.
+     */
+    static makeKey(namespace: string, key: string): string;
+    /**
+     * Splits a composite cache key back into its namespace and key parts.
+     * Falls back to the "default" namespace when no separator is found.
+     * @param compositeKey - The composite key to parse.
+     * @returns An object containing the namespace and key.
+     */
+    static parseKey(compositeKey: string): {
+        namespace: string;
+        key: string;
+    };
+    private getRemainingTtlSeconds;
+    /**
+     * Writes or updates a fact in the store.
+     * @param key - Fact identifier.
+     * @param value - The fact payload.
+     * @param namespace - Namespace to store the fact under.
+     * @param ttlSeconds - Optional time-to-live in seconds.
+     * @returns An object indicating whether a new fact was created.
+     */
+    write(key: string, value: unknown, namespace: string, ttlSeconds?: number): {
+        created: boolean;
+    };
+    /**
+     * Reads a single fact by key and namespace.
+     * @param key - Fact identifier.
+     * @param namespace - Namespace the fact belongs to.
+     * @returns The fact metadata including TTL info, or null if not found.
+     */
+    read(key: string, namespace: string): FactMetadata | null;
+    /**
+     * Lists facts with optional namespace filtering, glob pattern matching, and pagination.
+     * Can optionally include values and store-level statistics.
+     */
+    list(options: {
+        namespace?: string;
+        pattern?: string;
+        limit: number;
+        includeValues: boolean;
+        includeStats: boolean;
+    }): {
+        facts: Array<Record<string, unknown>>;
+        stats?: MemoryStats;
+    };
+    /** Returns all namespaces with their respective fact counts. */
+    getNamespaces(): NamespaceInfo[];
+    /**
+     * Searches facts by regex pattern, matching against both keys and values.
+     * Validates the regex for safety against ReDoS before executing.
+     */
+    search(options: {
+        query: string;
+        namespace?: string;
+        limit: number;
+    }): {
+        results: Array<Record<string, unknown>>;
+        total_matches: number;
+        limit: number;
+    };
+    get size(): number;
+    get maxEntries(): number;
+    /**
+     * Deletes a single fact by key and namespace.
+     * @param key - Fact identifier.
+     * @param namespace - Namespace the fact belongs to.
+     * @returns True if the fact existed and was deleted.
+     */
+    delete(key: string, namespace: string): boolean;
+    /**
+     * Deletes all facts within the given namespace.
+     * @param namespace - The namespace to clear.
+     * @returns The number of facts deleted.
+     */
+    deleteNamespace(namespace: string): number;
+    /**
+     * Persists the cache to disk using atomic write (temp file + rename).
+     * Skips saving when no changes have been made or when the cache is empty
+     * but the file on disk still contains data (safety guard).
+     * @returns True if the save was performed successfully.
+     */
+    save(): Promise<boolean>;
+    /** Loads facts from the on-disk JSON file into the cache. Starts empty if the file is missing or corrupt. */
+    load(): Promise<void>;
+    private autosaveTimer;
+    /**
+     * Starts a recurring autosave timer that persists dirty state to disk.
+     * @param intervalMs - Interval between saves in milliseconds. Values <= 0 are ignored.
+     */
+    startAutosave(intervalMs: number): void;
+    /** Stops the autosave timer if one is running. */
+    stopAutosave(): void;
+    /**
+     * Exports all facts as a versioned JSON-serializable object.
+     * Includes TTL remaining at the time of export.
+     * @returns An export payload with version, timestamp, count, and fact data.
+     */
+    export(): Record<string, unknown>;
+    /**
+     * Imports facts from a JSON string previously produced by {@link export}.
+     * @param dataStr - JSON string containing the export payload.
+     * @param merge - When true, merges into existing data; when false, replaces all facts.
+     * @returns Summary with imported and overwritten counts.
+     */
+    import(dataStr: string, merge: boolean): Record<string, unknown>;
+}