Synapse Openclaw Plugin

Research Orchestration for Human Researchers and AI Agents

中文

Synapse is a research orchestration platform that brings human researchers and AI agents together. It manages the full research lifecycle — from literature review and question formulation through experiment execution and report generation — with built-in agent management, compute orchestration, and real-time observability.

Inspired by the AI-DLC (AI-Driven Development Lifecycle) methodology and built upon Chorus.

Milestone: We reproduced Karpathy's auto-research task and outcome pattern on Synapse. Unlike designing the behavior of a single agent through a program.md, Synapse treats autonomous experimentation as a native platform capability. Research projects, experiment lifecycles, compute allocation, and context accumulation are all managed through structured MCP tools, creating dynamic contexting. Research memory is persisted in the platform and exposed as tool-based state that agents can call, fetch, and expand on demand according to the current situation, rather than forcing everything to be loaded into an agent's context window up front.

---

What's New

v0.7.0 — PGlite Local Mode & Server Action Fix (2026-04-20)   🔴 New

• One-command local install: npm install -g @synapse-research/synapse && synapse — zero-dependency PGlite mode, no PostgreSQL or Redis required
• Fixed critical bug where research question creation silently failed in standalone mode (server actions replaced with REST API)
• Fixed cache directory permission error when installed globally via sudo npm install -g
• Completion notifications now show a checkmark icon instead of a plain dot
• Health check no longer reports "degraded" when Redis is configured but not yet lazy-loaded

v0.6.1 — Experiment Board UI Polish (2026-04-15)

• Project descriptions on the dashboard now preserve intentional blank lines when expanded, improving readability for structured briefs
• The experiment plan side panel now renders above the detail sheet overlay, uses the shared panel background, and allows normal text selection
• The autonomous experiment entry button is more prominent, with refreshed blue styling and a yellow lightning icon for faster scanning
• The experiment detail sheet is wider on large screens, giving experiment plans, results, and progress logs more room

v0.6.0 — Agent Types & Research Copilot (2026-04-12)

• Agents now have a type field (OpenClaw or Claude Code) with internal transport mapping — Web UI dispatch features only show realtime-capable agents
• Claude Code Research Copilot: SessionStart presents projects with progress summaries and guides users through the research lifecycle (paper search → deep research → questions → experiments → analysis)
• synapse_checkin returns assigned experiments and project progress for intelligent workflow suggestions
• Agent management UI gains a type selector and badge display

v0.5.1 — DeepXiv Integration (2026-04-10)

• Paper search now uses DeepXiv hybrid search (BM25 + vector) over arXiv, with arXiv API as fallback. Removed Semantic Scholar and OpenAlex.
• Agents can read full paper content via progressive reading tools: synapse_read_paper_brief, synapse_read_paper_head, synapse_read_paper_section, synapse_read_paper_full
• Deep research literature reviews are now based on actual paper content, not just abstracts
• DeepXiv token configurable from Settings > Integrations

v0.5.0 — Autonomous Loop & Related Works (2026-03-29)

• Autonomous experiment loop: agents propose → humans review → agents execute
• Related Works page with auto-search, manual arXiv URL addition, and deep research reports
• Experiment live status tracking (sent/ack/checking/queuing/running)
• Compute pool binding per project

---

Table of Contents

• Vibe Research
• Features
• Getting Started
• Progress
• Documentation
• License

Vibe Research

Vibe Coding showed that people can describe intent and let AI handle execution. Vibe Research applies that same shift to the research lifecycle:

Humans set direction. Agents execute, report, propose, and iterate. Humans review, steer, and decide.

Stages of Agent Autonomy in Research

Synapse is built to move research teams through these stages deliberately.

• Streamline Stage 1 by making experiment execution, compute access, result capture, and reporting a default operational loop instead of a pile of manual handoffs.
• Make Stage 2 reliable by keeping context, papers, experiments, progress, and review in one system, so agents can act independently without drifting off-task.
• Make Stage 3 feasible by building the control plane for project-level delegation: structured context, observability, orchestration, permissions, and human steering when it matters most.

---

Features

Project Workspace

Synapse gives each research project a shared operational home for briefs, datasets, evaluation methods, research questions, experiments, reports, and rolling synthesis. Instead of bouncing across docs, scripts, spreadsheets, and chat threads, humans and agents work from the same source of truth.

Related Works and Deep Research

• Paste an arXiv URL to add a paper with metadata fetched automatically
• Assign a pre_research agent to search Semantic Scholar and build a project paper set
• Generate literature review documents directly inside the project workspace

Research Question Canvas

• Organize research questions in a canvas-style hierarchy with parent-child structure
• Track question progress from exploration to experiment creation and completion
• Keep question context connected to the experiments and reports it produces

Experiment Execution Board

• Five-column experiment pipeline: draft → pending_review → pending_start → in_progress → completed
• Live status badges for agent execution: sent, ack, checking_resources, queuing, running
• Progress reporting through synapse_report_experiment_progress
• Autonomous loop support, so agents can propose the next experiments when queues are empty

Agent Management

• API-key based agent access to Synapse MCP tools
• User-scoped agent ownership, key management, and session observability

Five agent permission roles (composable):

Permission	Responsibility
Pre-research	Literature search, related works discovery via Semantic Scholar
Research	Propose research questions, hypothesis formulation
Experiment	Execute experiments, allocate compute, report progress
Report	Generate experiment reports, literature reviews, synthesis documents
Admin	Create/delete projects, manage groups, review research questions

Compute Orchestration

• Compute pools, node inventory, GPU reservations, and per-project pool binding
• Managed SSH access bundles for secure compute access from agent environments
• Keep agents aligned with available resources before, during, and between runs

Reports, Synthesis, and MCP Surface

• Agents write experiment reports in the context of the project instead of filling rigid templates
• Synapse maintains project-level synthesis documents as research evolves
• 70+ MCP tools cover project context, literature search, experiment execution, compute access, and collaboration

Getting Started

Quick Start (No Dependencies)

npm install -g @synapse-research/synapse
synapse

Open http://localhost:13000 and log in with admin@synapse.local / synapse.

This runs Synapse with an embedded PGlite database — no PostgreSQL or Redis required. Data is stored in ~/.synapse/data.

Options: synapse --port 3000 --data-dir /path/to/data --help

Docker

git clone https://github.com/Vincentwei1021/Synapse.git
cd Synapse

export DEFAULT_USER=admin@example.com
export DEFAULT_PASSWORD=changeme
docker compose up -d

Open http://localhost:3000 and log in.

Local Development

Prerequisites: Node.js 22+, pnpm 9+, PostgreSQL

cp .env.example .env
# Edit .env to configure DATABASE_URL

pnpm install
pnpm db:push
pnpm dev

open http://localhost:3000

The default .env.example includes a built-in login account:

Field	Value
Email	dev@synapse.local
Password	synapse123

You can change these by editing DEFAULT_USER and DEFAULT_PASSWORD in your .env file. When both variables are set, Synapse enables a simple email/password login without requiring OIDC configuration.

Connect AI Agents

Option 1: OpenClaw (Recommended)

openclaw plugins install @vincentwei1021/synapse-openclaw-plugin

Then configure in OpenClaw settings: set synapseUrl and apiKey.

Tip: If you encounter Request timed out before a response was generated, increase the idle timeout in your OpenClaw config: set agents.defaults.llm.idleTimeoutSeconds to 300.

Option 2: Claude Code Plugin

claude
/plugin marketplace add Vincentwei1021/Synapse
/plugin install synapse@synapse-plugins

Set environment variables:

export SYNAPSE_URL="http://localhost:3000"
export SYNAPSE_API_KEY="syn_your_api_key"

Option 3: Manual MCP Configuration

Create .mcp.json in your project root:

{
  "mcpServers": {
    "synapse": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": {
        "Authorization": "Bearer syn_your_api_key"
      }
    }
  }
}

Progress

Implemented

• Research-project workspace with briefs, datasets, evaluation methods, experiments, documents, and rolling synthesis
• Research-question hierarchy and canvas-style question management
• Five-stage experiment board with live execution status and progress updates
• Agent-generated experiment reports and project-level synthesis documents
• Related works workflow with Semantic Scholar search, paper collection, and deep research reports
• Composable agent permissions: pre_research, research, experiment, report, admin
• User-scoped agent ownership, API keys, and agent session observability
• Compute pools, node inventory, GPU reservations, and project-level pool binding
• Managed node access bundles for secure agent access to compute
• Autonomous experiment proposal loop for keeping project momentum when queues empty out
• Comments, mentions, notifications, and real-time SSE updates
• 70+ MCP tools covering context retrieval, literature, experiments, compute, and collaboration

Planned

• Steer running agents during an in_progress experiment
• Stream raw experiment logs back into the panel in real time
• Run experiments in parallel via isolated git trees / worktrees
• Strengthen evaluation loops with first-class baselines and accept/reject criteria
• Track reproducibility artifacts: code revision, config, outputs, and environment

---

Documentation

Document	Description
CLAUDE.md	Development guide and coding conventions
Architecture	Technical architecture
MCP Tools	MCP tools reference
OpenClaw Plugin	Plugin design and hooks
Docker	Docker deployment guide

---

License

AGPL-3.0 — see LICENSE.txt