Trigger Scenarios

MCP Claude Desktop Cursor MCP hyperspace_search hyperspace_insert model context protocol mcp-hyperspacedb tool use

Install

npx skills add YARlabs/hyperspace-db --skill hyperspacedb-mcp -g -y

More Options

Non-standard path

npx skills add https://github.com/YARlabs/hyperspace-db/tree/main/integrations/hyperspacedb-skills/skills/hyperspacedb-mcp -g -y

Use without installing

npx skills use YARlabs/hyperspace-db@hyperspacedb-mcp

指定 Agent (Claude Code)

npx skills add YARlabs/hyperspace-db --skill hyperspacedb-mcp -a claude-code -g -y

安装 repo 全部 skill

npx skills add YARlabs/hyperspace-db --all -g -y

预览 repo 内 skill

npx skills add YARlabs/hyperspace-db --list

SKILL.md

Frontmatter

{
    "name": "hyperspacedb-mcp",
    "description": "Model Context Protocol (MCP) server for HyperspaceDB. Use this skill to configure, connect, and use HyperspaceDB tools in Claude Desktop, Cursor, Windsurf, Antigravity, or any MCP-compatible AI host. Covers all 30+ available MCP tools. Trigger on: \"MCP\", \"Claude Desktop\", \"Cursor MCP\", \"hyperspace_search\", \"hyperspace_insert\", \"model context protocol\", \"mcp-hyperspacedb\", \"tool use\"."
}

HyperspaceDB MCP Servers

HyperspaceDB provides two official Model Context Protocol (MCP) servers:

mcp-hyperspacedb (Database Plane, v4.0.0): 27 tools for collection DDL, vector CRUD, HNSW graph traversal, Lyapunov stability analysis, Gromov delta hyperbolicity, and Koopman momentum.
mcp-hyperspace-memory (Cognitive Memory Plane, v1.0.0): 8 tools for autonomous agent memory, episodic facts, session isolation, Fréchet mean consolidation, and hallucination verification.

Setup & Configuration

Add to your MCP config file (e.g., claude_desktop_config.json, .cursor/mcp.json):

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

Config file locations by host:

Host	Config path
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`.cursor/mcp.json` in project root
Windsurf	`~/.windsurf/mcp.json`
Antigravity / custom	Per host documentation

Environment Variables

Variable	Default	Description
`HYPERSPACE_HOST`	`localhost:50051`	gRPC address of HyperspaceDB node
`HYPERSPACE_API_KEY`	`I_LOVE_HYPERSPACEDB`	Authentication key

Never hardcode these values. Always pass via environment variables.

Complete Tool Reference

📁 Collection Management

Tool	Description
`hyperspace_list_collections`	List all collections with stats
`hyperspace_create_collection`	Create a new collection (name, dimension, metric: cosine/l2/lorentz/poincare/hybrid, cascadePipeline)
`hyperspace_delete_collection`	Permanently delete a collection and all vectors
`hyperspace_freeze_collection`	Make collection read-only
`hyperspace_unfreeze_collection`	Re-enable inserts
`hyperspace_rebuild_index`	Rebuild and optimize the HNSW index
`hyperspace_vacuum`	Purge soft-deleted vectors, reclaim disk space

📥 Data Operations

Tool	Description
`hyperspace_insert_text`	Insert text (auto-embedded server-side)
`hyperspace_delete_points`	Delete a vector by ID
`hyperspace_get_points`	Retrieve vectors by IDs

🔍 Search

Tool	Description
`hyperspace_search_text`	Semantic search by text query; supports `hybrid_alpha` for BM25 fusion
`hyperspace_search_wasserstein`	Optimal Transport cross-distribution search

🕸️ Graph & Hierarchy

Tool	Description
`hyperspace_get_neighbors`	Direct HNSW neighbors of a node
`hyperspace_graph_traverse`	BFS/DFS multi-hop traversal
`hyperspace_explore_graph`	Visualization-ready graph data (nodes + edges)
`hyperspace_get_subsumption_tree`	Lorentz hierarchy tree from a root concept
`hyperspace_get_concept_parents`	Parent concepts in the hierarchy
`hyperspace_find_clusters`	Unsupervised cluster detection

🧠 Cognitive AI

Tool	Description
`hyperspace_analyze_thought_stability`	Lyapunov CoT convergence analysis (returns `{ lyapunov_exponent, is_stable }`)
`hyperspace_predict_momentum`	Koopman trajectory momentum forecast (returns `number[]` — next vector)
`hyperspace_get_trust_score`	Composite reasoning trust score (returns `number` 0–1)
`hyperspace_analyze_geometry`	Gromov Delta analysis → optimal metric (cosine/l2/lorentz/poincare/hybrid)

⚙️ System & Cache

Tool	Description
`hyperspace_get_stats`	Node telemetry, vector counts, clock
`hyperspace_trigger_reconsolidation`	Trigger Flow Matching sleep-mode optimization
`hyperspace_cache_stats`	L0 cache hit/miss statistics
`hyperspace_cache_clear`	Clear L0 cache for a collection
`hyperspace_cache_config`	Update cache eviction policy and ANN threshold

Example Prompts

Once connected, you can say to your AI agent:

"Create a collection called 'team_memory' with cosine metric and 1536 dimensions."

"Search 'team_memory' for documents about Kubernetes deployments."

"Analyze the geometry of these vectors and tell me the best metric to use."

"Check if my reasoning chain [ids: 1,2,3,4,5] is stable or diverging."

"Show me the parent concepts of node 42 in 'knowledge_graph'."

"What are the main topic clusters in 'research_papers'?"

How Cognitive Tools Work

The MCP server implements cognitive tools as client-side computations:

getPoints() fetches the stored vectors for the given trajectory IDs
Mathematical analysis (Lyapunov, Koopman, trust) runs inside the MCP server process
Results are returned without any server-side RPC for the math itself

This means cognitive tools work against any version of the HyperspaceDB server.

Geometry awareness: When collection metric is hybrid, momentum extrapolation splits the vector into Lorentz (first 33 dims) and Euclidean (remaining dims) parts, extrapolates each independently, then recombines.

hyperspacedb-mcp