Skip to main content
Glama
mcp-hyperspace-memory

mcp-hyperspace-memory

Official
by YARlabs
README.md
# 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)](https://modelcontextprotocol.io) 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`](../mcp-hyperspacedb) alongside it.

---

## Quick Start

### Claude Desktop / Cursor IDE / Windsurf / OpenWebUI

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

```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](https://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`)
```json
{
  "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
```json
{
  "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**:
```json
{
  "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_id`s 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:

```bash
# 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

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

---

## License

MIT — © YARlabs  
Docs: [yar.ink/memory](https://yar.ink/memory)

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