Skip to main content
Glama
Project Synapse
by angrysky56

🧠 Project Synapse MCP 서버

LLM-WIKI 통합을 갖춘 자율 지식 합성 엔진

Documentation

Project Synapse는 Neo4j 2026.x 그래프 데이터베이스와 Obsidian 마크다운 위키를 결합하여 지속적이고 복합적인 지식 베이스를 구축하는 MCP(Model Context Protocol) 서버입니다. 원시 텍스트는 의미론적 파이프라인을 통해 벡터 임베딩이 포함된 상호 연결된 그래프 노드로 처리되며, 사람이 읽을 수 있는 위키 계층은 탐색 가능한 상호 연결된 마크다운 페이지를 제공합니다.

📚 문서

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)

  • ANN 의미론적 검색을 지원하는 네이티브 VECTOR 타입

  • 키워드 검색을 위한 전체 텍스트 BM25 인덱스

  • 하이브리드 검색 (벡터 + BM25 점수 융합)

  • 숨겨진 관계를 발견하기 위한 그래프 탐색

  • 형식 의미론 분석을 위한 몬태규 문법 파서

  • 자율적인 통찰력 생성을 위한 제텔카스텐 엔진

LLM-WIKI 통합

  • Obsidian 마크다운 볼트와 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 (Community 또는 Enterprise)

  • 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은 웹 페이지에서 탐색 메뉴, 광고, 상용구 등을 제거하고 깔끔한 마크다운을 추출합니다. 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

참고: Synapse는 셸의 PATH에 없더라도 nvm 경로를 통해 defuddle을 자동으로 찾습니다. 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. 린트: wiki_lint → 고아 노드, 깨진 링크, 오래된 주장 수정

  5. 롤백: Git은 Obsidian Git 플러그인을 통해 버전 제어를 처리합니다

이론적 기반

  • 몬태규 문법: 의미 추출을 위한 형식적 구성 의미론

  • 제텔카스텐 방법론: 창발적 구조를 가진 원자적 연결 노트

  • 그래프 이론: 커뮤니티 탐지, 중심성, 경로 분석

  • Karpathy LLM-WIKI: 상태 비저장 RAG 대비 지속적인 지식 컴파일

  • Vannevar Bush의 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