convez.ai
MCP Server
7blacky7

synapse

7blacky7/synapse

Ver no GitHub
InicialPluginScore · de 0 a 100

KI-Gedächtnis & Code-Intelligenz — Semantische Code-Suche, Wissensaustausch und Projekt-Pläne über MCP (Model Context Protocol). Verbindet lokale CLIs (Claude Code, Codex) und Web-KIs (Claude.ai) mit Qdrant + Ollama Embeddings.

Instalação

$npx convez-ai 7blacky7/synapse

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
6

README

A tradução para o português deste README ainda está na fila.

🧠 Synapse — lokales KI-Gedächtnis, Code-Intelligence & Agenten-Orchestrierung

Synapse verwandelt lokale Softwareprojekte in eine strukturierte, durchsuchbare und automatisierbare Wissensbasis für KI-Agenten.

Es verbindet Dateisystem-Indexierung, PostgreSQL, Qdrant, Code-Parser, MCP/REST-Tools, persistente Spezialisten, Shell-Queues und isolierte Docker-Workspaces zu einem lokalen System für KI-gestützte Entwicklung. Spezialisten können je nach Provider über lokale CLI-Runtimes oder über API-Keys laufen; bei Gemini ist beides möglich: Gemini CLI oder Google/Gemini API-Key.


Kurzfassung

Synapse ist kein einzelnes Suchtool. Es ist ein lokales Betriebssystem für KI-Arbeit an Codebasen:

Projektdateien
   ↓
FileWatcher + Parser
   ↓
PostgreSQL: Dateien, Symbole, Referenzen, Chunks, Wissen, Jobs
   ↓
Qdrant: semantische Vektorsuche
   ↓
MCP / REST Tools
   ↓
KI-Agenten, Spezialisten, Shell-Jobs, Workspaces

Die Kernidee: Eine KI soll nicht bei jeder Session wieder bei null anfangen. Code, Erkenntnisse, Regeln, Tasks, Fehler-Patterns und Agentenstatus bleiben persistent und werden über Tools abrufbar.


Was Synapse konkret macht

Synapse löst mehrere Probleme gleichzeitig:

ProblemSynapse-Antwort
KI verliert Kontext nach Session-EndeMemories, Thoughts, Plans, Proposals und Skills bleiben in PostgreSQL/Qdrant erhalten.
Code-Suche über grep ist flachcode_intel kennt Funktionen, Variablen, Symbole, Referenzen, Statements, Calls und Entrypoints.
Semantische Suche findet Konzepte, aber keine StrukturQdrant ergänzt PostgreSQL; Struktur bleibt in PostgreSQL.
Web-KIs haben keinen lokalen DateisystemzugriffREST-API + PG-Queues delegieren Arbeit an den lokalen FileWatcher-Daemon oder Workspaces.
Agenten arbeiten unkoordiniertChat, Inbox, Channels, Events und Specialist-Jobs bilden einen lokalen Agentenbus.
Shell-Ausführung von Web-KIs ist riskantShell-Jobs laufen über Queue, Daemon/Workspace-Routing, Logs und Audit-Trail.
Mehrere Edits sind schwer atomar zu reviewenfiles/files_batch bieten Plan/Commit, Hash-Checks, Anchors, Versionierung und Rollback.
Integrationstests brauchen mehrere DiensteWorkspaces stellen benannte Docker-Instanzen mit DNS, Rollen und eigenem HOME bereit.

Architekturüberblick

                            ┌──────────────────────────────┐
                            │          KI / User            │
                            │ Claude Code / Desktop / Web   │
                            │ ChatGPT / Claude.ai / Gemini  │
                            └───────────────┬──────────────┘
                                            │
                ┌───────────────────────────┴───────────────────────────┐
                │                                                       │
        ┌───────▼────────┐                                      ┌───────▼────────┐
        │ MCP Server     │                                      │ REST API       │
        │ stdio lokal    │                                      │ HTTP + SSE     │
        └───────┬────────┘                                      └───────┬────────┘
                │                                                       │
                └───────────────────────┬───────────────────────────────┘
                                        │
                              ┌─────────▼─────────┐
                              │    Synapse Core    │
                              │  packages/core     │
                              └─────────┬─────────┘
                                        │
      ┌─────────────────────┬───────────┼───────────┬─────────────────────┐
      │                     │           │           │                     │
┌─────▼─────┐        ┌──────▼──────┐ ┌──▼──────┐ ┌──▼────────┐    ┌──────▼──────┐
│PostgreSQL │        │   Qdrant    │ │ Parser  │ │ FileWatch │    │ Agenten     │
│Source of  │        │ Vektorindex │ │ 60+     │ │ Daemon    │    │ Wrapper     │
│Truth      │        │             │ │ Sprachen│ │ + Queue   │    │ Spezialisten│
└─────┬─────┘        └──────┬──────┘ └─────────┘ └─────┬─────┘    └──────┬──────┘
      │                     │                          │                 │
      │                     │                          │                 │
      │             ┌───────▼────────┐                 │        ┌────────▼────────┐
      │             │ Semantische    │                 │        │ Claude/Gemini    │
      │             │ Suche          │                 │        │ Subprozesse      │
      │             └────────────────┘                 │        └─────────────────┘
      │                                                │
      │                                          ┌─────▼─────┐
      │                                          │Filesystem │
      │                                          │Projekte   │
      │                                          └───────────┘
      │
      └──────────────────────────────────────────────────────────────┐
                                                                     │
                                                          ┌──────────▼──────────┐
                                                          │ Docker Workspaces   │
                                                          │ main/app/db/qa/...  │
                                                          └─────────────────────┘

Die wichtigste Pipeline: Code-Indexierung

Die zentrale Indexing-Pipeline sitzt in packages/core/src/services/code.ts.

Die Analyse der Funktionen zeigt diesen Ablauf:

indexFile()
   ↓
storeFileContent()
   ↓
enqueueParseAndEmbed()
   ↓
parseAndEmbed()
   ↓
PostgreSQL + Qdrant

Stage 1: schnelle Speicherung

storeFileContent(filePath, projectName, projectRoot) liest Dateiinhalt und Metadaten und schreibt sie nach PostgreSQL.

Datei vom FileWatcher
   ↓
readFileWithMetadata()
   ↓
content_hash berechnen
   ↓
upsertCodeFile()
   ↓
code_files

PostgreSQL enthält dadurch nicht nur Pfade, sondern auch Inhalt, Hash, Typ und später Indexierungszeitpunkte.

Stage 2: asynchrones Parsing und Embedding

enqueueParseAndEmbed(project, filePath) entkoppelt die teure Arbeit vom FileWatcher. parseAndEmbed(project, filePath) ist der zentrale Hotspot.

Der Flow von parseAndEmbed sieht, vereinfacht, so aus:

parseAndEmbed(project, filePath)
   ↓
getPool()
   ↓
Idempotenz-Check:
  indexed_at + embedded_at + unembedded count
   ↓
Dateiinhalt aus code_files lesen
   ↓
Parser über getParserForFile(filePath) wählen
   ↓
bei unbekanntem Filetype: parsed_at/indexed_at setzen und beenden
   ↓
Parser ausführen
   ├─ Symbole
   ├─ Referenzen
   ├─ Statements
   └─ CallEdges
   ↓
chunkFile(content, filePath, project)
   ↓
code_chunks in PostgreSQL ersetzen
   ↓
wenn Embeddings aktiv:
   ├─ ensureProjectCollection(project)
   ├─ deleteByFilePath(collection, filePath, project)
   ├─ embedBatch(chunks)
   └─ insertVectors(...)
   ↓
code_files.indexed_at / parsed_at / chunk_count aktualisieren

Wichtig: Synapse trennt bewusst Struktur und Semantik:

PostgreSQL
  code_files
  code_symbols
  code_references
  code_statements
  code_call_edges
  code_chunks

Qdrant
  project_<name>_code
  project_<name>_memories
  project_<name>_thoughts
  project_<name>_proposals
  project_<name>_docs
  project_<name>_media

PostgreSQL ist die Wahrheit. Qdrant ist der semantische Suchindex.


Code-Intelligence statt Grep

Synapse indexiert nicht nur Text. Es erzeugt aus Code eine strukturierte Analyseebene.

packages/core/src/services/code-intel.ts stellt u. a. bereit:

getProjectTree()
getFunctions()
getVariables()
getSymbols()
getReferences()
fullTextSearchCode()
getFileContent()
getStatements()
getCallEdges()
getExecutionFlow()
getEntrypoints()

Das bedeutet: Eine KI muss nicht raten, welche Datei relevant ist. Sie kann fragen:

Welche Funktionen gibt es in dieser Datei?
Wer ruft diese Funktion?
Wo ist dieses Symbol definiert?
Welche Statements laufen in dieser Funktion?
Welche Top-Level-Entrypoints gibt es?

Empfohlener Analyse-Workflow

1. code_intel.tree(path, depth: 1-2)
   ↓
2. code_intel.search_batch([...], limit_per_query: 3-5)
   ↓
3. code_intel.functions(file_path)
   ↓
4. code_intel.flow(file_path, scope)
   ↓
5. code_intel.file(file_path, from_line, to_line)

Erst Struktur, dann Flow, erst ganz zuletzt Rohtext.


Parser-System

packages/core/src/parser/ enthält viele spezialisierte Parser. In der analysierten Projektstruktur sind dort 72 Dateien mit über 300 Funktionen indexiert.

Synapse unterstützt u. a. Parser für:

TypeScript / JavaScript
Python
Go
Rust
Java
C / C++
C#
PHP
Ruby
Kotlin
Swift
Dart
SQL
Shell
Dockerfile
YAML
TOML
GraphQL
Elixir
Haskell
Zig
Solidity
Fortran
Ada
PowerShell
Objective-C
Nix
Svelte
Vue
WGSL / GLSL
COBOL
CMake
Racket
Lean
Dhall
Jsonnet
Moo
...

Die Parser liefern keine vollständige Compiler-AST für jede Sprache, sondern eine praktische Analyseform für KI-Arbeit:

ParsedSymbol[]
ParsedReference[]
ParsedStatement[]
ParsedCallEdge[]

So kann Synapse auch für viele Sprachen zumindest Funktionen, Klassen, Imports, SQL, Routen, Strings, Statements und Call-Kanten extrahieren.


MCP Server: lokale Tool-Schnittstelle

@synapse/mcp-server ist der lokale MCP-Server für Claude Code, Claude Desktop, Cline/Codex-ähnliche Clients und andere stdio-MCP-Clients.

Der Server nutzt das MCP SDK und registriert konsolidierte Tools wie:

project
search
memory
thought
proposal
plan
chat
channel
event
specialist
docs
admin
code_intel
code_check
files
shell
guide

Der Startbereich von packages/mcp-server/src/server.ts zeigt, dass der Server Core-Services, Agenten-Services und Tool-Module zusammenführt.

Response-Enrichment

Synapse ergänzt Tool-Antworten mit Kontext für Agenten:

Tool Call
   ↓
withOnboarding / Response Enhancement
   ↓
optional:
  agentOnboarding
  pendingEvents
  unreadChat
  activeAgents

Damit sieht ein Agent beim normalen Arbeiten automatisch:

  • ob Projektregeln geladen werden müssen
  • ob Events zu bestätigen sind
  • ob ungelesene Chatnachrichten warten
  • welche anderen Agenten aktiv sind

REST API und MCP-over-HTTP

@synapse/rest-api stellt dieselben Fähigkeiten für Web-KIs bereit.

Wichtige Eigenschaften:

Fastify Server
   ↓
REST-Routen für Tools
   ↓
MCP-over-HTTP
   ↓
SSE + JSON-RPC
   ↓
OAuth Discovery für Claude.ai Connector

packages/rest-api/src/routes/mcp.ts enthält die MCP-over-HTTP-Schicht. Dort werden u. a. verarbeitet:

initialize
tools/list
tools/call

Außerdem gibt es Endpunkte für:

/mcp/sse
/mcp/messages?sessionId=...
/.well-known/oauth-authorization-server
/oauth/*

Die REST-API initialisiert zusätzlich einen Parser-Worker-Pool. Das verhindert Event-Loop-Stalls bei großen Dateien und kann serverseitig parseUnparsedFiles nachziehen, wenn kein lokaler FileWatcher läuft.


FileWatcher-Daemon und PG-Queues

Der FileWatcher-Daemon ist die lokale Brücke zwischen Server/Web-KI und dem echten Projekt auf dem Rechner.

Es gibt zwei Generationen/Varianten im Repo:

packages/file-watcher-daemon/      # Moo-basierter Daemon/Tray
packages/file-watcher-daemon-ts/   # TypeScript-Daemon mit HTTP API und Workers

Der Daemon übernimmt:

Projekt aktivieren/deaktivieren
Dateisystem beobachten
Dateiänderungen an Core weitergeben
Shell-Jobs aus PostgreSQL claimen
eSpecialist-Jobs aus PostgreSQL claimen
Project-Init-Jobs claimen
Status per HTTP/SSE bereitstellen

Queue-Architektur

PostgreSQL ist hier nicht nur DB, sondern auch Job-Bus:

REST oder MCP schreibt Job nach PostgreSQL
   ↓
Trigger feuert NOTIFY
   ↓
Daemon LISTENt auf Channel
   ↓
Daemon claimt Job
   ↓
Daemon führt lokal aus
   ↓
Result/Logs zurück nach PostgreSQL

Wichtige Queues:

shell_jobs
specialist_jobs
project_init_jobs

Aus dem Schema sind NOTIFY-Trigger für u. a. diese Jobs vorhanden:

notify_shell_job_created()
notify_specialist_job_created()
notify_project_init_job_created()

Shell: lokal oder Workspace

Das shell-Tool ist nicht einfach ein Bash-Wrapper. Es routet nach Umgebung:

shell(exec)
   ↓
läuft lokaler Daemon mit frischem Heartbeat?
   ├─ ja: PG-Queue → lokaler Daemon → echtes Projekt-FS
   └─ nein: Docker Workspace → isolierte Ausführung

Antworten enthalten executed_via, damit Agenten sehen, ob der Befehl lokal oder im Workspace lief.

Logs und Historie bleiben in PostgreSQL erhalten:

shell.history
shell.get
shell.log
shell.activity

log unterstützt Range-Reads und Regex-Suche in Job-Ausgaben.


Files-Layer: versionierte Code-Änderungen

Das files-Tool schreibt nicht blind in Dateien. Es arbeitet über PostgreSQL und erzeugt Versionen.

Typische Operationen:

read
create
update
search_replace
search_replace_batch
replace_lines
insert_after
delete_lines
move
copy
delete
versions
get_version
restore
restore_batch
history

Dateiversionierung, History und Rollback

Jede Dateiänderung über den files-Layer erzeugt automatisch einen Snapshot in der Versionshistorie. Dadurch kann Synapse nicht nur Dateien schreiben, sondern Änderungen nachvollziehen, vergleichen und zurückrollen.

Wichtige Aktionen:

files(versions)
  listet alle Versionen einer Datei

files(get_version)
  lädt den kompletten Inhalt einer alten Version

files(history)
  zeigt projektweit, wer wann was warum geändert hat

files(restore)
  stellt eine einzelne alte Dateiversion wieder her

files(restore_batch)
  rollt eine komplette Multi-File-Batch zurück

Das macht den Files-Layer zu einem Audit- und Recovery-System:

Änderung durch Agent
   ↓
file_versions Snapshot
   ↓
reason / agent_id / edit_action / batch_id / feature_tag
   ↓
history zeigt den Änderungspfad
   ↓
get_version lädt alte Inhalte
   ↓
restore oder restore_batch geht zurück

Bei Multi-File-Commits bekommen alle betroffenen Dateien dieselbe batch_id. Damit kann eine ganze Änderungseinheit später gemeinsam wiederhergestellt werden, statt Datei für Datei manuell zurückzugehen.

Für Review-Workflows gibt es zwei Ebenen:

Plan-Phase
  previews zeigen, was geändert würde
  expected_hashes schützen gegen Drift

History/Versionen
  versions + get_version zeigen alte Stände
  history zeigt Kontext, Agent, Grund und Batch

So kann ein Koordinator nach einem fehlerhaften Agentenlauf nicht nur fragen „was ist passiert?“, sondern gezielt jeden betroffenen Stand inspizieren und den passenden Snapshot zurückholen.

Atomare Multi-File-Edits

packages/core/src/services/file-batch.ts implementiert Plan/Commit für mehrere Dateien.

Relevante Funktionen:

prepareOpsForApply()
verifyAnchor()
applyOpInMemory()
planBatch()
commitBatch()
cancelBatch()
getBatchPlan()

Ablauf:

files_batch(plan, ops[])
   ↓
Dateien lesen
   ↓
Ops im Speicher anwenden
   ↓
expected_hashes + previews speichern
   ↓
plan_id zurückgeben

files_batch(commit, plan_id)
   ↓
Hash gegen aktuellen Stand prüfen
   ↓
wenn stale: Konflikte zurückgeben
   ↓
wenn sauber: alle Änderungen in PG-TX anwenden
   ↓
file_versions mit gemeinsamer batch_id schreiben

Zusätzliche Sicherheitsmechanismen:

anchor_text / anchor_contains
  schützt vor Drift an Zielzeilen

expected_hashes
  schützen vor Änderungen zwischen Plan und Commit

restore_batch
  rollt ganze Multi-File-Batches zurück

agent_note / reason / feature_tag
  machen Änderungen auditierbar

Persistentes Wissen

Synapse unterscheidet mehrere Wissensformen:

SystemZweck
memorydauerhaftes Projektwissen: Architektur, Regeln, Entscheidungen, Gotchas
thoughtkurzfristige Erkenntnisse, Zwischenstände, Handoffs
planProjektplan und Tasks
proposalCode- oder Architekturvorschläge
docskuratierte Tech-Doku und Wissens-Airbag
code_checkbekannte Fehler-Patterns mit Fix-Hinweisen

Diese Systeme sind nicht Markdown-Dateien, sondern Tools mit Speicherung, Suche, Tags, Versionierung und teilweise Embeddings.


Agenten, Channels, Events und Spezialisten

Synapse hat ein lokales Agentenmodell.

Koordinator
   ↓
spawn / wake / stop / purge
   ↓
Spezialist-Wrapper
   ↓
Claude/Gemini/Subprozess

Chat, Inbox, Channels

chat
  Broadcasts und DMs zwischen Agenten

inbox
  1:1 Nachrichten an Spezialisten

channel
  Gruppenräume für Spezialisten-Teams

Event-System

Events sind verbindliche Steuersignale, keine normalen Chatnachrichten.

event.emit()
   ↓
agent_events
   ↓
Agent sieht pendingEvents in Tool-Antworten
   ↓
event.ack()
   ↓
agent_event_acks

Typische Event-Arten:

WORK_STOP
CRITICAL_REVIEW
ARCH_DECISION
TEAM_DISCUSSION
ANNOUNCEMENT
NEW_TASK
CHECK_CHANNEL

Spezialisten-Wrapper

Der Spezialisten-Wrapper liegt in packages/agents/src/wrapper.ts und ist einer der großen Hotspots des Projekts.

Er startet als eigener Node-Prozess und steuert einen KI-CLI-Subprozess.

MCP / REST / Daemon
   ↓
Unix Domain Socket / JSON-RPC
   ↓
Agent Wrapper
   ↓
ProcessManager
   ↓
Provider-Runtime
   ├─ Claude CLI Subprozess
   ├─ Gemini CLI Runtime
   └─ Gemini API Runtime (`@google/genai`, GOOGLE_API_KEY)

Wichtige Funktionen im Wrapper:

setupPgListeners()
startSocketServer()
handleRpcRequest()
handleWake()
handleStop()
handleStatus()
wakeAgent()
heartbeatPoll()
recoverStuckAgent()
pollChannelMessages()
pollInboxMessages()
pollSynapseItems()
updateStatusPg()
rotateAgent()
cleanup()
main()

Der Wrapper pollt und verarbeitet:

Channel-Nachrichten
Inbox-Nachrichten
Memories
Thoughts
Plan-Tasks
Pending Events
Token-/Context-Status
Statusupdates nach PostgreSQL

Dadurch kann ein Spezialist über längere Zeit als persistente lokale Helferinstanz existieren.


Skills für Spezialisten

Spezialisten haben ein eigenes Skill-Verzeichnis.

Typische Dateien:

rules.md
errors.md
patterns.md
context.md
meta.yaml
logs/YYYY-MM-DD.md

Damit können Regeln, bekannte Fehler, Muster und Kontext über Wrapper-Neustarts hinweg erhalten bleiben.


Workspaces: isolierte Docker-Testumgebungen

Synapse enthält einen Workspace-Orchestrator für Docker-Sandboxen.

Grundidee:

Projekt
   ├─ main
   ├─ app
   ├─ qa
   ├─ db-1
   └─ db-2

Jeder Workspace ist ein Container mit eigenem HOME-Volume. Alle teilen /workspace als Source-Sicht, aber Builds und Zustände können getrennt laufen.

DNS-Schema:

main:     http://synapse-ws-<projekt>:<port>
benannt:  http://synapse-ws-<projekt>-<name>:<port>

Beispiel für einen Integrationstest:

workspace: db-1    Rolle db-postgres, Port 5432
workspace: app     Backend, Port 3000
workspace: qa      Testclient, curl/wine/etc.

Ablauf:

workspace db-1 startet PostgreSQL
   ↓
workspace app startet Backend
   ↓
workspace qa testet http://synapse-ws-<projekt>-app:3000/health

Workspaces sind lazy gestartet, werden nach Idle-Zeit gestoppt und können per pin geschützt werden.


Datenmodell: wichtigste PostgreSQL-Tabellen

Synapse verwendet PostgreSQL als Source of Truth.

Wichtige Tabellen/Subsysteme:

code_files
code_chunks
code_symbols
code_references
code_statements
code_call_edges
memories
thoughts
plans
proposals
tech_docs
agent_sessions
chat_messages
agent_events
agent_event_acks
specialist_channels
specialist_channel_messages
specialist_inbox
shell_jobs
specialist_jobs
project_init_jobs
wrapper_status
project_workspaces
workspace_roles
file_versions
file_batch_plans
error_patterns
watcher_events

Qdrant hält dazu die semantischen Collections, z. B.:

project_<name>_code
project_<name>_memories
project_<name>_thoughts
project_<name>_proposals
project_<name>_docs
project_<name>_media

Projektstruktur

Aus der analysierten Codebase:

synapse/
├── packages/
│   ├── core/
│   │   └── src/
│   │       ├── services/        # Code, Files, Memory, Plans, Events, Queues, Workspaces
│   │       ├── parser/          # 60+ Sprachparser
│   │       ├── db/              # PostgreSQL Schema + Client
│   │       ├── embeddings/      # Google/OpenAI/Ollama/Cohere Provider
│   │       ├── qdrant/          # Collections + Vektoroperationen
│   │       ├── watcher/         # Ignore/Binary/FileWatcher-Utilities
│   │       └── guide/           # Tool-Dokumentation
│   ├── mcp-server/
│   │   ├── src/server.ts
│   │   ├── src/tools/
│   │   └── hooks/
│   ├── rest-api/
│   │   ├── src/server.ts
│   │   ├── src/routes/mcp.ts
│   │   └── src/services/workspace-orchestrator.ts
│   ├── agents/
│   │   ├── src/wrapper.ts
│   │   ├── src/heartbeat.ts
│   │   ├── src/process.ts
│   │   └── src/skills.ts
│   ├── agents-gemini/
│   ├── agents-antigravity/
│   ├── file-watcher-daemon/
│   ├── file-watcher-daemon-ts/
│   └── web-ui/
├── docker/
│   ├── synapse-workspace/
│   └── synapse-workspace-podman/
├── scripts/
└── skills/

Setup

Voraussetzungen

Node.js >= 20
pnpm
PostgreSQL
Qdrant
Google AI API Key für Embeddings
optional: Context7 API Key
optional: Claude/Gemini CLI für Spezialisten
optional: Docker für Workspaces

Installation

pnpm install
pnpm run build

Wichtige Root-Skripte:

pnpm run build        # alle Packages bauen
pnpm run build:core   # Core
pnpm run build:mcp    # MCP Server
pnpm run build:api    # REST API
pnpm run build:agents # Agenten
pnpm run dev:mcp      # MCP Server watch/dev
pnpm run dev:api      # REST API dev
pnpm run lint
pnpm run clean

Google API Key: Embeddings und Gemini-Spezialisten

Synapse kann denselben GOOGLE_API_KEY an zwei Stellen nutzen:

1. Embeddings
   → Google Embedding Provider für semantische Suche

2. Gemini-Spezialisten
   → optional API-basierte Specialist-Runtime über @google/genai

Bei Gemini gibt es zwei Betriebsarten:

Gemini CLI
  → nutzt lokale CLI/Auth auf dem Zielsystem

Google/Gemini API-Key
  → nutzt @google/genai + GOOGLE_API_KEY

Das ist eine bewusste Entscheidung pro Setup: Wer seine Gemini CLI verwenden will, kann das tun. Wer lieber über den API-Key geht, kann die API-basierte Runtime verwenden. packages/agents-gemini/src/runtime.ts enthält dafür eine eigene Google/Gemini-Runtime. Sie kann standalone laufen oder im SYNAPSE_WRAPPER_MODE=1 vom Synapse-Wrapper gespawnt werden.

GOOGLE_API_KEY=...
   ↓
Synapse Embeddings
   ↓
Qdrant Vektoren

GOOGLE_API_KEY=...
   ↓
Gemini Specialist Runtime
   ↓
Spezialist läuft über Google API statt lokale Claude CLI

Standardmäßig nutzt die Gemini-Runtime den Embedding-Key mit:

SYNAPSE_GEMINI_USE_EMBEDDING_KEY=true

Wenn das auf false gesetzt wird, kann die Runtime perspektivisch Credentials aus provider_credentials laden und fällt sonst wieder auf ENV zurück.

Embedding-Provider und Vektor-Dimensionen

Synapse nutzt Embeddings für semantische Suche in Qdrant. Der empfohlene Standard ist Google, wenn ein GOOGLE_API_KEY vorhanden ist. Ollama ist primär der lokale Fallback, wenn kein Google-Key genutzt werden soll oder darf.

Wichtig: Qdrant-Collections haben eine feste Vektorgröße. Man kann den Embedding-Provider oder das Modell daher nicht beliebig wechseln, wenn das neue Modell eine andere Dimension erzeugt.

Google Embedding Modell
   → z. B. 3072 Dimensionen
   → Qdrant Collection wird mit 3072 angelegt

Ollama Modell
   → je nach Modell andere Dimension
   → passt NICHT automatisch in dieselbe Collection

Wenn du den Provider wechselst, gibt es nur sichere Wege:

1. Modell wählen, das dieselbe Vektor-Dimension erzeugt
   → bestehende Collection bleibt kompatibel

2. Collection neu aufbauen / migrieren
   → alte Vektoren löschen oder re-embedden

3. Projekt bewusst neu indexieren
   → alle Chunks mit neuem Modell neu schreiben

Unsicher ist:

Provider wechseln
   ↓
neue Embeddings mit anderer Dimension
   ↓
in alte Qdrant-Collection schreiben
   ↓
Dimension-Mismatch / kaputte oder unbrauchbare Suche

Kurz gesagt:

GOOGLE_API_KEY vorhanden → Google verwenden
kein Google-Key       → Ollama möglich
Provider-Wechsel     → Dimension prüfen oder re-indexieren

MCP-Konfiguration

Beispiel aus .mcp.json.example:

{
  "mcpServers": {
    "synapse": {
      "command": "node",
      "args": ["/pfad/zu/synapse/packages/mcp-server/dist/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "EMBEDDING_PROVIDER": "google",
        "GOOGLE_API_KEY": "dein-google-api-key",
        "DATABASE_URL": "postgresql://synapse:passwort@localhost:5432/synapse",
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "nomic-embed-text",
        "CONTEXT7_API_KEY": "dein-context7-key"
      }
    }
  }
}

Wichtige Umgebungsvariablen

DATABASE_URL
QDRANT_URL
QDRANT_API_KEY
EMBEDDING_PROVIDER
GOOGLE_API_KEY
OPENAI_API_KEY
OLLAMA_URL
OLLAMA_MODEL
CONTEXT7_API_KEY
API_PORT
API_HOST
MAX_FILE_SIZE_MB
CHUNK_SIZE
CHUNK_OVERLAP
DEBOUNCE_MS
PARSER_WORKER_THREADS
PARSER_LOOP_DISABLED
PARSER_LOOP_INTERVAL_MS
SYNAPSE_SKIP_EMBEDDINGS
SYNAPSE_KEEP_ALIVE
SYNAPSE_POLL_INTERVAL
SYNAPSE_WS_PER_PROJECT_CAP
SYNAPSE_WS_PRIVILEGED_ROLES

Praktische Arbeitsweise für KI-Agenten

Synapse ist am stärksten, wenn Agenten nicht direkt Dateien dumpen, sondern strukturierte Tools nutzen.

Code verstehen

code_intel.tree(path, depth)
code_intel.search_batch([...])
code_intel.functions(file_path)
code_intel.flow(file_path, scope)
code_intel.file(file_path, from_line, to_line)

Impact-Analyse

code_intel.references(name)
code_intel.calls(callee)
code_intel.functions(name)

Änderung vorbereiten

memory.find_for_file(file_path)
docs.get_for_file(file_path)
files_batch(plan, ops[], anchor_contains)
files_batch(commit, plan_id)

Wissen sichern

thought.add(...)
memory.write(...)
plan.update_task(...)
channel.post(...)

Design-Prinzipien

PostgreSQL first
Qdrant second
code_intel before grep
flow before file dump
tools before shell
files before direct write
plans before multi-file commit
anchors before risky edits
DNS names before container IPs

Synapse ist absichtlich lokal-first. Es soll dem User gehören: eigene Projekte, eigene Datenbank, eigene Agenten, eigene Workspaces.


Lizenz

MIT

Ver o original no GitHub

Bom para

Relacionados