HyperspaceDB

The ROS2 node links against the C++ SDK, providing native support for Zero-Knowledge client-side encryption. For high-security applications (e.g., protecting sensor readings, maps, or private logs), developers can extend their custom ROS2 nodes by accessing the underlying HyperspaceClient instance.

To ensure data is encrypted before it reaches the cloud or a DePIN server, use the following methods on the HyperspaceClient:

• RegisterCollectionKey: To set up encryption keys for a collection.
• InsertSecure: To perform encrypted insertions.

For high-availability cloud deployments, use the Leader-Follower architecture.

• Leader: Acts as the Coordinator. It handles all Writes, manages cluster topology, and streams Write-Ahead Log (WAL) events.
• Follower: Acts as a read-only replica. Followers can be promoted to Leaders if the current leader fails.

Each node is identified by a unique node_id and uses a Lamport logical clock for ordering.

# Start a Leader node
./hyperspace-server --port 50051 --role leader

# Start a Follower node pointing to the leader
./hyperspace-server --port 50052 --role follower --leader http://127.0.0.1:50051

HyperspaceDB uses a hybrid $H^{33} imes ext{R}^{768}$ vector geometry. For agents managing long-term memory or complex reasoning, the following tools enable interaction with hierarchical cognitive structures:

• Hierarchical Navigation: Use hyperspace_get_concept_parents to find hypernyms in Lorentz space ($H^{33}$) or hyperspace_get_subsumption_tree to trace full taxonomic trees.
• Reasoning Stability: Use hyperspace_analyze_thought_stability to calculate Lyapunov convergence of a Chain of Thought (CoT) trajectory. This helps detect if a model is hallucinating or converging on a stable logical attractor.
• Semantic Retrieval: hyperspace_search_text performs natural language lookups using a 96D MRL RAM HNSW scan combined with an 801D Disk payload rerank.

HyperspaceDB supports MRL via a Cascade Pipeline. This allows for a two-stage retrieval process: performing a fast initial search on a truncated low-dimensional vector (e.g., 64D) and then reranking the top results using the full-dimensional vector (e.g., 1024D).

To implement this, define a cascadePipeline in your CollectionSchema containing MrlLayer objects. You specify the cutoffDimension for the fast search and rerankTopK for the second stage.

final schema = pb.CollectionSchema(
  components: [
    pb.VectorComponent(name: 'main', metric: 'lorentz', fullDimension: 1025)
  ],
  cascadePipeline: [
    pb.MrlLayer(
      componentName: 'main',
      cutoffDimension: 129, // 128D (+1) fast search
      storeInRam: true,
      rerankTopK: 100
    )
  ]
);
await client.createCollection('mrl_docs', schema);

Cognitive tools in the HyperspaceDB MCP server are implemented as client-side computations. This allows them to work against any version of the HyperspaceDB server.

The Workflow:

1. The tool calls getPoints() to fetch the stored vectors for the specific trajectory IDs.
2. Mathematical analysis (such as Lyapunov, Koopman, or trust scores) is performed locally within the MCP server process.
3. The results are returned to the AI host without requiring additional server-side RPC for the mathematical computations.

Geometry Awareness: When a collection uses the hybrid metric, momentum extrapolation handles the vector by splitting it into Lorentz (the first 33 dimensions) and Euclidean (the remaining dimensions) parts. It extrapolates each part independently and then recombines them.

MRL allows for high-performance cascading searches. You define an MrlLayer in the CascadePipeline of your CollectionSchema. This specifies a CutoffDimension for the initial fast search on a truncated vector, and a RerankTopK value for re-ranking results using the full-dimensional vector.

schema := &pb.CollectionSchema{
    Components: []*pb.VectorComponent{
        {Name: "primary", Metric: "lorentz", FullDimension: 1025, Weight: 1.0},
    },
    CascadePipeline: []*pb.MrlLayer{
        {
            ComponentName:   "primary",
            CutoffDimension: 129, // Initial search on 128D (+1)
            StoreInRam:      true,
            RerankTopK:      100,
        },
    },
}
client.CreateCollection(ctx, "mrl_collection", schema)

A thought trajectory is a sequence of vector IDs representing the progression of an agent's reasoning (e.g., each step of a Chain of Thought stored as a vector).

By storing Chain of Thought (CoT) steps in HyperspaceDB, you can apply mathematical analysis to detect hallucinations, measure convergence, and predict future reasoning direction. These tools are implemented as client-side computations in the SDK: they fetch stored vectors via getPoints() and then apply mathematical analysis locally, making them compatible with any version of the HyperspaceDB server.

Supported geometries for cognitive tools:

• lorentz, poincare — full Lorentz/hyperbolic math
• hybrid — applies Lorentz math to first 33 dims, Euclidean to the rest
• cosine, l2 — Euclidean approximations

[id_1: "observe problem"] → [id_2: "form hypothesis"] → [id_3: "test hypothesis"] → ...

HyperspaceDB treats vectors as nodes in a dynamic graph where relationships are inferred from geometry (e.g., Lorentz/Poincare for hierarchy, L2/Cosine for similarity).

• getSubsumptionTree(id1, id2): Extracts directed hierarchies from Lorentz-encoded data.
• traverse({ startId, traversalMode, breadthLimit }): Navigates the graph. traversalMode can be 0: GREEDY, 1: DIFFUSIVE, or 2: MOMENTUM.
• getNeighbors(id): (Implicitly available via graph APIs) Retrieves adjacent nodes.

// Extract directed hierarchies
const tree = await client.getSubsumptionTree(1, 5);

// Navigate the graph
const results = await client.traverse({
    startId: 1,
    traversalMode: 2, // MOMENTUM
    breadthLimit: 5
});