MCP 服务器

MahoRAGa

Persistent, graph-powered memory for AI agents that provides long-term semantic recall using a local Kuzu graph database.

README

<h1 align="center">🧠 MahoRAGa</h1>

<p align="center"> <b>Persistent, graph-powered memory for AI agents.</b><br> <sub>A production-ready MCP server that gives Claude, Cursor, and any agentic framework long-term semantic recall.</sub> </p>

Why MahoRAGa?

If you've ever watched an AI agent solve the same bug twice, you already know the pain this project solves.

MahoRAGa gives your agents a long-term memory they can actually use: past errors, fixes, concepts, and artifacts stay connected in a local graph so future sessions can build on previous work instead of starting from zero.

🔁 Never solve the same bug twice. Errors and solutions are persisted and semantically searchable.
🧩 Cross-project knowledge. Concepts learned in one project are instantly available in others.
📊 Activity intelligence. Daily summaries, session histories, and project timelines — all queryable.
🔒 100% local. Your data never leaves your machine. No API keys, no cloud dependencies.

Visual Viewer (Browser)

If you prefer to inspect memory visually, there's now a separate local viewer stack:

viewer_api/ → read-only API for graph data
viewer_ui/ → interactive browser UI (zoom, pan, drag, search, node details)

Run backend:

source .venv/bin/activate
uvicorn viewer_api.main:app --host 127.0.0.1 --port 8090 --reload

Run frontend:

cd viewer_ui
npm install
npm run dev

Open:

http://127.0.0.1:5173

Strict multi-agent provenance

Writes now support strict provenance tracking so you can audit which agent + model performed each mutation and when.

Required actor context on mutating tools

Mutating tools require actor_context with:

agent_id
agent_name
model_id
model_name
provider

agent_id and agent_name must match exactly and must be one of the configured OpenCode agent names from:

~/.config/opencode/agents/*.md

Example valid agent names include: build, planner, frontend-specialist, security-reviewer, etc.

If you want to override the allowed list (for CI/tests), set:

MAHORAGA_ALLOWED_AGENTS=build,planner,frontend-specialist

Provenance query tools

get_agent_activity
get_model_activity
get_action_timeline
get_entity_provenance

Features

Category	Highlights
Graph Engine	Kuzu embedded graph DB with strict referential integrity and cascade-safe deletes
Semantic Search	`all-MiniLM-L6-v2` embeddings with hybrid ranking (similarity + recency + context + keywords)
MCP Protocol	25+ tools exposed via FastMCP over stdio — plug into Claude Code, Cursor, or any MCP client
Artifacts	Attach datasheets, configs, logs, and code snippets to sessions and errors
Daily Activity	Automatic aggregation of sessions into daily summaries with garbage collection
Performance	Vectorized clustering, batched Cypher queries, pagination on all list endpoints
Reliability	Input validation, safe limit clamping, thread-safe connections, and comprehensive test suite

Quick Start

Linux / macOS

git clone https://github.com/Aadi775/MahoRAGa.git
cd MahoRAGa
chmod +x setup.sh && ./setup.sh

Windows

git clone https://github.com/Aadi775/MahoRAGa.git
cd MahoRAGa
setup.bat

Both scripts create a .venv, install all dependencies, and configure the MCP server entry automatically.

Connect to Your Agent

You can run MahoRAGa in two different modes depending on whether you want one agent, or multiple agents/windows sharing the same brain.

Mode 1: Single Client (stdio)

If you only use one AI coding agent (e.g., just Claude Desktop), you can let the client spawn MahoRAGa directly. Add this to your MCP config (.mcp.json or ~/.claude.json):

{
  "mcpServers": {
    "mahoraga": {
      "command": "/path/to/MahoRAGa/.venv/bin/mahoraga-kg"
    }
  }
}

Mode 2: Multi-Client Shared Brain (SSE)

KùzuDB uses file-level locking, meaning if you try to open MahoRAGa in Cursor and OpenCode at the same time using stdio, they will crash fighting over the lock. Instead, start MahoRAGa as a shared HTTP server in the background:

# Start the shared server manually in a terminal
mahoraga-kg --transport sse --port 8000

Then, configure all your MCP clients to connect to this shared endpoint instead of launching their own process:

{
  "mcpServers": {
    "mahoraga-remote": {
      "type": "remote",
      "url": "http://localhost:8000/sse"
    }
  }
}

Any MCP-Compatible Client

MahoRAGa speaks standard MCP. Point your client to either the CLI executable or the SSE endpoint and you're set.

Optional: Auto-start SSE on boot (systemd user service)

If you want the SSE server to start automatically when your laptop boots:

# Install + enable + start user service
chmod +x install_sse_autostart.sh uninstall_sse_autostart.sh
./install_sse_autostart.sh

This creates ~/.config/systemd/user/mahoraga-sse.service, enables it, and starts it immediately.

Useful commands:

systemctl --user status mahoraga-sse.service
journalctl --user -u mahoraga-sse.service -f

To remove it:

./uninstall_sse_autostart.sh

To run user services even before login, enable linger once:

sudo loginctl enable-linger $USER

MCP Tools Reference

🗂️ Projects

Tool	Description
`add_project`	Create a new project node
`update_project`	Update metadata or merge two projects
`list_projects`	Paginated list of all projects

📝 Sessions

Tool	Description
`add_session`	Start a session (auto-creates project if needed)
`close_session`	Close and generate daily activity
`get_recent_sessions`	Fetch recent sessions across projects
`delete_session`	Cascade-delete with DailyActivity sync

🐛 Errors & Solutions

Tool	Description
`log_error`	Log an error with semantic embedding
`log_solution`	Attach a fix to a logged error
`get_error_solutions`	Find similar past errors and their solutions
`cluster_errors`	Group related errors by vector similarity

🧠 Knowledge

Tool	Description
`add_concept`	Add a semantic knowledge entry
`update_concept`	Update and re-embed a concept
`link_concept_to_session`	Associate a concept with a session
`batch_link_concepts`	Bulk-link multiple concepts efficiently
`search`	Hybrid semantic + keyword search

📎 Artifacts

Tool	Description
`add_artifact`	Attach a file/document to the graph
`link_artifact_to_session`	Connect artifact to a session
`link_artifact_to_error`	Connect artifact to an error
`get_project_artifacts`	List artifacts for a project
`search_artifacts_by_tag`	Tag-based artifact search

📊 Analytics

Tool	Description
`get_project_history`	Full session/error/solution timeline
`get_daily_summary`	Aggregated stats for a specific date
`get_learning_progress`	Error resolution trends over time
`get_project_daily_activities`	Paginated daily activity feed

🔧 Admin

Tool	Description
`delete_old_sessions`	Prune sessions older than N days (with DailyActivity GC)
`delete_project`	Full cascade delete of a project
`get_unlinked_concepts`	Find orphaned concepts

Search Algorithm

MahoRAGa uses a hybrid ranking algorithm that blends four signals:

Weight	Signal	Description
55%	Semantic Similarity	Cosine similarity between query and content embeddings
20%	Recency	Exponential decay favoring recent knowledge
15%	Context Richness	Bonus for concepts with linked errors, solutions, and sessions
10%	Keyword Overlap	Title-boosted keyword matching for precision

Graph Schema

Project ← HAS_PROJECT ← Session → CONTRIBUTES_TO → DailyActivity → BELONGS_TO → Project
                              ↑
                     OCCURRED_IN
                              |
                           Error ← SOLVES ← Solution
                              ↑
                        ATTACHED_TO
                              |
                          Artifact ← USES_ARTIFACT ← Session
                              ↑
                         ILLUSTRATES
                              |
                           Concept ← REFERENCES ← Session

Nodes: Project · Session · Error · Solution · Concept · DailyActivity · Artifact

Data Storage

All data is stored locally in an embedded Kuzu database:

~/.config/mahoraga/graph.db

No external services, no network calls, no cloud sync. Fully offline-capable.

Development

# Activate virtual environment
source .venv/bin/activate

# Run the full test suite (87 tests)
pytest tests/ -v

# Run performance benchmarks
pytest tests/test_performance.py -v

# Run search tuning tests
pytest tests/test_search_tuning.py -v

Documentation

A full interactive documentation site is included in the docs/ directory, built with React, Vite, TailwindCSS, GSAP, and Framer Motion.

cd docs && npm install && npm run dev

Then open http://localhost:5173.

Demos — How Agents Use MahoRAGa

🟢 Demo 1: Basic Agent Session

When an agent starts working on your project, it opens a session and logs everything it does:

Agent → add_session(project_name="my-api", summary="Fix auth middleware", files_touched=["src/auth.ts"])
       ↳ Returns: { session_id: "abc-123" }

Agent → log_error(session_id="abc-123", message="JWT expired during refresh", context="Token TTL was 0", file="src/auth.ts")
       ↳ Returns: { error_id: "err-456" }

Agent → log_solution(error_id="err-456", description="Set TTL to 3600s in config", code_snippet="config.jwt.ttl = 3600")
       ↳ Returns: { solution_id: "sol-789" }

Agent → add_concept(title="JWT Refresh Flow", content="Always check token expiry before API calls. Default TTL should be 1hr.", tags=["auth", "jwt"])
       ↳ Returns: { concept_id: "con-012" }

Agent → link_concept_to_session(concept_id="con-012", session_id="abc-123")
Agent → close_session(session_id="abc-123")

The graph now holds a permanent record: what went wrong, how it was fixed, and what was learned.

🔍 Demo 2: Agent Recalls Past Knowledge

A week later, the same (or different) agent hits a similar issue. Instead of starting from scratch:

Agent → search(query="JWT token expiry authentication")
       ↳ Returns:
         concepts: [{ title: "JWT Refresh Flow", similarity: 0.94, recency_score: 0.98 }]
         sessions: [{ summary: "Fix auth middleware", files: ["src/auth.ts"] }]
         errors:   [{ message: "JWT expired during refresh" }]
         solutions:[{ description: "Set TTL to 3600s in config", code: "config.jwt.ttl = 3600" }]

Agent → get_error_solutions(error_message="token has expired")
       ↳ Returns 3 similar past errors ranked by semantic similarity, each with their solution

The agent immediately knows the fix without re-debugging. Zero wasted time.

📎 Demo 3: Attaching Artifacts

Agents can persist files, logs, and configs as searchable artifacts:

Agent → add_artifact(
          artifact_type="config",
          title="Production JWT Config",
          content="{ jwt: { ttl: 3600, algorithm: 'RS256', issuer: 'api.example.com' } }",
          description="Auth service JWT configuration",
          tags=["production", "auth", "config"]
        )
       ↳ Returns: { artifact_id: "art-345" }

Agent → link_artifact_to_session(artifact_id="art-345", session_id="abc-123")
Agent → search_artifacts_by_tag(tag="auth")
       ↳ Returns: [{ title: "Production JWT Config", type: "config", ... }]

📊 Demo 4: Project Analytics

Agents (or you) can query high-level project intelligence:

Agent → get_project_history(project_name="my-api", limit=10)
       ↳ Returns: last 10 sessions with all errors and solutions

Agent → get_daily_summary(date="2026-03-24")
       ↳ Returns: { total_sessions: 5, total_errors: 12, projects: [...] }

Agent → get_learning_progress(project_name="my-api")
       ↳ Returns: { errors_logged: 47, errors_resolved: 41, resolution_rate: 0.87 }

🧹 Demo 5: Maintenance & Cleanup

Keep the graph lean over time:

Agent → delete_old_sessions(days=30)
       ↳ Deletes sessions older than 30 days
       ↳ Automatically garbage-collects orphaned DailyActivity nodes
       ↳ Preserves all Concepts (knowledge is never lost)

Agent → get_unlinked_concepts(limit=20)
       ↳ Find concepts not linked to any session (candidates for cleanup or review)

License

MIT — use it however you want.