MahoRAGa
Persistent graph-powered memory for AI agents using Kuzu embedded database.
Ask AI about MahoRAGa
Powered by Claude Β· Grounded in docs
I know everything about MahoRAGa. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π§ MahoRAGa
Persistent, graph-powered memory for AI agents.
A production-ready MCP server that gives Claude, Cursor, and any agentic framework long-term semantic recall.
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 dataviewer_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_idagent_namemodel_idmodel_nameprovider
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_activityget_model_activityget_action_timelineget_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.
