Graphiti MCP Server 实战指南为 AI Agent 构建可查询的时序知识图谱内存服务【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphitiGraphiti 是一个用于构建和查询**时序感知知识图谱temporally-aware knowledge graph**的框架专为在动态环境中运行的 AI Agent 设计。本指南聚焦仓库中的 mcp_server/README.md完整讲解如何通过 Model Context ProtocolMCP将 Graphiti 的能力暴露给 Claude Desktop、Cursor、VS Code 等 MCP 客户端从 Docker 一键启动、config.yaml 配置、双图数据库FalkorDB / Neo4j切换到 13 个 MCP 工具的实际用法与并发调优。读完本文你将掌握一套可复制的AI Agent 持久化记忆部署方案并理解其底层调用链与配置优先级。一、Graphiti MCP Server 是什么与传统的检索增强生成RAG方法不同Graphiti 会持续将用户交互、结构化与非结构化的企业数据以及外部信息整合进一个连贯、可查询的图结构中。它支持增量数据更新、高效检索和精确的历史查询且无需完整重算图谱因此非常适合构建交互式、上下文感知的 AI 应用。Graphiti MCP Server 是这个框架的一个实验性 MCP 实现它把 Graphiti 的核心功能通过 MCP 协议暴露出来让 AI 助手可以读写知识图谱。从源码看整个服务围绕三个核心抽象组织数据见 graphiti_mcp_server.py 中的服务指令Episodes情节内容片段如文本、消息或 JSON 数据Nodes实体图节点即从内容中抽取出的实体Facts事实实体与实体之间的关系边。每一份信息都按group_id分区因此你可以在同一张图里维护多个相互隔离的知识域。更重要的是它的双时序模型bi-temporal model每个 episode 既记录何时被写入也记录所描述事件实际发生的时间。当你向add_memory传入reference_time时就设置了事件发生时间否则默认使用当前时间。事实facts携带valid_at/invalid_at元数据新信息可以取代旧事实同时历史被完整保留——这正是时序感知的核心。核心能力一览Episode 管理新增、检索、删除 episode支持文本、消息、JSON 三种来源实体管理搜索并管理图中的实体节点与关系搜索能力通过语义与混合检索搜索事实边和节点摘要分组管理通过group_id组织和管理相关数据图维护清空图、重建索引图数据库支持FalkorDB默认与 Neo4j 双后端多 LLM 提供商OpenAI、Anthropic、Gemini、Groq、Azure OpenAI多 Embedding 提供商OpenAI、Voyage、Sentence Transformers、Gemini丰富实体类型内置 Preference、Requirements、Procedures、Locations、Events、Organizations、Documents 等用于结构化知识抽取HTTP 传输默认 HTTP 传输MCP 端点为/mcp/兼容主流客户端队列化异步处理episode 异步处理支持可配置并发上限二、快速开始两种接入路径克隆仓库git clone https://github.com/getzep/graphiti.git或使用 GitHub CLIgh repo clone getzep/graphiti路径一Claude Desktop 等仅支持 stdio 的客户端记录本目录的完整路径cd graphiti pwd安装环境依赖。在 Claude、Cursor 或其他 MCP 客户端中配置使用 stdio 传输具体配置文件的存放位置请查阅各客户端文档。路径二Cursor 等支持 HTTP 的客户端进入mcp_server目录cd graphiti/mcp_server使用 Docker Compose 启动FalkorDB MCP Server 组合容器推荐docker compose up这会同时在单个容器中启动 FalkorDB 和 MCP Server。备选方案使用 Neo4j 拆分容器运行docker compose -f docker/docker-compose-neo4j.yml up将 MCP 客户端指向http://localhost:8000/mcp/。从 docker-compose.yml 可以看到组合容器同时暴露三个端口6379FalkorDB/Redis、3000FalkorDB Web UI、8000MCP Server HTTP并通过healthcheck定期执行redis-cli ping探活。默认镜像为zepai/knowledge-graph-mcp:latest构建参数GRAPHITI_CORE_VERSION默认锁定0.29.1、MCP_SERVER_VERSION默认1.0.2。三、安装与前置条件前置条件Docker 与 Docker Compose默认 FalkorDB 方案需要OpenAI API Key用于 LLM 操作或其它受支持 LLM 提供商的 API Key可选Python 3.10若以独立方式运行 MCP Server 并连接外部 FalkorDB 实例仓库 pyproject.toml 声明了 Python 3.10 的要求若使用 Neo4j 后端官方要求Neo4j 5.26 或更高版本仓库中 docker-compose-neo4j.yml 固定使用neo4j:5.26.0镜像。安装步骤克隆仓库并进入mcp_server目录。使用uv创建虚拟环境并安装依赖# 安装 uv如尚未安装 curl -LsSf https://astral.sh/uv/install.sh | sh # 一步完成虚拟环境创建与依赖安装 uv sync # 可选安装额外的 LLM 提供商anthropic、gemini、groq、voyage、sentence-transformers uv sync --extra providersuv sync会依据pyproject.toml与uv.lock解析出确定性的依赖集合额外的providersextra 用于启用多 LLM/Embedding 提供商所需的可选依赖。四、配置体系config.yaml、环境变量与命令行参数服务支持三种配置来源优先级从高到低为命令行参数 环境变量 config.yaml文件 内置默认值这一优先级在 schema.py 的settings_customise_sources中实现init_settingsCLI优先随后是环境变量、YAML、dotenv最后是字段默认值。apply_cli_overrides则负责把--llm-provider、--model等参数逐个覆盖到配置对象上。默认配置服务开箱即用自带合理默认值项目默认值传输方式HTTPhttp://localhost:8000/mcp/数据库FalkorDB与 MCP Server 同容器组合部署LLMOpenAI模型gpt-5.5EmbedderOpenAItext-embedding-3-small数据库配置FalkorDB默认FalkorDB 是基于 Redis 的图数据库随 MCP Server 打包在同一 Docker 容器中是默认且推荐的方案database: provider: falkordb # Default providers: falkordb: uri: redis://localhost:6379 password: # Optional database: default_db # OptionalNeo4j生产环境或需要功能更完整的图数据库时推荐 Neo4jdatabase: provider: neo4j providers: neo4j: uri: bolt://localhost:7687 username: neo4j password: your_password database: neo4j # Optional, defaults to neo4j从源码看GraphitiService.initialize()graphiti_mcp_server.py会根据provider字段分别构造FalkorDriverhost/port/password/database或Neo4jDriveruri/user/password/database并以max_coroutinesself.semaphore_limit注入 Graphiti 客户端——这解释了并发限制如何在核心层生效。若数据库未启动会抛出带有明确排障提示的RuntimeError例如提示cd mcp_server docker compose up启动 FalkorDB。完整配置示例config.yaml 骨架server: transport: http # Default. Options: stdio, httpsse 已弃用 host: 0.0.0.0 port: 8000 llm: provider: openai # 或 anthropic、gemini、groq、azure_openai model: gpt-5.5 # 默认模型 max_tokens: 4096 # 兼容 OpenAI 的提供商可选json_schema默认或 json_object structured_output_mode: json_schema embedder: provider: openai # 或 azure_openai、gemini、voyage model: text-embedding-3-small dimensions: 1536 database: provider: falkordb # Default. Options: falkordb, neo4jconfig.yaml支持${VAR_NAME}或${VAR_NAME:default}形式的环境变量展开。这一机制由 schema.py 的YamlSettingsSource._expand_env_vars递归实现不仅支持整值替换还能把true/1/yes/on自动转为布尔值、空值转为None并对字典、列表递归展开。仓库提供了四份可直接使用的配置文件config.yaml通用默认配置含完整 LLM/Embedder/Database providers 与内置实体类型config-docker-falkordb.yaml面向docker-compose-falkordb.ymlFalkorDB URI 默认redis://falkordb:6379config-docker-falkordb-combined.yaml组合容器配置config-docker-neo4j.yamlNeo4j 后端配置使用 Ollama 运行本地 LLM将 Ollama 配置为 OpenAI 兼容端点即可llm: provider: openai model: gpt-oss:120b # 或你偏好的 Ollama 模型 api_base: http://localhost:11434/v1 api_key: ollama # 需要占位 key structured_output_mode: json_object # 当 json_schema 被接受但不强制生效时使用 embedder: provider: sentence_transformers # 本地部署推荐 model: all-MiniLM-L6-v2确保 Ollama 已在本地运行ollama serve。重要提示Graphiti 依赖结构化JSON输出来完成实体/边抽取与去重其可靠性在小型或本地模型上差异很大。请优先使用你的硬件能运行的最强模型——非常小的模型经常输出不符合预期 schema 的 JSON表现为摄入失败。关于structured_output_modejson_schemavsjson_object取舍的背景参见主 README.md 的 Structured output and small models 一节。如果某个 OpenAI 兼容端点接受json_schema却返回缺少extracted_entities等字段的对象请将structured_output_mode设为json_object这样 Graphiti 会把 schema 注入 prompt 而非依赖提供方侧的 schema 强制。这一字段在 schema.py 中被定义为Literal[json_schema, json_object]默认json_schema。内置实体类型Graphiti MCP Server 内置了用于结构化知识抽取的实体类型默认始终启用可通过config.yaml的entity_types段配置实体类型说明Preference用户偏好、选择、意见或取舍优先抽取用户特定信息Requirement必须满足的具体需求、特性或功能Procedure标准操作流程与顺序指令Location活动发生的物理或虚拟地点Event有时限的活动、事件或经历Person内容中提到的个人Organization公司、机构、团体或正式实体Document各种形式的信息内容书籍、文章、报告、视频等Topic对话、兴趣或知识领域的主题作为兜底Object物理物品、工具、设备或财物作为兜底配置方式完整清单见 config.yamlgraphiti: entity_types: - name: Preference description: User preferences, choices, opinions, or selections - name: Requirement description: Specific needs, features, or functionality # ... 其余实体类型在 episode 摄入期间MCP Server 会自动使用这些实体类型从对话和文档中抽取并结构化信息。底层实现上type_config.py 的build_entity_types/build_edge_types/build_edge_type_map会把配置转换成 Pydantic 模型注册给 graphiti-core若名称与src/models/entity_types.py、src/models/edge_types.py中注册的富模型匹配则使用带类型化属性的富模型否则按名称 描述构建文档型模型。升级注意这些内置类型现在注册为带类型化属性的富模型例如description抽取时会将属性存储到实体上。随附的默认config.yaml已启用它们因此在默认配置上运行的现有部署会从无属性抽取切换到富属性抽取。若要保持旧行为请将graphiti.entity_types设为空列表或删除这些条目。此外config.yaml还支持自定义边事实类型与连接约束graphiti: # 可选边事实类型。名称与 src/models/edge_types.py 中注册的模型匹配时使用富 Pydantic 模型 # 否则按下方 description 构建文档型模型。留空则保持 graphiti-core 默认边抽取行为。 # edge_types: # - name: WorksFor # description: Employment or membership of a person in an organization # 可选哪些边类型允许连接哪些实体类型。Entity 作为任一端点的通配符。 # edge_type_map: # - source: Person # target: Organization # edge_types: [WorksFor]关键环境变量NEO4J_URINeo4j 数据库 URI默认bolt://localhost:7687NEO4J_USERNeo4j 用户名默认neo4jNEO4J_PASSWORDNeo4j 密码默认demodemoNEO4J_DATABASENeo4j 数据库名默认neo4jOPENAI_API_KEYOpenAI API KeyOpenAI LLM/embedder 必需ANTHROPIC_API_KEYAnthropic API Key用于 Claude 模型GOOGLE_API_KEYGoogle API Key用于 Gemini 模型GROQ_API_KEYGroq API KeyAZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_DEPLOYMENTAzure OpenAI 三项必需配置AZURE_OPENAI_EMBEDDINGS_ENDPOINT/AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT可选Azure OpenAI Embedding 端点AZURE_OPENAI_API_VERSION可选Azure OpenAI API 版本USE_AZURE_AD可选是否使用 Azure 托管标识认证SEMAPHORE_LIMITepisode 处理并发度详见下文并发调优可将这些变量写入项目目录下的.env文件。服务启动时会优先加载mcp_server/.envgraphiti_mcp_server.py 通过load_dotenv实现找不到时回退到当前工作目录。除上述变量外配置模板中还可设置FALKORDB_URI、FALKORDB_PASSWORD、FALKORDB_DATABASE、MODEL_NAME、EMBEDDER_MODEL、GRAPHITI_GROUP_ID、USER_ID、EPISODE_ID_PREFIX等。五、运行 MCP Server默认方案FalkorDB 组合容器docker compose up启动后获得HTTP 传输http://localhost:8000/mcp/FalkorDB 图数据库localhost:6379FalkorDB Web UIhttp://localhost:3000OpenAI LLMgpt-5.5 模型使用 Neo4j 运行方式一Docker Compose# 同时启动 Neo4j 与 MCP Server docker compose -f docker/docker-compose-neo4j.yml up该 compose 文件默认凭据用户名neo4j、密码demodemo、Bolt URIbolt://neo4j:7687、浏览器 UIhttp://localhost:7474并将config-docker-neo4j.yaml只读挂载为容器内/app/mcp/config/config.yaml。方式二直连已有 Neo4j# 设置环境变量 export NEO4J_URIbolt://localhost:7687 export NEO4J_USERneo4j export NEO4J_PASSWORDyour_password # 以 Neo4j 运行 uv run main.py --database-provider neo4j或直接指定 Neo4j 配置文件uv run main.py --config config/config-docker-neo4j.yaml使用 FalkorDB 运行方式一Docker Compose分离容器docker compose -f docker/docker-compose-falkordb.yml upFalkorDB 配置Redis 端口6379、Web UIhttp://localhost:3000、连接redis://falkordb:6379。方式二直连已有 FalkorDB# 设置环境变量 export FALKORDB_URIredis://localhost:6379 export FALKORDB_PASSWORD # 如有密码保护则填写 # 以 FalkorDB 运行 uv run main.py --database-provider falkordb或uv run main.py --config config/config-docker-falkordb.yaml命令行参数一览参数说明取值--configYAML 配置文件路径默认config.yaml--llm-providerLLM 提供商openai、anthropic、gemini、groq、azure_openai--embedder-providerEmbedding 提供商openai、azure_openai、gemini、voyage--database-provider数据库提供商falkordb默认、neo4j--modelLLM 模型名如gpt-5.5--temperatureLLM 温度0.0–2.0--transport传输方式http默认、stdiosse已弃用--group-id图的命名空间默认main--destroy-graph启动时销毁所有 Graphiti 图布尔开关入口文件 main.py 是一个向后兼容的包装器它将src目录加入 Python 路径后调用graphiti_mcp_server.main()因此已有的部署脚本和文档可以直接使用uv run main.py ...。启动时服务会执行build_indices_and_constraints()构建索引并依次打印 LLM/Embedder/Database/Group ID/Transport 等配置日志。六、并发控制与 429 限流调优Graphiti 的摄入流水线面向高并发设计由SEMAPHORE_LIMIT环境变量控制它决定同时处理多少个 episode。由于每个 episode 涉及多次 LLM 调用实体抽取、去重、摘要实际并发的 LLM 请求数会是该值的数倍。默认值SEMAPHORE_LIMIT10适用于 OpenAI Tier 3、中档 Anthropic。按 LLM 提供商调整的建议值OpenAI按 RPM 分级层级速率建议SEMAPHORE_LIMITTier 1免费3 RPM1–2Tier 260 RPM5–8Tier 3500 RPM10–15Tier 45,000 RPM20–50Anthropic层级速率建议SEMAPHORE_LIMIT默认档50 RPM5–8高配额档1,000 RPM15–30Azure OpenAI请查阅 Azure Portal 中的配额后酌情调整从保守值开始逐步提高。Ollama本地取决于硬件 →SEMAPHORE_LIMIT1-5观察 CPU/GPU 使用率调整。症状与监控设置过高出现 429 限流错误、并行处理导致 API 成本上升设置过低episode 吞吐缓慢、API 配额利用不足监控手段观察日志中的429错误关注服务日志中的 episode 处理耗时在 LLM 提供商控制台核对实际请求速率跟踪 token 用量与成本设置方式写入.envSEMAPHORE_LIMIT10 # 根据你的 LLM 提供商层级调整源码中的信号量定义在 graphiti_mcp_server.pyint(os.getenv(SEMAPHORE_LIMIT, 10))它同时作为asyncio.Semaphore的容量和 Graphiti 客户端的max_coroutines传入。值得补充的是episode 之间并非完全乱序queue_service.py 为每个group_id维护独立的asyncio.Queue同一 group 的 episode 由单 worker 严格顺序处理以避免竞态条件不同 group 之间则通过全局信号量并发执行。这解释了返回立即成功、后台异步处理、同 group 串行的行为。七、Docker 部署与 .env 配置Dockerfile 使用uv管理依赖保证依赖安装的一致性。官方预构建容器为zepai/knowledge-graph-mcpstandalone 变体见 Dockerfile.standalone。环境配置在 mcp_server 目录创建 .env 文件cd graphiti/mcp_server cp .env.example .env编辑 .env 设置 API Key# 必需 - 至少一个 LLM 提供商的 API Key OPENAI_API_KEYyour_openai_api_key_here # 可选 - 其他 LLM 提供商 ANTHROPIC_API_KEYyour_anthropic_key GOOGLE_API_KEYyour_google_key GROQ_API_KEYyour_groq_key # 可选 - Embedding 提供商 VOYAGE_API_KEYyour_voyage_key重要.env文件必须位于mcp_server/目录即docker/子目录的上一级。运行 Docker Compose所有命令都必须在mcp_server目录下执行以确保.env被正确加载cd graphiti/mcp_server方案一FalkorDB 组合容器默认最简单docker compose up方案二Neo4j 数据库分离容器docker compose -f docker/docker-compose-neo4j.yml up方案三FalkorDB 分离容器docker compose -f docker/docker-compose-falkordb.yml up访问服务HTTP 端点http://localhost:8000/mcp/健康检查http://localhost:8000/health源码中通过mcp.custom_route(/health)注册返回{status: healthy, service: graphiti-mcp}供 Docker 与负载均衡器探活从 docker/ 子目录运行 Compose 的注意事项如果在docker/子目录而不是mcp_server/运行 Docker Compose需要修改 compose 文件中的.env路径# 将 compose 文件中的这行 env_file: - path: ../.env # 从 mcp_server/ 运行时 # 改为 env_file: - path: .env # 从 mcp_server/docker/ 运行时不过官方推荐始终从mcp_server/目录运行以避免混淆。八、可用的 MCP 工具Graphiti MCP Server 暴露以下工具均以mcp.tool()注册见 graphiti_mcp_server.py工具功能add_memory向知识图谱添加 episode支持文本、JSON 与消息格式add_triplet直接添加单条事实源实体 - 事实 - 目标实体绕过抽取search_nodes搜索相关实体支持entity_types与center_node_uuidsearch_memory_facts搜索相关事实边支持edge_types与valid_at/invalid_at日期范围过滤summarize_saga生成或刷新 saga 中 episode 的滚动摘要build_communities检测实体社区并生成高层社区摘要get_episode_entities溯源查询特定 episode UUID 创建的实体与事实delete_entity_edge从图中删除一条实体边delete_episode删除 episode并级联删除其独占创建的实体/事实get_entity_edge按 UUID 获取实体边get_episodes获取指定 group 最近的 episodesclear_graph清空指定 group(s) 的图谱数据get_status查询 MCP Server 状态与数据库连接add_memory核心写入工具这是向图写入信息的主要途径。调用后立即返回在后台异步处理。关键参数nameepisode 名称episode_body要持久化的内容当sourcejson时必须是正确转义的 JSON 字符串而非 Python 字典服务会自动从中抽取实体与关系source来源类型text默认、json、message三选一source_description来源描述reference_timeISO-8601 时间戳表示所描述事件的发生时间如2025-01-15T10:30:00Z无时区时按 UTC 解释省略则取当前时间。该参数在入队前即被解析校验parse_reference_time格式非法会立即报错而非后台静默失败excluded_entity_types本次抽取要排除的实体类型名列表custom_extraction_instructions仅对本次 episode 生效的额外自然语言抽取指引previous_episode_uuids显式指定用作上下文/对话历史的先前 episode UUID 列表覆盖自动检索update_communities为True时增量更新受本 episode 影响的社区摘要默认Falsesaga/saga_previous_episode_uuid将 episode 关联到有序 saga供summarize_saga汇总示例# 添加纯文本内容 add_memory( nameCompany News, episode_bodyAcme Corp announced a new product line today., sourcetext, source_descriptionnews article, group_idsome_arbitrary_string ) # 添加结构化 JSON 数据episode_body 应为 JSON 字符串 add_memory( nameCustomer Profile, episode_body{company: {name: Acme Technologies}, products: [{id: P001, name: CloudSync}, {id: P002, name: DataMiner}]}, sourcejson, source_descriptionCRM data ) # 记录过去发生的事件双时序 add_memory( nameHistorical Note, episode_bodyThe merger closed in early 2020., reference_time2020-03-01T00:00:00Z )搜索工具语义 关键词 图搜索search_nodes默认使用 RRFReciprocal Rank Fusion混合检索配置当传入center_node_uuid时会自动切换为基于节点距离node_distance的重排配置源码中对应NODE_HYBRID_SEARCH_RRF与NODE_HYBRID_SEARCH_NODE_DISTANCE两个配方。search_memory_facts则支持valid_at_after/valid_at_before/invalid_at_after/invalid_at_before四组 ISO-8601 时间边界实现某时间点/时间窗内有效的事实查询——这正是时序知识图谱相对普通 RAG 的关键差异能力。自定义实体类型与边事实类型——包括哪些边类型允许连接哪些实体类型——可在config/config.yaml的graphiti段下配置参见其中的entity_types、edge_types与edge_type_map键。九、与 MCP 客户端集成VS Code / GitHub CopilotVS Code 配合 GitHub Copilot Chat 扩展支持 MCP Server。在 VS Code 设置.vscode/mcp.json或全局设置中添加{ mcpServers: { graphiti: { uri: http://localhost:8000/mcp/, transport: { type: http } } } }其他 MCP 客户端stdio重要需要安装 Python 包管理器uv确保填写uv二进制的完整路径与 Graphiti 项目文件夹的完整路径。{ mcpServers: { graphiti-memory: { transport: stdio, command: /Users/user/.local/bin/uv, args: [ run, --isolated, --directory, /Users/user/dev/zep/graphiti/mcp_server, --project, ., main.py, --transport, stdio ], env: { NEO4J_URI: bolt://localhost:7687, NEO4J_USER: neo4j, NEO4J_PASSWORD: password, OPENAI_API_KEY: sk-XXXXXXXX, MODEL_NAME: gpt-5.5 } } } }仓库还提供了可直接参考的 mcp_config_stdio_example.json 模板。对于 HTTP 传输默认使用{ mcpServers: { graphiti-memory: { transport: http, url: http://localhost:8000/mcp/ } } }集成 Cursor IDE使用默认 HTTP 传输运行 MCP Serveruv run main.py --group-id your_group_id提示指定group_id可为图谱数据划分命名空间不指定时服务使用main作为 group_id。或docker compose up配置 Cursor 连接{ mcpServers: { graphiti-memory: { url: http://localhost:8000/mcp/ } } }将 Graphiti 规则添加到 Cursor 的 User Rules 中详见 cursor_rules.md。这些规则定义了一整套 Agent 记忆使用范式任务开始前总是先用search_nodes/search_facts检索相关偏好与流程并按实体类型过滤发现新需求/偏好时立即用add_memory存储长需求拆分为短逻辑块将用户偏好记录为 procedure、把实体关系存为 facts工作中遵循已发现的偏好、按步骤执行 procedure使用center_node_uuid围绕特定节点扩展检索。在 Cursor 中启动 Agent 会话。该集成使 Cursor 中的 AI 助手能够通过 Graphiti 的知识图谱能力维持持久记忆。集成 Claude DesktopDocker MCP ServerGraphiti MCP Server 使用 HTTP 传输端点为/mcp/。Claude Desktop 原生不支持 HTTP 传输因此需要通过mcp-remote之类的网关桥接运行 MCP Serverdocker compose up # 或直接用 uv 运行 uv run main.py可选全局安装 mcp-remote如果希望全局安装或遇到npx拉取包的问题可以npm install -g mcp-remote否则下一步的npx会自动处理。配置 Claude Desktop打开配置文件通常是claude_desktop_config.json在mcpServers段中添加{ mcpServers: { graphiti-memory: { command: npx, // 若 npx 不在 PATH 中可写 mcp-remote 的完整路径 args: [ mcp-remote, http://localhost:8000/mcp/ ] } } }如果已有mcpServers条目把graphiti-memory或你选的名字作为新键加入即可。重启 Claude Desktop使配置生效。十、遥测TelemetryGraphiti MCP Server 使用 Graphiti 核心库其中包含匿名遥测收集。初始化服务器时会收集匿名使用统计以帮助改进框架。收集内容匿名标识符与系统信息操作系统、Python 版本Graphiti 版本与配置选择LLM 提供商、数据库后端、embedder 类型绝不收集个人数据、API Key 或实际图谱内容禁用方式export GRAPHITI_TELEMETRY_ENABLEDfalse或写入.env文件GRAPHITI_TELEMETRY_ENABLEDfalse收集内容与原因的完整说明见主 README.md 的 Telemetry 一节。十一、需求清单与适用前提Python 3.10 或更高版本OpenAI API Key用于 LLM 操作与 embeddings或其他 LLM 提供商的 API KeyMCP 兼容客户端Docker 与 Docker Compose默认 FalkorDB 组合容器方案需要可选Neo4j 数据库5.26 或更高版本如果不使用默认的 FalkorDB 方案结语Graphiti MCP Server 将时序感知知识图谱的能力封装成标准的 MCP 工具集使 Claude、Cursor、VS Code 等 AI 助手获得跨会话的持久记忆add_memory负责写入支持文本/JSON/消息与reference_time双时序search_nodes/search_memory_facts负责按实体类型、边类型与时间窗精确检索summarize_saga与build_communities提供高层摘要get_episode_entities支持全程溯源。结合 FalkorDB 单容器一键部署、Neo4j 生产级后端切换、SEMAPHORE_LIMIT并发调优与structured_output_mode兼容策略你可以基于 mcp_server 快速落地一套可维护的 Agent 记忆系统——所有配置示例与运行命令均可直接复制使用。【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Graphiti MCP Server 实战指南：为 AI Agent 构建可查询的时序知识图谱内存服务
Graphiti MCP Server 实战指南为 AI Agent 构建可查询的时序知识图谱内存服务【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphitiGraphiti 是一个用于构建和查询**时序感知知识图谱temporally-aware knowledge graph**的框架专为在动态环境中运行的 AI Agent 设计。本指南聚焦仓库中的 mcp_server/README.md完整讲解如何通过 Model Context ProtocolMCP将 Graphiti 的能力暴露给 Claude Desktop、Cursor、VS Code 等 MCP 客户端从 Docker 一键启动、config.yaml 配置、双图数据库FalkorDB / Neo4j切换到 13 个 MCP 工具的实际用法与并发调优。读完本文你将掌握一套可复制的AI Agent 持久化记忆部署方案并理解其底层调用链与配置优先级。一、Graphiti MCP Server 是什么与传统的检索增强生成RAG方法不同Graphiti 会持续将用户交互、结构化与非结构化的企业数据以及外部信息整合进一个连贯、可查询的图结构中。它支持增量数据更新、高效检索和精确的历史查询且无需完整重算图谱因此非常适合构建交互式、上下文感知的 AI 应用。Graphiti MCP Server 是这个框架的一个实验性 MCP 实现它把 Graphiti 的核心功能通过 MCP 协议暴露出来让 AI 助手可以读写知识图谱。从源码看整个服务围绕三个核心抽象组织数据见 graphiti_mcp_server.py 中的服务指令Episodes情节内容片段如文本、消息或 JSON 数据Nodes实体图节点即从内容中抽取出的实体Facts事实实体与实体之间的关系边。每一份信息都按group_id分区因此你可以在同一张图里维护多个相互隔离的知识域。更重要的是它的双时序模型bi-temporal model每个 episode 既记录何时被写入也记录所描述事件实际发生的时间。当你向add_memory传入reference_time时就设置了事件发生时间否则默认使用当前时间。事实facts携带valid_at/invalid_at元数据新信息可以取代旧事实同时历史被完整保留——这正是时序感知的核心。核心能力一览Episode 管理新增、检索、删除 episode支持文本、消息、JSON 三种来源实体管理搜索并管理图中的实体节点与关系搜索能力通过语义与混合检索搜索事实边和节点摘要分组管理通过group_id组织和管理相关数据图维护清空图、重建索引图数据库支持FalkorDB默认与 Neo4j 双后端多 LLM 提供商OpenAI、Anthropic、Gemini、Groq、Azure OpenAI多 Embedding 提供商OpenAI、Voyage、Sentence Transformers、Gemini丰富实体类型内置 Preference、Requirements、Procedures、Locations、Events、Organizations、Documents 等用于结构化知识抽取HTTP 传输默认 HTTP 传输MCP 端点为/mcp/兼容主流客户端队列化异步处理episode 异步处理支持可配置并发上限二、快速开始两种接入路径克隆仓库git clone https://github.com/getzep/graphiti.git或使用 GitHub CLIgh repo clone getzep/graphiti路径一Claude Desktop 等仅支持 stdio 的客户端记录本目录的完整路径cd graphiti pwd安装环境依赖。在 Claude、Cursor 或其他 MCP 客户端中配置使用 stdio 传输具体配置文件的存放位置请查阅各客户端文档。路径二Cursor 等支持 HTTP 的客户端进入mcp_server目录cd graphiti/mcp_server使用 Docker Compose 启动FalkorDB MCP Server 组合容器推荐docker compose up这会同时在单个容器中启动 FalkorDB 和 MCP Server。备选方案使用 Neo4j 拆分容器运行docker compose -f docker/docker-compose-neo4j.yml up将 MCP 客户端指向http://localhost:8000/mcp/。从 docker-compose.yml 可以看到组合容器同时暴露三个端口6379FalkorDB/Redis、3000FalkorDB Web UI、8000MCP Server HTTP并通过healthcheck定期执行redis-cli ping探活。默认镜像为zepai/knowledge-graph-mcp:latest构建参数GRAPHITI_CORE_VERSION默认锁定0.29.1、MCP_SERVER_VERSION默认1.0.2。三、安装与前置条件前置条件Docker 与 Docker Compose默认 FalkorDB 方案需要OpenAI API Key用于 LLM 操作或其它受支持 LLM 提供商的 API Key可选Python 3.10若以独立方式运行 MCP Server 并连接外部 FalkorDB 实例仓库 pyproject.toml 声明了 Python 3.10 的要求若使用 Neo4j 后端官方要求Neo4j 5.26 或更高版本仓库中 docker-compose-neo4j.yml 固定使用neo4j:5.26.0镜像。安装步骤克隆仓库并进入mcp_server目录。使用uv创建虚拟环境并安装依赖# 安装 uv如尚未安装 curl -LsSf https://astral.sh/uv/install.sh | sh # 一步完成虚拟环境创建与依赖安装 uv sync # 可选安装额外的 LLM 提供商anthropic、gemini、groq、voyage、sentence-transformers uv sync --extra providersuv sync会依据pyproject.toml与uv.lock解析出确定性的依赖集合额外的providersextra 用于启用多 LLM/Embedding 提供商所需的可选依赖。四、配置体系config.yaml、环境变量与命令行参数服务支持三种配置来源优先级从高到低为命令行参数 环境变量 config.yaml文件 内置默认值这一优先级在 schema.py 的settings_customise_sources中实现init_settingsCLI优先随后是环境变量、YAML、dotenv最后是字段默认值。apply_cli_overrides则负责把--llm-provider、--model等参数逐个覆盖到配置对象上。默认配置服务开箱即用自带合理默认值项目默认值传输方式HTTPhttp://localhost:8000/mcp/数据库FalkorDB与 MCP Server 同容器组合部署LLMOpenAI模型gpt-5.5EmbedderOpenAItext-embedding-3-small数据库配置FalkorDB默认FalkorDB 是基于 Redis 的图数据库随 MCP Server 打包在同一 Docker 容器中是默认且推荐的方案database: provider: falkordb # Default providers: falkordb: uri: redis://localhost:6379 password: # Optional database: default_db # OptionalNeo4j生产环境或需要功能更完整的图数据库时推荐 Neo4jdatabase: provider: neo4j providers: neo4j: uri: bolt://localhost:7687 username: neo4j password: your_password database: neo4j # Optional, defaults to neo4j从源码看GraphitiService.initialize()graphiti_mcp_server.py会根据provider字段分别构造FalkorDriverhost/port/password/database或Neo4jDriveruri/user/password/database并以max_coroutinesself.semaphore_limit注入 Graphiti 客户端——这解释了并发限制如何在核心层生效。若数据库未启动会抛出带有明确排障提示的RuntimeError例如提示cd mcp_server docker compose up启动 FalkorDB。完整配置示例config.yaml 骨架server: transport: http # Default. Options: stdio, httpsse 已弃用 host: 0.0.0.0 port: 8000 llm: provider: openai # 或 anthropic、gemini、groq、azure_openai model: gpt-5.5 # 默认模型 max_tokens: 4096 # 兼容 OpenAI 的提供商可选json_schema默认或 json_object structured_output_mode: json_schema embedder: provider: openai # 或 azure_openai、gemini、voyage model: text-embedding-3-small dimensions: 1536 database: provider: falkordb # Default. Options: falkordb, neo4jconfig.yaml支持${VAR_NAME}或${VAR_NAME:default}形式的环境变量展开。这一机制由 schema.py 的YamlSettingsSource._expand_env_vars递归实现不仅支持整值替换还能把true/1/yes/on自动转为布尔值、空值转为None并对字典、列表递归展开。仓库提供了四份可直接使用的配置文件config.yaml通用默认配置含完整 LLM/Embedder/Database providers 与内置实体类型config-docker-falkordb.yaml面向docker-compose-falkordb.ymlFalkorDB URI 默认redis://falkordb:6379config-docker-falkordb-combined.yaml组合容器配置config-docker-neo4j.yamlNeo4j 后端配置使用 Ollama 运行本地 LLM将 Ollama 配置为 OpenAI 兼容端点即可llm: provider: openai model: gpt-oss:120b # 或你偏好的 Ollama 模型 api_base: http://localhost:11434/v1 api_key: ollama # 需要占位 key structured_output_mode: json_object # 当 json_schema 被接受但不强制生效时使用 embedder: provider: sentence_transformers # 本地部署推荐 model: all-MiniLM-L6-v2确保 Ollama 已在本地运行ollama serve。重要提示Graphiti 依赖结构化JSON输出来完成实体/边抽取与去重其可靠性在小型或本地模型上差异很大。请优先使用你的硬件能运行的最强模型——非常小的模型经常输出不符合预期 schema 的 JSON表现为摄入失败。关于structured_output_modejson_schemavsjson_object取舍的背景参见主 README.md 的 Structured output and small models 一节。如果某个 OpenAI 兼容端点接受json_schema却返回缺少extracted_entities等字段的对象请将structured_output_mode设为json_object这样 Graphiti 会把 schema 注入 prompt 而非依赖提供方侧的 schema 强制。这一字段在 schema.py 中被定义为Literal[json_schema, json_object]默认json_schema。内置实体类型Graphiti MCP Server 内置了用于结构化知识抽取的实体类型默认始终启用可通过config.yaml的entity_types段配置实体类型说明Preference用户偏好、选择、意见或取舍优先抽取用户特定信息Requirement必须满足的具体需求、特性或功能Procedure标准操作流程与顺序指令Location活动发生的物理或虚拟地点Event有时限的活动、事件或经历Person内容中提到的个人Organization公司、机构、团体或正式实体Document各种形式的信息内容书籍、文章、报告、视频等Topic对话、兴趣或知识领域的主题作为兜底Object物理物品、工具、设备或财物作为兜底配置方式完整清单见 config.yamlgraphiti: entity_types: - name: Preference description: User preferences, choices, opinions, or selections - name: Requirement description: Specific needs, features, or functionality # ... 其余实体类型在 episode 摄入期间MCP Server 会自动使用这些实体类型从对话和文档中抽取并结构化信息。底层实现上type_config.py 的build_entity_types/build_edge_types/build_edge_type_map会把配置转换成 Pydantic 模型注册给 graphiti-core若名称与src/models/entity_types.py、src/models/edge_types.py中注册的富模型匹配则使用带类型化属性的富模型否则按名称 描述构建文档型模型。升级注意这些内置类型现在注册为带类型化属性的富模型例如description抽取时会将属性存储到实体上。随附的默认config.yaml已启用它们因此在默认配置上运行的现有部署会从无属性抽取切换到富属性抽取。若要保持旧行为请将graphiti.entity_types设为空列表或删除这些条目。此外config.yaml还支持自定义边事实类型与连接约束graphiti: # 可选边事实类型。名称与 src/models/edge_types.py 中注册的模型匹配时使用富 Pydantic 模型 # 否则按下方 description 构建文档型模型。留空则保持 graphiti-core 默认边抽取行为。 # edge_types: # - name: WorksFor # description: Employment or membership of a person in an organization # 可选哪些边类型允许连接哪些实体类型。Entity 作为任一端点的通配符。 # edge_type_map: # - source: Person # target: Organization # edge_types: [WorksFor]关键环境变量NEO4J_URINeo4j 数据库 URI默认bolt://localhost:7687NEO4J_USERNeo4j 用户名默认neo4jNEO4J_PASSWORDNeo4j 密码默认demodemoNEO4J_DATABASENeo4j 数据库名默认neo4jOPENAI_API_KEYOpenAI API KeyOpenAI LLM/embedder 必需ANTHROPIC_API_KEYAnthropic API Key用于 Claude 模型GOOGLE_API_KEYGoogle API Key用于 Gemini 模型GROQ_API_KEYGroq API KeyAZURE_OPENAI_API_KEY/AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_DEPLOYMENTAzure OpenAI 三项必需配置AZURE_OPENAI_EMBEDDINGS_ENDPOINT/AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT可选Azure OpenAI Embedding 端点AZURE_OPENAI_API_VERSION可选Azure OpenAI API 版本USE_AZURE_AD可选是否使用 Azure 托管标识认证SEMAPHORE_LIMITepisode 处理并发度详见下文并发调优可将这些变量写入项目目录下的.env文件。服务启动时会优先加载mcp_server/.envgraphiti_mcp_server.py 通过load_dotenv实现找不到时回退到当前工作目录。除上述变量外配置模板中还可设置FALKORDB_URI、FALKORDB_PASSWORD、FALKORDB_DATABASE、MODEL_NAME、EMBEDDER_MODEL、GRAPHITI_GROUP_ID、USER_ID、EPISODE_ID_PREFIX等。五、运行 MCP Server默认方案FalkorDB 组合容器docker compose up启动后获得HTTP 传输http://localhost:8000/mcp/FalkorDB 图数据库localhost:6379FalkorDB Web UIhttp://localhost:3000OpenAI LLMgpt-5.5 模型使用 Neo4j 运行方式一Docker Compose# 同时启动 Neo4j 与 MCP Server docker compose -f docker/docker-compose-neo4j.yml up该 compose 文件默认凭据用户名neo4j、密码demodemo、Bolt URIbolt://neo4j:7687、浏览器 UIhttp://localhost:7474并将config-docker-neo4j.yaml只读挂载为容器内/app/mcp/config/config.yaml。方式二直连已有 Neo4j# 设置环境变量 export NEO4J_URIbolt://localhost:7687 export NEO4J_USERneo4j export NEO4J_PASSWORDyour_password # 以 Neo4j 运行 uv run main.py --database-provider neo4j或直接指定 Neo4j 配置文件uv run main.py --config config/config-docker-neo4j.yaml使用 FalkorDB 运行方式一Docker Compose分离容器docker compose -f docker/docker-compose-falkordb.yml upFalkorDB 配置Redis 端口6379、Web UIhttp://localhost:3000、连接redis://falkordb:6379。方式二直连已有 FalkorDB# 设置环境变量 export FALKORDB_URIredis://localhost:6379 export FALKORDB_PASSWORD # 如有密码保护则填写 # 以 FalkorDB 运行 uv run main.py --database-provider falkordb或uv run main.py --config config/config-docker-falkordb.yaml命令行参数一览参数说明取值--configYAML 配置文件路径默认config.yaml--llm-providerLLM 提供商openai、anthropic、gemini、groq、azure_openai--embedder-providerEmbedding 提供商openai、azure_openai、gemini、voyage--database-provider数据库提供商falkordb默认、neo4j--modelLLM 模型名如gpt-5.5--temperatureLLM 温度0.0–2.0--transport传输方式http默认、stdiosse已弃用--group-id图的命名空间默认main--destroy-graph启动时销毁所有 Graphiti 图布尔开关入口文件 main.py 是一个向后兼容的包装器它将src目录加入 Python 路径后调用graphiti_mcp_server.main()因此已有的部署脚本和文档可以直接使用uv run main.py ...。启动时服务会执行build_indices_and_constraints()构建索引并依次打印 LLM/Embedder/Database/Group ID/Transport 等配置日志。六、并发控制与 429 限流调优Graphiti 的摄入流水线面向高并发设计由SEMAPHORE_LIMIT环境变量控制它决定同时处理多少个 episode。由于每个 episode 涉及多次 LLM 调用实体抽取、去重、摘要实际并发的 LLM 请求数会是该值的数倍。默认值SEMAPHORE_LIMIT10适用于 OpenAI Tier 3、中档 Anthropic。按 LLM 提供商调整的建议值OpenAI按 RPM 分级层级速率建议SEMAPHORE_LIMITTier 1免费3 RPM1–2Tier 260 RPM5–8Tier 3500 RPM10–15Tier 45,000 RPM20–50Anthropic层级速率建议SEMAPHORE_LIMIT默认档50 RPM5–8高配额档1,000 RPM15–30Azure OpenAI请查阅 Azure Portal 中的配额后酌情调整从保守值开始逐步提高。Ollama本地取决于硬件 →SEMAPHORE_LIMIT1-5观察 CPU/GPU 使用率调整。症状与监控设置过高出现 429 限流错误、并行处理导致 API 成本上升设置过低episode 吞吐缓慢、API 配额利用不足监控手段观察日志中的429错误关注服务日志中的 episode 处理耗时在 LLM 提供商控制台核对实际请求速率跟踪 token 用量与成本设置方式写入.envSEMAPHORE_LIMIT10 # 根据你的 LLM 提供商层级调整源码中的信号量定义在 graphiti_mcp_server.pyint(os.getenv(SEMAPHORE_LIMIT, 10))它同时作为asyncio.Semaphore的容量和 Graphiti 客户端的max_coroutines传入。值得补充的是episode 之间并非完全乱序queue_service.py 为每个group_id维护独立的asyncio.Queue同一 group 的 episode 由单 worker 严格顺序处理以避免竞态条件不同 group 之间则通过全局信号量并发执行。这解释了返回立即成功、后台异步处理、同 group 串行的行为。七、Docker 部署与 .env 配置Dockerfile 使用uv管理依赖保证依赖安装的一致性。官方预构建容器为zepai/knowledge-graph-mcpstandalone 变体见 Dockerfile.standalone。环境配置在 mcp_server 目录创建 .env 文件cd graphiti/mcp_server cp .env.example .env编辑 .env 设置 API Key# 必需 - 至少一个 LLM 提供商的 API Key OPENAI_API_KEYyour_openai_api_key_here # 可选 - 其他 LLM 提供商 ANTHROPIC_API_KEYyour_anthropic_key GOOGLE_API_KEYyour_google_key GROQ_API_KEYyour_groq_key # 可选 - Embedding 提供商 VOYAGE_API_KEYyour_voyage_key重要.env文件必须位于mcp_server/目录即docker/子目录的上一级。运行 Docker Compose所有命令都必须在mcp_server目录下执行以确保.env被正确加载cd graphiti/mcp_server方案一FalkorDB 组合容器默认最简单docker compose up方案二Neo4j 数据库分离容器docker compose -f docker/docker-compose-neo4j.yml up方案三FalkorDB 分离容器docker compose -f docker/docker-compose-falkordb.yml up访问服务HTTP 端点http://localhost:8000/mcp/健康检查http://localhost:8000/health源码中通过mcp.custom_route(/health)注册返回{status: healthy, service: graphiti-mcp}供 Docker 与负载均衡器探活从 docker/ 子目录运行 Compose 的注意事项如果在docker/子目录而不是mcp_server/运行 Docker Compose需要修改 compose 文件中的.env路径# 将 compose 文件中的这行 env_file: - path: ../.env # 从 mcp_server/ 运行时 # 改为 env_file: - path: .env # 从 mcp_server/docker/ 运行时不过官方推荐始终从mcp_server/目录运行以避免混淆。八、可用的 MCP 工具Graphiti MCP Server 暴露以下工具均以mcp.tool()注册见 graphiti_mcp_server.py工具功能add_memory向知识图谱添加 episode支持文本、JSON 与消息格式add_triplet直接添加单条事实源实体 - 事实 - 目标实体绕过抽取search_nodes搜索相关实体支持entity_types与center_node_uuidsearch_memory_facts搜索相关事实边支持edge_types与valid_at/invalid_at日期范围过滤summarize_saga生成或刷新 saga 中 episode 的滚动摘要build_communities检测实体社区并生成高层社区摘要get_episode_entities溯源查询特定 episode UUID 创建的实体与事实delete_entity_edge从图中删除一条实体边delete_episode删除 episode并级联删除其独占创建的实体/事实get_entity_edge按 UUID 获取实体边get_episodes获取指定 group 最近的 episodesclear_graph清空指定 group(s) 的图谱数据get_status查询 MCP Server 状态与数据库连接add_memory核心写入工具这是向图写入信息的主要途径。调用后立即返回在后台异步处理。关键参数nameepisode 名称episode_body要持久化的内容当sourcejson时必须是正确转义的 JSON 字符串而非 Python 字典服务会自动从中抽取实体与关系source来源类型text默认、json、message三选一source_description来源描述reference_timeISO-8601 时间戳表示所描述事件的发生时间如2025-01-15T10:30:00Z无时区时按 UTC 解释省略则取当前时间。该参数在入队前即被解析校验parse_reference_time格式非法会立即报错而非后台静默失败excluded_entity_types本次抽取要排除的实体类型名列表custom_extraction_instructions仅对本次 episode 生效的额外自然语言抽取指引previous_episode_uuids显式指定用作上下文/对话历史的先前 episode UUID 列表覆盖自动检索update_communities为True时增量更新受本 episode 影响的社区摘要默认Falsesaga/saga_previous_episode_uuid将 episode 关联到有序 saga供summarize_saga汇总示例# 添加纯文本内容 add_memory( nameCompany News, episode_bodyAcme Corp announced a new product line today., sourcetext, source_descriptionnews article, group_idsome_arbitrary_string ) # 添加结构化 JSON 数据episode_body 应为 JSON 字符串 add_memory( nameCustomer Profile, episode_body{company: {name: Acme Technologies}, products: [{id: P001, name: CloudSync}, {id: P002, name: DataMiner}]}, sourcejson, source_descriptionCRM data ) # 记录过去发生的事件双时序 add_memory( nameHistorical Note, episode_bodyThe merger closed in early 2020., reference_time2020-03-01T00:00:00Z )搜索工具语义 关键词 图搜索search_nodes默认使用 RRFReciprocal Rank Fusion混合检索配置当传入center_node_uuid时会自动切换为基于节点距离node_distance的重排配置源码中对应NODE_HYBRID_SEARCH_RRF与NODE_HYBRID_SEARCH_NODE_DISTANCE两个配方。search_memory_facts则支持valid_at_after/valid_at_before/invalid_at_after/invalid_at_before四组 ISO-8601 时间边界实现某时间点/时间窗内有效的事实查询——这正是时序知识图谱相对普通 RAG 的关键差异能力。自定义实体类型与边事实类型——包括哪些边类型允许连接哪些实体类型——可在config/config.yaml的graphiti段下配置参见其中的entity_types、edge_types与edge_type_map键。九、与 MCP 客户端集成VS Code / GitHub CopilotVS Code 配合 GitHub Copilot Chat 扩展支持 MCP Server。在 VS Code 设置.vscode/mcp.json或全局设置中添加{ mcpServers: { graphiti: { uri: http://localhost:8000/mcp/, transport: { type: http } } } }其他 MCP 客户端stdio重要需要安装 Python 包管理器uv确保填写uv二进制的完整路径与 Graphiti 项目文件夹的完整路径。{ mcpServers: { graphiti-memory: { transport: stdio, command: /Users/user/.local/bin/uv, args: [ run, --isolated, --directory, /Users/user/dev/zep/graphiti/mcp_server, --project, ., main.py, --transport, stdio ], env: { NEO4J_URI: bolt://localhost:7687, NEO4J_USER: neo4j, NEO4J_PASSWORD: password, OPENAI_API_KEY: sk-XXXXXXXX, MODEL_NAME: gpt-5.5 } } } }仓库还提供了可直接参考的 mcp_config_stdio_example.json 模板。对于 HTTP 传输默认使用{ mcpServers: { graphiti-memory: { transport: http, url: http://localhost:8000/mcp/ } } }集成 Cursor IDE使用默认 HTTP 传输运行 MCP Serveruv run main.py --group-id your_group_id提示指定group_id可为图谱数据划分命名空间不指定时服务使用main作为 group_id。或docker compose up配置 Cursor 连接{ mcpServers: { graphiti-memory: { url: http://localhost:8000/mcp/ } } }将 Graphiti 规则添加到 Cursor 的 User Rules 中详见 cursor_rules.md。这些规则定义了一整套 Agent 记忆使用范式任务开始前总是先用search_nodes/search_facts检索相关偏好与流程并按实体类型过滤发现新需求/偏好时立即用add_memory存储长需求拆分为短逻辑块将用户偏好记录为 procedure、把实体关系存为 facts工作中遵循已发现的偏好、按步骤执行 procedure使用center_node_uuid围绕特定节点扩展检索。在 Cursor 中启动 Agent 会话。该集成使 Cursor 中的 AI 助手能够通过 Graphiti 的知识图谱能力维持持久记忆。集成 Claude DesktopDocker MCP ServerGraphiti MCP Server 使用 HTTP 传输端点为/mcp/。Claude Desktop 原生不支持 HTTP 传输因此需要通过mcp-remote之类的网关桥接运行 MCP Serverdocker compose up # 或直接用 uv 运行 uv run main.py可选全局安装 mcp-remote如果希望全局安装或遇到npx拉取包的问题可以npm install -g mcp-remote否则下一步的npx会自动处理。配置 Claude Desktop打开配置文件通常是claude_desktop_config.json在mcpServers段中添加{ mcpServers: { graphiti-memory: { command: npx, // 若 npx 不在 PATH 中可写 mcp-remote 的完整路径 args: [ mcp-remote, http://localhost:8000/mcp/ ] } } }如果已有mcpServers条目把graphiti-memory或你选的名字作为新键加入即可。重启 Claude Desktop使配置生效。十、遥测TelemetryGraphiti MCP Server 使用 Graphiti 核心库其中包含匿名遥测收集。初始化服务器时会收集匿名使用统计以帮助改进框架。收集内容匿名标识符与系统信息操作系统、Python 版本Graphiti 版本与配置选择LLM 提供商、数据库后端、embedder 类型绝不收集个人数据、API Key 或实际图谱内容禁用方式export GRAPHITI_TELEMETRY_ENABLEDfalse或写入.env文件GRAPHITI_TELEMETRY_ENABLEDfalse收集内容与原因的完整说明见主 README.md 的 Telemetry 一节。十一、需求清单与适用前提Python 3.10 或更高版本OpenAI API Key用于 LLM 操作与 embeddings或其他 LLM 提供商的 API KeyMCP 兼容客户端Docker 与 Docker Compose默认 FalkorDB 组合容器方案需要可选Neo4j 数据库5.26 或更高版本如果不使用默认的 FalkorDB 方案结语Graphiti MCP Server 将时序感知知识图谱的能力封装成标准的 MCP 工具集使 Claude、Cursor、VS Code 等 AI 助手获得跨会话的持久记忆add_memory负责写入支持文本/JSON/消息与reference_time双时序search_nodes/search_memory_facts负责按实体类型、边类型与时间窗精确检索summarize_saga与build_communities提供高层摘要get_episode_entities支持全程溯源。结合 FalkorDB 单容器一键部署、Neo4j 生产级后端切换、SEMAPHORE_LIMIT并发调优与structured_output_mode兼容策略你可以基于 mcp_server 快速落地一套可维护的 Agent 记忆系统——所有配置示例与运行命令均可直接复制使用。【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考