A Research Assistant System for PhDs and Researchers — Beginner Guide

Who is this for? You're a PhD student, early-career faculty, or researcher juggling dozens of projects scattered across folders; you keep searching "when was that grant deadline again?"; and although you use Claude Code/ChatGPT, you find yourself re-explaining the same context every session. This guide is for you.

End state: every project, methodology, student, and grant lives in a single searchable knowledge graph. The AI auto-records what you do every session. New information triggers automatic graph updates.

Why bother?

Your current setup probably looks like this:

Left: PDFs, docx, and PNGs scattered across the desktop. 16 project folders. "Where did I write down that method explanation?" — daily search.

Right: every project organized as a vault entity page. An automated tracker processes new notes. Asking the AI "Tell me about Project X" yields full context in one line.

Follow this guide to the end and you reach the right side. 1-2 hours per day for 7 days.

0. Glossary — 7 terms used throughout

0.5. AI Agents — Claude Code vs Codex

This system uses two AI coding agents complementarily. Both are LLM-backed, but what each does best and how you control them differ.

Two agents, two roles

Claude Code (Anthropic) — primary engineering agent - Deep vault integration: Stop hooks for auto-session-recording, slash commands like /slides and /recall - Long context window (200K-1M tokens) — can pull your whole vault into context - Strengths: multi-step reasoning, careful file edits, vault navigation - Where: directly reads/writes every file in the vault

Codex (OpenAI) — secondary engineering agent - Sessions stored at ~/.codex/sessions/ (rollout JSONL). No Stop hook — manual pwsh codex_digest.ps1 after each session - Strengths: fast code generation, image generation, reasoning-mode - Where: green-field code, cross-checking when Claude is stuck, prototypes

When to use which

CLI control — the 5 essentials

(1) Where to run for auto-context

cd C:\Users\<you>\ObsidianVault
claude                              # Claude Code CLI
# or
codex                               # Codex CLI

Both agents walk up the parent chain looking for: - Claude Code: CLAUDE.md - Codex: AGENTS.md

So opening either inside your vault means "tell me about project X" gets answered immediately.

(2) Hook registration — Claude Code only

~\.claude\settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "command",
          "command": "powershell.exe -File <vault>\\scripts\\save_session.ps1 -Source claude"
        }]
      }
    ]
  }
}

Available events: Stop, SessionStart, PostToolUse, PreToolUse, UserPromptSubmit. We only use Stop.

(3) Slash Commands — Claude Code only

Create ~\.claude\commands\<name>.md and call as /<name> <args>. Example: /slides ProjectA.

(4) Memory — Claude Code's auto-context

~\.claude\projects\<machine>\memory\MEMORY.md is auto-injected at every session start.

(5) Codex post-session digest — three approaches

Method A — manual: pwsh C:\Users\<you>\ObsidianVault\scripts\codex_digest.ps1

Method B — shell wrapper:

function cdx {
  codex @args
  pwsh "$env:USERPROFILE\ObsidianVault\scripts\codex_digest.ps1"
}

Method C — Codex automation:

# ~/.codex/automations/vault-digest/automation.toml
version = 1
id = "vault-digest"
kind = "cron"
prompt = "Run: pwsh C:\\Users\\<you>\\ObsidianVault\\scripts\\codex_digest.ps1"
status = "ACTIVE"
rrule = "FREQ=HOURLY;INTERVAL=2"

Desktop app differences

Claude Desktop: no hooks, has MCP, no slash commands. Recommended for quick chat. Codex Desktop: no hooks, IDE-integrated. Recommended for in-IDE coding.

1. The core idea — a 3-layer second brain

Layer 1 — Project knowledge (wiki/entities/, wiki/concepts/): notes you write yourself. Permanent asset.

Layer 2 — Activity log (wiki/activity/, wiki/situation/, wiki/sources/Sessions YYYY-MM-DD.md): auto-generated daily snapshots.

Layer 3 — AI memory (~/.claude/projects/<machine>/memory/): small files Claude Code auto-loads at session start.

2. Automation flow — "what happens every 2 hours"

A Windows scheduled task (or macOS launchd, Linux cron) runs every 2 hours. The script:

1. Scans newly added / modified files
2. Collects side-channel signals: git, GitHub, calendar
3. Sends note changes to an LLM that judges "what changed"
4. Rebuilds the ontology graph
5. Aggregates results into Today.md

Cost: ~$0.001-0.005 per run. 12 runs/day = $0.02-0.05/day = $1-2/month.

3. Prerequisites

Required from Day 1:

• [ ] Obsidian (obsidian.md, free)
• [ ] Claude Code (claude.com/claude-code)
• [ ] Python 3.11+
• [ ] Basic terminal skills

Required from Day 4 onward: - [ ] OpenRouter API key (openrouter.ai, $5 lasts months) - [ ] gh CLI (cli.github.com) — optional

3.5. CLI Installation — Claude Code & Codex

Claude Code (Anthropic) — primary agent

Prerequisites: Anthropic subscription · Node.js 18+

Windows: download the .exe from https://claude.com/claude-code → install → claude --version → claude (browser auth opens)

Or via npm:

npm install -g @anthropic-ai/claude-code

macOS:

brew install --cask claude-code
# or
npm install -g @anthropic-ai/claude-code

Linux: npm install -g @anthropic-ai/claude-code

First-run auth: claude → browser auto-opens for Anthropic login → token saved to ~/.claude/auth.json.

claude /help          # available slash commands
claude /status        # current model / auth / context

Codex (OpenAI) — secondary agent (optional)

Prerequisites: ChatGPT subscription · Node.js 18+

Windows: https://chatgpt.com/codex installer or npm install -g @openai/codex macOS: brew install codex or npm Linux: npm install -g @openai/codex

First-run auth: codex → browser → OpenAI login → token saved to ~/.codex/auth.json.

Both CLIs together

cd C:\Users\<you>\ObsidianVault
claude     # primary
codex      # secondary (optional)

My OS is Windows / macOS / Linux. Help me install Codex CLI through to first-run auth.

1. Verify Node.js 18+
2. npm install -g @openai/codex (or OS-recommended)
3. codex --version
4. codex → browser login

Then create ~/.codex/AGENTS.md with one line:
"My vault is at C:\Users\\ObsidianVault\. Always read wiki/Today.md before starting any work."

Troubleshooting

Day 1 — Create your vault

Today's goal: create an empty Obsidian vault and hand-write an entity page for your most active project. No automation yet.

Step 1.1 — Create the vault

Launch Obsidian → "Create new vault" → name ResearchVault, location C:\Users\<you>\ObsidianVault\.

Step 1.2 — Folder structure

ObsidianVault/
└── wiki/
    ├── entities/        ← one page per project / person / grant
    ├── concepts/        ← one page per method / theory
    ├── sources/         ← raw documents / digests / session logs
    └── (activity/, situation/ are auto-created later)

Create a wiki/ folder inside `C:\Users\\ObsidianVault\` with three subfolders: entities/, concepts/, sources/. Put a one-line README.md in each explaining what it holds.

Step 1.3 — Your first entity page

Pick your most active project. Example uses fictional Project A:

---
type: project
title: "Project A"
status: active
tier: 2
deadline: 2026-08-15
related:
  - "<span class="wikilink">&lt;my name&gt;</span>"
  - "<span class="wikilink">Method A</span>"
---

# Project A

(One-sentence project description.)

- **PI**: <span class="wikilink">&lt;my name&gt;</span>
- **Methods**: <span class="wikilink">Method A</span>, <span class="wikilink">Method B</span>
- **Status**: pilot N participants in progress, external grant X under review.

## Open issues
- Core component accuracy at X% — needs more validation.

My most active project is [PROJECT NAME]. Build wiki/entities/[PROJECT NAME].md following the Day 1 step 1.3 template:
- frontmatter: type: project, status: active, tier: 2, deadline: [YYYY-MM-DD]
- related: my name + 1-2 frequently used methods (as wikilinks)

Body: one-sentence description, PI / Methods / Status bullets, ## Open issues section.

Step 1.4 — Repeat for one or two more

Add an advisee, a frequently-used method, an in-progress grant. At least 3-4 entities for the next-day automation to have a meaningful graph.

Day 2 — Today.md (single entry point)

Today's goal: build the one page you read every day.

Step 2.1 — Create wiki/Today.md

---
type: meta
title: "Today — Single Entry Point"
---

# Today — Single Entry Point

> **Always start here.** Read first every session.

## 1. Where to ask what

| If you need… | Look here |
|---|---|
| **"My project X — design / theory / methods"** | `wiki/entities/<X>.md` |
| **"Who advises whom; grants where I'm PI"** | <span class="wikilink">&lt;my name&gt;</span> |
| **"Methodology"** | `wiki/concepts/` |
| **"What do I need to do today?"** | This page § 2-3 |

## 2. Active deadlines

| Deadline | Item | D- |
|---|---|---|
| YYYY-MM-DD | <span class="wikilink">Grant Name</span> submission | D-XX |

## 3. Active project priorities

### Tier 1 — Submit-imminent
- <span class="wikilink">Project A</span> — one-line status

### Tier 2 — Active development
- <span class="wikilink">Project B</span> — one-line status

### Tier 3 — Backlog
- <span class="wikilink">Project C</span>

## 4. Recent activity (auto-updated)
<!-- BEGIN AUTO RECENT -->
(filled automatically on Day 4)
<!-- END AUTO RECENT -->

## 5. Quick commands
(added Day 4-7)

Build wiki/Today.md from the Day 2 template. Fill § 2 and § 3:
- Deadline: [grant name] [YYYY-MM-DD]
- Tier 1: [project nearing deadline]
- Tier 2: [1-3 active-development projects]
- Tier 3: [backlog projects]

Leave BEGIN/END AUTO RECENT markers in § 4 alone — Day 4 fills those. Then walk me through Pinning Today.md in Obsidian.

Step 2.2 — Pin in Obsidian

Right-click Today.md → "Pin".

Day 3 — Connect Claude Code + auto session log

Step 3.1 — User-level CLAUDE.md

Create C:\Users\<you>\CLAUDE.md:

# User-level Claude Code instructions

## On every session start
1. Read `C:\Users\<you>\ObsidianVault\wiki\Today.md` first.
2. Auto-memory at `~\.claude\projects\<machine>\memory\MEMORY.md` is auto-injected.
3. Prefer existing vault content over reasoning from scratch.

## Knowledge locations
| Question type | Where |
|---|---|
| Project design / methods / status | `wiki/entities/<project>.md` |
| Methodology / theory | `wiki/concepts/` |
| Recent activity | `wiki/activity/<date>.md` |

## User style
- Reply in English (or Korean — user is bilingual).
- Short and direct.

Create `C:\Users\\CLAUDE.md` from the Day 3 step 3.1 template:
- "On every session start" section
- "Knowledge locations" table
- "User style" (concise, direct)

My vault path: C:\Users\\ObsidianVault\

Step 3.2 — Register the session-recording hook

~\.claude\settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"C:\\Users\\<you>\\ObsidianVault\\scripts\\save_session.ps1\" -Source claude"
          }
        ]
      }
    ]
  }
}

Step 3.3 — Minimal save_session.ps1

$VaultRoot = 'C:\Users\<you>\ObsidianVault'
$LogFile   = Join-Path $VaultRoot 'wiki\log.md'

$stdin = [Console]::In.ReadToEnd()
$session = if ($stdin) { $stdin | ConvertFrom-Json } else { @{} }
$sid = if ($session.session_id) { $session.session_id.Substring(0, 8) } else { '--------' }

$stamp = (Get-Date).ToString('yyyy-MM-dd HH:mm')
$line  = "- $stamp [claude $sid] session ended"

if (-not (Test-Path $LogFile)) { New-Item $LogFile -ItemType File -Force | Out-Null }
Add-Content -Path $LogFile -Value $line -Encoding UTF8

Set up Day 3 steps 3.2-3.3:

1. Add a Stop hook in `~\.claude\settings.json` (create if missing). Command:
   powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Users\\ObsidianVault\scripts\save_session.ps1 -Source claude

2. Create `C:\Users\\ObsidianVault\scripts\save_session.ps1`. Behavior:
   - Read JSON on stdin from the Stop hook
   - Append "- YYYY-MM-DD HH:mm [claude SID8] session ended" to wiki\log.md

Watch out for Windows backslash escaping in JSON.

Step 3.4 — Verify

Open a Claude session, ask about your project, end the session. wiki/log.md should have a new line.

Day 4 — The every-2-hour automated tracker

Step 4.1 — daily_tracker.ps1

$VaultRoot = 'C:\Users\<you>\ObsidianVault'
$ActivityDir = Join-Path $VaultRoot 'wiki\activity'
$today = (Get-Date).ToString('yyyy-MM-dd')
$note  = Join-Path $ActivityDir "$today.md"

if (-not (Test-Path $ActivityDir)) { New-Item -ItemType Directory $ActivityDir -Force | Out-Null }

$lines = @("# Activity $today", "")
$cutoff = (Get-Date).AddHours(-24)
$recent = Get-ChildItem -Path "$VaultRoot\wiki" -Recurse -File -Include *.md |
    Where-Object { $_.LastWriteTime -gt $cutoff } |
    Sort-Object LastWriteTime -Descending | Select-Object -First 30

$lines += "## File activity (last 24h)"
foreach ($f in $recent) {
    $rel = $f.FullName.Replace($VaultRoot, '').Replace('\','/')
    $lines += "- $($f.LastWriteTime.ToString('HH:mm')) ``$rel``"
}

Set-Content -Path $note -Value ($lines -join "`r`n") -Encoding UTF8
Write-Output "Wrote $note"

Step 4.2 — Register the Windows scheduled task

Method A — natural language to Claude Code/Codex CLI (recommended):

Register a Windows scheduled task "ResearchAssistantTracker" with:
- Daily start at 00:00 → repeat every 120 minutes → 23:59 duration (12 fires/day)
- Command: powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Users\\ObsidianVault\scripts\daily_tracker.ps1
- Extras: StartWhenAvailable=true, DisallowStartIfOnBatteries=false, StopIfGoingOnBatteries=false

Use schtasks.exe + Get-ScheduledTask + Set-ScheduledTask. After registering, show next-fire time.

Method B — direct (raw):

schtasks.exe /Create /TN "ResearchAssistantTracker" `
  /SC DAILY /ST 00:00 /RI 120 /DU 23:59 `
  /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File C:\Users\<you>\ObsidianVault\scripts\daily_tracker.ps1" /F

12 fires/day (00, 02, 04, ..., 22).

Step 4.3 — Catch-up after computer was off

$task = Get-ScheduledTask -TaskName ResearchAssistantTracker
$task.Settings.StartWhenAvailable = $true
$task.Settings.DisallowStartIfOnBatteries = $false
Set-ScheduledTask -TaskName ResearchAssistantTracker -Settings $task.Settings

Step 4.4 — Run once now

powershell.exe -File C:\Users\<you>\ObsidianVault\scripts\daily_tracker.ps1

Day 5 — Ontology

5.0 — What's an ontology and why bother?

Just remember two tables:

(1) Types:

(2) Relations:

5.0.1 — How auto-extraction works

build_ontology.py runs every 2 hours and:

1. Reads every wiki/**/*.md, parses type: frontmatter
2. Extracts every <span class="wikilink">wikilink</span> in body
3. Cue-word matching ±100 chars (e.g., "funded by" → fundedBy)
4. Type-domain enforcement (auto-orient direction)
5. Outputs JSON-LD

Step 5.1-5.5

Pull the full build_ontology.py from the guide (https://educatian.github.io/research-assistant-ai-workflow-en/) into my vault scripts/. Then:

1. Run python build_ontology.py once → confirm wiki/_ontology.json + _ontology_summary.md + _ontology_graph.html appear
2. Append `& python "$VaultRoot\scripts\build_ontology.py"` to daily_tracker.ps1
3. Open _ontology_graph.html and visually confirm

My vault: C:\Users\\ObsidianVault\

python C:\Users\<you>\ObsidianVault\scripts\build_ontology.py
# → wiki/_ontology.json + _ontology_graph.html

# Add to tracker
# (append to daily_tracker.ps1)
& python "$VaultRoot\scripts\build_ontology.py"

# Query
python scripts\query_ontology.py "Project A"
python scripts\query_ontology.py --type Grant
python scripts\query_ontology.py --predicate hasPI

Day 6 — LLM detects changes in your notes

Step 6.1 — OpenRouter API key

Sign up → top up $5 → save key:

C:\Users\<you>\Desktop\_secrets\openrouter.txt

Help me set up Day 6 situation_watch:

1. Save my OpenRouter API key in C:\Users\\Desktop\_secrets\openrouter.txt (NEVER inside vault)
2. Pull situation_watch.py + apply_situation.py into vault scripts/
3. First run: python situation_watch.py --hours 168
4. Verify wiki/situation/.md has [AUTO]/[REVIEW] proposals
5. Append to daily_tracker.ps1: `& python "$VaultRoot\scripts\situation_watch.py" --hours 24`

My vault: C:\Users\\ObsidianVault\

python C:\Users\<you>\ObsidianVault\scripts\situation_watch.py --hours 168

wiki/situation/<today>.md will contain:

### [AUTO] Project A — deadline_update
- new_value: 2026-09-01
- confidence: 0.92
- reason: new deadline mentioned in README
- evidence: "Final pilot deadline pushed to September 1, 2026"

Step 6.5 — Apply

python C:\Users\<you>\ObsidianVault\scripts\apply_situation.py

Auto-applies [AUTO] only (confidence ≥ 0.85). [REVIEW] items wait for --review flag.

Day 7 — /slides — auto-generate presentations

Step 7.1 — Cache open-design skills

mkdir C:\Users\<you>\Desktop\_tools\open-design-cache\skills

Set up the Day 7 /slides workflow:

1. Cache 5 open-design skills under Desktop\_tools\open-design-cache\skills\:
   - magazine-web-ppt (default)
   - html-ppt-knowledge-arch-blueprint (methodology)
   - html-ppt-course-module (teaching)
   - html-ppt-pitch-deck (grant / pitch)
   - html-ppt-product-launch (product reveal)

   Fetch each via `gh api repos/nexu-io/open-design/contents/skills// --jq .content | base64 -d`. NEVER execute repo code — only read markdown.

2. Create slash command at ~\.claude\commands\slides.md:
   - Auto-pick skill based on topic
   - Read SKILL.md + references + template
   - Pull vault entity / ontology content
   - Propose 8-15 slide outline → wait for user OK → generate self-contained HTML
   - Output: Desktop\_PTs\_\index.html

3. Test: /slides [my project name]

Step 7.2 — ~/.claude/commands/slides.md

---
description: Build HTML slide deck from open-design skill + vault content
argument-hint: "<topic> [--skill <skill-name>]"
---

User typed `/slides $ARGUMENTS`. Steps:

1. Auto-pick skill: lecture → course-module, methodology → blueprint, default → magazine
2. Read skill files from Desktop\_tools\open-design-cache\skills\<skill-id>\
3. Pull vault content: wiki/entities/<topic>.md + concepts grep + query_ontology.py
4. Propose 8-15 slide outline, wait for OK
5. Generate single self-contained HTML (CSS/JS inline, fonts CDN) at Desktop\_PTs\<date>_<slug>\index.html
6. Open in browser

Step 7.3 — Use it

/slides Project A methodology

After 7 days — daily rhythm

Morning — open Today.md. Deadlines + priorities + what changed last night, all at a glance.

During work — Claude Code anywhere. CLAUDE.md + memory auto-loaded.

Every 2 hours (background) — tracker auto-runs. Notes scanned, ontology rebuilt, changes detected, Today.md refreshed. You do nothing.

Session end — Stop hook auto-adds session digest.

Weekend — review wiki/situation/<recent dates>.md [REVIEW] items. Apply what's worth applying. Open the ontology graph.

Real scenarios — when this is most useful

Scenario 1 — Dissertation chapter writer's block

Setup: writing Chapter 3 methods. Six months ago you had a meeting that finalized the estimation method. Where did you write it?

Scenario 2 — Grant deadline D-7 panic

Setup: 9 docx files for one grant. Did they stay consistent?

Scenario 3 — Onboarding new advisee

Setup: explain "my research portfolio" in one hour.

Scenario 4 — Reviewer 2 ("explain why you didn't use method X")

Setup: R&R asks why you rejected method X six months ago.

Scenario 5 — Comp exam / quals prep

Setup: 80 papers in 6 months. Need the citation network.

Common pitfalls (troubleshooting)

Customizing — log every change as a note

Every number/threshold/keyword is designed to be customized. As complexity grows, document each change:

wiki/sources/
├── My Tracker Setup.md          ← cadence / start time
├── My LLM Tuning.md              ← model / threshold / keywords
├── My Ontology Customization.md  ← types/relations
├── My Hook Setup.md              ← hook events
└── My Custom Skills.md           ← slash commands / slide skills

Each note: type: source + tags: [tuning, customization] + timestamp. Day 5 ontology auto-picks them up — python query_ontology.py "tuning" answers "how has my system evolved?".

Core principles

1. A single entry point eliminates search — Today.md instead of "where did I write that".
2. Memory beats prompt engineering — ~/.claude/projects/<machine>/memory/ instead of re-explaining.
3. Ontology beats flat tags — "all grants where I'm PI" in one CLI line.
4. LLM at the edges only — orchestrator is plain Python/PowerShell.
5. Auto-apply is conservative — every LLM proposal has confidence + [REVIEW] fallback.
6. Every action must be reversible — undo, audit logs, regeneratable graph.