surveyHelper

Mention a paper — surveyHelper remembers it, analyzes it, maps its citation graph, and tells you what the graph means. All on your machine, and honest about what it can prove.

A local-first research companion. It runs as an MCP server (any MCP agent can use it) with an optional OpenClaw ambient plugin. Your papers, analyses, and notes never leave your machine.

flowchart LR
    U([You mention a paper]) --> M[MCP server]
    M --> C["Instant card<br/>purpose · references · code"]
    M -. enqueue .-> W[Worker]
    W --> A[Deep grounded analysis]
    W --> S["Citation-graph synthesis<br/>verbatim-verified contradictions"]
    C --> DB[("Postgres + pgvector<br/>your local memory")]
    A --> DB
    S --> DB
    DB --> R[Ambient recall + proactive surfacing]

What you get

• Instant cards — give it an arXiv id or title and get the paper's purpose, references, and code link in seconds.
• Deep grounded analysis — contribution, method, results, and limitations, extracted from the full text with a faithfulness check.
• Citation-graph synthesis you can trust — lineage, open problems, and contradictions across the graph. It only asserts a contradiction when it can quote verbatim evidence from both papers; otherwise it labels it tentative. It tells you what it can prove and is honest about what it can't.
• Personal memory — tracks what you care about (interests, papers you've read/understood) and proactively surfaces new work.
• Ambient awareness — with the OpenClaw plugin, say "the BERT paper" in chat and it injects what your graph already knows — no command, no tool call.

Quick start

You need Docker and one LLM API key (Anthropic, OpenAI, or Gemini).

git clone https://github.com/rich7420/SurveyHelper.git && cd SurveyHelper
cp .env.example .env          # set ONE provider key
docker compose up -d          # pgvector + worker + MCP server (:8765) + scheduler
docker compose run --rm worker surveyhelper-verify    # → "✓ surveyHelper is working"

No Postgres setup, no subscription, no machine-specific wiring. Then point any MCP agent at http://localhost:8765/mcp, or follow the Getting Started guide for your first survey (~5 minutes).

No API key but you run OpenClaw? Set SURVEYHELPER_LLM_BACKEND=cli to reuse its claude -p subscription (runs natively — see Operations).

Use it with OpenClaw (optional)

Make it ambient — it recognizes a paper you mention in chat and injects what your graph knows:

bash openclaw/install.sh                              # register the MCP server + skill
openclaw plugins install clawhub:openclaw-surveyhelper   # the ambient-recognition hook (from ClawHub)

(Or install the hook from a clone with bash openclaw/plugin/install-plugin.sh.) The MCP server is a standard endpoint, so it also works with Claude Desktop and other MCP clients.

How it works

Three pieces, all local:

• MCP server — what your agent calls; returns the instant card and queues the deep work.
• Worker — a background daemon that does the paced fetching, analysis, and synthesis.
• Postgres + pgvector — the memory: the paper graph, analyses, and your personal layer.

The instant card never waits on slow APIs; references and deep analysis fill in in the background. Full detail in docs/ARCHITECTURE.md.

Docs

• Getting Started — zero to your first survey
• Vision · Roadmap — what it is and where it's going
• Architecture · Operations — internals, running, troubleshooting
• Contributing · Release process

MIT licensed.