HyperspaceDB MCP Server

The HyperspaceDB MCP Server acts as a high-performance cognitive bridge, enabling Large Language Models (LLMs) to interact with HyperspaceDB — a multi-geometry vector database designed for advanced AI memory and spatial computing.

This server implements the Model Context Protocol (MCP), exposing a comprehensive suite of tools for geometrical data analysis, graph traversal, and cognitive AI metrics directly to models in Claude Desktop, Cursor, and other MCP hosts.

🚀 Key Features

1. Geometric Data Diagnostics

Identify the optimal geometry for your data using Gromov Delta-hyperbolicity analysis.

• hyperspace_analyze_geometry: Uses the 4-point condition to recommend Lorentz, Poincare, Cosine, or L2 metrics for your datasets.

2. Cognitive AI Tools (Agentic Logic)

Track and manage the model's internal reasoning stability.

• hyperspace_analyze_thought_stability: Calculates Lyapunov Convergence of a trajectory (Chain of Thought). Detects if a model is "hallucinating" or converging on a stable logical attractor.
• hyperspace_find_clusters: Detects emergent semantic regions in the database knowledge graph to help the model synthesize higher-level concepts.

3. High-Performance Knowledge Retrieval

• hyperspace_search_text: Natural language semantic search using server-side embeddings.
• hyperspace_search_wasserstein: Optimal Transport (OT) based search for comparing complex distributions and finding non-obvious conceptual overlaps.
• hyperspace_insert_text: Asynchronous storage of factual claims or system logs with automatic vectorization.

4. Graph Memory Navigation

• hyperspace_graph_traverse: Perform deep BFS/DFS traversal through the HNSW knowledge graph. Allows the model to "follow paths" between disparate facts to build complex reasoning chains.

🛠️ Installation & Setup

Prerequisites

• Node.js 18+
• Running instance of HyperspaceDB (default: localhost:50051)

1. Run directly with npx (Recommended)

You don't need to install anything. Just run:

npx mcp-hyperspacedb

2. Configuration for MCP Hosts

Add the following to your MCP configuration file (e.g., claude_desktop_config.json or Cursor settings):

☁️ YAR.INK Cloud SaaS Connection (Recommended)

{
  "mcpServers": {
    "hyperspacedb": {
      "command": "npx",
      "args": ["-y", "mcp-hyperspacedb"],
      "env": {
        "HYPERSPACE_HOST": "the.yar.ink",
        "HYPERSPACE_API_KEY": "sk_YOUR_API_KEY"
      }
    }
  }
}

🏠 Local / Self-Hosted Instance

{
  "mcpServers": {
    "hyperspacedb": {
      "command": "npx",
      "args": ["-y", "mcp-hyperspacedb"],
      "env": {
        "HYPERSPACE_HOST": "localhost:50051",
        "HYPERSPACE_API_KEY": "I_LOVE_HYPERSPACEDB"
      }
    }
  }
}

🧠 Agent Memory & Hyperbolic Hierarchy

HyperspaceDB operates on a hybrid $H^{33} \times \mathbb{R}^{768}$ vector geometry native space. When using Agent Memory, LLM agents can query and manipulate cognitive structures via:

• hyperspace_get_concept_parents: Retrieve parent hypernym concepts in Lorentz space ($H^{33}$).
• hyperspace_get_subsumption_tree: Trace full taxonomic subsumption trees starting from any concept ID.
• hyperspace_analyze_thought_stability: Check Chain-of-Thought (CoT) convergence using Lyapunov exponents to detect hallucinations.
• hyperspace_search_text: Natural language memory lookup with 96D MRL RAM HNSW scan + 801D Disk payload rerank.

🧩 Available Tools

Data Tools

• hyperspace_list_collections: Get all active collections.
• hyperspace_create_collection: Setup new memory spaces with specific geometry.
• hyperspace_delete_collection: Permanently delete a collection and all of its vectors.
• hyperspace_insert_text: Store new facts into the DB.
• hyperspace_delete_points: Delete a single vector point from a collection by its ID.
• hyperspace_get_points: Retrieve vector coordinate and metadata for a list of point IDs.
• hyperspace_search_text: Query the DB using semantic similarity.
• hyperspace_search_wasserstein: Advanced cross-feature distribution search.

Graph & AI Tools

• hyperspace_get_neighbors: Explore local connectivity in the vector graph.
• hyperspace_get_concept_parents: Retrieve parent concepts in a hierarchical collection.
• hyperspace_get_subsumption_tree: Retrieve the Lorentz hierarchy subsumption tree starting from a given root ID.
• hyperspace_explore_graph: Traverse the graph and return nodes and links in a format ready for visualization.
• hyperspace_graph_traverse: Perform multi-hop logical exploration.
• hyperspace_find_clusters: Identify thematic regions in vector space.
• hyperspace_predict_momentum: Forecast future agent thought paths using Koopman momentum extrapolation.
• hyperspace_get_trust_score: Evaluate stability and trust score for a given thought trajectory path.
• hyperspace_analyze_thought_stability: Validate Chain of Thought (CoT) stability.
• hyperspace_analyze_geometry: Run Gromov Delta analysis on raw vectors.

System & Cache Tools

• hyperspace_get_stats: Telemetry on cluster health, clocks, and vector volume.
• hyperspace_rebuild_index: Rebuild and optimize the HNSW index on the server for a specific collection.
• hyperspace_vacuum: Perform vacuuming on the database to permanently purge deleted vectors and reclaim disk space.
• hyperspace_trigger_reconsolidation: Manually trigger "AI Sleep Mode" (Flow Matching optimization) for a collection.
• hyperspace_freeze_collection: Freeze a collection to make it read-only, preventing new inserts.
• hyperspace_unfreeze_collection: Unfreeze a previously frozen collection to allow inserts again.
• hyperspace_cache_stats: Get cache statistics (hits, misses, policy, etc.) for a specific collection's L0 Hot Tier Cache.
• hyperspace_cache_clear: Clear/purge all items in the L0 Cache for a specific collection.
• hyperspace_cache_config: Update L0 Cache configuration (eviction policy, ANN threshold) for a specific collection.

👨‍💻 Development

To run in development mode with live logs:

npm run dev

📜 License

MIT