# 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.

![ResearchGraph workspace](docs/images/workspace.png)

## 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.

## Run locally

You need Git, [uv](https://docs.astral.sh/uv/getting-started/installation/), and a running Docker engine with Compose. uv installs Python 3.12 if needed.

```bash
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.

```bash
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](docs/operations.md) 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:

```json
{
  "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:

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

Copy the seven folders under [`skills/`](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.

| Skill | Responsibility |
|---|---|
| `research-triage` | Relevance, inclusion/exclusion reasons and reading priority |
| `research-extract` | Methods, equations, claims, limitations and provenance |
| `research-architecture` | Components, tensor flow, variants, repeats and figures |
| `research-retrieve` | Bounded search, graph traversal, evidence and coverage |
| `research-experiment` | Hypotheses, configurations, measurements and failures |
| `research-synthesize` | Comparisons, conflicting evidence and decisions |
| `research-checkpoint` | Durable progress and fresh-context handoffs |

## Architecture

```mermaid
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](docs/graph-model.md), [harness design](docs/harness.md), and [operations](docs/operations.md).

## Verification

```bash
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:

| Retrieval | Recall@5 | MRR |
|---|---:|---:|
| Full text | 0.8182 | 0.8864 |
| Full text + graph | 0.9545 | 0.7803 |

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](docs/evaluation.md) and [recorded output](docs/evaluation-fixture.json).

## 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](CONTRIBUTING.md). MIT licensed; imported sources retain their original rights.