Skip to main content
Glama
mcp-hyperspace-memory

mcp-hyperspace-memory

Official
by YARlabs

mcp-hyperspace-memory

Zero-Code cognitive memory for AI agents — powered by HyperspaceDB SaaS.
8 tools. One config block. No code required.

What is this?

mcp-hyperspace-memory is a Model Context Protocol (MCP) server that gives your AI agent a production-grade, persistent memory backed by HyperspaceDB's hyperbolic vector engine.

It is intentionally scoped to memory operations only — no DDL, no collection management, no admin tools. If you need full vector DB access, use mcp-hyperspacedb alongside it.


Related MCP server: AGI MCP Server

Quick Start

Claude Desktop / Cursor IDE / Windsurf / OpenWebUI

Add to your MCP config (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-hyperspace-memory"],
      "env": {
        "HYPERSPACE_API_KEY": "<YOUR_API_KEY>",
        "MEMORY_COLLECTION": "agent_memory"
      }
    }
  }
}

That's it. Restart your agent and it will discover 8 memory tools automatically.

Get your API key at yar.ink/dashboard.


Environment Variables

Variable

Default

Required

Description

HYPERSPACE_API_KEY

—

✅

Database API key (sk_... for SaaS or your local DB password)

HYPERSPACE_ENCRYPTION_KEY

—

—

Client-side Zero-Knowledge encryption key (activates orthogonal/Lorentz projection + AES-256-GCM payload encryption)

CDE_API_KEY / YAR_API_KEY

—

—

Cloud API key for v5_Embedding_801 (used when local DB has a custom password)

MEMORY_COLLECTION

agent_memory

—

Collection name to store memories in

HYPERSPACE_HOST

the.yar.ink

—

Set to localhost:50051 to run with a self-hosted instance


🔑 Authentication Architecture: How Keys Work

Scenario 1: Managed Cloud SaaS (the.yar.ink)

{
  "HYPERSPACE_API_KEY": "sk_YOUR_YAR_API_KEY",
  "MEMORY_COLLECTION": "agent_memory"
}

A single sk_ key authenticates both your HyperspaceDB SaaS database storage and the v5_Embedding_801 vectorizer.

Scenario 2: Local DB (Default Security) + Cloud v5 Embeddings

{
  "HYPERSPACE_HOST": "localhost:50051",
  "HYPERSPACE_API_KEY": "sk_YOUR_YAR_API_KEY",
  "MEMORY_COLLECTION": "agent_memory"
}

Because the host is localhost and the key starts with sk_, the client connects to your local DB with default credentials (I_LOVE_HYPERSPACEDB), while forwarding sk_... to https://the.yar.ink/v1/embeddings for high-dimensional vectorization. Data stays 100% on your local disk!

Scenario 3: Local DB (Custom Password) + Cloud v5 Embeddings (Two Separate Keys)

If you configured a custom password in your local .env (HYPERSPACE_API_KEY=my_local_secret), provide two distinct keys:

{
  "HYPERSPACE_HOST": "localhost:50051",
  "HYPERSPACE_API_KEY": "my_local_secret",
  "YAR_API_KEY": "sk_YOUR_YAR_API_KEY",
  "MEMORY_COLLECTION": "agent_memory"
}
  • HYPERSPACE_API_KEY: Authenticates to the local gRPC server (localhost:50051).

  • YAR_API_KEY: Authenticates to the cloud embedding API (https://the.yar.ink/v1/embeddings).

Available Tools

Tool

Description

memory_remember

Store a memory, fact, or procedure with session_id, memory_type (semantic, episodic, procedural), importance (1-10), and optional tags

memory_recall

Semantic search with importance boost, recency half-life decay, and candidate oversampling, filterable by session_id, memory_type, or min_importance

memory_forget

Delete a specific memory by ID

memory_update

Atomically replace an existing memory (delete + store new version with refreshed embeddings)

memory_list_sessions

Enumerate unique active session_ids with multi-probe semantic discovery

memory_explore_hierarchy

Navigate Lorentz hyperbolic concept tree (broader vs narrower concepts)

memory_consolidate

Synthesize clusters of memories into a single abstract Fréchet Mean hyperbolic concept vector with optional persistence and source archiving

memory_verify_claim

Mathematical anti-hallucination verification using 129D MRL hybrid (Lorentz + Cosine) space with adaptive trust threshold

memory_link

Explicitly connect two memory/concept entities with a directed, labeled, weighted edge in the native CSR vector-graph

memory_unlink

Delete an explicit directed edge with zero-lag invalidation

memory_induce_edges

Declaratively induce knowledge graph edges across memory entries from existing metadata attributes (path_hierarchy, foreign_key, exact_match)

hyperspace_query_planner

Enterprise Query Planner & Intent Disambiguator: detects ambiguous user queries, generates multiple-choice clarifying questions, or splits compound questions into parallel sub-queries

memory_stats

Diagnostic status report showing vector count, collection health, and active indexing schema


🧪 Testing & Verification

Run the test suite against your cluster or local instance:

# 1. Comprehensive verification (all 9 tools + session isolation)
npm test

# 2. Brutal high-concurrency stress test (30 parallel memories, NIAH recall, Fréchet consolidation)
npm run test:stress

Architecture

Agent (Claude / Cursor)
    ↓  MCP stdio
mcp-hyperspace-memory (this package)
    ↓  gRPC / hyperspace-sdk-ts
HyperspaceDB SaaS (the.yar.ink)
    └─ MEMORY_COLLECTION  (e.g. "agent_memory")
         ├─ Lorentz head  (33D, f32, hyperbolic hierarchy)
         └─ Euclidean head (768D, 1-bit ADC, 61.4× compressed)

Key design decisions

  • MEMORY_COLLECTION in env: The agent never needs to pass the collection name per-call. One env var scopes all memory to the right namespace.

  • Deterministic IDs: Memory IDs are hash(text + session_id) — inserting the same memory twice is idempotent.

  • SaaS default: HYPERSPACE_HOST defaults to the.yar.ink. Self-hosted instances work by setting the env var.

  • No admin tools: No create_collection, delete_collection, or rebuild_index. Memory users never need these.


Comparison with mcp-hyperspacedb

Feature

mcp-hyperspace-memory

mcp-hyperspacedb

Target user

AI agent end-user

Developer / DevOps

Collection management

❌

✅

Cache control

❌

✅

Cognitive memory tools

✅ (8 tools)

❌

Works local + SaaS

SaaS-only

✅ both

Config complexity

1 API key

host + API key


Self-Hosting

{
  "env": {
    "HYPERSPACE_HOST": "localhost:50051",
    "HYPERSPACE_API_KEY": "I_LOVE_HYPERSPACEDB",
    "MEMORY_COLLECTION": "my_memory"
  }
}

License

MIT — © YARlabs
Docs: yar.ink/memory

Available Tools

16 tools
hyperspace_query_plannerB

Enterprise Query Planner & Intent Disambiguator. Evaluates raw user queries before issuing memory retrieval. Detects ambiguous intent, returns multiple-choice questions for the user, or splits compound questions into parallel sub-queries.

Inputs: raw_user_query (required), context, collections, max_sub_queries.

memory_consolidateA

Consolidate a cluster of related episodic memories into a single abstract semantic concept using the Fréchet Mean on the hyperboloid. Optionally stores the synthesized summary_text back into memory (persist: true) and cleans up source memories (archive_sources: true). Returns a JSON report with consolidated_id, mean vector, and source IDs.

Inputs: topic_query (required), limit, persist, summary_text, +1 more.

memory_explore_hierarchyB

Explore conceptual hierarchy in memory using Lorentz Cone Subsumption. 'up' navigates to parent/hypernym concepts; 'down' returns the subsumption tree of descendant concepts. Returns a JSON structure of the hierarchy.

Inputs: direction (required), concept_id (required), limit.

memory_forgetC

Delete a specific memory by numeric memory_id from collection 'agent_cognitive_memories_129'. Returns a JSON object with success status and confirmation message.

Inputs: memory_id (required).

memory_induce_edgesB

Declaratively induce explicit graph edges across memory entries from existing metadata attributes (path_hierarchy, foreign_key, exact_match).

Inputs: rules (required).

memory_list_sessionsB

Discover unique session_ids and active conversation threads present in collection 'agent_cognitive_memories_129'. Uses multi-probe vector queries to ensure comprehensive session discovery. Returns a JSON object with session_count and list of sessions with memory counts and recent sample previews.

Inputs: limit.

memory_query_plannerD

Alias for hyperspace_query_planner.

Inputs: raw_user_query (required), context, collections, max_sub_queries.

memory_recallA

Retrieve the most relevant memories for a query from collection 'agent_cognitive_memories_129' using semantic similarity. Filter by session_id, memory_type ('semantic'|'episodic'|'procedural'), or min_importance (1-10). Returns a JSON object with query, filters, and ranked memories with cognitive scores.

Inputs: query (required), limit, session_id, memory_type, +1 more.

memory_rememberA

Store a new memory, event, fact, or procedure for the agent in collection 'agent_cognitive_memories_129'. Automatically vectorizes text and stores with session_id, tags, memory_type (semantic, episodic, procedural), and importance (1-10). Returns a JSON object with memory_id, status, and metadata summary.

Inputs: text (required), session_id (required), tags, importance, +1 more.

memory_statsA

Get operational statistics and health diagnostics for the memory collection 'agent_cognitive_memories_129'. Returns a JSON object with total vector count, dimension, metric, cascade settings, and host information.

Inputs: no named parameters.

memory_updateA

Update an existing memory by deleting memory_id and storing new_text with refreshed embeddings and metadata. Returns a JSON object with old_memory_id, new_memory_id, and status.

Inputs: new_text (required), memory_id (required), session_id (required), tags, +2 more.

memory_verify_claimA

Verify whether a logical claim (conclusion) is geometrically consistent with a premise in 129D MRL hybrid space (Lorentz + Cosine). Returns a JSON object with status ('VERIFIED'|'REJECTED'), trust_score (0.0-1.0), geodesic distances, and geometric explanation to prevent hallucinations.

Inputs: premise (required), conclusion (required), threshold.

memory_verify_generationC

Tribunal Router: Mathematically verify whether an LLM response stays within the geometric entailment cones and geodesic boundaries of retrieved memory IDs.

Inputs: llm_answer (required), context_ids (required), check_geodesic, max_distance_threshold.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 16 tools

    Disambiguation3/5

    Core memory CRUD tools are clearly distinct, but memory_query_planner is an exact alias of hyperspace_query_planner, creating direct confusion. Several advanced operations also overlap in concept (memory_link/memory_link_batch/memory_induce_edges, and memory_verify_claim/memory_verify_generation), though their descriptions help differentiate them.

    Naming Consistency4/5

    Most tools follow a predictable memory_verb_noun snake_case pattern, such as memory_remember, memory_recall, and memory_forget. The main deviations are hyperspace_query_planner and its duplicate alias memory_query_planner, which break the memory_ prefix convention.

    Tool Count4/5

    At 16 tools, the surface is slightly above the ideal 3-15 range but still reasonable for a feature-rich memory system with graph, hierarchy, consolidation, and verification capabilities. The only clear redundancy is the duplicated query planner alias.

    Completeness4/5

    The server covers the core memory lifecycle well: create, recall, update, delete, list sessions, stats, hierarchy exploration, consolidation, graph linking, and verification. Minor gaps remain around bulk memory operations and explicit session lifecycle management, but no major dead ends are obvious.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with persistent, searchable memory that survives across conversations using semantic search, temporal versioning, and smart organization. Enables long-term context retention and cross-session continuity for AI assistants.
      14
      -
    • F
      license
      B
      quality
      D
      maintenance
      Enables persistent memory for AI systems by providing tools for episodic, semantic, and procedural data storage through a vector-and-graph-enhanced database. It allows models to maintain long-term continuity using similarity search, thematic clustering, and identity tracking.
      24
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides persistent long-term memory for AI agents through semantic search and automated knowledge graph extraction. It enables agents to store, recall, and reason over facts, preferences, and relationships across multiple conversations and sessions.
      14
      6 npm
      MIT