Seahorse RAG MCP

Seahorse RAG MCP is a local MCP memory server for edge devices that can connect related facts across passages instead of only returning the nearest lexical match.

Quick Proof

Measured on the committed fixture scripts/data/proof_pi5_zram.json on this Raspberry Pi 5 (4GB).

Proof query: What should I switch on when a Pi 5 starts crawling during on-device inference?

Proof artifact: docs/proofs/pi5_zram_proof_2026-04-11.json

This is a small measured repro case, not a comprehensive benchmark. Results may change with different corpora, models, or hardware.

Actual CLI example:

seahorse index --text "Raspberry Pi 5 can bog down when a local model overruns RAM."
seahorse index --text "On Raspberry Pi 5, that kind of slowdown usually means memory pressure rather than a CPU bottleneck."
seahorse index --text "Raspberry Pi 5 users often enable zram so compressed pages stay in memory before disk swap."
seahorse search "What should I switch on when a Pi 5 starts crawling during on-device inference?"

Indexing content...
Indexing complete.
Indexing content...
Indexing complete.
Indexing content...
Indexing complete.
Searching for: What should I switch on when a Pi 5 starts crawling during on-device inference?

Results:
Raspberry Pi 5 users often enable zram so compressed pages stay in memory before disk swap.

Related MCP server: budget-aware-mcp

Quick Start

uvx ... seahorse-server and seahorse run both start a long-lived stdio MCP server. A quiet terminal with the process still running is the expected success state until an MCP client connects.

What You Get

What Gets Created

Performance On This Pi 5

These are reproducible operational numbers measured on a Raspberry Pi 5 (4GB) on 2026-04-11.

Full snapshot and caveats: docs/PERFORMANCE_SNAPSHOT_PI5_2026-04-11.md

This proof is generated by scripts/proof_baseline.py. Candidate fixture search lives in scripts/search_proof_candidates.py.

Who It's For

• MCP users who want a local memory/search server behind tools like Claude Desktop, Cursor, Windsurf, or OpenClaw.

• Agent builders who want a small Python package exposing graph-backed retrieval rather than standing up a separate vector database service.

• Edge/offline tinkerers who care about retrieval quality on constrained machines such as Raspberry Pi 5.

This is a better fit if you want graph-backed retrieval and local control. It is not meant to replace a full hosted search stack or a general-purpose cloud vector database.

🎯 Use Cases

Seahorse is designed for high-precision retrieval in environments where reliability and offline capability are paramount:

• Personal Knowledge Assistant: Index your notes and local documents for a second brain that works 100% offline.

• Technical Manuals: Gives field engineers high-recall access to complex equipment manuals without needing an internet connection.

• Field Operations: Fast, secure RAG for agents who need to reason over mission-critical data in the field.

• Smart Homes: Helps local LLMs understand the relationships between devices, routines, and user habits.

Features

• HippoRAG 2 Architecture: Uses passage and phrase nodes with dense-sparse integration.

• Reliability: Hub-aware residual teleport (p_self, alpha, seed-hub t_H), sink handling for dangling nodes, and recursion safety to prevent search explosions.

• Edge Performance: Built on SQLite for storage (no heavy in-memory loading), uses GLiNER for extraction, and iGraph for fast retrieval.

• Local INT8 Re-ranking: Optional ONNX cross-encoder reranker for Top-N precision lift without LLM dependency.

• Memory Management: Automatically adjusts retrieval depth based on system RAM and zram.

• Contextual Search: Tracks your conversation history to improve relevance while preventing "echo chambers" through drift control.

• MCP Native: Plugs directly into any MCP-compliant agent as a tool or skill.

Retrieval Status

• Default path: igraph.personalized_pagerank (stable production mode).

• Applied improvements: dynamic node budget, typed fanout cap, type budget pruning, degree-based hub self-loop, residual teleport, seed-hub self-return suppression, dynamic damping.

• Future work (optional mode):

  • Truncated PPR (K-step) with mass-policy checks.

  • COO one-shot sparse step kernel + fully vectorized 2-pass pruning for very large edge sets.

🚀 Quick Start

0. Choose Your Path

1. Prerequisites

• Python 3.11+

• pip or uv

• On Linux/ARM systems, be ready to install libigraph-dev if a suitable python-igraph wheel is not available

For the fastest experience and pre-built wheel support, we recommend uv:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Helpful on systems where python-igraph needs system headers
sudo apt-get install -y libigraph-dev

1.1 What You Actually Need To Install

• Just run the server locally: Python 3.11+, then pip install . or use uvx.

• Develop or run tests: pip install -e ".[dev]".

• Use vector search reliably: a Python build with SQLite loadable extension support.

• Use the ONNX GLiNER path: run seahorse models once after install.

2. Run Without Cloning

This is the fastest copy-paste path if you just want a portable MCP server process:

uvx --from git+https://github.com/pch8286/seahorse-rag-mcp.git seahorse-server

The expected success state is a long-running process waiting on stdio for an MCP client.

3. Clone And Install Locally

git clone https://github.com/pch8286/seahorse-rag-mcp.git
cd seahorse-rag-mcp
pip install .

For development:

pip install -e ".[dev]"

3.1 Development And Test Setup

If you want to run the test suite, install the dev extra first:

pip install -e ".[dev]"
pytest -q

Optional pyenv workflow:

pyenv exec python -V
pyenv exec python -m pytest -q

4. OpenClaw Preset

The repository ships an OpenClaw preset at presets/openclaw.json. The preset is the reusable integration surface. The raw uvx --from ... seahorse-server command above is just the underlying portable launch command.

5. Vector Search Requirement

Vector Search requires SQLite Extension Support. Standard Python builds on some platforms (e.g., Ubuntu/Debian system Python) may be compiled without --enable-loadable-sqlite-extensions.

• If extensions are unavailable, Seahorse will safely disable vector search and fall back to pure graph traversal.

• To enable vector search, ensure your Python environment supports sqlite3.enable_load_extension.

6. Run The Server

Start the server directly:

seahorse run

This also stays alive as a long-running stdio MCP server rather than printing a short demo result.

Legacy compatibility commands pam run and hippo run are still supported.

6.1 One-Time Model Setup

Download/prepare ONNX GLiNER bundle:

seahorse models

This uses the default repo lmo3/gliner2-multi-v1-onnx and local dir models/gliner_onnx. If seahorse is not installed on PATH yet, run the Python module entrypoint:

python -m seahorse.cli models

Legacy python -m edge_hippo.cli models still works.

6.2 What The MCP Server Exposes

• Tool: add_document(text)

• Tool: search(query, session_id="default")

• Tool: upsert_memory(key, value, scope="global", kind="fact", ...)

• Tool: delete_memory(key, scope="global")

• Resource: graph://stats

7. CLI Usage (Optional)

Manage the knowledge graph from your terminal:

# Show stats
seahorse stats

# Index text
seahorse index --text "Raspberry Pi 5 is the latest model."

# Link synonyms (Critical for hybrid search)
seahorse optimize-graph --threshold 0.6

# Search
seahorse search "RPi 5"

Example: End-To-End CLI

seahorse index --text "Raspberry Pi 5 has 8GB of RAM."
seahorse index --text "ZRAM can reduce memory pressure on Raspberry Pi devices."
seahorse search "How can I reduce memory pressure on Raspberry Pi 5?"

Typical indexing output:

Indexing content...
Indexing complete.

Typical search output:

Searching for: How can I reduce memory pressure on Raspberry Pi 5?

Results:
ZRAM can reduce memory pressure on Raspberry Pi devices.

Runtime Notes

• Default storage path: ./data/knowledge_graph.db

• Settings can be overridden with environment variables or a local .env file

• First use may auto-download model assets if GLINER_ONNX_AUTO_SETUP=True

• If you want deterministic setup for demos or deployment, run seahorse models before starting the server

⚙️ Configuration

Reranker Activation Example

export RERANK_ENABLED=true
export RERANK_MODEL_PATH=/absolute/path/to/model_quantized.onnx
export RERANK_TOKENIZER_PATH=/absolute/path/to/tokenizer.json
export RERANK_TOP_N=20
export RERANK_FUSION_METHOD=weighted_sum

Reranker Fixed Behavior (Summary)

• Dedup by passage_id is applied before Top-N selection.

• top_n=0 falls back immediately to PPR-only.

• top_n=1 is zero-division safe (s_ppr=1.0).

• Input weights are auto-normalized by w_ppr + w_rerank; non-positive sum falls back.

• Pair tokenization uses manual [CLS] query [SEP] passage [SEP] packing with only_second overflow trimming.

• ORT inputs are fixed int64; logits are processed in float32.

🧠 Contextual Re-ranking

Weighted context from previous turns is automatically applied to search results if session_id is reused.

• Drift Control: Automatically detects topic shifts and flushes context if the new query is topologically disconnected from history.

• Preserves Narrative: Keeps relevant entities in the "Reset Vector" for PPR to maintain focus.

✅ Core Coverage (85%+ Gate)

Run concise core tests (reranker + retrieval) with module-level coverage threshold:

./scripts/test_core_coverage.sh

🔌 Integrations

1. Generic MCP Client

To use Seahorse with any MCP-compliant agent (such as Cursor, Windsurf, or your own custom agent), add the following to your agent's configuration:

{
  "mcpServers": {
    "seahorse-rag-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/pch8286/seahorse-rag-mcp.git",
        "seahorse-server"
      ]
    }
  }
}

If you already installed the package locally, you can also use command: "seahorse" with args: ["run"].

2. Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "seahorse-rag-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/pch8286/seahorse-rag-mcp.git",
        "seahorse-server"
      ]
    }
  }
}

3. OpenClaw

We provide a pre-configured preset for OpenClaw at presets/openclaw.json.

📈 Performance At A Glance

Numbers below were measured on this exact Raspberry Pi 5 4GB machine on 2026-04-11. Treat them as operational reference numbers for this hardware, not guarantees for other environments.

For the full snapshot, commands, and caveats, see docs/PERFORMANCE_SNAPSHOT_PI5_2026-04-11.md.

🧪 Measured On This Machine

Public Smoke Eval

This is a tiny public sanity set for regression checking, not a leaderboard benchmark.

🏗️ Architecture & Optimization

For detailed architecture decisions, data schema, and Raspberry Pi 5 specific optimizations, refer to TECH_SPEC.md.

Internal Benchmark Snapshot

The following numbers come from a larger internal benchmark snapshot comparing Seahorse against a vector-only baseline. The exact corpus and harness are not fully published in this repository yet, so treat these numbers as directional architecture evidence, not a public scorecard.

Recall vs. Node Budget (Scalability)

Seahorse dynamically adjusts its search depth based on available RAM. The table below reflects intended tradeoffs from the same internal benchmark snapshot above rather than a fresh public repro.

Bottom line: the public numbers you can reproduce today are the Pi 5 operational snapshot and the tiny smoke eval above. The larger comparative recall claims remain informative, but they should be read as internal evidence until the full benchmark corpus is published.

📚 References & Research

This implementation is based on the following research papers:

1. HippoRAG 2: https://arxiv.org/pdf/2502.14802

2. Edge-Optimized GraphRAG: https://arxiv.org/pdf/2602.01965

3. Dense-Sparse Integration: https://arxiv.org/pdf/2510.08958

Public snapshot in this README was measured on a Raspberry Pi 5 (4GB). Older internal benchmark notes may come from different Pi 5 or server-class configurations.

License

This project is licensed under the MIT License. See LICENSE.

Downloaded model assets are not covered by this repository's MIT license. If you use automatically downloaded GLiNER or other upstream model artifacts, you must also comply with the licenses and terms attached to those upstream models.