oh-memos-mcp 1.0.0

package/.env.example

@@ -0,0 +1,27 @@
+# ============================================================================
+# oh-memos-mcp Environment Configuration
+# ============================================================================
+# Copy this file to .env in your project root and adjust values.
+# Priority: CLI args > environment variables > defaults
+# ============================================================================
+
+# --- Required ---
+MEMOS_URL=http://localhost:18000        # oh-memos API address
+MEMOS_USER=dev_user                     # Default user ID
+MEMOS_DEFAULT_CUBE=dev_cube             # Default memory cube ID
+MEMOS_CUBES_DIR=/path/to/cubes          # Absolute path to cubes directory
+
+# --- Timeouts (seconds) ---
+# MEMOS_TIMEOUT_TOOL=300                # Tool call timeout (default: 300)
+# MEMOS_TIMEOUT_STARTUP=30              # Startup timeout (default: 30)
+# MEMOS_TIMEOUT_HEALTH=5                # Health check timeout (default: 5)
+# MEMOS_API_WAIT_MAX=60                 # Max API wait time (default: 60)
+
+# --- Feature Flags ---
+# MEMOS_ENABLE_DELETE=false             # Enable memory deletion (default: false)
+# MEMOS_LOG_LEVEL=WARNING               # DEBUG | INFO | WARNING | ERROR
+
+# --- Neo4j (optional, for direct graph queries) ---
+# NEO4J_HTTP_URL=http://localhost:7474
+# NEO4J_USER=neo4j
+# NEO4J_PASSWORD=your_password

package/README.md

@@ -0,0 +1,71 @@
+# oh-memos-mcp
+
+MCP Server for MemOS — Intelligent Memory Management for AI Assistants.
+
+Node.js implementation. No Python required.
+
+## Quick Start
+
+```json
+{
+  "mcpServers": {
+    "memos": {
+      "command": "npx",
+      "args": ["-y", "oh-memos-mcp"],
+      "env": {
+        "MEMOS_URL": "http://localhost:18000",
+        "MEMOS_USER": "dev_user",
+        "MEMOS_DEFAULT_CUBE": "dev_cube",
+        "MEMOS_CUBES_DIR": "/path/to/data/memos_cubes"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MEMOS_URL` | Yes | — | MemOS API base URL |
+| `MEMOS_USER` | Yes | — | Default user ID |
+| `MEMOS_DEFAULT_CUBE` | Yes | — | Default memory cube ID |
+| `MEMOS_CUBES_DIR` | Yes | — | Path to cubes storage directory |
+| `NEO4J_HTTP_URL` | No | — | Neo4j HTTP endpoint for graph queries |
+| `NEO4J_USER` | No | — | Neo4j username |
+| `NEO4J_PASSWORD` | No | — | Neo4j password |
+| `MEMOS_ENABLE_DELETE` | No | `false` | Enable delete functionality |
+
+## Tools (18)
+
+- **memos_save** — Save memories with explicit type classification
+- **memos_search** — Semantic search with keyword reranking
+- **memos_search_context** — Context-aware search with conversation history
+- **memos_list_v2** — List memories with compaction
+- **memos_get** — Get full memory details by ID
+- **memos_get_stats** — Memory type statistics
+- **memos_suggest** — Smart search suggestions
+- **memos_context_resume** — Recover context after compaction
+- **memos_trace_path** — Trace reasoning paths between memories
+- **memos_get_graph** — Knowledge graph with relationships
+- **memos_export_schema** — Graph schema and statistics
+- **memos_impact** — Forward blast radius analysis
+- **memos_calendar** — Calendar view (project/student modes)
+- **memos_list_cubes** — List available memory cubes
+- **memos_register_cube** — Register a cube with the API
+- **memos_create_user** — Create a MemOS user
+- **memos_validate_cubes** — Validate and fix cube configs
+- **memos_delete** — Delete memories (disabled by default)
+
+## Development
+
+```bash
+npm install
+npm run dev    # Run with tsx (no build needed)
+npm run build  # Compile to dist/
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- MemOS backend API running (Python FastAPI, port 18000)

package/dist/api-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MemOS MCP Server API Client Module
+ *
+ * HTTP fetch wrapper with timeout, retry, and health check.
+ */
+export declare function fetchWithTimeout(url: string, options?: RequestInit & {
+    timeoutMs?: number;
+}): Promise<Response>;
+export declare function waitForApiReady(maxWait?: number, interval?: number): Promise<boolean>;
+export type HttpMethod = "GET" | "POST" | "DELETE";
+export interface ApiCallOptions {
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+export interface ApiCallResult {
+    success: boolean;
+    data: Record<string, unknown> | null;
+    status: number;
+}
+export declare function apiCallWithRetry(method: HttpMethod, url: string, cubeId: string, options?: ApiCallOptions, ensureCubeRegistered?: (cubeId: string, force?: boolean) => Promise<[boolean, string | null]>): Promise<ApiCallResult>;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.js

@@ -0,0 +1,127 @@
+/**
+ * MemOS MCP Server API Client Module
+ *
+ * HTTP fetch wrapper with timeout, retry, and health check.
+ */
+import { MEMOS_URL, MEMOS_API_WAIT_MAX, MEMOS_TIMEOUT_HEALTH, MEMOS_TIMEOUT_TOOL, logger, registeredCubes } from "./config.js";
+// ============================================================================
+// Fetch with Timeout
+// ============================================================================
+export async function fetchWithTimeout(url, options = {}) {
+    const timeoutMs = (options.timeoutMs ?? MEMOS_TIMEOUT_TOOL) * 1000;
+    const { timeoutMs: _, ...fetchOptions } = options;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, {
+            ...fetchOptions,
+            signal: controller.signal,
+        });
+        return response;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// ============================================================================
+// API Readiness Check
+// ============================================================================
+export async function waitForApiReady(maxWait, interval = 2.0) {
+    const maxWaitMs = (maxWait ?? MEMOS_API_WAIT_MAX) * 1000;
+    const intervalMs = interval * 1000;
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        try {
+            const response = await fetchWithTimeout(`${MEMOS_URL}/users`, {
+                timeoutMs: MEMOS_TIMEOUT_HEALTH,
+            });
+            if (response.ok) {
+                logger.debug("MemOS API is ready");
+                return true;
+            }
+        }
+        catch {
+            // Not ready yet
+        }
+        await sleep(intervalMs);
+    }
+    logger.warning(`MemOS API not ready after ${maxWait ?? MEMOS_API_WAIT_MAX}s`);
+    return false;
+}
+function buildUrl(base, params) {
+    if (!params)
+        return base;
+    const urlParams = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined)
+            urlParams.append(k, String(v));
+    }
+    const qs = urlParams.toString();
+    return qs ? `${base}?${qs}` : base;
+}
+async function doFetch(method, url, options) {
+    const finalUrl = buildUrl(url, options.params);
+    const headers = {
+        "Content-Type": "application/json",
+        ...options.headers,
+    };
+    const fetchOptions = {
+        method,
+        headers,
+    };
+    if (options.body !== undefined && method !== "GET") {
+        fetchOptions.body = JSON.stringify(options.body);
+    }
+    const response = await fetchWithTimeout(finalUrl, fetchOptions);
+    if (!response.ok && response.status !== 400) {
+        return { status: response.status, data: null };
+    }
+    try {
+        const data = await response.json();
+        return { status: response.status, data };
+    }
+    catch {
+        return { status: response.status, data: null };
+    }
+}
+export async function apiCallWithRetry(method, url, cubeId, options = {}, ensureCubeRegistered) {
+    const { status, data } = await doFetch(method, url, options);
+    if (status === 200 && data) {
+        if (data.code === 200) {
+            return { success: true, data, status: 200 };
+        }
+        // API returned error code - try re-registration if available
+        if (ensureCubeRegistered) {
+            registeredCubes.delete(cubeId);
+            const [regSuccess] = await ensureCubeRegistered(cubeId, true);
+            if (regSuccess) {
+                const retry = await doFetch(method, url, options);
+                if (retry.status === 200 && retry.data && retry.data.code === 200) {
+                    return { success: true, data: retry.data, status: 200 };
+                }
+                return { success: false, data: retry.data, status: 200 };
+            }
+        }
+        return { success: false, data, status: 200 };
+    }
+    if (status === 400 && ensureCubeRegistered) {
+        // 400 often means cube not loaded
+        registeredCubes.delete(cubeId);
+        const [regSuccess] = await ensureCubeRegistered(cubeId, true);
+        if (regSuccess) {
+            const retry = await doFetch(method, url, options);
+            if (retry.status === 200 && retry.data && retry.data.code === 200) {
+                return { success: true, data: retry.data, status: 200 };
+            }
+        }
+        return { success: false, data: null, status: 400 };
+    }
+    return { success: false, data, status };
+}
+// ============================================================================
+// Helper
+// ============================================================================
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=api-client.js.map

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MemOS MCP Server Configuration Module (TypeScript)
+ *
+ * Configuration priority: CLI args > environment variables > defaults
+ */
+export declare const logger: {
+    debug: (msg: string) => void;
+    info: (msg: string) => void;
+    warning: (msg: string) => void;
+    error: (msg: string) => void;
+    exception: (msg: string, err?: unknown) => void;
+};
+export declare const MEMOS_URL: string;
+export declare const MEMOS_USER: string;
+export declare const MEMOS_DEFAULT_CUBE: string;
+export declare const MEMOS_CUBES_DIR: string;
+export declare const MEMOS_TIMEOUT_TOOL: number;
+export declare const MEMOS_TIMEOUT_STARTUP: number;
+export declare const MEMOS_TIMEOUT_HEALTH: number;
+export declare const MEMOS_API_WAIT_MAX: number;
+export declare const MEMOS_ENABLE_DELETE: boolean;
+export declare const NEO4J_HTTP_URL: string | undefined;
+export declare const NEO4J_USER: string | undefined;
+export declare const NEO4J_PASSWORD: string | undefined;
+export declare const registeredCubes: Set<string>;
+export declare const lastRegistrationAttempt: Map<string, number>;
+export declare const REGISTRATION_RETRY_INTERVAL = 5;
+export declare const MEMORY_TYPES: Set<string>;
+export declare function isDefaultCubeFromEnv(): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,163 @@
+/**
+ * MemOS MCP Server Configuration Module (TypeScript)
+ *
+ * Configuration priority: CLI args > environment variables > defaults
+ */
+import { config as loadDotenv } from "dotenv";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+import { parseArgs } from "util";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Load .env with priority: cwd > package root > dotenv default search
+const cwdEnv = resolve(process.cwd(), ".env");
+const pkgRoot = resolve(__dirname, "..", "..");
+const pkgEnv = resolve(pkgRoot, ".env");
+if (existsSync(cwdEnv)) {
+    loadDotenv({ path: cwdEnv, override: true });
+}
+else if (existsSync(pkgEnv)) {
+    loadDotenv({ path: pkgEnv, override: true });
+}
+else {
+    loadDotenv(); // fallback: search from cwd upward
+}
+// ============================================================================
+// CLI Argument Parsing
+// ============================================================================
+function parseCliArgs() {
+    try {
+        const { values } = parseArgs({
+            args: process.argv.slice(2),
+            options: {
+                "memos-url": { type: "string" },
+                "memos-user": { type: "string" },
+                "memos-default-cube": { type: "string" },
+                "memos-cubes-dir": { type: "string" },
+                "memos-enable-delete": { type: "string" },
+                "memos-timeout-tool": { type: "string" },
+                "memos-timeout-startup": { type: "string" },
+                "memos-timeout-health": { type: "string" },
+                "memos-api-wait-max": { type: "string" },
+            },
+            strict: false,
+        });
+        return values;
+    }
+    catch {
+        return {};
+    }
+}
+const _args = parseCliArgs();
+// ============================================================================
+// Logging
+// ============================================================================
+const _logLevel = process.env.MEMOS_LOG_LEVEL?.toUpperCase() ?? "WARNING";
+const LOG_LEVELS = {
+    DEBUG: 0,
+    INFO: 1,
+    WARNING: 2,
+    ERROR: 3,
+};
+const _currentLevel = LOG_LEVELS[_logLevel] ?? LOG_LEVELS.WARNING;
+export const logger = {
+    debug: (msg) => {
+        if (_currentLevel <= LOG_LEVELS.DEBUG) {
+            process.stderr.write(`[DEBUG] ${msg}\n`);
+        }
+    },
+    info: (msg) => {
+        if (_currentLevel <= LOG_LEVELS.INFO) {
+            process.stderr.write(`[INFO] ${msg}\n`);
+        }
+    },
+    warning: (msg) => {
+        if (_currentLevel <= LOG_LEVELS.WARNING) {
+            process.stderr.write(`[WARN] ${msg}\n`);
+        }
+    },
+    error: (msg) => {
+        if (_currentLevel <= LOG_LEVELS.ERROR) {
+            process.stderr.write(`[ERROR] ${msg}\n`);
+        }
+    },
+    exception: (msg, err) => {
+        process.stderr.write(`[ERROR] ${msg}: ${err}\n`);
+    },
+};
+// ============================================================================
+// Configuration Helpers
+// ============================================================================
+function getEnv(key, ...alternatives) {
+    const val = process.env[key]?.trim();
+    if (val)
+        return val;
+    for (const alt of alternatives) {
+        const altVal = process.env[alt]?.trim();
+        if (altVal)
+            return altVal;
+    }
+    return undefined;
+}
+function requireEnv(name, value) {
+    if (!value) {
+        throw new Error(`${name} is required (set ${name} in .env)`);
+    }
+    return value;
+}
+function parseFloat2(name, value, defaultVal) {
+    if (!value)
+        return defaultVal;
+    const n = parseFloat(value);
+    if (isNaN(n))
+        throw new Error(`${name} must be a float, got: ${value}`);
+    return n;
+}
+// ============================================================================
+// Core Configuration (CLI args > env vars > defaults)
+// ============================================================================
+// -- API Connection --
+export const MEMOS_URL = requireEnv("MEMOS_URL", _args["memos-url"] ?? getEnv("MEMOS_URL", "MEMOS_BASE_URL"));
+export const MEMOS_USER = requireEnv("MEMOS_USER", _args["memos-user"] ?? getEnv("MEMOS_USER", "MOS_USER_ID"));
+const _defaultCubeFromEnv = _args["memos-default-cube"] != null || process.env["MEMOS_DEFAULT_CUBE"] != null;
+export const MEMOS_DEFAULT_CUBE = requireEnv("MEMOS_DEFAULT_CUBE", _args["memos-default-cube"] ?? getEnv("MEMOS_DEFAULT_CUBE"));
+export const MEMOS_CUBES_DIR = requireEnv("MEMOS_CUBES_DIR", _args["memos-cubes-dir"] ?? getEnv("MEMOS_CUBES_DIR"));
+// -- Timeouts (seconds) --
+export const MEMOS_TIMEOUT_TOOL = parseFloat2("MEMOS_TIMEOUT_TOOL", _args["memos-timeout-tool"] ?? getEnv("MEMOS_TIMEOUT_TOOL"), 300.0);
+export const MEMOS_TIMEOUT_STARTUP = parseFloat2("MEMOS_TIMEOUT_STARTUP", _args["memos-timeout-startup"] ?? getEnv("MEMOS_TIMEOUT_STARTUP"), 30.0);
+export const MEMOS_TIMEOUT_HEALTH = parseFloat2("MEMOS_TIMEOUT_HEALTH", _args["memos-timeout-health"] ?? getEnv("MEMOS_TIMEOUT_HEALTH"), 5.0);
+export const MEMOS_API_WAIT_MAX = parseFloat2("MEMOS_API_WAIT_MAX", _args["memos-api-wait-max"] ?? getEnv("MEMOS_API_WAIT_MAX"), 60.0);
+// -- Feature Flags --
+const _enableDeleteRaw = _args["memos-enable-delete"] ?? getEnv("MEMOS_ENABLE_DELETE") ?? "false";
+export const MEMOS_ENABLE_DELETE = _enableDeleteRaw.toLowerCase() === "true";
+// -- Neo4j (for fallback direct graph queries) --
+export const NEO4J_HTTP_URL = getEnv("NEO4J_HTTP_URL");
+export const NEO4J_USER = getEnv("NEO4J_USER");
+export const NEO4J_PASSWORD = getEnv("NEO4J_PASSWORD");
+// ============================================================================
+// Cube Registration Tracking
+// ============================================================================
+export const registeredCubes = new Set();
+export const lastRegistrationAttempt = new Map();
+export const REGISTRATION_RETRY_INTERVAL = 5.0; // seconds
+// ============================================================================
+// Memory Types
+// ============================================================================
+export const MEMORY_TYPES = new Set([
+    "ERROR_PATTERN",
+    "DECISION",
+    "MILESTONE",
+    "BUGFIX",
+    "FEATURE",
+    "CONFIG",
+    "CODE_PATTERN",
+    "GOTCHA",
+    "PROGRESS",
+]);
+// ============================================================================
+// Helper
+// ============================================================================
+export function isDefaultCubeFromEnv() {
+    return _defaultCubeFromEnv;
+}
+//# sourceMappingURL=config.js.map

package/dist/cube-manager.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MemOS MCP Server Cube Management Module
+ *
+ * Handles cube discovery, config, and registration.
+ */
+import type { CubeInfo } from "./types.js";
+export declare function getCubesBaseDir(): string;
+export declare function getLocalCubesBaseDir(): string;
+export declare function listAvailableCubes(): CubeInfo[];
+export declare function getCubePath(cubeId: string): string | null;
+export declare function validateAndFixCubeConfig(cubeId: string, configPath: string): [boolean, string | null];
+export declare function ensureCubeDirectory(cubeId: string): [string | null, string | null];
+export declare function verifyCubeLoaded(cubeId: string): Promise<boolean>;
+export declare function ensureCubeRegistered(cubeId: string, force?: boolean): Promise<[boolean, string | null]>;
+export declare function getDefaultCubeId(): string;
+//# sourceMappingURL=cube-manager.d.ts.map