Skip to main content
Glama
MahoRAGa
by Aadi775

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

Available Tools

55 tools
add_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

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

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

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

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

    B3.2/5.0

    Scored across 55 tools

    Disambiguation5/5

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

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      14
      6 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Persistent semantic memory for AI agents, enabling storage, semantic search, knowledge graph connections, and inter-instance messaging across conversations using local models via Ollama.
      50
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent knowledge graph memory for AI agents, enabling them to store, recall, and query facts about people, projects, and relationships across sessions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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