GEWU draws on géwù zhìzhī (格物致知) — examining sources, connecting evidence-backed ideas, and preserving reusable knowledge for project teams. It provides a shared research library accessed via a read-only web application, with contributions made exclusively through typed Model Context Protocol (MCP) proposals submitted by local workspace agents.

Architecture & Documentation

Local setup and first use: docs/GETTING_STARTED.md
Engineering Handbook: docs/README.md
Product Requirements & Scope: docs/PRD.md and docs/GOAL.md
Implementation Plan: docs/IMPLEMENTATION_PLAN.md
System Architecture: docs/architecture/ARCHITECTURE.md
Acceptance & Evidence Contract: docs/architecture/ACCEPTANCE_CONTRACT.md
Local Agent Specification: docs/architecture/LOCAL_AGENT.md
Local Agent Pack Repository: agents/gewu/README.md

GEWU Local Research Agent

GEWU ships a modular research-agent instruction pack in agents/gewu, modeled after the RESEARCH workspace agents (such as Winnow and Praxis). Rather than embedding an unverified agent engine inside the knowledge service, reasoning and tool execution run inside existing local agent hosts:

Target Hosts: Claude, Codex, Antigravity, and OpenCode. Native discovery and workflows remain unqualified.
Role Profile: agents/gewu/AGENTS.md
Claude Harness Pointer: agents/gewu/CLAUDE.md
Modular Skills:
- kb-ingest: Process selected source materials into evidence-bound node proposals.
- kb-query: Retrieve and explain accepted knowledge with exact citations and scope limits.
- kb-curate: Audit freshness, identify duplicates or contradictions, and propose corrections.
- kb-synthesize: Assemble multi-source comparative syntheses with dependency tracking.
Shared Protocols: EVIDENCE.md, SCOPE.md, CONTRIBUTIONS.md.

Setting Up a Project Directory

GEWU supports two workspace topologies:

Dedicated Research Workspace: A standalone directory focused entirely on research, ingestion, and knowledge synthesis.
Integrated User Project Directory: An existing code or engineering project where developers want on-demand access to GEWU research workflows without disturbing their primary development environment.

Workspace Directory Layout

<project-root>/
  AGENTS.md                 # Project instructions with GEWU research routing
  CLAUDE.md                 # Claude instructions with GEWU research routing
  GEMINI.md                 # Gemini context with GEWU research routing
  .agents/
    gewu/                   # Isolated GEWU pack
      AGENTS.md             # Canonical GEWU research profile
      manifest.json         # Module registry and checksum verification
      protocols/            # Shared evidence, scope and contribution protocols
      skills/               # Namespaced kb-* skills
      pipelines/            # Pipeline stage procedures
  Inbox/                    # Raw source documents targeted for ingestion
  Drafts/                   # Working notes and unaccepted local drafts
  Runs/                     # Resumption checkpoints and local run receipts

Step-by-Step Setup Instructions

1. Initialize Operational Folders

Create the standard folders for agent resources and local file boundaries:

mkdir -p <project-root>/.agents Inbox Drafts Runs

2. Install the GEWU Agent Pack

Install the pack into its isolated directory and add reversible routing pointers:

python path/to/GEWU/agents/gewu/scripts/install.py install <project-root> --mode integrated

Use --mode dedicated for a research-only workspace. Installation refuses an occupied .agents/gewu destination. The installer does not edit host MCP configuration or store credentials.

3. Configure Harness Entry Points

The installer appends marked routing blocks to root AGENTS.md, CLAUDE.md, and GEMINI.md, preserving existing instruction content. Remove them with python <pack>/scripts/install.py uninstall <project-root>; removal stops if a managed block changed.

4. Configure Local Agent Host (Claude, Codex, Antigravity, OpenCode)

Configure the selected host's project MCP entry for the authenticated Streamable HTTP endpoint, normally <service-url>/mcp. Supply the bearer token through the host's secure credential or environment mechanism; do not place a live token in checked-in config. Host-specific connection setup is not yet qualified. The local gewu-connector executable is an explicit-file upload bridge and does not provide the general GEWU tool catalog. Its upload receipt includes a typed source candidate for proposal_submit; selected paths and bytes stay inside the connector. Omitting source_revision_id derives a content-bound local revision and checkpoints it for exact retry; callers resuming an existing workflow can pass its original revision ID.

Working with Existing Agents, Skills, and Folders

When adding GEWU into a user project folder that already has active agents, skills, and configuration folders, GEWU operates with strict boundary isolation:

1. Agent Personas & Profile Routing (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`)

No Overwriting of Root Personas: An existing AGENTS.md or CLAUDE.md in the project root defines the user's primary development rules (coding conventions, architecture, testing). GEWU never overwrites this file.

Reference Routing: Add a dedicated section to your existing root AGENTS.md or CLAUDE.md directing research and knowledge queries to GEWU:

## Research & Knowledge Base (GEWU)
For knowledge base queries, source ingestion, curation, or synthesis:
- Refer to the GEWU profile in `.agents/gewu/AGENTS.md`.
- Use the `kb-*` skills located in `.agents/gewu/skills/`.

Session Preservation: The agent remains focused on software engineering by default, transitioning into research mode only when explicit knowledge tasks are requested.

2. Multi-Agent Skill Coexistence & Namespacing

Canonical Skill Directory (.agents/gewu/skills/): All GEWU skills are namespaced with the prefix kb- (kb-ingest, kb-query, kb-curate, kb-synthesize). They remain isolated from existing domain or engineering skills.
Host-Specific Skill Locations (.gemini/skills, .claude/skills, .opencode/skills): If your development environment relies on host-specific skill folders, you can symlink or copy individual kb-* skill folders into those locations. Existing skills in those folders are left completely untouched.
Self-Contained Instruction Boundaries: Each kb-* skill only references its corresponding pipeline and shared protocols; it does not depend on proprietary host runtime hooks.

3. File System & State Isolation (`Inbox/`, `Drafts/`, `Runs/`)

No Untracked Code Changes: GEWU local skills never touch application source trees, rewrite project files, or make blanket safety git commits.
Input Isolation (Inbox/): Ingestion is restricted to documents explicitly placed in Inbox/ or explicitly passed as file parameters.
Draft Isolation (Drafts/): Intermediate reading notes, candidate extractions, and unaccepted drafts remain strictly in Drafts/.
Checkpoint Isolation (Runs/): Resumption states, step hashes, and local receipts are saved in Runs/.
Durable Acceptance via MCP: Knowledge changes become canonical only through typed MCP proposal operations submitted to the GEWU service. The service verifies exact evidence locations and acceptance policies before issuing durable receipts.

4. Tool & MCP Transport Independence

The installer leaves host MCP configuration unchanged. Add a uniquely named GEWU server using the selected host's project-level configuration and verify that existing server entries remain intact.

URL capture scope

The authenticated source_capture_url tool blocks all requests unless the service operator sets GEWU_FETCH_ALLOWED_HOSTS to exact comma-separated hostnames. It rejects private or reserved DNS answers, nonstandard ports, and redirects to hosts outside that list. Archive support includes UTF-8 text, Markdown, HTML visible-text extraction and PDF text extraction on Linux when bubblewrap, Poppler pdftotext and prlimit are installed. PDF parsing runs with no network, an empty environment, read-only system mounts and resource limits. Mixed text and blank pages produce a partial extraction; image-only/scanned PDFs report PDF_NO_TEXT as unavailable. Encrypted or unsupported PDFs report explicit extraction failure codes. Capture returns a stable source identity, a content-bound revision candidate, and a typed record to submit through proposal_submit; failed captures return an unarchived bookmark candidate. Other operating systems do not yet have a qualified PDF sandbox.

Optional Jev relevance signal

The backend can call OpenRouter's Jev Decisions API when it records an ingest-review flag. Add OPENROUTER_API_KEY to the ignored .env file (.env.example is a template), then restart gewu-api. The app restricts .env permissions to the current user. It sends the project title, north star, key questions, candidate excerpt, summary and rationale to Jev for a relevance probability and research-lens suggestion. For facet labels, it also sends each agent-proposed candidate and the closest labels from that project so Jev can score fit and choose an existing label or the new_label option; Jev chooses among the candidate text supplied and does not invent label wording. The backend adds a new label to the canonical project catalog only when Jev selects new, the candidate ranks within the configured top N for its facet, and fit, new-label probability and choice confidence meet their thresholds. Defaults are tags top 5 and audience/use_for/domain top 3 each, fit >= 0.90, new-label probability >= 0.90 and confidence >= 0.80. This automation also requires the local embedding model to be installed and configured with GEWU_EMBEDDING_MODEL_PATH and its verified GEWU_EMBEDDING_MODEL_SHA256; use .env.example for optional model and threshold settings. GEWU never downloads model weights at service startup. Without Jev or embeddings, ingest and the review queue continue, but the service does not auto-add labels. Keep the key on the server and out of browser or agent configuration. See OpenRouter's Jev API guide for API and billing details.

README.md

GEWU (格物)