Skip to main content
Glama

Scholar Agent

Python 3.10+ License: MIT MCP Ready

中文

LLM общего назначения часто бывают неточными и устаревшими в специализированных областях. Scholar Agent объединяет онлайн-исследования + накопление локальных знаний в устойчивый маховик знаний, со временем делая ваш ИИ умнее в вашей предметной области. Он также создает базу знаний, понятную человеку, для быстрого обучения. Бесшовная интеграция с Claude Code и VS Code Copilot через MCP.

Что он делает

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)

  • Умная оценка — Четырехмерный механизм оценки (релевантность, актуальность, популярность, качество) ранжирует статьи в соответствии с вашими исследовательскими интересами

  • Заметки глубокого анализа — Автоматическая генерация markdown-заметок в стиле Obsidian из 20+ разделов с плейсхолдерами <!-- LLM: --> для завершения с помощью ИИ

  • Извлечение изображений — Извлечение изображений из исходных архивов 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

Быстрая фиксация пары вопрос-ответ в виде черновой карточки

ingest_source

Добавление URL или необработанного текста в базу знаний

build_graph

Генерация интерактивного графа знаний (vis.js)

Академические инструменты (установите SCHOLAR_ACADEMIC=1 для включения)

Инструмент

Описание

search_papers

Поиск в arXiv + Semantic Scholar с 4-мерной оценкой

search_conf_papers

Поиск статей конференций через DBLP + обогащение S2

analyze_paper

Генерация markdown-заметок глубокого анализа (20+ разделов)

extract_paper_images

Извлечение рисунков из исходников arXiv / PDF

paper_to_card

Преобразование анализа статьи в карточку знаний

daily_recommend

Рабочий процесс ежедневных рекомендаций статей

link_paper_keywords

Автоматическая привязка ключевых слов как [[wikilinks]] в заметках

Рекомендуемый рабочий процесс

Для наилучшего качества анализа следуйте этому порядку:

  1. Скачивание статьи: download_paper("2510.24701", 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

Нет

API-ключ Semantic Scholar (получить бесплатно)

LLM_API_KEY

Нет

API-ключ LLM для продвинутого конвейера синтеза

Структура проекта

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 — Стандартный Markdown + YAML frontmatter + [[wiki-links]]

  • CLI управления знаниями — Проверка frontmatter, обнаружение осиротевших карточек, поиск дубликатов, управление жизненным циклом

  • Отказоустойчивость провайдеров — Каждый источник поиска работает независимо; при отсутствии сети переключается на локальный поиск

Тестирование

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.
      -