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"

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:

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:

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):

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:

1. Run synaptex context and read the result

2. Query past session memories via qmd (if installed)

3. Confirm: "🧠 Synaptex loaded — active projects: [list]"

MCP synaptex-search

Available tools directly in Claude Code during a conversation:

Compatibility matrix

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.