Skip to main content
Glama

Scholar Agent

Python 3.10+ License: MIT MCP Ready

中文

범용 LLM은 전문 분야에서 부정확하거나 구식인 경우가 많습니다. Scholar Agent는 온라인 조사 + 로컬 지식 축적을 결합하여 지속 가능한 지식 플라이휠을 구축함으로써, 시간이 지남에 따라 귀하의 도메인에서 AI를 더욱 스마트하게 만듭니다. 또한 빠른 학습을 위해 사람이 읽을 수 있는 지식 베이스를 구축합니다. MCP를 통해 Claude Code 및 VS Code Copilot과 원활하게 통합됩니다.

주요 기능

Your question
    │
    ▼
Online research (LLM web search + academic APIs)
    │
    ▼
Structured synthesis (with citations, confidence, uncertainty)
    │
    ▼
Local accumulation (Markdown knowledge cards + BM25 index)
    │
    ▼
Next question: AI checks local first ── hit? ──► use directly, fast & accurate
    │ miss
    ▼
Research again → accumulate → reindex ──► knowledge base keeps growing

각 라운드는 복합적으로 작용합니다. 지식 카드는 초안 → 검토됨 → 신뢰됨 → 오래됨 → 폐기됨의 전체 수명 주기 관리를 거칩니다.

Related MCP server: codememory

학술 연구 파이프라인

Scholar Agent에는 포괄적인 학술 논문 연구 파이프라인이 포함되어 있습니다:

  • 논문 검색 — arXiv, DBLP, Semantic Scholar에서 논문을 검색합니다. 주요 학회(CVPR, ICCV, ECCV, ICLR, AAAI, NeurIPS, ICML, ACL, EMNLP, MICCAI)별로 필터링합니다.

  • 스마트 스코어링 — 4차원 스코어링 엔진(관련성, 최신성, 인기도, 품질)이 귀하의 연구 관심사에 따라 논문 순위를 매깁니다.

  • 심층 분석 노트 — AI 보조 완성을 위한 <!-- LLM: --> 플레이스홀더가 포함된 20개 이상의 섹션으로 구성된 Obsidian 스타일의 마크다운 노트를 자동 생성합니다.

  • 그림 추출 — arXiv 소스 아카이브 및 PDF에서 이미지를 추출합니다(PyMuPDF 사용).

  • 일일 추천 — 자동화된 일일 논문 검색, 스코어링, 중복 제거 및 추천 노트 생성.

  • 논문 → 지식 카드 — 논문 분석을 지식 플라이휠에 다시 공급되는 지식 카드로 변환합니다.

  • 키워드 자동 연결 — 노트를 스캔하여 기술 용어를 찾고 자동으로 [[wiki-links]]를 생성합니다.

빠른 시작

기존 프로젝트에 포함하기

cd my-project && git clone https://github.com/zfy465914233/scholar-agent.git
bash scholar-agent/setup.sh
# Restart Claude Code to activate

이 명령은 디렉토리 구조를 생성하고, 설정 템플릿을 복사하며, 스킬을 설치하고, 지식 인덱스를 빌드합니다.

독립형 프로젝트로 사용하기

# Clone and install
git clone https://github.com/zfy465914233/scholar-agent.git
cd scholar-agent
pip install -r requirements.txt

# Build the knowledge index
python scripts/local_index.py --output indexes/local/index.json

MCP 설정은 미리 구성되어 있습니다:

  • Claude Code: .mcp.json이 준비되어 있습니다. 프로젝트 디렉토리로 cd한 후 Claude Code를 시작하세요.

  • VS Code Copilot: .vscode/mcp.json이 준비되어 있습니다. 프로젝트를 열고 에이전트 모드를 활성화하세요.

MCP 도구

핵심 도구 (항상 사용 가능)

도구

설명

query_knowledge

로컬 지식 베이스 검색

save_research

구조화된 연구 결과를 지식 카드로 저장

list_knowledge

모든 지식 카드 탐색

capture_answer

Q&A 쌍을 초안 카드로 빠르게 캡처

ingest_source

URL 또는 원시 텍스트를 지식 베이스로 수집

build_graph

대화형 지식 그래프 생성 (vis.js)

학술 도구 (SCHOLAR_ACADEMIC=1 설정 시 활성화)

도구

설명

search_papers

4차원 스코어링을 사용하여 arXiv + Semantic Scholar 검색

search_conf_papers

DBLP + S2 보강을 통해 학회 논문 검색

analyze_paper

심층 분석 마크다운 노트 생성 (20개 이상의 섹션)

extract_paper_images

arXiv 소스 / PDF에서 그림 추출

paper_to_card

논문 분석을 지식 카드로 변환

daily_recommend

일일 논문 추천 워크플로우

link_paper_keywords

노트 내 키워드를 [[wikilinks]]로 자동 연결

권장 워크플로우

최상의 분석 품질을 위해 다음 순서를 따르세요:

  1. 논문 다운로드: download_paper("2510.24701", title="Paper Title", domain="LLM")

  2. 그림 추출: extract_paper_images("2510.24701") (로컬 PDF 자동 감지)

  3. 심층 분석: analyze_paper(paper_json) (로컬 PDF 자동 감지 및 전체 텍스트 추출)

팁: 분석 전에 PDF를 다운로드하면 전체 텍스트 추출이 가능하여 특정 데이터, 공식, 실험 결과가 포함된 고품질 노트를 생성할 수 있습니다. 로컬 PDF가 없으면 분석은 초록에만 의존합니다.

설정

.scholar.json

.scholar.json 파일은 지식 경로와 학술 연구 설정을 구성합니다. 주석이 포함된 전체 예제는 .scholar.example.json을 참조하세요.

주요 섹션:

  • knowledge_dir — 지식 카드 디렉토리 경로

  • index_path — BM25 검색 인덱스 경로

  • academic.research_interests — 귀하의 연구 도메인, 키워드 및 arXiv 카테고리

  • academic.scoring — 논문 스코어링 가중치 및 차원

환경 변수

.env.example을 .env로 복사하고 구성하세요:

변수

필수

설명

SCHOLAR_ACADEMIC

아니오

학술 도구를 활성화하려면 1로 설정

S2_API_KEY

아니오

Semantic Scholar API 키 (무료 발급)

LLM_API_KEY

아니오

고급 합성 파이프라인을 위한 LLM API 키

프로젝트 구조

scholar-agent/
├── mcp_server.py              # MCP server (13 tools)
├── setup_mcp.py               # Embed into existing projects
├── pyproject.toml             # Package configuration
├── .scholar.json               # Project & academic configuration
├── schemas/                   # Answer + evidence JSON schemas
├── scripts/
│   ├── academic/              # Academic research modules
│   │   ├── arxiv_search.py    # arXiv + Semantic Scholar search
│   │   ├── conf_search.py     # Conference paper search (DBLP)
│   │   ├── paper_analyzer.py  # Deep-analysis note generation
│   │   ├── scoring.py         # 4-dim paper scoring engine
│   │   ├── image_extractor.py # Figure extraction from PDFs
│   │   ├── note_linker.py     # Wiki-link discovery + keyword linking
│   │   └── daily_workflow.py  # Daily recommendation pipeline
│   ├── scholar_config.py       # Configuration reader
│   ├── local_index.py         # BM25 index builder
│   ├── local_retrieve.py      # Knowledge retrieval
│   ├── close_knowledge_loop.py # Knowledge card builder
│   └── ...                    # Research, synthesis, governance, graph
├── knowledge/                 # Knowledge cards (gitignored, user-generated)
├── indexes/                   # Generated indexes (gitignored)
└── tests/                     # 247 tests

추가 기능

  • 다각적 연구 — 5가지 관점(학술적, 기술적, 응용적, 역발상적, 역사적)에서 병렬 연구 수행

  • Obsidian 호환 — 표준 마크다운 + YAML 프런트매터 + [[wiki-links]]

  • 지식 거버넌스 CLI — 프런트매터 검증, 고아 카드 감지, 중복 찾기, 수명 주기 관리

  • 공급자 내결함성 — 각 검색 소스는 독립적으로 실패하며, 오프라인 시 로컬 검색으로 대체

테스트

python -m pytest tests/ -v

247개 테스트, 약 13초 소요. 외부 서비스가 필요하지 않습니다.

라이선스

MIT — LICENSE를 참조하세요.

Available Tools

12 tools
build_graphA

Build an interactive knowledge graph visualization.

Generates a self-contained HTML file showing all knowledge cards as nodes and their wiki-links as edges. Open the output file in a browser to explore the knowledge graph visually. Compatible with Obsidian vaults.

Returns the path to the generated graph.html file.

Inputs: no named parameters. Returns: result

capture_answerA

Capture a useful Q&A answer as a draft knowledge card.

Use this ONLY when a conversation produces a SUBSTANTIVE answer that is worth persisting — meaning it provides genuine technical insight, a non-obvious explanation, or actionable knowledge that cannot be found in standard references.

DO NOT use this tool for:

  • Single-sentence answers or brief definitions

  • Answers that could be found in any standard reference (Wikipedia, docs)

  • Trivial facts, simple yes/no responses, or content shorter than 150 characters

  • Paper or topic-level knowledge that requires source verification

If you have structured evidence and claims, prefer save_research instead — it produces higher-quality cards with proper source attribution.

The answer text MUST be at least 150 characters. Write a thorough explanation covering the key insight, context, and practical implications.

Inputs: query (required), answer (required), tags, language. Returns: result

fetch_urlA

Fetch a web URL and return its main content as markdown — first-hand retrieval (G5).

抓取网页正文(已做 HTML→正文提取)返回给调用方,用于在 save_research 之前把 knowledge card 建立在一手出处之上,而非凭记忆或摘要。同时把完整正文存本地 快照 knowledge/_snapshots/<sha1(url)>.md(含 captured_at),防止原链接失效 (招聘 JD、网页易下架)后无法回溯(G2)。

典型用法:fetch_url 抓一手 → 基于正文写带具体数字/机制的深度 answer → save_research 存卡。

Inputs: url (required), max_chars. Returns: result

import_paperpulse_noteA

Import a distilled paper note from PaperPulse SaaS directly into the local Scholar Agent knowledge base.

Inputs: paper_id (required), api_token. Returns: result

ingest_sourceA

Ingest a URL or raw text into the knowledge base as a draft card.

For URLs: fetches the page content, extracts text, and saves as a card. For text: saves the provided text directly as a card.

Use this when you want to add external documents, articles, or notes to the knowledge base without requiring structured JSON.

Inputs: source (required), tags, title, language. Returns: result

lint_knowledgeA

Run read-only content health checks over the local knowledge base.

Reports orphan cards, broken wiki-links, cards not updated within stale_days, and highly overlapping titles. This tool never edits files.

Inputs: stale_days. Returns: result

list_knowledgeA

List all knowledge cards in the local knowledge base.

Returns card metadata (id, title, topic, type) for browsing and discovery.

Inputs: topic. Returns: result

query_knowledgeA

Search the local knowledge base for relevant information.

Returns top-k knowledge cards matching the query, with scores and content. Use this to find existing knowledge before doing web research.

Inputs: query (required), limit, rerank. Returns: result

save_researchA

Save structured research results as a knowledge card in the local knowledge base.

The answer_json must conform to schemas/answer.schema.json: { "answer": "detailed answer text", "supporting_claims": [{"claim": "...", "evidence_ids": ["..."], "confidence": "high|medium|low"}], "inferences": ["..."], "uncertainty": ["..."], "missing_evidence": ["..."], "suggested_next_steps": ["..."], "sources": ["https://example.com/source1", "https://example.com/source2"], "visual_aids": [{"type": "mermaid|image_url|image_path", "content": "...", "caption": "...", "alt_text": "..."}] }

IMPORTANT quality requirements:

  • The "answer" field MUST be at least 200 characters of substantive content.

  • You MUST include at least 1 supporting_claim with evidence_ids and confidence.

  • Each claim text MUST be at least 20 characters — vague one-word claims are rejected.

  • DO NOT create cards with empty supporting_claims — every card needs evidence-backed claims.

  • Aim for 3+ supporting claims, inferences, uncertainty, and suggested_next_steps for high-quality cards.

  • DO NOT use this tool for trivial facts or one-sentence answers — those are not worth persisting.

  • ALWAYS include a "sources" array with the URLs you referenced during research. These are written to the card's frontmatter source_refs for provenance tracking.

  • evidence_ids in supporting_claims SHOULD cite the source URL (from "sources") — the card renders them as clickable [host](url) source links. Opaque ids like "s1" stay as bare text and lose the link.

  • For first-hand depth: call fetch_url on key sources BEFORE writing the answer, so it cites concrete numbers/mechanisms from the actual page (not memory). fetch_url also archives a local snapshot (knowledge/_snapshots/) so dead links stay traceable. save_research best-effort snapshots any listed sources in the background even without an explicit fetch_url.

  • When language="zh" (default), the entire answer field MUST be written in Chinese (中文). When language="en", write in English.

When to include visual_aids (auto-judge by topic):

  • Processes / workflows / data flow → mermaid flowchart or sequence diagram

  • Architecture / system design → mermaid graph or class diagram

  • Comparisons or hierarchies → mermaid diagram or table

  • Spatial / geometric concepts → image_url or mermaid

  • Pure definitions or simple facts → omit visual_aids

When sources contain useful images (charts, diagrams, figures):

  • If a source page has a relevant diagram/chart with clear explanatory value, include it as visual_aids with type "image_url" and the image's absolute URL

  • Judge relevance: prefer diagrams explaining mechanisms, architecture overviews, comparison charts, result plots — skip decorative screenshots or generic stock photos

  • Always provide a descriptive caption explaining what the image shows

For method/procedural content (how-to, implementation, deployment, etc.), also include:

  • expected_output: Description of what a successful result looks like — output format, shape, key metrics, or acceptance criteria. Synthesize from the answer if sources don't explicitly provide this.

  • example: A minimal worked example (sample input → processing steps → expected output). Construct synthetically based on the answer if sources lack one. Write '[insufficient data — needs supplementation]' only if impossible to construct.

Visual aids placement (optional after_section field):

  • "answer" — insert after the main answer paragraph (default for architecture/pipeline diagrams)

  • "supporting_claims" — insert after claims (default for evidence figures/charts)

  • "inferences", "uncertainty", "missing_evidence", "suggested_next_steps" — after respective sections

  • Omit after_section to place at the end of the card (backward compatible)

Inputs: query (required), answer_json (required), domain, language, +1 more. Returns: result

scan_stale_knowledgeA

Report knowledge cards whose source freshness exceeds domain thresholds.

Unlike lint_knowledge's updated_at check, this uses source_date/captured year with the domain-specific freshness policy used by card validation. This tool is read-only.

Inputs: no named parameters. Returns: result

validate_knowledgeA

Validate local knowledge cards without modifying files.

Runs card frontmatter validation plus body-density/source-freshness checks. Use this before relying on a knowledge base or after bulk imports.

Inputs: verbose. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes (query, save, ingest, validate, fetch, list, lint, scan, build, import). However, save_research, capture_answer, and ingest_source all persist knowledge cards with different input formats, which could cause confusion despite detailed descriptions.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case (e.g., query_knowledge, save_research, fetch_url). Verbs are descriptive and the pattern is predictable across all 12 tools.

    Tool Count5/5

    12 tools is well-scoped for a knowledge management server. The set covers querying, saving, ingesting, validating, listing, linting, scanning dead links, building graphs, and importing notes—no bloat or deficiency.

    Completeness3/5

    The tool surface covers create (save, capture, ingest), read (query, list), and checking tools, but lacks update and delete operations for knowledge cards. This is a notable gap that could hinder full life cycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents to retrieve and manage code context with hybrid search, project memory, and observability via MCP tools.
      30
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to persistently store, semantically search, and recall project-specific and cross-project knowledge across sessions, with everything kept local in SQLite. It also exposes project context, guidelines, and preferences as MCP resources for agents to read and write directly.
      -