neo-research

neo-research

Research pipeline for Claude Code. One command turns any topic into agent expertise — without blowing your context window.

> /research "SwiftUI NavigationStack in iOS 17+ with programmatic navigation"

Research complete: swiftui-navigationstack
- Sources: 14 fetched, 12 indexed
- Expertise: ~/.claude/research/swiftui-navigationstack/expertise.md (3.2K tokens)
- Skill generated: ~/.claude/skills/swiftui-navigationstack/SKILL.md
- Deep-dive: rlm_search(query="...", project="swiftui-navigationstack")

Why this exists

We built neo-research as a Docker sandbox for running Python and testing whether a REPL-based approach to recursive language model programs could work. It worked, but the project was missing a clear purpose — a bag of tools without a workflow.

At the same time, we had a separate /research skill that was supposed to help Claude learn new topics. It was doing fetch-and-hope: search Google, grab some pages, dump them in a knowledge store, and cross your fingers.

Neither tool was solving the real problem: how do you make an AI agent actually know a topic the way a developer knows a topic? Not "I have some indexed docs I can search." Real working knowledge — the kind where you understand the mental model, know the common patterns, and can warn about the gotchas before someone hits them.

So we combined them. The sandbox REPL handles the heavy data processing (fetching, indexing, querying) without burning context tokens. The research methodology structures what to look for. The distillation step turns raw indexed content into a compact expertise artifact. The agent reads 10-15K tokens of targeted excerpts instead of 500K of raw docs.

The result is a research pipeline that vibe coders can use: /research <topic> and your agent becomes the expert. The RLM REPL theory still gets tested — the sandbox runs all the programmatic knowledge store queries during distillation. But now it has a reason to exist.

Table of Contents

• How the pipeline works
• Install
• Quick start
• What it generates
• Tools (21 total)
• Architecture
• Knowledge store
• Sandbox
• Configuration
• Contributing
• License

How the pipeline works

/research "WebTransport protocol"
         │
         ▼
  ┌─────────────────────────┐
  │ 1. Parse input           │  Topic, URLs, context — any format
  │ 2. Build question tree   │  4-7 branches: what/how/API/gotchas/...
  │ 3. Discover sources      │  Targeted search per branch, quality-ranked
  │ 4. Fetch to disk         │  curl → markdown → .mv2 (zero context cost)
  │ 5. Distill               │  Query .mv2 per branch → expertise.md
  │ 6. Generate artifacts    │  Skill and/or subagent from expertise
  └─────────────────────────┘
         │
         ▼
  Agent now knows the topic.
  Knowledge store available for deep-dives.

The input is flexible. A topic name, a paragraph of context, specific URLs, or a mix of all three. The pipeline figures out what to search for based on a question tree — not blind keyword searches.

Content never enters the agent's context window during fetch. Pages go to disk, then into a .mv2 knowledge store. The agent only reads targeted excerpts during the distillation phase.

Install

/plugin marketplace add shihwesley/shihwesley-plugins
/plugin install neo-research@shihwesley-plugins

First run creates a Python venv and installs dependencies automatically.

Docker is optional — the research pipeline and knowledge tools work without it. Sandbox execution tools need Docker.

git clone https://github.com/shihwesley/neo-research.git
cd neo-research
./scripts/setup.sh

# Start MCP server directly (stdio transport)
./scripts/start-server.sh

# Optional: build Docker sandbox image
docker compose up -d --build

Quick start

After installing, restart Claude Code. The MCP server loads with 21 tools.

Research a topic (the main workflow):

> /research fastapi

Research complete: fastapi
- Sources: 14 fetched, 12 indexed
- Expertise: ~/.claude/research/fastapi/expertise.md (4.1K tokens)
- Knowledge store: ~/.claude/research/fastapi/knowledge.mv2
- Skill generated: ~/.claude/skills/fastapi/SKILL.md

Search indexed knowledge directly:

> Use rlm_search("dependency injection") to find the pattern

Found 5 results:
  1. [0.94] tutorial/dependencies.md — "Declare the dependency..."
  2. [0.88] advanced/dependencies.md — "Sub-dependencies are resolved..."