Seahorse RAG

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).

Method	Retrieval mode	Measured top result	Target hit @1	Time
Vector-only baseline	same embeddings, cosine top-1, no graph expansion	On Raspberry Pi 5, that kind of slowdown usually means memory pressure rather than a CPU bottleneck.	No	0.752 ms
Seahorse	graph retrieval + phrase expansion + synonym linking	Raspberry Pi 5 users often enable zram so compressed pages stay in memory before disk swap.	Yes	3379.842 ms

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.

Quick Start

If you want to...	Run this
Most users: try the MCP server immediately	uvx --from git+https://github.com/pch8286/seahorse-rag-mcp.git seahorse-server
Install the local CLI	git clone https://github.com/pch8286/seahorse-rag-mcp.git && cd seahorse-rag-mcp && pip install .
Develop or run tests	git clone https://github.com/pch8286/seahorse-rag-mcp.git && cd seahorse-rag-mcp && pip install -e ".[dev]"

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

Surface	What it does	Example
seahorse-server	Runs the MCP stdio server	uvx --from git+https://github.com/pch8286/seahorse-rag-mcp.git seahorse-server
add_document(text)	Adds text into the graph	Store notes, docs, facts, preferences
search(query, session_id)	Retrieves linked context	Ask follow-up questions across multiple indexed passages
upsert_memory(...)	Writes structured high-integrity memory	Save preferences, rules, decisions
delete_memory(...)	Removes structured memory by key	Clean up outdated facts
graph://stats	Exposes graph stats as an MCP resource	Inspect node / edge counts
seahorse CLI	Local indexing and search without an MCP client	seahorse index ..., seahorse search ...

What Gets Created

After you use it	Where it appears	Why you care
Local graph database	./data/knowledge_graph.db	Your indexed memory persists here
Optional ONNX model bundle	models/gliner_onnx	Used for local entity extraction
Optional quantized embedding bundle	models_quantized/...	Used for faster local embedding on constrained hardware
Possible upstream model cache	platform-specific Hugging Face cache	First-time model downloads may also populate external caches

Performance On This Pi 5

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

Metric	Result	Why it matters
Startup ready	11.167s	Full model warmup before first heavy real query
Search latency	6.098s/query	Tiny public smoke-eval average on this machine
Indexing duration	43.164s for 4 docs	Small-batch local ingestion reference
Peak RSS	1476 MB	Important on 4GB edge hardware
Public smoke eval	100% raw recall, 99.17% adaptive recall	Tiny public sanity set, not a leaderboard benchmark

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

If you want to...	Recommended path
Try Seahorse as an MCP server without cloning the repo	uvx --from git+https://github.com/pch8286/seahorse-rag-mcp.git seahorse-server
Install the CLI locally on your machine	Clone the repo and run pip install .
Develop, run tests, or edit the code	Clone the repo and run pip install -e ".[dev]"

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

Variable	Default	Description
GLINER_MODEL	fastino/gliner2-multi-v1	Default GLiNER fallback model id (Hugging Face).
GLINER_ONNX_PATH	models/gliner_onnx	Local ONNX GLiNER bundle directory.
GLINER_ONNX_REPO_ID	lmo3/gliner2-multi-v1-onnx	ONNX GLiNER repo id for auto/setup download.
GLINER_ONNX_AUTO_SETUP	True	Auto-download ONNX GLiNER when local bundle is missing.
HIPPO_PERFORMANCE_PROFILE	auto	auto, low, mid, or high.
HIPPO_NODE_MAX	None	Override profile's max nodes limit.
HIPPO_MEMORY_ALPHA	None	Override memory allocation fraction (e.g. 0.1).
RERANK_ENABLED	False	Enable local cross-encoder reranker.
RERANK_MODEL_PATH	None	Path to reranker ONNX model (.onnx).
RERANK_TOKENIZER_PATH	None	Path to reranker tokenizer.json.
RERANK_TOP_N	20	Number of top PPR candidates passed to fusion.
RERANK_FUSION_METHOD	weighted_sum	weighted_sum or rrf.
RERANK_W_PPR	0.7	PPR fusion weight (auto-normalized with rerank weight).
RERANK_W_RERANK	0.3	Reranker fusion weight (auto-normalized with PPR weight).
RERANK_RRF_K	60	RRF constant k.
RERANK_MODEL_MAX_LEN	512	Cross-encoder max input length.
RERANK_QUERY_MAX_LEN	64	Query token cap before packing.
RERANK_PASSAGE_MAX_LEN	448	Passage token cap before packing.

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.

Question	What to expect on this Pi 5 (4GB)	Confidence
Can it start quickly?	Time-to-interactive was about 0.01s, but full model readiness took about 11.17s.	High
Can it answer searches locally?	On a tiny public smoke set, average search latency was about 6.10s/query.	Medium
Can it index small batches?	Indexing 4 docs took about 43.16s end-to-end on the current setup.	Medium
How much memory does it use?	Peak RSS reached about 1476 MB during indexing/retrieval on this 4GB machine.	High
Is there a public sanity check?	The tiny public eval set reached 100% raw recall and 99.17% adaptive recall.	Medium

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

🧪 Measured On This Machine

Component	Value
Date	2026-04-11
Machine	Raspberry Pi 5 Model B Rev 1.1
CPU	Cortex-A76, 4 cores, 2.4 GHz
RAM	4 GB
Swap / zram	2 GB
OS	Debian 13 (trixie), aarch64
Python	3.13.5

Metric	Result	Notes
Startup TTI	0.014s	CLI becomes interactive quickly before full model warmup
Startup ready	11.167s	Models loaded and ready for first real use
Peak RSS at ready	1185 MB	During startup warmup
Indexing duration	43.164s	4 docs from the public eval set, batch size 1
Indexing throughput	0.093 docs/s	Tiny public set, not a throughput leaderboard
Retrieval avg latency	6.098s/query	5 queries from the public eval set
Retrieval peak RSS	1476 MB	Peak resident set during retrieval run
SQLite smoke query	10.600s	Includes engine/model startup overhead in the benchmark path

Public Smoke Eval

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

Public dataset	Docs	Queries	Metric	Result	Interpretation
scripts/data/eval_scenarios.json	4	5	Raw recall	100.00%	All tiny-set targets were recovered by the current heuristic check
scripts/data/eval_scenarios.json	4	5	Adaptive recall	99.17%	Slightly penalized version of recall that factors estimated node usage
scripts/data/eval_scenarios.json	4	5	Drift control	100.00%	On this tiny set, irrelevant-topic drift was rejected cleanly
scripts/data/eval_scenarios.json	4	5	Linkage density	5.33	Phrase-to-phrase linkage remained dense after synonym optimization

🏗️ 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.

Metric	Seahorse	Vector-only baseline	Status
Peak raw recall	72.0%	22.4%	Internal snapshot
Adaptive recall	20.2%	14.8%	Internal snapshot
Context control	100.0%	100.0%	Internal snapshot
Token savings	71.3%	-131.4%	Internal snapshot
Startup time	< 1.2s	< 1.0s	Internal snapshot

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.

Profile	Node budget	Intended memory range	Bias	Best use case
Max Profile	Uncapped	16GB+	Quality-first	Server or desktop evaluation
High Profile	10,000	8GB+ edge boxes	Higher recall	Heavier local retrieval
Mid Profile	5,000	4GB to 8GB-class edge devices	Balanced	Everyday Pi usage
Low Profile	2,000	Tight-memory environments	Latency/memory-first	Strict constrained mode

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.