MahoRAGa
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MahoRAGa show me past errors about database timeout"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Memory Palace
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 --reloadRun frontend:
cd viewer_ui
npm install
npm run devOpen:
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 |
|
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.shWindows
git clone https://github.com/Aadi775/MahoRAGa.git
cd MahoRAGa
setup.batBoth 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 8000Then, 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.shThis 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 -fTo remove it:
./uninstall_sse_autostart.shTo run user services even before login, enable linger once:
sudo loginctl enable-linger $USERMCP Tools Reference
ποΈ Projects
Tool | Description |
| Create a new project node |
| Update metadata or merge two projects |
| Paginated list of all projects |
π Sessions
Tool | Description |
| Start a session (auto-creates project if needed) |
| Close and generate daily activity |
| Fetch recent sessions across projects |
| Cascade-delete with DailyActivity sync |
π Errors & Solutions
Tool | Description |
| Log an error with semantic embedding |
| Attach a fix to a logged error |
| Find similar past errors and their solutions |
| Group related errors by vector similarity |
π§ Knowledge
Tool | Description |
| Add a semantic knowledge entry |
| Update and re-embed a concept |
| Associate a concept with a session |
| Bulk-link multiple concepts efficiently |
| Hybrid semantic + keyword search |
π Artifacts
Tool | Description |
| Attach a file/document to the graph |
| Connect artifact to a session |
| Connect artifact to an error |
| List artifacts for a project |
| Tag-based artifact search |
π Analytics
Tool | Description |
| Full session/error/solution timeline |
| Aggregated stats for a specific date |
| Error resolution trends over time |
| Paginated daily activity feed |
π§ Admin
Tool | Description |
| Prune sessions older than N days (with DailyActivity GC) |
| Full cascade delete of a project |
| 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 β SessionNodes: Project Β· Session Β· Error Β· Solution Β· Concept Β· DailyActivity Β· Artifact
Data Storage
All data is stored locally in an embedded Kuzu database:
~/.config/mahoraga/graph.dbNo 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 -vDocumentation
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 devThen 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 solutionThe 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.
Available Tools
55 toolsadd_artifactB
Create a new artifact in the knowledge graph.
Artifacts store files, configs, logs, code snippets, datasheets, etc.
Inputs: artifact_type (required), title (required), description (required), content (required), +4 more. Returns: object
add_conceptC
Add a new concept to the knowledge graph.
Concepts are semantic knowledge entries that can be linked to sessions.
Inputs: title (required), content (required), tags, actor_context. Returns: object
add_projectB
Create a new project node in the knowledge graph.
Inputs: name (required), path (required), description, actor_context. Returns: object
add_sessionA
Create a new session linked to a project.
If the project doesn't exist, it will be auto-created. For new projects, project_path is required.
Inputs: project_name (required), summary (required), files_touched (required), project_path, +1 more. Returns: object
add_tag_to_conceptA
Add a tag to a concept without re-embedding.
Inputs: concept_id (required), tag (required), actor_context. Returns: object
batch_add_conceptsA
Add multiple concepts at once.
Each concept dict should have: title, content, and optionally tags.
Inputs: concepts (required), actor_context. Returns: object
batch_link_conceptsA
Link multiple concepts to a session at once.
Inputs: concept_ids (required), session_id (required), actor_context. Returns: object
close_sessionB
Close a session and update its end timestamp.
Also creates or updates the DailyActivity node for the session's date.
Inputs: session_id (required), ended_at, actor_context. Returns: object
delete_artifactC
Delete an artifact and all its relationships.
Inputs: artifact_id (required), actor_context. Returns: object
delete_conceptA
Delete a concept from the knowledge graph.
Also removes any REFERENCES relationships to sessions.
Inputs: concept_id (required), actor_context. Returns: object
delete_old_sessionsB
Delete old sessions and their errors/solutions (keeps concepts).
Smart cleanup that preserves learned concepts while removing old session data.
Inputs: days_to_keep, actor_context. Returns: object
delete_projectA
Delete a project and all its sessions, errors, and solutions.
Warning: This is a cascade delete and cannot be undone.
Inputs: project_id (required), actor_context. Returns: object
delete_sessionA
Delete a session and all its errors and solutions.
Warning: This is a cascade delete and cannot be undone.
Inputs: session_id (required), actor_context. Returns: object
get_action_timelineC
Get filtered provenance timeline events.
Inputs: project_id, agent_id, model_id, since, +3 more. Returns: object
get_agent_activityC
Get action events performed by a specific agent.
Inputs: agent_id (required), start_date, end_date. Returns: object
get_artifact_detailsB
Get full details of an artifact.
Inputs: artifact_id (required). Returns: object
get_concept_detailsB
Get concept with all sessions that reference it.
Inputs: concept_id (required). Returns: object
get_concepts_by_projectB
Get all concepts linked to a project's sessions.
Inputs: project_id (required). Returns: object
get_daily_activityB
Get daily activity for a specific date and project.
Inputs: date (required), project_id (required). Returns: object
get_daily_summaryA
Get aggregated summary for a specific date across all projects.
Inputs: date (required). Returns: object
get_entity_provenanceC
Get action history for a specific entity.
Inputs: target_type (required), target_id (required), limit. Returns: object
get_error_detailsB
Get error with all its solutions.
Inputs: error_id (required). Returns: object
get_error_solutionsA
Find similar errors and their solutions using semantic search.
Inputs: error_message (required), top_k. Returns: object
get_errors_without_solutionsB
Find unresolved errors (errors without solutions).
Inputs: project_id. Returns: object
get_learning_progressB
Track concept growth and activity over time for a project.
Inputs: project_id (required). Returns: object
get_model_activityC
Get action events produced by a specific model.
Inputs: model_id (required), start_date, end_date. Returns: object
get_most_referenced_conceptsB
Get the most referenced concepts across all sessions.
Inputs: limit. Returns: object
get_project_artifactsA
Get all artifacts linked to a project's sessions.
Inputs: project_id (required), limit, offset. Returns: object
get_project_daily_activitiesC
Get all daily activities for a project.
Inputs: project_id (required), limit, offset. Returns: object
get_project_errors_by_typeB
Cluster project errors by similarity to find common error patterns.
Inputs: project_id (required), similarity_threshold. Returns: object
get_project_historyB
Get all sessions, errors, and solutions for a project.
Inputs: project_name (required), limit, offset. Returns: object
get_project_statsB
Get comprehensive statistics for a project.
Returns session count, error count, resolution rate, top files with errors, etc.
Inputs: project_id (required). Returns: object
get_recent_errorsB
Get the most recent errors across all projects.
Inputs: limit. Returns: object
get_recent_sessionsB
Get the most recent sessions across all projects.
Inputs: limit. Returns: object
get_session_conceptsA
Get all concepts linked to a specific session.
Inputs: session_id (required). Returns: object
get_session_detailsA
Get full session info including errors, solutions, and linked concepts.
Inputs: session_id (required). Returns: object
get_session_errorsA
Get all errors for a specific session.
Inputs: session_id (required). Returns: object
get_unlinked_conceptsB
Find concepts that are not linked to any session.
Returns: dict with list of unlinked concepts
Inputs: limit, offset. Returns: object
link_artifactB
Link an artifact to a session, concept, or error.
Inputs: artifact_id (required), target_id (required), target_type (required), actor_context. Returns: object
link_concept_to_sessionA
Link a concept to a session.
Creates a REFERENCES relationship from session to concept.
Inputs: concept_id (required), session_id (required), actor_context. Returns: object
list_artifactsC
List artifacts filtered by type.
Inputs: artifact_type (required), limit, offset. Returns: object
list_projectsB
List all projects in the knowledge graph.
Returns: dict with list of projects sorted by creation date
Inputs: limit, offset. Returns: object
log_errorA
Log an error that occurred during a session.
Creates an Error node with embedded message for semantic search.
Inputs: session_id (required), message (required), context (required), file (required), +1 more. Returns: object
log_solutionB
Log a solution for a previously logged error.
Inputs: error_id (required), description (required), code_snippet, actor_context. Returns: object
remove_tag_from_conceptB
Remove a tag from a concept without re-embedding.
Inputs: concept_id (required), tag (required), actor_context. Returns: object
searchA
Search the knowledge graph for relevant information.
Performs semantic search over concepts, then traverses the graph to find related sessions, errors, and solutions.
Results are ranked by: 55% similarity, 20% recency, 15% context richness, 10% keyword overlap.
Inputs: query (required), top_k. Returns: object
search_artifacts_by_tagC
Find artifacts by tag.
Inputs: tag (required), limit, offset. Returns: object
search_by_tagB
Find concepts by tag (non-semantic search).
Inputs: tag (required). Returns: object
unlink_artifact_from_sessionC
Remove an artifact link from a session.
Inputs: artifact_id (required), session_id (required), actor_context. Returns: object
unlink_concept_from_sessionC
Remove a concept reference from a session.
Inputs: concept_id (required), session_id (required), actor_context. Returns: object
update_artifactA
Update an artifact's metadata or content (re-embeds automatically).
Inputs: artifact_id (required), title, description, content, +3 more. Returns: object
update_conceptB
Update a concept's content (re-embeds automatically).
Inputs: concept_id (required), new_content (required), new_title, actor_context. Returns: object
update_daily_activityC
Update a daily activity's summary.
Inputs: activity_id (required), summary (required), actor_context. Returns: object
update_projectB
Update a project's metadata or merge with another project.
Inputs: project_id (required), name, path, description, +2 more. Returns: object
update_session_summaryC
Update a session's summary.
Inputs: session_id (required), summary (required), actor_context. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 55 tools
Each tool targets a distinct entity and operation (e.g., add_artifact vs add_concept, get_session_details vs get_concept_details). There is no meaningful overlap; even similar search tools have different scopes (semantic vs tag-based).
Tool names follow a consistent verb_noun pattern (e.g., add_artifact, delete_session, get_daily_activity). Minor variations like 'list' vs 'get' are standard, and batch operations are uniformly prefixed. No mixing of conventions.
With 55 tools, the count far exceeds the typical well-scoped range. While the domain is broad, this many tools risks overwhelming agents and suggests insufficient consolidation or granularity.
The tool set covers CRUD and lifecycle operations for all major entities (artifacts, concepts, sessions, projects, errors, solutions). Minor gaps exist, such as no direct update or delete for individual errors, but workflows are supported via session deletion and event logging.
Maintenance
Related MCP Connectors
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Shared long-term memory for AI agents: save and recall context as a searchable knowledge graph.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Related MCP Servers
AlicenseAqualityDmaintenanceProvides persistent long-term memory for AI agents through semantic search and automated knowledge graph extraction. It enables agents to store, recall, and reason over facts, preferences, and relationships across multiple conversations and sessions.146 npmMIT- AlicenseNot gradedqualityDmaintenancePersistent semantic memory for AI agents, enabling storage, semantic search, knowledge graph connections, and inter-instance messaging across conversations using local models via Ollama.50MIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent knowledge graph memory for AI agents, enabling them to store, recall, and query facts about people, projects, and relationships across sessions.MIT
- AlicenseNot gradedqualityBmaintenanceEnables persistent, graph-based memory for AI agents, allowing them to store, traverse, and recall relationships between facts, decisions, and context across sessions for efficient reasoning and reduced token usage.MIT