Skip to main content
Glama

MindPulse Academic Suite

Scholar Agent is part of the MindPulse Academic Suite, forming a powerful synergy between local open-source tools and fully-managed cloud services:

  • ๐ŸŒŒ Scholar Agent (Open Source & Local): A local-first knowledge flywheel that integrates with your IDE via MCP (Model Context Protocol). It saves research answers as local Markdown knowledge cards, building your custom personal LLM-Wiki.

  • โšก PaperPulse (Cloud SaaS): A fully-managed daily academic digest SaaS that monitors arXiv/Semantic Scholar, scores papers based on your personalized research preferences, and delivers distilled summaries straight to your WeChat or Email.

Feature

Scholar Agent (Local)

PaperPulse (Cloud SaaS)

Hosting & Mode

Local MCP Server (Open Source)

Fully-Managed SaaS (Closed Source)

Core Workflow

On-demand research query & knowledge synthesis

Automated daily crawling, scoring & email/WeChat push

Storage

Local Markdown Files / Vector DB

Cloud Postgres / Managed Index

IDE Integration

Deeply integrated with Claude Code, VS Code, Cursor

Web-based Dashboard & Chatbot

Pricing

Free & Open Source

Free Tier / Premium Subscriptions

๐Ÿ’ก Synergy (One-Click Local Sync):

  • One-Click Sync: When your Scholar Agent MCP server is running locally, simply click the "Import to Local Scholar Agent" button on the PaperPulse web interface. The note will be instantly synced and written to your local knowledge/ directory via a secure local loopback interface, bypass browser sandbox constraints and rebuild your search index automatically!

  • Manual Export: You can also click "Export Markdown" to download the standard Markdown note and place it into your knowledge base directory manually.


Related MCP server: codememory

Why

Every AI conversation generates knowledge โ€” research findings, technical explanations, citations. But LLMs are stateless: each new session starts from zero. The research your AI completed yesterday is not available today.

Scholar Agent makes AI knowledge persistent. It saves research and answers as local knowledge cards โ€” structured, citable, and interconnected. Before answering, the AI checks existing local knowledge first, building on what it has already learned rather than starting from scratch each time.

The result is a personal LLM-Wiki: structured, traceable, continuously growing โ€” making your AI increasingly accurate in the domains you care about.


Demo


What It Does

Architecture & Data Flow

When you ask a question, the agent routes the query through a local-first retrieval loop before falling back to external sources:

sequenceDiagram
    actor User
    participant Host as Claude Code / VS Code
    participant MCP as Scholar Agent (MCP Server)
    participant Local as Local Index (BM25)
    participant Web as arXiv / Semantic Scholar

    User->>Host: Prompt: "Explain MoE"
    Host->>MCP: query_knowledge("MoE")
    MCP->>Local: BM25 Query
    alt Local Hit (BM25 Score >= Threshold)
        Local-->>MCP: Match (e.g. mixture-of-experts.md)
        MCP-->>Host: Local Note Context
    else Local Miss
        MCP->>Web: API Fallback (arxiv + web search)
        Web-->>MCP: Raw Papers & Metadata
        MCP->>MCP: Synthesize & Distill
        MCP->>Local: Save Card (Staging -> Validate -> Promote)
        MCP-->>Host: Synthesized Answer + Citations
    end
    Host->>User: Natural Language Response

Knowledge Persistence

Each conversation can produce a knowledge card โ€” a structured record with:

  • The question asked

  • Evidence-backed answer with citations

  • Confidence scores and uncertainty flags

  • Source references you can trace back

These cards accumulate into a searchable local knowledge base. Next time a similar question comes up, the AI draws from what's already been researched.

Knowledge Network

Cards aren't isolated files. Scholar Agent:

  • Maintains a quality lifecycle for each card: draft โ†’ reviewed โ†’ trusted โ†’ stale โ†’ deprecated

  • Auto-generates [[wiki-links]] between related cards

  • Tracks provenance โ€” every claim links back to its source evidence

  • Outputs Obsidian-compatible Markdown (YAML frontmatter + wiki-links)

  • Obsidian Graph Ready โ€” Open your knowledge data directory (e.g. ~/scholar/) directly as an Obsidian Vault to navigate your visual knowledge graph.

Evidence-Based Answers

When researching a question, Scholar Agent:

  1. Searches local knowledge (BM25 keyword index)

  2. Falls back to web and academic APIs when local knowledge is insufficient

  3. Synthesizes answers where every claim cites its source

  4. Flags claims that lack supporting evidence

  5. Returns structured results with confidence levels and suggested next steps

Academic Research Pipeline

For paper research, Scholar Agent provides:

  • Paper Search โ€” arXiv, DBLP, Semantic Scholar with 10+ top-conference filters

  • Smart Scoring โ€” 4-dimensional ranking: relevance, recency, popularity, quality

  • Deep Analysis โ€” 20+ section structured notes with AI-assisted completion

  • Figure Extraction โ€” From arXiv source archives and PDFs

  • Daily Recommendations โ€” Dual-track: 2 top-conference papers + 2 arXiv innovation papers

  • Paper โ†’ Knowledge Card โ€” Feed analyses back into the knowledge base


Quick Start

Install

pip install py-scholar-agent

Or with pipx (isolated environment):

pipx install py-scholar-agent

Or from source:

git clone https://github.com/zfy465914233/scholar-agent.git
cd scholar-agent
pip install -e .

Setup

scholar-agent init

One command creates the Scholar home, knowledge data directories, writes config, and registers MCP with Claude Code. Use scholar-agent init --host all to register Claude Code, VS Code Copilot, and OpenCode in one pass. Check the result with scholar-agent doctor --format text.

Modes

Mode

Command

Knowledge Data

Config/Index Home

Scope

Global (recommended)

scholar-agent init

~/scholar/

~/.scholar/

Every project

Project-Local

SCHOLAR_HOME=./scholar scholar-agent init

my-project/scholar/

my-project/scholar/

Current project only

Docker

docker run -v ~/scholar:/data scholar-agent serve-mcp

/data/

/data/

Isolated


MCP Integration

Scholar Agent runs as an MCP server, integrating directly into your tools:

  • Claude Code โ€” scholar-agent install claude --write

  • VS Code Copilot โ€” scholar-agent install vscode --write

  • OpenCode โ€” scholar-agent install opencode --write

Core tools (always available): query_knowledge ยท save_research ยท list_knowledge ยท capture_answer ยท ingest_source ยท build_graph ยท validate_knowledge ยท lint_knowledge ยท scan_stale_knowledge ยท scan_dead_links

Academic tools (set SCHOLAR_ACADEMIC=1): search_papers ยท search_conf_papers ยท download_paper ยท analyze_paper ยท extract_paper_images ยท paper_to_card ยท daily_recommend ยท link_paper_keywords

save_research is provenance-gated: pass a non-empty sources array and cite those sources from every supporting_claims[].evidence_ids. For unsourced conversation captures, use capture_answer instead. URL ingestion and fetch_url archive first-hand source snapshots under knowledge/_snapshots/; those internal snapshots are excluded from card indexing and governance scans.

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "scholar-agent": {
      "command": "scholar-agent",
      "args": ["serve-mcp"],
      "env": {
        "SCHOLAR_ACADEMIC": "1"
      }
    }
  }
}

Local Retrieval

Knowledge is indexed with BM25 for fast keyword search โ€” no external dependencies required. An optional embedding layer adds semantic similarity: build it once with scholar-agent index --build-embedding-index and query_knowledge automatically switches to hybrid (BM25 + semantic) retrieval, keeping the index fresh as you add cards.


CLI Reference

Command

Description

scholar-agent init

One-command setup: Scholar home + knowledge data dirs + config + MCP registration

scholar-agent serve-mcp

Start the MCP server

scholar-agent doctor --format text --host all

Show environment and MCP host registration diagnostics

scholar-agent health

Read-only project health summary for config, index, stale cards, duplicates, and dangling links

scholar-agent config show

Show resolved configuration

scholar-agent index --build-embedding-index

Build/rebuild the search index; the flag enables hybrid retrieval

scholar-agent scan-stale --refresh

Report stale cards and optionally refresh source snapshots

scholar-agent report-dangling

Report dangling [[wikilinks]] across notes and knowledge cards

scholar-agent report-dead-links

Diagnose dead source URLs (404/410/connection failure) across knowledge cards

scholar-agent install claude --write

Register MCP with Claude Code

scholar-agent install vscode --write

Register MCP with VS Code Copilot

scholar-agent install opencode --write

Register MCP with OpenCode


Configuration

Environment Variables

Variable

Required

Description

SCHOLAR_ACADEMIC

No

Set to 1 to enable academic tools

SCHOLAR_HOME

No

Override Scholar home. When unset, config/indexes default to ~/.scholar/ and knowledge data defaults to ~/scholar/; when set, both are rooted in SCHOLAR_HOME.

S2_API_KEY

No

Semantic Scholar API key (get one free)

LLM_API_KEY

No

LLM API key for advanced synthesis pipeline

Config File

See .scholar.example.json for a full example. Key sections:

  • knowledge_dir โ€” Knowledge cards directory. Defaults to ~/scholar/knowledge; with SCHOLAR_HOME set, defaults to $SCHOLAR_HOME/knowledge.

  • index_path โ€” BM25 search index. Defaults to ~/.scholar/indexes/local/index.json; with SCHOLAR_HOME set, defaults to $SCHOLAR_HOME/indexes/local/index.json.

  • academic.research_interests โ€” Your domains, keywords, arXiv categories

  • academic.scoring โ€” Paper scoring weights

Default Path Layout

~/.scholar/
โ”œโ”€โ”€ config/         # Configuration files
โ”œโ”€โ”€ indexes/        # BM25 search index
โ”œโ”€โ”€ cache/          # Cached data
โ””โ”€โ”€ outputs/        # Generated outputs

~/scholar/
โ”œโ”€โ”€ knowledge/      # Knowledge cards
โ”œโ”€โ”€ paper-notes/    # Paper analysis notes
โ””โ”€โ”€ daily-notes/    # Daily paper recommendations

When SCHOLAR_HOME is set, both groups are created under that directory.


Daily research flow

Ask a question (via MCP)
  โ†’ Scholar Agent searches local knowledge first
  โ†’ Falls back to web/academic APIs when needed
  โ†’ Synthesizes answer with citations
  โ†’ Saves as a knowledge card
  โ†’ Next similar question draws from local knowledge

Paper analysis flow

For best paper analysis quality:

  1. Download: download_paper("2510.24701", title="Paper Title", domain="LLM")

  2. Extract images: extract_paper_images("2510.24701")

  3. Deep analysis: analyze_paper(paper_json)

  4. Feed into knowledge base: paper_to_card(paper_json)

Downloading the PDF first enables full-text extraction, producing notes with specific data, formulas, and experimental results.


Development

make dev       # Install with dev dependencies + pre-commit hooks
make lint      # Run ruff + mypy
make test      # Run the offline test suite (1554 tests collected; runtime varies by machine)
make coverage  # Run tests with coverage report
make build     # Build distribution package
make check-dist # Build and validate sdist/wheel contents
make docker    # Build Docker image

See CONTRIBUTING.md for detailed guidelines.

Highlights

  • Knowledge persistence โ€” Every conversation can produce a reusable knowledge card; the local knowledge base grows over time

  • Evidence-based โ€” Every claim cites its source, with confidence scores and uncertainty flags

  • Quality lifecycle โ€” Cards are validated, scored, promoted, and deprecated. Full provenance tracking

  • Knowledge network โ€” Wiki-links connect related cards into a navigable knowledge graph

  • Obsidian compatible โ€” Markdown + YAML frontmatter + [[wiki-links]]. Your data, no lock-in

  • Academic pipeline โ€” Search โ†’ Score โ†’ Analyze โ†’ Extract โ†’ Recommend, fully automated

  • MCP integration โ€” Works with Claude Code, VS Code Copilot, and OpenCode out of the box

  • Offline-first โ€” Local BM25 index, graceful degradation when external APIs are unavailable

Comparison

Wondering how Scholar Agent compares to mem0, MemGPT, or Zep? See docs/comparison.md for a detailed breakdown.

License

MIT โ€” see 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
    ResponsivenessOutdated data

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