Polyg MCP

The memory system that understands causality.

Ask "why did auth fail?" and get a traced causal chain — not just similar documents.

Problem · Architecture · Pipeline · Quick Start · Deep Dive

______________________________________________________________________

问题

大多数代理内存都是平面检索——文本块上的余弦相似性。polyg-mcp是一个多图记忆系统，它追踪因果链，重建时间线，映射实体依赖关系，并用置信度评分的因果路径回答“为什么”。

Query: "Why did the auth service fail?"

Vector store → 5 documents mentioning "auth service" ranked by cosine similarity.

polyg-mcp  → JWT_SECRET removed (PR #1234) → deploy missing secret → CrashLoopBackOff → 503s
                    ↓ 100%                        ↓ 100%                  ↓ 95%           ↓ 90%

             Root cause identified with full causal chain.
             Confidence degrades at each hop — quantified uncertainty, not guesswork.

通过类型化交叉链接连接的四个专用图（语义、实体、时间、因果）(X_REPRESENTS, X_INVOLVES, X_AFFECTS, X_REFERS_TO)允许单个查询遍历所有四个维度。该系统公开了15个MCP工具，每次检索需要2个LLM调用——一个用于意图分类，一个用于综合。

______________________________________________________________________

建筑

系统概述

MCP Client (Claude, Cursor, any MCP agent)
     │
     │  MCP Protocol (HTTP/SSE)
     ▼
PolygMCPServer ─── Tool Registration (15 tools: 6 MAGMA + 7 write + 2 admin)
     │
     ▼
SharedResources ── Orchestrator, FalkorDB Adapter, LLM Provider, Embedding Provider
     │
     ▼
MAGMA Pipeline ── IntentClassifier → Executor → Merger → Linearizer → Synthesizer
     │
     ├── SemanticGraph   (S_Concept, vector similarity, cosine distance)
     ├── EntityGraph      (E_Entity, E_RELATES, BFS traversal)
     ├── TemporalGraph    (T_Event, T_Fact, ISO timestamp sort)
     ├── CausalGraph      (C_Node, C_CAUSES with confidence, path traversal)
     └── CrossLinker       (X_REPRESENTS, X_INVOLVES, X_AFFECTS, X_REFERS_TO)
            │
            ▼
       FalkorDB (Redis-based graph database, Cypher queries)

四个内存图

跨图链接

这些图表不是孤立的。已输入 X_ 边跨图边界连接节点，实现从单个查询的多跳遍历：

所有交叉链接使用 MERGE 为了幂等性。当一个图被清除时，孤立 X_ 链接会自动清除。

横向示例 — *“为什么在周二部署后身份验证失败？”*:

Semantic search      → S_Concept("auth-service", score=0.92)
    ↓ X_REPRESENTS
Entity expand        → E_Entity("auth-service", type=SERVICE) → E_RELATES → E_Entity("api-gateway")
    ↓ X_INVOLVES
Temporal expand      → T_Event("deploy v2.3.0", 14:00) → T_Event("CrashLoop", 14:03)
    ↓ X_REFERS_TO
Causal expand        → C_Node("secret removed") →[100%]→ C_Node("crash") →[95%]→ C_Node("503s")

______________________________________________________________________

MAGMA管道

岩浆 （多图自适应基于图的内存架构）通过2个LLM调用，分7步处理每次检索：

意图自适应深度

分类器为每个图分配遍历深度。这是自适应检索的核心——系统不是均匀扩展的。

             Semantic  Entity  Temporal  Causal
  WHY            1       1        1        3      ← deep causal chain traversal
  WHEN           1       1        3        1      ← deep timeline reconstruction
  WHO / WHAT     1       2        1        1      ← entity relationship expansion
  EXPLORE        2       2        2        2      ← uniform exploration

线性化策略

合并后，必须为LLM上下文窗口排序节点。排序策略依赖于意图：

多视图增强

在多个图扩展中发现的节点获得了相关性提升。直觉：如果一个节点出现在因果和时间视图中，它更有可能是答案的核心。

final_score = avg_score × 1.5^(view_count - 1)

  1 view  → 1.0×     (single graph only)
  2 views → 1.5×     (corroborated)
  3 views → 2.25×    (strong cross-graph signal)
  4 views → 3.375×   (central to entire context)

______________________________________________________________________

快速开始

安装

npm install -g polyg-mcp
# or run directly
npx polyg-mcp

先决条件

FalkorDB（图形数据库）：

docker run -d -p 6379:6379 falkordb/falkordb

克劳德桌面版

添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "polyg": {
      "command": "npx",
      "args": ["polyg-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-key-here",
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379"
      }
    }
  }
}

Docker Compose

git clone https://github.com/Captain-Jay29/polyg-mcp.git
cd polyg-mcp
cp .env.example .env
docker-compose up -d

来源

git clone https://github.com/Captain-Jay29/polyg-mcp.git
cd polyg-mcp && npm install
cp .env.example .env
npm run dev

______________________________________________________________________

MCP工具

通过MCP暴露的15个工具。与Claude、Cursor和任何MCP代理兼容。

MAGMA Retrieval (6 tools)

Write (7 tools)

Admin (2 tools)

______________________________________________________________________

配置

# .env
OPENAI_API_KEY=sk-...               # Required — LLM + embeddings
EMBEDDING_MODEL=text-embedding-3-small
LLM_MODEL=gpt-4o-mini
CLASSIFIER_MAX_TOKENS=1000           # Intent classifier token limit
SYNTHESIZER_MAX_TOKENS=2000          # Synthesizer output limit

FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_QUERY_TIMEOUT=30000         # Max query execution (ms)

POLYG_PORT=3000
POLYG_LOG_LEVEL=info
POLYG_PARALLEL_TIMEOUT=30000         # Graph expansion timeout (ms)
POLYG_MAX_RETRIES=3                  # LLM retry with exponential backoff

______________________________________________________________________

项目结构

polyg-mcp/
├── packages/
│   ├── core/src/
│   │   ├── graphs/
│   │   │   ├── semantic.ts         # Vector similarity (cosine over 1536-dim)
│   │   │   ├── entity.ts           # Entity relationships (BFS)
│   │   │   ├── temporal.ts         # Timeline queries (ISO sort)
│   │   │   ├── causal.ts           # Cause-effect chains (path traversal)
│   │   │   └── cross-linker.ts     # X_* relationship management
│   │   ├── executor/
│   │   │   └── magma-executor.ts   # MAGMA pipeline orchestration
│   │   ├── retrieval/
│   │   │   ├── subgraph-merger.ts  # Multi-view boosting
│   │   │   ├── context-linearizer.ts
│   │   │   └── seed-extraction.ts
│   │   ├── agents/
│   │   │   ├── intent-classifier.ts
│   │   │   └── synthesizer.ts
│   │   └── storage/
│   │       └── falkordb-adapter.ts # Cypher query builder
│   ├── server/src/
│   │   ├── mcp-server-factory.ts   # 15 tool registrations
│   │   └── shared-resources.ts     # Dependency injection
│   └── shared/src/
│       ├── types.ts                # TypeScript interfaces
│       └── schemas.ts              # Zod validation
├── docker-compose.yml
└── tests/

______________________________________________________________________

贡献

看 贡献.md.

pnpm test
pnpm lint
pnpm build

许可证

麻省理工学院

______________________________________________________________________

Built for agents that need to answer "why" — not just "what".

Report Bug · Request Feature