AI导哈

知识图谱管理工具

Mnemosyne MCP是一个AI驱动的知识图谱集成工具，提供图形管理、SPARQL查询和实时文档编辑功能，适用于开发者和数据分析师。

  • by sophia-labs
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 sophia-labs/mnemosyne-mcp

使用说明

Mnemosyne MCP

这是一项正在进行的工作，文档是人工生成的，在人们被广泛鼓励阅读和使用这段代码之前，将由人类重写。感谢您对这件事的关注XOXO-VERA

Claude Code、Goose和Codex的人工智能知识图集成

Mnemosyne MCP(neem)历史上公开了一整套图形管理工具。我们目前正在根据在本地kubectl上下文中运行的新FastAPI后端从头开始重建这些工具。

状态： MCP服务器通过Hocuspocus/Y.js提供23多种工具，用于知识图管理、SPARQL查询、实时文档编辑和工作区组织。

特征：

  • 🔌 与本地FastAPI后端的可靠连接（通过env-vars或kubectl端口转发）
  • 🩺 自动启动运行状况探测，以便您知道后端是否可访问
  • 🔐 基于浏览器的OAuth身份验证(neem init)
  • 📊 全图CRUD操作（创建、列出、删除）
  • 🔍 SPARQL查询和更新支持
  • 📝 通过Y.js CRDT进行实时文档编辑

安装

uv tool install -e .

在当地发展的同时 uv:

uv sync
uv run neem --help

命令

neem init               # Authenticate (run browser-based OAuth)
neem status             # Show token status and Claude Code config
neem logout             # Remove saved token (optional: keep config)
neem config             # Inspect config details (with optional --show-token)

快速开始

步骤1：安装并验证

# Install the package
uv tool install -e .

# Authenticate with Mnemosyne
neem init                     # Opens your browser to log in

neem init 仅处理身份验证——接下来的步骤将展示如何手动连接每个MCP客户端。

在注册MCP服务器之前，从kubectl上下文中暴露FastAPI后端：

kubectl port-forward svc/mnemosyne-api 8080:80

MCP服务器默认为 http://127.0.0.1:8080 该端口向前匹配。HTTP和WebSocket连接都通过端口8080。

步骤2：将MCP服务器添加到您的代理

使用Claude代码（本地后端）：

claude mcp add mnemosyne --scope user \
  -- uv run neem-mcp-server

使用Claude代码（托管API）：

连接到托管API时（例如。 api.garden.sophia-labs.com)禁用WebSocket流，而不是本地端口转发。WS端点是集群内部的，不会暴露在外部——如果没有这个标志，基于作业的工具，如 list_graphs 将挂起长达60秒，然后回落到HTTP轮询。

claude mcp add mnemosyne --scope user \
  --env MNEMOSYNE_FASTAPI_URL=https://api.garden.sophia-labs.com \
  -- uv run neem-mcp-server

或直接添加到 ~/.claude.json:

"mcpServers": {
  "mnemosyne": {
    "type": "stdio",
    "command": "uv",
    "args": ["run", "neem-mcp-server"],
    "env": {
      "MNEMOSYNE_FASTAPI_URL": "https://api.garden.sophia-labs.com",
    }
  }
}

首先通过以下方式进行身份验证 neem init。代币存储在 ~/.mnemosyne/config.json 自动刷新约30天。

使用Codex

codex mcp add mnemosyne \
  --env LOG_LEVEL=ERROR \
  -- uv run neem-mcp-server

开发模式快捷方式： 追加 --env MNEMOSYNE_DEV_TOKEN=<user> 和 --env MNEMOSYNE_DEV_USER_ID=<user> 当后端运行时 MNEMOSYNE_AUTH__MODE=dev_no_auth。HTTP和WebSocket都会在没有OAuth的情况下模拟该用户。

海关港口？ 添加 --env MNEMOSYNE_FASTAPI_URL=http://127.0.0.1:XXXX 如果您的端口转发与默认的8080不同。

开发模式（跳过OAuth）

如果后端运行 MNEMOSYNE_AUTH__MODE=dev_no_auth，在启动MCP服务器之前设置两个env变量，以完全绕过OAuth流：

export MNEMOSYNE_DEV_USER_ID=alice
export MNEMOSYNE_DEV_TOKEN=alice  # many clusters treat the token string as the user id
uv run neem-mcp-server

HTTP请求和WebSocket握手都将发送 X-User-ID: alice 加 Sec-WebSocket-Protocol: Bearer.alice，满足后端的开发模式保护。在确定生产目标时，取消这些envs。

使用示例

注册服务器后，要求您的MCP客户端运行 list_graphs。它提交作业，通过流式传输实时事件 /ws，并在后端不通告推送提示时回退到HTTP轮询。

FastAPI后端配置

MCP服务器现在假设它应该与在本地kubectl上下文中运行的FastAPI后端通信。

  1. 点 kubectl 在所需的集群(kubectl config use-context ...).
  2. 端口转发FastAPI服务，以便在您的工作站上可以访问它（例如： kubectl port-forward svc/mnemosyne-fastapi 8001:8000).
  3. 开始 neem-mcp-server 使用支持的后端配置选项之一：
    • MNEMOSYNE_FASTAPI_URL （首选）或遗产 MNEMOSYNE_API_URL.
    • MNEMOSYNE_FASTAPI_HOST, MNEMOSYNE_FASTAPI_PORT，可选 MNEMOSYNE_FASTAPI_SCHEME 如果你想单独提供主机/端口（对于kubectl端口转发脚本很方便）。
    • MNEMOSYNE_FASTAPI_HEALTH_PATH 如果FastAPI应用程序公开了非标准健康端点（默认为 /health).

如果这些环境变量都没有设置，则服务器默认为 http://127.0.0.1:8001，与前面的采样端口对齐。在启动时，我们会发出一个轻量级的健康探测，以便您立即知道后端是否可访问。

许可证管理

令牌在后台使用OAuth刷新令牌自动刷新。初始身份验证后，您将在没有任何手动干预的情况下保持登录状态约30天。

当刷新令牌最终到期时，只需运行 neem init 重新验证。

重要：设置 LOG_LEVEL=ERROR Codex CLI避免任何stderr对stdio协议的干扰。

可用的MCP工具

图形管理

  • list_graphs –列出经过身份验证的用户拥有的所有知识图（使用 include_deleted=true 显示软删除的图形）
  • create_graph –创建一个带有ID、标题和可选描述的新知识图
  • delete_graph –删除图形（默认情况下为软删除，使用 hard=true 永久删除）

SPARQL运营

  • sparql_query –对图形执行只读SPARQL SELECT/CONSTRUCT查询
  • sparql_update –执行SPARQL INSERT/DELETE/UPDATE操作以修改图形数据

命名空间引用： 编写SPARQL查询时，请使用以下确切的前缀：

PREFIX doc: <http://mnemosyne.dev/doc#>
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX nfo: <http://www.semanticdesktop.org/ontologies/2007/03/22/nfo#>
PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX nie: <http://www.semanticdesktop.org/ontologies/2007/01/19/nie#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>

警告： 请勿使用 urn:mnemosyne:schema:doc: 作为doc名称空间，它将不匹配任何内容。

定向

  • get_user_location –获取用户当前正在查看的图形和文档（最小标记）
  • get_workspace –获取图形的文件夹/文件结构（主要探索工具）
  • get_session_state –获取完整的会话状态，包括选项卡和首选项（大负载，很少需要）

文件夹操作

  • create_folder –在工作区中创建一个新文件夹
  • rename_folder –重命名文件夹
  • move_folder –将文件夹移动到其他父文件夹
  • delete_folder –删除文件夹（可选级联删除内容）

文档操作（通过Hocuspocus/Y.js）

  • read_document –以TipTap XML格式读取文档内容
  • write_document –用TipTap XML替换文档内容
  • append_to_document –在文档末尾添加一个块
  • move_document –将文档移动到其他文件夹
  • delete_document –从工作区导航中删除文档

块级操作

  • get_block –通过ID读取特定块（包括text_length和格式化运行）
  • query_blocks –搜索符合特定条件的块
  • update_block –更新块的属性或替换整个内容
  • edit_block_text –在块内的字符偏移处插入/删除文本（CRDT安全协作编辑）
  • insert_block –相对于现有块插入新块
  • delete_block –删除一个块（可为儿童选择级联）
  • batch_update_blocks –在单个交易中更新多个区块

人工制品操作

  • move_artifact –将工件移动到其他文件夹
  • rename_artifact –重命名工件

连线操作（语义连接）

  • list_wire_predicates –列出按类别组织的可用语义谓词
  • create_wire –在文档或块之间创建语义连接（通过Y.js CRDT同步）
  • get_wires –将所有电线连接到文档（按方向过滤：输出/输入/两者）
  • traverse_wires –BFS遍历起始文档中的线图（深度可达10）

TipTap XML格式

文档使用TipTap的XML表示形式，并提供完整的格式支持：

阻碍： paragraph, heading （级别=“1-3”）， bulletList, orderedList, blockquote, codeBlock （语言=“…”）， taskList, taskItem （选中=“true”）， horizontalRule

标记（可嵌套）： strong, em, strike, code, mark （突出显示）， a （href=“…”）

注释标记： 引用外部内容的特殊内联标记：

  • footnote –自带注释 data-footnote-content 属性
  • commentMark –参考注释 data-comment-id 属性

例子：

<paragraph>Text with <mark>highlight</mark> and a note<footnote data-footnote-content="This is a footnote"/></paragraph>

图管理和SPARQL工具将作业提交到FastAPI后端，在可用时通过WebSocket流式传输实时更新，否则退回HTTP轮询。文档、块、文件夹和连线操作通过Hocuspocus使用Y.js CRDT进行实时同步。

SPARQL数据模型

文档、文件夹和工件通过两个后端管道具体化为RDF：

  • 工作空间物化器 –同步工作区Y.Doc中的元数据（标题、文件夹结构、顺序）
  • 文件材料化者 –同步文档Y中的内容（块、段落、文本节点）。文档

常见的RDF类型： doc:TipTapDocument, doc:Folder, doc:Artifact, doc:XmlFragment, doc:Paragraph, doc:Heading, doc:TextNode

常见谓词： dcterms:title, nfo:fileName, nfo:belongsToContainer, doc:order, doc:section, doc:content, doc:childNode, doc:siblingOrder, doc:createdAt, doc:updatedAt

实体URI模式： urn:mnemosyne:user:{user_id}:graph:{graph_id}:{type}:{entity_id} 内容片段使用 # 后缀： ...doc:{id}#frag, ...doc:{id}#block-{block_id}, ...doc:{id}#node-{n}

列出所有标题文档的示例查询：

PREFIX doc: <http://mnemosyne.dev/doc#>
PREFIX dcterms: <http://purl.org/dc/terms/>

SELECT ?doc ?title WHERE {
  ?doc a doc:TipTapDocument .
  ?doc dcterms:title ?title .
} ORDER BY ?title

配置

  • 代币存储在 ~/.mnemosyne/config.json （用覆盖 MNEMOSYNE_CONFIG_DIR).

建筑

此软件包包含两个主要组件：

1.CLI工具(neem)

位于 neem.cli:

  • OAuth PKCE身份验证流程(neem.utils.oauth)
  • 安全令牌存储(neem.utils.token_storage)
  • Claude代码配置管理(neem.utils.claude_config)

2.MCP服务器(neem-mcp-server)

位于 neem.mcp.server:

  • 标准运输 –通过stdin/stdout与Claude Code通信
  • 后端解析器 –从env-vars或kubectl服务主机确定FastAPI基本URL
  • 健康探头 –启动时Ping FastAPI后端，以便您知道端口转发/上下文是否正确
  • 实时作业布线 – neem.mcp.jobs 提供一个websocket友好的客户端，一旦后端发出提示，工具就可以使用该客户端订阅作业进度
  • 结构化日志记录 –所有日志都会转到stderr（stdio安全），并带有可选文件输出

此重置的关键设计原则：

  • 本地第一循环 –假设开发人员通过kubectl瞄准FastAPI pod
  • 最小表面积 –在新工具合同最终确定之前，保持服务器精简
  • 显式配置 –更喜欢环境变量而不是隐藏的默认值，这样CLI工具就可以注入设置

发展

本地开发

# Install in development mode
uv sync
uv pip install -e .

# Run the CLI
uv run neem init

# Test the MCP server
uv run neem-mcp-server

项目结构

src/neem/
├── cli.py                          # CLI commands (init, status, logout, config)
├── hocuspocus/                     # Y.js CRDT client layer
│   ├── client.py                   # WebSocket client for Hocuspocus
│   ├── document.py                 # Document Y.Doc operations
│   ├── protocol.py                 # Y.js sync protocol handler
│   └── workspace.py                # Workspace Y.Doc operations
├── mcp/
│   ├── server/
│   │   ├── standalone_server.py    # Backend resolver, health probe, tool registration
│   │   └── standalone_server_stdio.py  # Stdio transport wrapper
│   ├── tools/
│   │   ├── basic.py                # list_graphs + job helpers
│   │   ├── graph_ops.py            # create/delete graph, SPARQL query/update
│   │   ├── hocuspocus.py           # Document, block, folder, artifact operations
│   │   └── wire_tools.py           # Semantic connection tools
│   ├── jobs/                       # Job streaming (WebSocket + polling)
│   ├── session.py                  # Session management
│   ├── auth.py                     # MCP auth context
│   ├── errors.py                   # MCP-specific errors
│   └── response_objects.py         # Formatted MCP responses
└── utils/
    ├── oauth.py                    # OAuth PKCE flow
    ├── token_storage.py            # Token persistence
    ├── claude_config.py            # Claude Code config management
    ├── logging.py                  # Structured logging
    ├── deployment_context.py       # Environment configuration
    └── errors.py                   # Base error classes

环境变量

  • MNEMOSYNE_FASTAPI_URL –首选FastAPI基本URL（默认为 http://127.0.0.1:8001).遗产 MNEMOSYNE_API_URL 如果设置，仍然很荣幸。
  • MNEMOSYNE_FASTAPI_HOST, MNEMOSYNE_FASTAPI_PORT, MNEMOSYNE_FASTAPI_SCHEME –单独指定主机/端口（便于脚本化的kubectl端口转发）。
  • MNEMOSYNE_FASTAPI_HEALTH_PATH –如果您的FastAPI应用程序未公开，则选择其他健康检查路径 /health.
  • MNEMOSYNE_FASTAPI_WS_URL –直接覆盖WebSocket网关（默认为 ws(s)://<host>/ws 源自HTTP基础）。
  • MNEMOSYNE_FASTAPI_WS_PATH –在以下情况下，将自定义路径附加到派生的WebSocket URL MNEMOSYNE_FASTAPI_WS_URL 未设置。
  • MNEMOSYNE_FASTAPI_WS_PORT –仅覆盖WebSocket端口，同时保持相同的主机/路径（当HTTP和WS在不同的本地端口上转发时很有用）。
  • MNEMOSYNE_FASTAPI_WS_DISABLE –设置为 true 选择退出WebSocket流（退回HTTP轮询）。
  • MNEMOSYNE_CONFIG_DIR –令牌存储位置（默认值： ~/.mnemosyne)
  • MNEMOSYNE_DEV_TOKEN –可选的dev-only覆盖，通过直接注入提供的承载令牌跳过OAuth流（仅在受信任的本地堆栈上使用）。
  • CLAUDE_CODE_SETTINGS_PATH –克劳德设置文件（默认值： ~/.claude/settings.json)
  • LOG_LEVEL –记录详细程度（默认值： INFO)
    • DEBUG –详细记录故障排除
    • INFO –正常操作日志记录（默认）
    • WARNING –安静模式，只有警告和错误
    • ERROR –静音模式，只有错误（建议用于Codex CLI）
    • CRITICAL –日志记录最少，仅出现严重错误

默认情况下，会话存储在内存中；不需要外部缓存服务。

故障排除

MCP服务器未加载

克劳德代码：

  1. 检查配置: cat ~/.claude.json | grep mnemosyne-graph
  2. 直接测试服务器: echo '{"jsonrpc": "2.0", "method": "initialize", "id": 1}' | neem-mcp-server
  3. 检查日志：克劳德代码启动时查找stderr输出
  4. 验证令牌: neem status 应显示“活动”身份验证
  5. 重新启动Claude代码：配置更改需要完全重新启动

对于Goose CLI：

  1. 检查配置: cat ~/.config/goose/config.yaml | grep mnemosyne-graph
  2. 验证是否启用了扩展: enabled: true 在配置中
  3. 检查超时：如果服务器启动缓慢，则增加到600秒
  4. 会话中的测试：启动一个新的Goose会话，并要求它列出可用的工具
  5. 检查环境：确保 MNEMOSYNE_FASTAPI_URL （或遗产 MNEMOSYNE_API_URL)设置正确

对于Codex CLI：

  1. 启用调试日志：Codex故意使stderr静音，使调试变得困难
  2. 设置LOGLEVEL：使用 LOG_LEVEL=ERROR 在环境中防止stderr干扰
  3. 手动测试：运行 echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | neem-mcp-server 验证它是否有效
  4. 检查配置：确保 codex.json 或者您的配置文件具有正确的命令和环境变量

身份验证问题

  1. 令牌不刷新：令牌在后台自动刷新。如果您看到身份验证错误，则您的刷新令牌可能已过期（约30天）。跑 neem init 重新验证。
  2. 检查令牌: neem status 查看令牌详细信息和到期时间
  3. 强制刷新: neem init --force 获得全新的代币

SPARQL返回空结果

最常见的原因是使用了错误的命名空间前缀。用途：

PREFIX doc: <http://mnemosyne.dev/doc#>

请勿使用 urn:mnemosyne:schema:doc: --它将悄无声息地匹配任何东西。

请参阅 docs/ 终端用户快速入门目录和详细指南 随包装一起装运或单独出版。

相关 MCP