research-wiki

Research Wiki: Persistent Research Knowledge Base

Subcommand: $ARGUMENTS

Overview

The research wiki is a persistent, per-project knowledge base that accumulates structured knowledge across the entire ARIS research lifecycle. Unlike one-off literature surveys that are used and forgotten, the wiki compounds — every paper read, idea tested, experiment run, and review received makes the wiki smarter.

Inspired by Karpathy's LLM Wiki pattern: compile knowledge once, keep it current, don't re-derive on every query.

Core Concepts

Four Entity Types

| Entity | Directory | Node ID format | What it represents | |--------|-----------|---------------|--------------------| | Paper | papers/ | paper:<slug> | A published or preprint research paper | | Idea | ideas/ | idea:<id> | A research idea (proposed, tested, or failed) | | Experiment | experiments/ | exp:<id> | A concrete experiment run with results | | Claim | claims/ | claim:<id> | A testable scientific claim with evidence status |

Typed Relationships (graph/edges.jsonl)

| Edge type | From → To | Meaning | |-----------|-----------|---------| | extends | paper → paper | Builds on prior work | | contradicts | paper → paper | Disagrees with results/claims | | addresses_gap | paper\|idea → gap | Targets a known field gap | | inspired_by | idea → paper | Idea sourced from this paper | | tested_by | idea\|claim → exp | Tested in this experiment | | supports | exp → claim\|idea | Experiment confirms claim | | invalidates | exp → claim\|idea | Experiment disproves claim | | supersedes | paper → paper | Newer work replaces older |

Edges are stored in graph/edges.jsonl only. The ## Connections section on each page is auto-generated from the graph — never hand-edit it.

Capture hygiene (anti-self-poisoning)

Before persisting an idea / claim / experiment note, screen it for operational noise that would harden into a self-cited falsehood (see [shared-references/capture-antipatterns.md](../shared-references/capture-antipatterns.md)). Resolve the helper via the canonical chain (integration-contract §2): .aris/tools/capture_filter.py → tools/capture_filter.py → $ARIS_REPO/tools/capture_filter.py (warn-and-skip if unresolved). Run python3 <capture_filter> - on the note text; if it flags env-failure / transient-error / negative-tool-claim, do NOT store it as a durable node — rewrite it to the fix / missing config / workaround, or drop it. Never store "codex/gemini/the reviewer can't do X" — that gets loaded into every future session and cited against the agent long after the real cause is gone. (The wiki's "failed ideas → anti-repeat memory" is the GOOD inverse: a class-level research finding, not operational noise.)

Wiki Directory Structure

research-wiki/
  index.md               # categorical index (auto-generated)
  log.md                 # append-only timeline
  gap_map.md             # field gaps with stable IDs (G1, G2, ...)
  query_pack.md          # compressed summary for /idea-creator (auto-generated, max 8000 chars)
  papers/
    <slug>.md            # one page per paper
  ideas/
    <idea_id>.md         # one page per idea
  experiments/
    <exp_id>.md          # one page per experiment
  claims/
    <claim_id>.md        # one page per testable claim
  graph/
    edges.jsonl          # materialized current relationship graph

Subcommands

Helper resolution (run before any subcommand below)

All wiki operations except plain directory bootstrap go through a single canonical helper, tools/research_wiki.py. Skills that touch the wiki must resolve $WIKI_SCRIPT via the chain below — never hard-code python3 tools/research_wiki.py …. Hard-coding silently fails when the project does not have tools/ on disk (the post-install_aris.sh default), which is exactly the failure mode that left a real user's research-wiki/ empty for a week.

cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
WIKI_SCRIPT=".aris/tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
[ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
[ -f "$WIKI_SCRIPT" ] || {
  echo "ERROR: research_wiki.py not found at .aris/tools/, tools/, or \$ARIS_REPO/tools/." >&2
  echo "       Fix one of:" >&2
  echo "         1. rerun 'bash tools/install_aris.sh' from the ARIS repo (creates .aris/tools symlink)" >&2
  echo "         2. export ARIS_REPO=<path-to-ARIS-repo>" >&2
  echo "         3. cp <ARIS-repo>/tools/research_wiki.py tools/" >&2
  exit 1
}

/research-wiki itself is the wiki tool — if the helper is missing the skill hard-fails. Caller skills that update the wiki as a side effect (/idea-creator, /result-to-claim, /research-lit, /arxiv, /alphaxiv, /deepxiv, /semantic-scholar, /exa-search) use the same chain but warn-and-skip instead of hard-failing — their primary output (idea list, claim verdict, paper summary) must still be delivered to the user.

/research-wiki init

Initialize the wiki for the current project. After resolving $WIKI_SCRIPT per the chain above:

python3 "$WIKI_SCRIPT" init research-wiki/

The helper creates research-wiki/{papers,ideas,experiments,claims,graph}/ plus index.md, log.md, gap_map.md, query_pack.md, and graph/edges.jsonl, then appends "Wiki initialized" to log.md.

(Earlier versions of this skill described a prose-only init that omitted query_pack.md — that drifted from the helper and made /idea-creator's Phase 0 query-pack check fall through to a rebuild_query_pack invocation that, under the old hard-coded path, silently failed. Delegating init to the helper is the single source of truth for the wiki schema.)

/research-wiki ingest "<paper title>" — arxiv: <id>

Add a paper to the wiki. This subcommand is thin wrapping around python3 "$WIKI_SCRIPT" ingest_paper …, which is the single implementation of paper ingest in ARIS (per [shared-references/integration-contract.md](../shared-references/integration-contract.md) — one helper, no copies). The helper does all of:

1. Fetch metadata — queries the arXiv Atom API when --arxiv-id is given
2. Generate slug — <first_author_last_name><year>_<keyword>
3. Check dedup — skip an existing page unless --update-on-exist
4. Create page — papers/<slug>.md with the schema below
5. Rebuild index.md and query_pack.md
6. Append log.md

Edge extraction (step 5/8 in the old manual flow) is not in ingest_paper; do it as a follow-up with add_edge per relationship identified:

# arXiv-known paper
python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
    --arxiv-id 2501.12345 --thesis "One-line claim from abstract."

# Venue paper with no arXiv mirror
python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
    --title "Attention Is All You Need" \
    --authors "Ashish Vaswani, Noam Shazeer, …" --year 2017 --venue "NeurIPS"

# Manual edge after ingest
python3 "$WIKI_SCRIPT" add_edge research-wiki/ \
    --from "paper:vaswani2017_attention_all_you" \
    --to "paper:chen2025_factorized_gap" \
    --type "extends" --evidence "Section 3.2: adapts the encoder block …"

Other skills (/research-lit, /arxiv, /alphaxiv, /deepxiv, /semantic-scholar, /exa-search) call the same helper directly in their own last step — they don't re-route through /research-wiki ingest as a subcommand, so they don't need an LLM roundtrip.

/research-wiki sync — arxiv-ids <id1>,<id2>,...

Batch backfill: ingest one or more arXiv IDs that were read earlier without being ingested (e.g., because research-wiki/ was set up after the reading happened,