ResearchGraph

Research memory your next agent can pick up.

Connect papers, model architectures, methods, experiments and the decisions behind them. Neo4j stores the scientific memory. Twelve MCP tools give your existing agent controlled access. Seven research skills guide reading, extraction and handoffs. A local web workspace lets you inspect and correct what the agent remembers.

This is a working local v0.1 for individual research. It does not call an LLM, require Graphiti, or automatically understand a paper just because its PDF was imported.

What you can do

• Import PDF, Markdown or text with content hashes, retained originals and page/character evidence.

• Describe models as versioned architectures with component instances, directed dataflow, shapes, repeats, equations and unknowns.

• Connect optimizers, nonlinearities, objectives, normalization, data methods and evaluation protocols as reusable concepts.

• Preserve hypotheses, controlled configurations, failed runs, observations and decisions without conflating them.

• Search full text and graph neighbors with explainable matches, project boundaries and signed continuation cursors.

• Resume bounded research sessions with search budgets, encountered records, findings and next queries in Neo4j.

• Correct records with optimistic concurrency checks and inspect saved revisions.

• Inspect retrieval traces and Prometheus API metrics; run a reproducible synthetic retrieval evaluation.

Related MCP server: Neo4j Agent Memory MCP Server

Run locally

You need Git, uv, and a running Docker engine with Compose. uv installs Python 3.12 if needed.

git clone https://github.com/amiteshk469/researchgraph.git
cd researchgraph
uv sync --frozen --python 3.12
uv run researchgraph init
docker compose up -d neo4j
# Wait for the database to become healthy:
docker compose ps
uv run researchgraph demo
uv run researchgraph serve

Open http://127.0.0.1:8765 and enter RG_API_TOKEN from the generated .env. Credentials are unique to your installation. The demo workspace is synthetic; create a separate workspace for actual research.

uv run researchgraph import ./paper.pdf --scope audio-thesis --title "Paper title"
uv run researchgraph search "time masking" --scope demo
uv run researchgraph evaluate

Import preserves text and metadata. Use an agent with the extraction skills to create scientific records. The service does not fetch URLs, perform OCR, interpret diagrams or automatically extract claims.

For a containerized web service, use docker compose --profile app up --build -d. See operations for source storage and container MCP configuration.

Connect your agent

MCP runs over local stdio with the same .env and Neo4j database. Clients supporting repository .mcp.json can use the included file when launched from this checkout. Otherwise use an absolute directory:

{
  "mcpServers": {
    "researchgraph": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/researchgraph", "run", "--frozen", "researchgraph", "mcp"]
    }
  }
}

For Codex, add the equivalent server in MCP settings, or merge this into the existing TOML configuration:

[mcp_servers.researchgraph]
command = "uv"
args = ["--directory", "/absolute/path/to/researchgraph", "run", "--frozen", "researchgraph", "mcp"]

Copy the seven folders under skills/ into your agent's skill directory (for example, ~/.agents/skills/ for Codex), preserving supporting files. Reconnect the agent and verify list_projects and inspect_schema are available. A configuration file alone does not establish that a client has loaded the tools.

Try:

Use ResearchGraph in demo. Investigate what the time-masking experiment supports. Begin a six-search research session, inspect evidence and failed runs, then checkpoint findings and next steps. Distinguish synthetic observations from a scientific conclusion.

Architecture

flowchart LR
    Human[Researcher] --> UI[Local research workspace]
    Agent[Existing AI agent] --> Skills[Seven research skills]
    Skills --> MCP[Twelve MCP tools · stdio]
    UI --> API[Authenticated FastAPI]
    MCP --> Service[Shared research service]
    API --> Service
    Service --> Harness[Budgets · checkpoints · seen IDs]
    Service --> Validation[Contracts · revisions · evidence checks]
    Service --> Search[Full-text + graph retrieval]
    Harness --> Neo[(Neo4j)]
    Validation --> Neo
    Search --> Neo
    Service --> Files[Local content-addressed sources]

Neo4j is the authority for records, relationships, revision snapshots, change receipts, sessions and traces. Original files live on disk, referenced by hash. There is no SQL metadata store or second vector database.

Read the graph model, harness design, and operations.

Verification

uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run pytest -q                         # integration tests skip by default
RG_INTEGRATION=1 uv run pytest -q         # requires the local Neo4j instance
uv run python scripts/validate_skills.py
uv run researchgraph evaluate

Integration tests create fresh UUID scopes and clean up only those scopes. They exercise transactions, concurrent revision conflicts, pinned evidence, scope isolation, stale cursors, source reconstruction, restore, resumed budgets, API authentication and a real MCP stdio round trip. CI uses a real Neo4j service.

The initial 12-query synthetic development fixture produced:

Graph expansion found more expected records while sometimes ranking them lower. This small hand-authored fixture is not held out. It does not measure extraction quality, reasoning or real-world research usefulness. See methodology and recorded output.

Deliberate boundaries

This is a local single-user tool. Scopes organize retrieval; they are not user permissions. HTTP uses one local token and stdio inherits database access. The API is not ready to expose as a public multi-user service.

Retrieval is lexical plus bounded graph expansion, without embeddings. Skills guide your agent; they are not an autonomous runtime or scheduler. Validation checks structure and provenance, not scientific truth. Large-corpus scaling and held-out extraction evaluation remain future work.

Contributions welcome: CONTRIBUTING.md. MIT licensed; imported sources retain their original rights.