ResearchOS Core

The offline-first workspace for turning literature into understanding.

Discover trusted research, capture evidence in context, reveal connections, and produce defensible synthesis—without losing the thread of your thinking.

Explore the demo · Architecture · Contributing

---

Research, without the fragmented workflow

ResearchOS Core is a full research environment for people who need more than a reference manager and more rigor than a chat window. It brings discovery, reading, annotation, deterministic analysis, graph exploration, and exports into one focused workspace—without a hosted LLM or cloud AI account.

Built around evidence. AI outputs are designed as durable, source-linked artifacts—not opaque answers detached from the research that supports them.

What you can do

	Capability	What it helps you achieve
🔎	Discover & import	Search scholarly work and build a local, source-aware paper library.
📖	Read in context	Open PDFs, track progress, create page-linked highlights, and write notes.
✦	Ask grounded questions	Use AI-assisted research conversations tied to workspace evidence.
◌	See the research graph	Explore relationships among papers, concepts, notes, and citations.
≡	Synthesize literature	Turn selected evidence into structured literature reviews.
◈	Delegate research tasks	Launch and inspect research-agent plans, steps, and artifacts.
↓	Ship results	Export citation-ready research in portable formats.

Research workflow

flowchart LR
  A["Ask a research question"] --> B["Discover papers"]
  B --> C["Import & normalize"]
  C --> D["Read PDF"]
  D --> E["Highlight evidence"]
  E --> F["Write linked notes"]
  F --> G["Ask grounded AI"]
  G --> H["Explore knowledge graph"]
  H --> I["Generate literature review"]
  I --> J["Export results"]

  classDef primary fill:#0e7490,stroke:#155e75,color:#fff;
  classDef artifact fill:#ecfeff,stroke:#0891b2,color:#164e63;
  class A,J primary;
  class B,C,D,E,F,G,H,I artifact;

Every step leaves behind reusable research artifacts. Notes retain their evidence, AI results retain their provenance, and graph connections remain explainable.

Screenshots

Landing	Workspace

Research library	Knowledge graph

Research insights	Project workspace

Reading & evidence

Demo

A full 1920×1080 product walkthrough — landing, demo workspace, library, knowledge graph, insights, projects, and the PDF reader — is available at docs/demo/researchos-demo.webm.

Regenerate the screenshots and video at any time against a running server:

npm run build && npx next start   # serve the production app on :3000
npm run demo:capture              # record docs/assets/*.png + docs/demo/researchos-demo.webm

Installation

Prerequisites

• Node.js 20 or later
• npm 10 or later

Local setup

From a fresh clone, the complete local database setup is one command:

npm run bootstrap

bootstrap installs dependencies, creates .env from .env.example when it is absent, generates Prisma Client, and applies the local SQLite migrations. It never overwrites an existing .env.

To run the required commands individually instead, no manual environment-file copy is needed:

git clone <your-repository-url>
cd researchos
npm install
npx prisma generate
npx prisma migrate dev
npm run dev

Open http://localhost:3000 to start exploring.

Environment

Configuration is validated at startup and kept server-side. npm install and all npm run startup scripts automatically create .env from the complete .env.example when it is absent. Prisma, Next.js, and the typed server configuration all read the same DATABASE_URL. Never commit .env.

Quick start

1. Open the application and choose Launch demo workspace for a guided, curated tour.
2. Search for a paper, concept, or author and import a useful source.
3. Open a paper, select text in the PDF, and save a highlight or note.
4. Search across workspace material or use the Research Explorer to retrieve cited evidence.
5. Inspect relationships in the knowledge graph, synthesize a literature review, then export your result.

Press Ctrl + K (or ⌘ + K) anywhere in the product to jump between research tools.

Architecture

ResearchOS is a modular monolith: one Next.js application with clear boundaries around the capabilities most likely to evolve—AI providers, data storage, identity, and background execution.

flowchart TB
  UI["Next.js App Router\nServer & Client Components"] --> API["Typed route handlers\nvalidation · auth · response mapping"]
  API --> SVC["Application services\nuse cases · domain policies"]
  SVC --> PORTS["Ports & contracts"]
  PORTS --> DB[("Relational data")]
  PORTS --> OBJ[("Object storage")]
  PORTS --> ANALYSIS["Offline Analysis Engine\nBM25 · LexRank · local embeddings"]
  PORTS --> JOBS["Durable jobs & workers"]

• UI stays presentational. React components do not own business rules, database access, or secrets.
• Services own application behavior. Routes validate, authorize, invoke a use case, and map a stable response.
• External dependencies live behind ports. The database, object storage, queues, and optional local model adapters can evolve without leaking through the product.
• Derived analysis artifacts are traceable. Algorithm version, input provenance, and schema version belong with durable results.

Read more in Architecture, Modules, and API design.

Offline Analysis Engine

sequenceDiagram
  participant R as Researcher
  participant W as Workspace
  participant I as Local index
  participant E as Analysis engine
  participant A as Artifact store

  R->>W: Ask a source-grounded question
  W->>I: Incrementally index workspace evidence
  I->>E: BM25 passages and local vectors
  E->>E: LexRank, keyword, graph, and metadata analytics
  E->>A: Persist output + algorithm + provenance
  A-->>R: Evidence-linked research artifact

The UI never acts as a model proxy. Requests pass through a task-oriented local analysis boundary, so source provenance and optional future local-model adapters remain consistent.

Technology stack

Layer	Technology
Application	Next.js 16, React 19, TypeScript
UI	Tailwind CSS, Framer Motion
Data	Prisma 7, SQLite for local development
Offline analysis	BM25, LexRank/TextRank-style ranking, TF-IDF, hashing embeddings
Research tooling	OpenAlex, PDF.js, Cytoscape, Graphology
Search & exports	Lunr, Fuse.js, DOCX, BibTeX, Markdown, HTML
Quality	ESLint, Prettier, strict TypeScript

Project structure

app/           Routes, layouts, and HTTP route handlers
components/    Reusable presentation components
services/      Application services, domain logic, and adapters
repositories/  Persistence implementations
lib/           Shared infrastructure: analysis, auth, graph, search, export
prisma/        Data schema and migrations
types/         Shared public TypeScript contracts
validators/    Boundary validation schemas
docs/          Architecture, module, API, and roadmap documentation

Available commands

npm run dev              # Start the local development server
npm run lint             # Run ESLint
npx tsc --noEmit         # Type-check without emitting files
npm run prisma:generate  # Generate the Prisma client
npm run prisma:migrate   # Apply local database migrations
npm run build            # Generate Prisma client and create production build

Roadmap

• Foundation: strict TypeScript, App Router, validated configuration, Prisma
• Local research flows: paper library, reading, annotations, search, graph
• Grounded research intelligence: AI-assisted research artifacts
• Production platform: managed database, storage, queue workers, observability
• Collaboration: memberships, shared collections, revisions, notifications
• Scale: semantic search and scalable graph computation

The detailed technical plan and decision gates live in docs/roadmap.md.

Contributing

Contributions are welcome. For a focused change:

1. Create a branch from the current default branch.

2. Keep business rules in services and preserve the boundaries documented in docs/.

3. Run the quality checks before opening a pull request:

   npm run lint
   npx tsc --noEmit
   npm run build
   

4. Describe the user-facing outcome and any architecture trade-offs in the pull request.

Please avoid introducing direct provider, database, or business-logic access into client components.

Built with OpenAI Codex

ResearchOS was designed and developed with OpenAI Codex acting as an AI software engineering assistant and reviewer.

Codex accelerated:

• Architecture design
• Full-stack implementation
• Component generation
• Refactoring
• Debugging
• Documentation
• Test generation
• UI iteration

GPT-5.6 and Codex were used throughout development to rapidly prototype, implement, and refine production-ready features while keeping a human-in-the-loop engineering workflow.

License

No open-source license has been declared for this repository yet. Until a license is added, all rights are reserved by the repository owner.

FAQ

It includes a paper library, but its purpose is broader: keeping sources, annotations, AI-assisted thinking, graph context, and outputs connected throughout the research process.

AI work is modeled as a source-backed artifact. The architecture records the provider/model policy, prompt version, inputs, output schema, and evidence references rather than treating an answer as untraceable text.

Yes. SQLite is intentionally appropriate for local development and single-user demos; repository boundaries are designed so production can move to managed Postgres without rewriting application services.

Open a GitHub issue in the repository, including a concise reproduction, expected behavior, and relevant screenshots or logs with sensitive information removed.

Acknowledgements

ResearchOS is built with the open-source ecosystem around Next.js, React, Prisma, Tailwind CSS, OpenAlex, Cytoscape.js, and PDF.js. Thank you to the maintainers and research communities that make ambitious, evidence-driven tools possible.

---