memorandum-mcp 0.1.0

package/README.md

@@ -0,0 +1,237 @@
+# memorandum-mcp
+
+[README on Russian](README.ru.md)
+
+MCP server with persistent memory for AI agents. Two memory types:
+
+- **Facts** — short key-value records with LRU eviction and optional TTL
+- **Documents** — structured storage with metadata, tags, topics, and semantic search
+
+## Features
+
+- LRU cache with configurable size and per-entry TTL
+- Namespace isolation for facts
+- Document storage with YAML index and Markdown frontmatter
+- Binary document support (base64 encoding, SHA-256 integrity)
+- File import with automatic MIME type detection
+- Semantic search via local HuggingFace embedding model (multilingual-e5-small)
+- Debounced batch embedding queue with failure tracking and retry
+- Atomic file writes (temp file + rename) for crash safety
+- Autosave with configurable interval
+- Export/import for facts backup and migration
+
+## Installation
+
+```bash
+npm install memorandum-mcp
+```
+
+Or run directly with npx:
+
+```bash
+npx memorandum-mcp
+```
+
+## Configuration
+
+Create `.memorandum/config.yaml` in your working directory:
+
+```yaml
+max_entries: 2048
+autosave_interval_seconds: 60
+storage_dir: .memorandum/
+```
+
+### All options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `max_entries` | `1000` | Maximum facts in LRU cache |
+| `autosave_interval_seconds` | `300` | Autosave interval (0 to disable) |
+| `storage_dir` | `.memorandum` | Base storage directory |
+| `max_document_size` | `16777216` | Max document body size in bytes (16 MiB) |
+| `semantic_enabled` | `true` | Enable semantic search |
+| `semantic_model` | `Xenova/multilingual-e5-small` | HuggingFace embedding model |
+| `semantic_model_dtype` | `q8` | Model quantization type |
+| `semantic_debounce_seconds` | `10` | Delay before batch embedding |
+| `semantic_max_queue_size` | `200` | Queue size before forced batch |
+| `semantic_max_retries` | `3` | Max retries per failed embedding |
+
+### Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `MEMORANDUM_STORAGE_DIR` | Override storage directory path |
+| `MEMORANDUM_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` |
+
+## Storage layout
+
+```
+.memorandum/
+  config.yaml          # Configuration
+  .gitignore           # Auto-generated, excludes cache/
+  facts/
+    facts.json         # LRU cache dump
+  documents/
+    _index.yaml        # Document index
+    doc-001.md         # Inline document (with YAML frontmatter)
+    doc-002.yaml       # Binary document sidecar
+    blobs/
+      doc-002.png      # Binary blob
+  cache/
+    vector-index.json  # Semantic search index
+```
+
+## MCP Tools
+
+### Facts (3 tools)
+
+#### `memory_write`
+
+Write or update a fact.
+
+```json
+{
+  "key": "server-web-01",
+  "value": { "ip": "192.168.1.10", "role": "webserver" },
+  "namespace": "servers",
+  "ttl_seconds": 3600
+}
+```
+
+#### `memory_read`
+
+Read a fact by key and namespace.
+
+```json
+{ "key": "server-web-01", "namespace": "servers" }
+```
+
+#### `memory_manage`
+
+Manage facts with actions: `list`, `search`, `namespaces`, `delete`, `delete_namespace`, `export`, `import`, `sync`.
+
+```json
+{ "action": "list", "namespace": "servers", "pattern": "web-*", "include_values": true }
+```
+
+```json
+{ "action": "search", "query": "webserver", "limit": 5 }
+```
+
+```json
+{ "action": "sync" }
+```
+
+### Documents (4 tools)
+
+#### `document_write`
+
+Create or update a document.
+
+```json
+{
+  "title": "Server inventory",
+  "body": "# Servers\n\n- web-01: 192.168.1.10\n- db-01: 192.168.1.20",
+  "topic": "infrastructure",
+  "tags": ["servers", "inventory"],
+  "content_type": "text/markdown"
+}
+```
+
+Update by providing `id`:
+
+```json
+{ "id": "doc-001", "tags": ["servers", "inventory", "updated"] }
+```
+
+Import a local file:
+
+```json
+{ "file_path": "/path/to/document.md" }
+```
+
+#### `document_read`
+
+```json
+{ "id": "doc-001", "include_body": true }
+```
+
+#### `document_list`
+
+```json
+{ "tag": "servers", "search": "inventory", "limit": 10 }
+```
+
+#### `document_delete`
+
+```json
+{ "id": "doc-001" }
+```
+
+### Semantic Search (2 tools)
+
+#### `semantic_search`
+
+Search by meaning across facts and documents.
+
+```json
+{
+  "query": "web server configuration",
+  "source": "all",
+  "limit": 10,
+  "threshold": 0.3
+}
+```
+
+#### `semantic_reindex`
+
+Rebuild the vector index.
+
+```json
+{ "source": "all" }
+```
+
+## Usage with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memorandum": {
+      "command": "npx",
+      "args": ["memorandum-mcp"]
+    }
+  }
+}
+```
+
+## Usage with Claude Code
+
+Add to your `.claude/settings.json` or project settings:
+
+```json
+{
+  "mcpServers": {
+    "memorandum": {
+      "command": "npx",
+      "args": ["memorandum-mcp"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/lionsoftware/memorandum.git
+cd memorandum
+npm install
+npm run build
+npm test
+```
+
+## License
+
+[GPL-3.0](LICENSE)

package/README.ru.md

@@ -0,0 +1,237 @@
+# memorandum-mcp
+
+[README in English](README.md)
+
+MCP-сервер с персистентной памятью для AI-агентов. Два типа памяти:
+
+- **Факты** — короткие key-value записи с LRU-вытеснением и опциональным TTL
+- **Документы** — структурированное хранилище с метаданными, тегами, топиками и семантическим поиском
+
+## Возможности
+
+- LRU-кэш с настраиваемым размером и TTL для каждой записи
+- Изоляция фактов по пространствам имён (namespaces)
+- Хранение документов с YAML-индексом и Markdown-фронтматтером
+- Поддержка бинарных документов (base64, проверка целостности SHA-256)
+- Импорт файлов с автоматическим определением MIME-типа
+- Семантический поиск через локальную модель HuggingFace (multilingual-e5-small)
+- Очередь пакетного эмбеддинга с debounce, отслеживанием ошибок и повторными попытками
+- Атомарная запись файлов (временный файл + rename) для защиты от сбоев
+- Автосохранение с настраиваемым интервалом
+- Экспорт/импорт фактов для резервного копирования и миграции
+
+## Установка
+
+```bash
+npm install memorandum-mcp
+```
+
+Или запуск напрямую через npx:
+
+```bash
+npx memorandum-mcp
+```
+
+## Конфигурация
+
+Создайте `.memorandum/config.yaml` в рабочей директории:
+
+```yaml
+max_entries: 2048
+autosave_interval_seconds: 60
+storage_dir: .memorandum/
+```
+
+### Все параметры
+
+| Параметр | По умолчанию | Описание |
+|----------|-------------|----------|
+| `max_entries` | `1000` | Максимум фактов в LRU-кэше |
+| `autosave_interval_seconds` | `300` | Интервал автосохранения (0 — отключить) |
+| `storage_dir` | `.memorandum` | Базовая директория хранения |
+| `max_document_size` | `16777216` | Максимальный размер документа в байтах (16 МиБ) |
+| `semantic_enabled` | `true` | Включить семантический поиск |
+| `semantic_model` | `Xenova/multilingual-e5-small` | Модель эмбеддингов HuggingFace |
+| `semantic_model_dtype` | `q8` | Тип квантизации модели |
+| `semantic_debounce_seconds` | `10` | Задержка перед пакетным эмбеддингом |
+| `semantic_max_queue_size` | `200` | Размер очереди для принудительного батча |
+| `semantic_max_retries` | `3` | Максимум повторных попыток на запись |
+
+### Переменные окружения
+
+| Переменная | Описание |
+|------------|----------|
+| `MEMORANDUM_STORAGE_DIR` | Переопределить путь к директории хранения |
+| `MEMORANDUM_LOG_LEVEL` | Уровень логирования: `debug`, `info`, `warn`, `error` |
+
+## Структура хранилища
+
+```
+.memorandum/
+  config.yaml          # Конфигурация
+  .gitignore           # Автоматически создаётся, исключает cache/
+  facts/
+    facts.json         # Дамп LRU-кэша
+  documents/
+    _index.yaml        # Индекс документов
+    doc-001.md         # Текстовый документ (с YAML-фронтматтером)
+    doc-002.yaml       # Сайдкар бинарного документа
+    blobs/
+      doc-002.png      # Бинарный блоб
+  cache/
+    vector-index.json  # Индекс семантического поиска
+```
+
+## MCP-инструменты
+
+### Факты (3 инструмента)
+
+#### `memory_write`
+
+Записать или обновить факт.
+
+```json
+{
+  "key": "server-web-01",
+  "value": { "ip": "192.168.1.10", "role": "webserver" },
+  "namespace": "servers",
+  "ttl_seconds": 3600
+}
+```
+
+#### `memory_read`
+
+Прочитать факт по ключу и пространству имён.
+
+```json
+{ "key": "server-web-01", "namespace": "servers" }
+```
+
+#### `memory_manage`
+
+Управление фактами. Действия: `list`, `search`, `namespaces`, `delete`, `delete_namespace`, `export`, `import`, `sync`.
+
+```json
+{ "action": "list", "namespace": "servers", "pattern": "web-*", "include_values": true }
+```
+
+```json
+{ "action": "search", "query": "webserver", "limit": 5 }
+```
+
+```json
+{ "action": "sync" }
+```
+
+### Документы (4 инструмента)
+
+#### `document_write`
+
+Создать или обновить документ.
+
+```json
+{
+  "title": "Инвентарь серверов",
+  "body": "# Серверы\n\n- web-01: 192.168.1.10\n- db-01: 192.168.1.20",
+  "topic": "infrastructure",
+  "tags": ["servers", "inventory"],
+  "content_type": "text/markdown"
+}
+```
+
+Обновление по `id`:
+
+```json
+{ "id": "doc-001", "tags": ["servers", "inventory", "updated"] }
+```
+
+Импорт локального файла:
+
+```json
+{ "file_path": "/path/to/document.md" }
+```
+
+#### `document_read`
+
+```json
+{ "id": "doc-001", "include_body": true }
+```
+
+#### `document_list`
+
+```json
+{ "tag": "servers", "search": "inventory", "limit": 10 }
+```
+
+#### `document_delete`
+
+```json
+{ "id": "doc-001" }
+```
+
+### Семантический поиск (2 инструмента)
+
+#### `semantic_search`
+
+Поиск по смыслу среди фактов и документов.
+
+```json
+{
+  "query": "конфигурация веб-сервера",
+  "source": "all",
+  "limit": 10,
+  "threshold": 0.3
+}
+```
+
+#### `semantic_reindex`
+
+Перестроить векторный индекс.
+
+```json
+{ "source": "all" }
+```
+
+## Использование с Claude Desktop
+
+Добавьте в `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "memorandum": {
+      "command": "npx",
+      "args": ["memorandum-mcp"]
+    }
+  }
+}
+```
+
+## Использование с Claude Code
+
+Добавьте в `.claude/settings.json` или настройки проекта:
+
+```json
+{
+  "mcpServers": {
+    "memorandum": {
+      "command": "npx",
+      "args": ["memorandum-mcp"]
+    }
+  }
+}
+```
+
+## Разработка
+
+```bash
+git clone https://github.com/lionsoftware/memorandum.git
+cd memorandum
+npm install
+npm run build
+npm test
+```
+
+## Лицензия
+
+[GPL-3.0](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Configuration schema and loader for Memorandum MCP server.
+ *
+ * Config file: {storage_dir}/config.yaml
+ */
+import { z } from 'zod';
+/** Zod schema defining all configuration options with defaults. */
+export declare const ConfigSchema: z.ZodObject<{
+    max_entries: z.ZodDefault<z.ZodNumber>;
+    autosave_interval_seconds: z.ZodDefault<z.ZodNumber>;
+    storage_dir: z.ZodDefault<z.ZodString>;
+    max_document_size: z.ZodDefault<z.ZodNumber>;
+    semantic_model: z.ZodDefault<z.ZodString>;
+    semantic_model_dtype: z.ZodDefault<z.ZodString>;
+    semantic_enabled: z.ZodDefault<z.ZodBoolean>;
+    semantic_debounce_seconds: z.ZodDefault<z.ZodNumber>;
+    semantic_max_queue_size: z.ZodDefault<z.ZodNumber>;
+    semantic_max_retries: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Inferred configuration type from {@link ConfigSchema}. */
+export type Config = z.infer<typeof ConfigSchema>;
+/** Derived paths from config. */
+export interface ResolvedPaths {
+    storageDir: string;
+    factsPath: string;
+    documentsPath: string;
+    cachePath: string;
+    configPath: string;
+}
+/** Resolve all storage paths from the base storage_dir. */
+export declare function resolvePaths(storageDir: string): ResolvedPaths;
+/** Load config from YAML file, falling back to defaults. */
+export declare function loadConfig(storageDir?: string): {
+    config: Config;
+    paths: ResolvedPaths;
+};

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * Configuration schema and loader for Memorandum MCP server.
+ *
+ * Config file: {storage_dir}/config.yaml
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { parse as yamlParse } from 'yaml';
+/** Zod schema defining all configuration options with defaults. */
+export const ConfigSchema = z.object({
+    /** Maximum number of facts in memory (LRU eviction threshold). */
+    max_entries: z.number().int().positive().default(1000),
+    /** Autosave interval in seconds (0 to disable). */
+    autosave_interval_seconds: z.number().int().nonnegative().default(300),
+    /** Base storage directory. */
+    storage_dir: z.string().default('.memorandum'),
+    /** Maximum document body size in bytes (default: 16 MiB). */
+    max_document_size: z.number().int().positive().default(16 * 1024 * 1024),
+    /** Embedding model ID for semantic search. */
+    semantic_model: z.string().default('Xenova/multilingual-e5-small'),
+    /** Model quantization dtype (e.g. q8, fp32). */
+    semantic_model_dtype: z.string().default('q8'),
+    /** Enable or disable semantic search. */
+    semantic_enabled: z.boolean().default(true),
+    /** Debounce delay in seconds before batch embedding (0 = immediate). */
+    semantic_debounce_seconds: z.number().int().nonnegative().default(10),
+    /** Maximum pending items in embedding queue before forced batch. */
+    semantic_max_queue_size: z.number().int().positive().default(200),
+    /** Maximum embedding retry attempts per item before marking as failed. */
+    semantic_max_retries: z.number().int().positive().default(3),
+});
+/** Resolve all storage paths from the base storage_dir. */
+export function resolvePaths(storageDir) {
+    return {
+        storageDir,
+        factsPath: join(storageDir, 'facts', 'facts.json'),
+        documentsPath: join(storageDir, 'documents'),
+        cachePath: join(storageDir, 'cache'),
+        configPath: join(storageDir, 'config.yaml'),
+    };
+}
+/** Load config from YAML file, falling back to defaults. */
+export function loadConfig(storageDir) {
+    const baseDir = storageDir ?? '.memorandum';
+    const configPath = join(baseDir, 'config.yaml');
+    let rawConfig = {};
+    if (existsSync(configPath)) {
+        const content = readFileSync(configPath, 'utf-8');
+        const parsed = yamlParse(content);
+        if (typeof parsed === 'object' && parsed !== null) {
+            rawConfig = parsed;
+        }
+    }
+    // Ensure storage_dir is set
+    if (!rawConfig.storage_dir) {
+        rawConfig.storage_dir = baseDir;
+    }
+    const config = ConfigSchema.parse(rawConfig);
+    const paths = resolvePaths(config.storage_dir);
+    return { config, paths };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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