Maho Ra Ga

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

______________________________________________________________________

为什么选择MahoRAGa？

每个AI代理会话都会启动 冷 --对过去的错误、解决方案或项目上下文没有记忆。MahoRAGa通过提供 本地图形数据库 代理可以跨会话进行读写操作，从而创建一个随着时间的推移而变得更加智能的动态知识库。

• 🔁 永远不要解决同一个bug两次。 错误和解决方案是持久的，在语义上是可搜索的。
• 🧩 跨项目知识。 在一个项目中学习到的概念可以立即在其他项目中使用。
• 📊 活动情报。 每日摘要、会话历史和项目时间表——所有这些都是可查询的。
• 🔒 100%本地。 你的数据永远不会离开你的机器。没有API键，没有云依赖关系。

______________________________________________________________________

特性

______________________________________________________________________

快速开始

Linux/macOS

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

视窗

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

这两个脚本都创建了一个 .venv，安装所有依赖项，并自动配置MCP服务器条目。

______________________________________________________________________

连接到您的代理

您可以在两种不同的模式下运行MahoRAGa，具体取决于您是想要一个代理，还是多个代理/窗口共享同一个大脑。

模式1：单客户端（stdio）

如果你只使用一个AI编码代理（例如，只使用Claude Desktop），你可以让客户端直接生成MahoRAGa。将此添加到您的MCP配置中(.mcp.json 或 ~/.claude.json):

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

模式2：多客户端共享大脑（SSE）

KùzuDB使用文件级锁定，这意味着如果你试图在Cursor中打开MahoRAGa _和_ OpenCode同时使用 stdio，他们会为争夺锁而打架。相反，在后台将MahoRAGa作为共享HTTP服务器启动：

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

然后，配置所有MCP客户端以连接到此共享端点，而不是启动它们自己的进程：

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

任何MCP兼容客户端

MahoRAGa讲话 标准MCP。将客户端指向CLI可执行文件或SSE端点，即可完成设置。

可选：启动时自动启动SSE（systemd用户服务）

如果您希望SSE服务器在笔记本电脑启动时自动启动：

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

这创造了 ~/.config/systemd/user/mahoraga-sse.service，启用它，并立即启动它。

有用的命令：

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

要删除它：

./uninstall_sse_autostart.sh

要在登录之前运行用户服务，请启用linger一次：

sudo loginctl enable-linger $USER

______________________________________________________________________

MCP工具参考

🗂️ 项目

📝 会话

🐛 错误和解决方案

🧠 知识

📎 人工制品

📊 分析

🔧 管理员

______________________________________________________________________

搜索算法

MahoRAGa使用 混合排名 混合四个信号的算法：

______________________________________________________________________

图形架构

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

节点： Project · Session · Error · Solution · Concept · DailyActivity · Artifact

______________________________________________________________________

数据存储

所有数据都存储在本地嵌入式Kuzu数据库中：

~/.config/mahoraga/graph.db

没有外部服务，没有网络呼叫，没有云同步。完全离线。

______________________________________________________________________

发展

# 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

______________________________________________________________________

文档

完整的交互式文档网站包含在 docs/ 目录，使用React、Vite、TailwindCSS、GSAP和Framer Motion构建。

cd docs && npm install && npm run dev

然后打开 http://localhost:5173.

______________________________________________________________________

演示——代理如何使用MahoRAGa

🟢 演示1：基本代理会话

当代理开始处理您的项目时，它会打开一个会话并记录它所做的一切：

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

该图现在保存了一个永久记录： 出了什么问题，如何解决，学到了什么.

______________________________________________________________________

🔍 演示2：代理人回忆过去的知识

一周后，同一（或不同）代理遇到了类似的问题。而不是从头开始：

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

代理程序无需重新调试即可立即知道修复程序。 零浪费时间。

______________________________________________________________________

📎 演示3：附加工件

代理可以将文件、日志和配置持久化为可搜索的工件：

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", ... }]

______________________________________________________________________

📊 演示4：项目分析

代理人（或您）可以查询高级项目情报：

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 }

______________________________________________________________________

🧹 演示5：维护和清理

随着时间的推移，保持图表倾斜：

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)

______________________________________________________________________

许可证

麻省理工学院——随心所欲地使用它。