Which integrations are available for this server?

Allows syncing CLAUDE.md files from a Forgejo repository. Allows syncing CLAUDE.md files from a Gitea repository. Allows syncing CLAUDE.md files from a GitHub repository. Allows syncing CLAUDE.md files from a GitLab repository. Provides semantic search capabilities via Ollama embedding models. Provides semantic search capabilities via OpenAI-compatible embedding models.

How do I use Synaptex?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Synaptex search for 'error handling' in my CLAUDE.md files" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Synaptex

by jeromelabophy-gif

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

Synaptex

Global brain for all your Claude Code projects.
Synaptex syncs your CLAUDE.md files across repos, builds a semantic index, and exposes everything to Claude via MCP.

Portable across operating systems (Linux x86/ARM, macOS, Windows WSL), Git hosts (Forgejo, Gitea, GitHub, GitLab, or just local folders), and embedding providers (Ollama, OpenAI, LM Studio, vLLM, LocalAI…).

Quick start

git clone <this-repo> ~/Synaptex
cd ~/Synaptex

bash install.sh                     # standard setup (embed backend)
# or:
bash install.sh --enable-leann      # adds BM25+vector search (~3 GB extra)

synaptex init                         # interactive wizard
synaptex sync                         # first sync + index
synaptex search "your query"

Related MCP server: vault-mcp-server

Prerequisites

Python 3.10+ with pip install -r requirements.txt
A repo source (one of: Forgejo, Gitea, GitHub, GitLab, or local folders)
For semantic search: Ollama (local or remote) with an embedding model pulled — not required if you use the fts5 backend

Five git providers, one variable

FORGE_TYPE in ~/.synaptex/.env:

Value	API used	Token scope
`forgejo`	Forgejo API v1 (`/api/v1/...`)	`read:repository`
`gitea`	Gitea API v1 (same as Forgejo)	`read:repository`
`github`	GitHub REST API v3	`repo` (read)
`gitlab`	GitLab REST API v4	`read_api`
`local`	Filesystem scan (no API)	none

local is the most universal: point LOCAL_REPOS_PATH to a folder containing your Git repos, and Synaptex reads CLAUDE.md files directly from disk. No tokens, no network, fully offline.

Three search backends, one switch

SYNAPTEX_SEARCH_BACKEND in ~/.synaptex/.env:

Value	Quality	Network needs	Disk cost	Use when
`embed` (default)	Semantic similarity (cosine)	Ollama (local or remote)	~tens of MB	You have an embedding provider
`leann`	BM25 + vector hybrid (best)	Ollama	~3 GB (PyTorch)	Quality matters more than disk
`fts5`	Keyword (SQLite FTS5)	None	Negligible	Fully offline, no Ollama

You can switch at any time — re-run synaptex sync to repopulate the index in the new backend.

Supported embedding providers

Ollama (default) — any model available via ollama pull
OpenAI-compatible — LM Studio, vLLM, LocalAI, OpenAI API: set OLLAMA_API_TYPE=openai

Configuration

~/.synaptex/.env (created by synaptex init or install.sh, chmod 600):

Variable	Description	Example
`FORGE_TYPE`	Source type	`forgejo` \| `gitea` \| `github` \| `gitlab` \| `local`
`FORGE_URL`	Git provider base URL (not needed for `github` or `local`)	`http://localhost:3000`
`FORGE_TOKEN`	API token with read access	`abc123...`
`FORGE_USER`	Your username on the git provider	`alice`
`LOCAL_REPOS_PATH`	Local folder to scan (when `FORGE_TYPE=local`)	`~/projects`
`SYNAPTEX_INCLUDE_PATTERNS`	Files to index per repo (comma-separated)	`CLAUDE.md` \| `CLAUDE.md,README.md` \| `*.md`
`SYNAPTEX_EXCLUDE_DIRS`	Local dirs to skip during scan (comma-separated)	`Drive-Archive,Secrets,Templates`
`SYNAPTEX_SEARCH_BACKEND`	Search engine	`embed` \| `leann` \| `fts5`
`OLLAMA_BASE_URL`	Ollama or OpenAI-compatible API	`http://localhost:11434`
`OLLAMA_API_TYPE`	API format	`ollama` \| `openai`
`OLLAMA_EMBED_MODEL`	Embedding model	`nomic-embed-text`
`OLLAMA_FALLBACK_MODEL`	Fallback model (optional)	`mxbai-embed-large`
`OLLAMA_API_KEY`	API key for OpenAI-compatible APIs (optional)	`sk-...`

Commands

`synaptex init`

Interactive wizard — generates ~/.synaptex/.env.

`synaptex status`

Check connectivity: git provider, Ollama, embedding model, index, backend, memory sheets, projects synced, last sync timestamp.

`synaptex sync`

Download files matching SYNAPTEX_INCLUDE_PATTERNS, generate memory sheets, re-index.

synaptex sync --dry-run              # preview without writing
synaptex sync                        # full sync
synaptex sync --no-index             # sync without re-indexing
synaptex sync --verbose              # log each file with [ok] or [skip] (reason)
synaptex sync --only mon-projet      # sync a single repo
synaptex sync --exclude tests        # exclude repos by name (repeatable)
synaptex sync --exclude ci --exclude sandbox

`synaptex clean`

Purge local caches (~/.synaptex/projects/ and/or ~/.synaptex/memory/).

synaptex clean --all       # purge projects + memory
synaptex clean --projects  # purge projects only (memory kept)
synaptex clean --memory    # purge memory only (projects kept)

`synaptex search`

Semantic (or keyword, depending on backend) search across all indexed files.

synaptex search "raspberry pi backup strategy"
synaptex search "authentication API" -k 3

`synaptex map`

Generate ~/.synaptex/index.md — a global map with a Mermaid dependency graph.

`synaptex context`

Generate an injectable context block for a Claude session.

synaptex context                  # all projects
synaptex context myrepo otherrepo # filtered

Claude Code integration

Slash command `/user:synaptex`

At the start of a session, type /user:synaptex to load global context.
With specific projects: /user:synaptex myrepo otherrepo

Claude will:

Run synaptex context and read the result
Query past session memories via qmd (if installed)
Confirm: "🧠 Synaptex loaded — active projects: [list]"

MCP `synaptex-search`

Available tools directly in Claude Code during a conversation:

Tool	Usage
`synaptex_search`	Search across CLAUDE.md files
`synaptex_list`	List all synced projects
`synaptex_context`	Return a project's context
`synaptex_status`	Infrastructure status

Compatibility matrix

Platform	Status	Notes
Linux x86_64	✅ Tested	Native
Linux aarch64 (Pi 4/5)	✅ Tested	`embed`/`fts5` backends recommended; `leann` works but install is slow
macOS Apple Silicon	✅ Should work	Bun + qmd binaries native; Ollama runs natively
macOS Intel	✅ Should work	Same as above
Windows (WSL2)	✅ Should work	Treat as Linux
Windows (Git Bash)	⚠️ Partial	`install.sh` skips `~/.local/bin` symlink — use `python3 synaptex.py` directly

File layout

~/.synaptex/
├── .env              ← secrets (chmod 600, never committed)
├── projects/         ← CLAUDE.md mirror (one folder per repo)
├── memory/           ← generated memory sheets
├── index.md          ← global map (synaptex map)
├── leann_index/      ← vector index (sqlite3 + optional leann)
└── sync.log          ← sync history

<repo>/
├── synaptex.py         ← CLI (Click)
├── forge.py          ← multi-git bridge (forgejo/gitea/github/gitlab/local)
├── embed.py          ← vector index (sqlite3 + cosine + OpenAI-compatible)
├── search.py         ← search backend router (embed/leann/fts5)
├── memory.py         ← memory sheets + Mermaid graph
├── context.py        ← injectable context block
├── mcp_synaptex.py     ← MCP server (stdio)
└── install.sh        ← full setup

Troubleshooting

Ollama not responding

curl http://localhost:11434/api/tags   # check it's running
ollama pull nomic-embed-text           # pull the default embed model

Git provider unreachable

For remote Forgejo/GitLab: check VPN or network connectivity
For GitHub: verify your token has repo scope
For local: verify LOCAL_REPOS_PATH points to a folder containing .git/ directories

Index empty after sync

synaptex status           # check embed model is available
synaptex sync             # re-run sync

Want offline search (no Ollama)

# In ~/.synaptex/.env:
SYNAPTEX_SEARCH_BACKEND=fts5
synaptex sync   # re-index with FTS5

Want best search quality

bash install.sh --enable-leann
# Then in ~/.synaptex/.env:
SYNAPTEX_SEARCH_BACKEND=leann
synaptex sync

qmd not found

export PATH="$HOME/.bun/bin:$PATH"

License

See LICENSE if present, or contact the repo owner.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

oneda
com.freeelatech
Persistent, governed institutional memory for Claude Code — specs, decisions, learnings.
Knowledge & Memory Documentation Access Note Taking
1
ctx A
io.github.vanshulgoyal101
Turn a GitHub repo or docs site into agent-ready context: pack it or search it, over MCP.
RAG Systems Search Documentation Access
611
mcp A
ai.promptarch
Research-backed linting + generation for agent context files (CLAUDE.md, AGENTS.md, Cursor rules).
Agent Orchestration Developer Tools
32
ContexterOAuth
io.github.maaakso
Share one project context across ChatGPT, Claude, Telegram and any MCP client.
Knowledge & Memory Note Taking
1

Related MCP Servers

Open Context
Developer Tools Knowledge & Memory Documentation Access
niawjunior
A
license
Not graded
quality
C
maintenance
AI context management for codebases – enables Claude Code to read, search, and update project documentation via MCP.
Updated 6 months ago (2026-03-29 15:26 UTC)
MIT
vault-mcp-server
Knowledge & Memory RAG Systems
thebackpackdevorg
A
license
Not graded
quality
D
maintenance
Turns any folder of Markdown files into a searchable, structured knowledge base for Claude Code, enabling persistent memory across sessions via tools like list, read, write, edit, search, and summarize.
Updated 6 months ago (2026-04-03 17:25 UTC)
MIT
stellavault
Knowledge & Memory Note Taking Search
Evanciel
A
license
Not graded
quality
A
maintenance
Enables Claude to read, search, and analyze your entire knowledge vault locally via MCP tools like search, drafting, and linting.
Updated a month ago (2026-08-25 08:10 UTC)
103 npm
4
MIT
Anamnesis
Knowledge & Memory Developer Tools
oscardvs
A
license
Not graded
quality
A
maintenance
Provides a local-first, file-based memory layer for Claude Code that syncs across machines via git over private networks, with MCP tools for search, write, and sync of human-readable markdown notes.
Updated 21 days ago (2026-09-01 20:26 UTC)
Apache 2.0

Synaptex

Quick start

Prerequisites

Five git providers, one variable

Three search backends, one switch

Supported embedding providers

Configuration

Commands

synaptex init

synaptex status

synaptex sync

synaptex clean

synaptex search

synaptex map

synaptex context

Claude Code integration

Slash command /user:synaptex

MCP synaptex-search

Compatibility matrix

File layout

Troubleshooting

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Open Context

vault-mcp-server

stellavault

Anamnesis

`synaptex init`

`synaptex status`

`synaptex sync`

`synaptex clean`

`synaptex search`

`synaptex map`

`synaptex context`

Slash command `/user:synaptex`

MCP `synaptex-search`