Skip to main content
Glama
Project Synapse
by angrysky56

🧠 Project Synapse MCP 服务器

具备 LLM-WIKI 集成的自主知识合成引擎

Documentation

Project Synapse 是一个 MCP(模型上下文协议)服务器,它将 Neo4j 2026.x 图数据库与 Obsidian Markdown 维基相结合,以创建持久且不断积累的知识库。原始文本通过语义流水线处理,转化为带有向量嵌入的互联图节点,同时人类可读的维基层提供了可浏览、相互链接的 Markdown 页面。

📚 文档

有关设置和使用 Project Synapse 的详细信息,请参阅以下指南:

  • 入门指南:安装和首次运行。

  • 架构:语义流水线和图的工作原理。

  • 配置:环境变量完整列表。

  • 开发:添加工具和贡献指南。

  • 测试:运行测试套件。

  • 贡献:项目贡献指南。

Related MCP server: KG Memory

这是什么(以及不是什么)

这是一个知识系统,而不是代码编辑器。 它用于项目周边的思考、研究和写作——架构决策、领域研究、设计原理、参考资料、会议记录。

代码存在于其仓库中。关于代码的知识则存在于此。

使用场景:

  • 积累数周/数月的深度研究

  • 项目知识库(为什么做出决策,而不仅仅是决策内容)

  • 个人知识管理(文章、书籍、播客笔记)

  • 以 AI 作为维基维护者的协作头脑风暴

每个项目的设置: 为每个项目创建一个独立的 Obsidian 库 + GitHub 仓库。将 WIKI_VAULT_PATH 环境变量指向它。一个 Neo4j 实例可以服务于多个项目(图可以共存)。

架构

Web / Raw Sources
         │
    [defuddle]          ← cleans web content before ingestion
         │
         ▼
┌──────────────────────┐     ┌─────────────────────┐
│  Semantic Pipeline   │────▶│  Neo4j Knowledge    │
│  (Montague Grammar,  │     │  Graph (entities,   │
│   NLP, embeddings)   │     │  facts, vectors)    │
└──────────────────────┘     └────────┬────────────┘
                                      │
                              ┌───────┴───────┐
                              │ Wiki Adapter  │
                              └───────┬───────┘
                                      │
                              ┌───────▼───────┐
                              │ Obsidian Vault│
                              │ (Markdown,    │
                              │  Git-synced)  │
                              └───────────────┘

关键特性

知识图谱 (Neo4j 2026.x)

  • 原生 VECTOR 类型,支持 ANN 语义搜索

  • 用于关键词搜索的全文 BM25 索引

  • 混合搜索(向量 + BM25 分数融合)

  • 用于发现隐藏关系的图遍历

  • 用于形式语义分析的蒙塔古语法解析器

  • 用于自主见解生成的卡片盒引擎

LLM-WIKI 集成

  • 连接 Obsidian Markdown 库与 Neo4j 图

  • 带有 YAML 前置元数据的完整页面 CRUD

  • 自动索引生成和仅追加日志

  • 健康检查:孤立节点检测、损坏的维基链接、缺失的前置元数据

  • 用于高效图同步的增量同步清单(内容哈希)

  • 基于 Andrej Karpathy 的 LLM Wiki 模式

网络内容摄取 (defuddle)

  • wiki_fetch_url 获取任何 URL,通过 defuddle 去除导航/广告/杂乱内容,摄取到 Neo4j,并归档到 Clippings/ —— 一次调用,完全自动化

  • wiki_ingest_raw 自动将处理后的文件从 raw/ 移动到 Clippings/ —— 保持收件箱整洁

  • raw/ 是一个真正的收件箱:每次会话后清空

仅限本地的嵌入(无需付费 API)

  • sentence-transformers(默认)—— 在 GPU 上运行

  • Ollama(可选)—— 任何本地嵌入模型

  • 所有向量通过 db.create.setNodeVectorProperty() 原生存储在 Neo4j 中

快速开始

先决条件

  • Python 3.12+

  • Neo4j 2026.x (社区版或企业版)

  • uv 包管理器 (pip install uv)

  • Obsidian 以及 Git 社区插件

  • 用于维基库的 GitHub 仓库(可以是私有的)

  • Node.js + defuddle(用于网络内容获取 —— 见下文)

Neo4j 设置

# Ubuntu/Debian — see neo4j.com for other platforms
sudo apt install neo4j
sudo systemctl start neo4j
sudo systemctl enable neo4j
# Set password (default user: neo4j)
sudo neo4j-admin set-initial-password your_password

defuddle 设置

defuddle 从网页中提取干净的 Markdown,在摄取前去除导航、广告和样板内容。wiki_fetch_url 所必需。

# Install Node.js if not present (via nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts
nvm use --lts

# Install defuddle globally
npm install -g defuddle

# Verify
defuddle --version

注意: 即使 defuddle 不在 shell 的 PATH 中,Synapse 也会通过 nvm 路径自动找到它。如果 wiki_fetch_url 报告未找到 defuddle,请确保它安装在 nvm 管理的 Node 版本中。

Obsidian 库设置

  1. 在 Obsidian 中创建一个新库(或克隆你的维基仓库)

  2. 安装 Git 社区插件(设置 → 社区插件 → 浏览 → "Git")

  3. 使用你的 GitHub 凭据配置 Git 插件

  4. 库结构(raw/、wiki/、Clippings/、AGENTS.md)由 Synapse 在首次运行时自动创建

安装

cd /home/ty/Repositories/ai_workspace
git clone <repository-url> project-synapse-mcp
cd project-synapse-mcp
uv venv --python 3.12 --seed
source .venv/bin/activate
uv add -e .
uv run python -m spacy download en_core_web_sm
cp .env.example .env  # edit with your Neo4j password and vault path

配置

编辑 .env:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j

# Embedding — local only, no paid APIs
EMBEDDING_PROVIDER=sentence-transformers  # or "ollama"
EMBEDDING_MODEL=sentence-transformers/all-mpnet-base-v2
EMBEDDING_DIMENSION=768

# Wiki vault
WIKI_VAULT_PATH=/path/to/your/obsidian-vault
WIKI_GITHUB_REPO=https://github.com/user/wiki-repo

Claude Desktop / MCP 集成

添加到你的 MCP 配置中:

{
  "mcpServers": {
    "project-synapse": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/project-synapse-mcp",
        "run", "python", "-m", "synapse_mcp.server"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "NEO4J_DATABASE": "neo4j",
        "WIKI_VAULT_PATH": "/path/to/obsidian-vault",
        "WIKI_GITHUB_REPO": "https://github.com/user/wiki-repo"
      }
    }
  }
}

MCP 工具

知识图谱

工具

描述

ingest_text

通过语义流水线处理文本 → Neo4j

query_knowledge

带有见解优先结果的向量语义搜索

explore_connections

用于隐藏关系的图遍历

generate_insights

自主卡片盒模式检测

analyze_semantic_structure

蒙塔古语法语义分析

维基 (LLM-WIKI)

工具

描述

wiki_fetch_url

获取 URL → defuddle 清理 → 摄取 → 归档到 Clippings/

wiki_ingest_raw

从 raw/ 摄取文件 → Neo4j + 自动移动到 Clippings/

wiki_write_page

创建/更新带有前置元数据的维基页面

wiki_read_page

按路径读取维基页面

wiki_search

跨维基页面的关键词搜索

wiki_list_pages

列出子目录中的所有页面

wiki_update_index

重建维基索引

wiki_lint

健康检查:孤立节点、损坏的链接、缺失的前置元数据

维基库结构

LLM-WIKI/
├── AGENTS.md           # Agent schema doc — conventions and workflows
├── raw/                # INBOX ONLY — unprocessed files; empty after each session
├── raw-inbox.base      # Obsidian Base view of pending raw/ queue
├── Clippings/          # Permanent archive — all processed sources land here
├── wiki/
│   ├── index.md        # Auto-generated page catalogue
│   ├── log.md          # Append-only activity log
│   ├── entities/       # People, tools, projects
│   ├── concepts/       # Ideas, theories, patterns
│   └── sources/        # Summaries of ingested sources

内容生命周期

You clip/save → raw/          # your inbox
     or
Agent fetches → wiki_fetch_url # web research
                    │
              [defuddle clean]
                    │
              [semantic pipeline] → Neo4j
                    │
              wiki_write_page → wiki/sources/
                    │
              auto-move → Clippings/   # permanent archive

raw/ 在会话后总是空的。Clippings/ 是所有已处理内容的永久记录。wiki/sources/ 中的源页面引用的是原始 URL,而不是文件路径。

工作流程

  1. 网络研究:wiki_fetch_url(url) → 一次调用完成获取、清理、摄取、归档

  2. 手动剪辑:放入 raw/,调用 wiki_ingest_raw(filename) → 摄取后自动归档

  3. 查询:query_knowledge(图)或 wiki_search(文件)→ 合成答案

  4. Lint:wiki_lint → 修复孤立节点、损坏的链接、过时的声明

  5. 回滚:Git 通过 Obsidian Git 插件处理版本控制

理论基础

  • 蒙塔古语法:用于意义提取的形式组合语义

  • 卡片盒方法:具有涌现结构的原子链接笔记

  • 图论:社区检测、中心性、路径分析

  • Karpathy LLM-WIKI:持久知识编译与无状态 RAG 的对比

  • 万尼瓦尔·布什的 Memex:带有维护轨迹的私有联想知识

许可证

MIT — 见 LICENSE。


Project Synapse:从响应式 RAG 到持久、不断积累的知识。

Available Tools

23 tools
analyze_semantic_structureB

Analyze the semantic structure of text using Montague Grammar parsing.

This tool provides insight into the formal semantic analysis capabilities and shows the logical form translations.

Args: text: Text to analyze semantically include_logical_form: Whether to include the formal logical representation

Returns: Semantic analysis with entities, relations, and optional logical forms

Inputs: text (required), include_logical_form. Returns: result

debug_testB

Simple test tool to check if MCP server is working.

Inputs: no named parameters. Returns: result

explore_connectionsB

Explore connections and relationships around a specific entity in the knowledge graph.

This tool implements the graph traversal capabilities for discovering non-obvious connections and patterns.

Args: entity: Entity name to explore from depth: How many relationship hops to explore (1-5) connection_types: Specific relationship types to follow

Returns: Visual representation of connections and discovered patterns

Inputs: entity (required), depth, connection_types. Returns: result

generate_insightsC

Trigger autonomous insight generation using the Zettelkasten engine.

This tool activates the autonomous synthesis engine to identify patterns and generate novel insights from the existing knowledge graph.

Args: topic: Optional topic to focus insight generation on confidence_threshold: Minimum confidence level for insights (0.0-1.0)

Returns: Generated insights with confidence scores and evidence trails

Inputs: topic, confidence_threshold. Returns: result

ingest_textB

Ingest and process text into the knowledge graph using semantic analysis.

This tool performs the core knowledge synthesis pipeline:

  1. Semantic parsing using Montague Grammar

  2. Entity extraction and relationship identification

  3. Storage in the Neo4j knowledge graph

  4. Automatic insight generation triggers

Args: text: Raw text to process and analyze source: Source identifier for provenance tracking metadata: Additional metadata about the text

Returns: Processing summary with entities and relationships extracted

Inputs: text (required), source, metadata. Returns: result

query_knowledgeA

Query the knowledge graph for facts and insights using natural language.

This tool provides the conversational interface to the knowledge base, prioritizing synthesized insights over raw facts.

Args: query: Natural language query include_insights: Whether to include AI-generated insights max_results: Maximum number of results to return

Returns: Query results with facts, insights, and reasoning trails

Inputs: query (required), max_results, include_insights. Returns: result

synapse_causal_windowA

Find candidate causes by temporal correlation.

Surfaces facts whose valid_from falls in the window [before - within_days, before] and that share at least one entity with facts about effect_entity.

This is exactly the "track everything you ate to find what caused the headaches" pattern — you record symptom onset, you record meals and medications, then this tool surfaces co-occurring events as candidates. The tool returns correlation; the human (or a downstream reasoning step) decides what caused what.

Args: effect_entity: The thing whose causes you're hunting (e.g. "headache", "rash", "build failure"). before: ISO date/datetime — when the effect was observed. within_days: How far back to search. Default 30.

Returns: Ranked list of candidate cause-effect pairings with day deltas.

Inputs: before (required), effect_entity (required), within_days. Returns: result

synapse_invalidateA

Mark a previously-recorded fact as no longer true.

Sets valid_to rather than deleting — the historical record stays intact, but the fact is no longer "currently true" for default queries.

Args: subject/predicate/object: The triple to invalidate. ended: ISO date/datetime when the fact stopped being true. Defaults to now if omitted.

Returns: Number of facts affected.

Inputs: object (required), subject (required), predicate (required), ended. Returns: result

synapse_memory_statsA

Quick stats: how many temporal facts are stored, time span covered.

Inputs: no named parameters. Returns: result

synapse_recallA

Look up time-stamped facts about an entity.

Args: entity: Name to look up. Matches subject, object, or both depending on direction. as_of: ISO date/datetime — if given, only facts valid at this point in time are returned. Omit for "currently true" facts. direction: "outgoing" (entity is the subject), "incoming" (entity is the object), or "both" (default).

Returns: Newline-separated list of facts with timestamps. Empty if none found.

Inputs: entity (required), as_of, direction. Returns: result

synapse_rememberA

Record a time-stamped fact in Synapse's episodic memory.

Use this whenever something is worth remembering across sessions: decisions, observations, "Ty said X on date Y", health/diet/symptom log entries, project milestones.

Args: subject: Who or what the fact is about. Free-form name. predicate: The relationship verb. snake_case preferred (e.g. "started_taking", "moved_to", "decided_to_use"). object: The other side of the relation. valid_from: ISO date or datetime when the fact became true. If omitted, "now" is used. Bare dates → midnight UTC. valid_to: ISO date or datetime when the fact stopped being true. Omit for still-current facts. confidence: 0–1. Default 1.0 for explicit user statements; lower when the agent is inferring. source: Where this fact came from. Defaults to "agent:claude" for things Claude is recording. Use "user" or a filename for facts from explicit user statements or document ingestion. note: Free-form context. Stored in metadata for later recall.

Returns: The fact id (stable content hash — safe to call twice).

Inputs: object (required), subject (required), predicate (required), note, +4 more. Returns: result

synapse_timelineA

Chronological view of remembered facts.

Args: entity: Scope to one entity, or None for the global timeline. limit: Max number of rows. Default 50.

Returns: Time-ordered fact list, oldest first.

Inputs: limit, entity. Returns: result

wiki_cluster_pagesA

Cluster wiki pages by semantic similarity using GAAC (TF-IDF).

Identifies:

  • Natural topic clusters — pages that belong together

  • Missing links — same-cluster pages with no wikilink between them

  • Merge candidates — pages so similar they may be redundant (sim > 0.7)

Args: n_clusters: Number of clusters (auto = sqrt of page count if omitted).

Inputs: n_clusters. Returns: result

wiki_fetch_urlA

Fetch a URL with defuddle (clean markdown extraction), save to raw/, ingest into the knowledge graph, and archive to Clippings/.

Use this when researching the web — it strips navigation and clutter, leaving only the article content. Much cleaner than raw web_fetch.

Args: url: The URL to fetch and process. ingest: If True (default), immediately ingest into Neo4j after saving. Set False to save to raw/ only for manual review first.

Inputs: url (required), ingest. Returns: result

wiki_hits_analysisA

Compute HITS hub and authority scores on the wiki wikilink graph.

Authorities = pages cited by many others — load-bearing knowledge nodes. Hubs = pages that link to many good authorities — navigation layers.

Use to identify which pages need deepening (high authority) and which need comprehensive link coverage (high hub).

Inputs: no named parameters. Returns: result

wiki_ingest_rawA

Read a raw source file and ingest it into both the knowledge graph and wiki.

Reads from raw/, runs it through the Synapse semantic pipeline, stores in Neo4j, and creates a summary page in wiki/sources/.

Args: filename: Filename inside the raw/ directory.

Inputs: filename (required). Returns: result

wiki_lintA

Run a health check on the wiki vault.

Detects orphan pages, broken wikilinks, and missing frontmatter.

Inputs: no named parameters. Returns: result

wiki_list_pagesB

List all markdown pages in the wiki vault with pagination.

Args: subdir: Subdirectory to list ('wiki' or 'raw'). limit: Maximum pages to return (default 50, max 200). offset: Offset for pagination. tag: Filter by tag.

Inputs: tag, limit, offset, subdir. Returns: result

wiki_read_pageB

Read a wiki page.

Args: path: Relative path from vault root (e.g. 'wiki/concepts/rag.md'). mode: What to return: - "meta": metadata/frontmatter only (from index, 0 file reads) - "excerpt": metadata + first 500 characters of page body (from index) - "full": complete page content (reads file from disk)

Inputs: path (required), mode. Returns: result

wiki_sync_indexA

Refresh the wiki index database from disk.

Runs automatically on server start and after write operations. Call manually if files were changed outside Synapse (e.g., Obsidian edits, git pull).

Inputs: no named parameters. Returns: result

wiki_update_indexB

Rebuild the wiki index from all wiki pages.

Args: deep: If True, performs a disk-level verification of all indexed files.

Inputs: deep. Returns: result

wiki_write_pageB

Write or update a wiki page with frontmatter.

Args: path: Relative path (e.g. 'wiki/entities/neo4j.md'). body: Markdown body content. summary: One-line summary for the index. tags: Comma-separated tags.

Inputs: body (required), path (required), tags, summary. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 23 tools

    Disambiguation3/5

    The tools are grouped into wiki, knowledge graph, and memory domains, but several have blurry boundaries: wiki_sync_index vs wiki_update_index, synapse_recall vs synapse_timeline, and ingest_text vs wiki_ingest_raw could cause misselection. Descriptions help clarify most overlaps, but not all.

    Naming Consistency4/5

    Most tools follow verb_noun snake_case with clear wiki_ and synapse_ prefixes, but the core knowledge graph tools (ingest_text, query_knowledge, explore_connections) lack a shared prefix and debug_test breaks the pattern. The naming is mostly consistent but not fully systematic.

    Tool Count3/5

    23 tools is in the heavy range and requires a lot of surface area to navigate, though each tool has a plausible role in the wiki/knowledge-graph/memory system. It is borderline: not overwhelming, but more than is clearly necessary.

    Completeness4/5

    The set covers wiki read/write/indexing, knowledge graph ingestion and querying, and episodic memory lifecycle management including invalidation and causal analysis. Minor gaps exist (no wiki page deletion, no explicit knowledge graph entity update/delete), but core workflows are well covered.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that transforms markdown notes into an AI-powered knowledge graph. It enables LLM clients to explore, analyze, and diagnose knowledge graphs through tools for node explanation, path finding, causal chain analysis, and wiki health reporting.
      5
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that implements a heavily typed knowledge graph memory system with AI-powered entity and relation extraction, enabling structured knowledge storage and retrieval from unstructured text using predefined or custom ontologies.
      9
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that compiles any text into a verifiable, graph-based knowledge base using deterministic chunking and parallel extraction of epistemology primitives.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that turns any compatible AI agent into a Zettelkasten partner for creating atomic notes, forming semantic links, detecting clusters, and synthesizing insights from your existing knowledge.
      19
      2
      MIT