Skip to content

xeniah/wetware

 
 

Repository files navigation

Wetware: Personalized Paper Recommender System

What research papers should I read right now to prime my learning and recall process?

Wetware is an AI-powered research assistant that creates personalized daily paper reading lists by analyzing your recent Obsidian notes, searching your paper backlog, and generating Anki cards for spaced repetition learning. It bridges the gap between content discovery and knowledge retention by understanding your evolving research interests and surfacing the most relevant papers at the right time.

Design

Agent Architecture

The Wetware system uses a workflow agent architecture with sequential and parallel sub-workflows to generate personalized paper recommendations:

graph TD
    Start([WetwarePaperRecommenderAgent<br/>Sequential Agent]) --> RM[ResearchMapperAgent]
    
    RM -->|research_topics| MR[ResearchMetaRubricAgent]
    
    MR -->|research_rubric| PSP{PaperSearchPipeline<br/>Parallel Agent}
    
    PSP --> PA[PersonalPaperAgent]
    PSP --> AA[ArxivAgent]
    
    PA -->|personal_papers| RA[RankingAgent]
    AA -->|arxiv_papers| RA
    
    RA -->|recommended_papers| ANK[AnkiAgent]
    
    %% Tool connections
    RM -.->|list_notes| OBS[(Obsidian Vault)]
    PA -.->|search_paper_queue| PQ[(Personal Queue)]
    AA -.->|arxiv_toolset| ARX[(ArXiv API)]
    RA -.->|write_recommended_papers_note| OBS
    ANK -.->|add_card<br/>list_cards<br/>save_deck| ANKI[(Anki Deck)]
    
    style Start fill:#2d3436,stroke:#74b9ff,stroke-width:3px,color:#fff
    style PSP fill:#2d3436,stroke:#a29bfe,stroke-width:2px,color:#fff
    style RM fill:#00b894,stroke:#00cec9,stroke-width:2px,color:#fff
    style MR fill:#6c5ce7,stroke:#a29bfe,stroke-width:2px,color:#fff
    style PA fill:#fdcb6e,stroke:#f39c12,stroke-width:2px,color:#000
    style AA fill:#fab1a0,stroke:#e17055,stroke-width:2px,color:#000
    style RA fill:#74b9ff,stroke:#0984e3,stroke-width:2px,color:#fff
    style ANK fill:#fd79a8,stroke:#e84393,stroke-width:2px,color:#fff
Loading

Agent Workflow

  1. ResearchMapperAgent: Analyzes your Obsidian notes from the last 14 days to identify:

    • Active research themes and emerging topics
    • Knowledge gaps and unresolved questions
    • Priority areas needing exploration
  2. ResearchMetaRubricAgent: Generates a domain-specific ranking rubric based on the research topics, defining:

    • Ranking dimensions with comparative anchors
    • Excellence indicators for the field
    • Context modifiers for different research types
  3. PaperSearchPipeline (Parallel): Simultaneously searches multiple sources:

    • PersonalPaperAgent: Queries your saved paper queue
    • ArxivAgent: Searches recent ArXiv papers (last 30 days)
  4. RankingAgent: Applies the rubric to rank all candidate papers and:

    • Selects top 5 papers for daily reading
    • Creates structured Obsidian note with reading plan
    • Provides "Why now" context for each paper
  5. AnkiAgent: Generates flashcards from selected papers:

    • Creates active recall questions
    • Focuses on one concept per card
    • Saves deck for spaced repetition

Features

  • Intelligent Theme Extraction: Analyzes your last 14 days of Obsidian notes to identify research priorities and knowledge gaps
  • Multi-Source Paper Discovery: Searches both your personal reading queue and recent ArXiv papers (last 30 days)
  • Domain-Specific Ranking: Generates custom evaluation rubrics based on your research field
  • Daily Reading Lists: Curates exactly 5 papers with clear "why now" justifications
  • Active Recall Integration: Automatically generates Anki flashcards from selected papers
  • MCP Server: Exposes functionality via Model Context Protocol for integration with AI assistants

Technical Stack

  • Agent Orchestration: Google ADK for multi-agent workflows (sequential and parallel)
  • Vector Storage: ChromaDB for semantic search and paper embeddings
  • Graph Database: Kuzu for managing paper relationships and metadata
  • MCP Server: FastMCP for exposing tools to AI assistants
  • Data Sources: Readwise API, ArXiv MCP, Obsidian vault
  • Spaced Repetition: Genanki for Anki deck generation

Installation

# Clone the repository
git clone https://github.com/yourusername/wetware.git
cd wetware

# Install Python dependencies with uv
uv sync

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys and paths

Configuration

Create a .env file with the following settings:

# API Keys
GOOGLE_API_KEY=your_google_api_key
READWISE_API_TOKEN=your_readwise_token

# Paths
VAULT_PATH=/path/to/your/obsidian/vault
DB_PATH=wetware.db

# Research Steering (customize for your field)
STEERING="Focus on machine learning, distributed systems, and AI safety"

# Note Exclusion Patterns (comma-separated)
NOTE_EXCLUSION_PATTERNS="Daily/,Archive/,Templates/"

Usage

As an MCP Server

# Run the MCP server
uv run mcp run server.py

Then configure your AI assistant (e.g., Claude) to connect to the MCP server.

Direct Agent Execution

from wetware.agent import root_agent

# Run the complete paper recommendation pipeline
result = root_agent.run()

Available MCP Tools

  • add_card: Add flashcard to daily Anki deck
  • list_cards: Retrieve all flashcards in current deck
  • save_deck: Export deck as .apkg file
  • write_recommended_papers_note: Create daily papers note in Obsidian
  • list_notes: Get recently modified Obsidian notes
  • search_paper_queue: Search personal paper backlog

Development

# Run tests
uv run pytest

# Format code
uv run black wetware/ tests/

# Lint
uv run ruff check wetware/ tests/

# Type checking
uv run mypy wetware/

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Resources

Helpful tools and lists on systematic literature review.

  • awesome-arxiv curated list of tools, libraries, datasets and resources for discovering, reading and working with papers from arXiv — the open-access repository for scientific research.
  • AlpahXiv Read, discover, and discuss the latest research on alphaXiv.
  • Connected Papers explore connected papers in a visual graph
  • Elicit AI research assistant
  • Leximancer Concept mining and discovery for research literature review.
  • Undermind research review agent and summarization workflow.
  • SciSpace / Typeset is a paper search and copilot.
  • Eilicit paper search and copilot. Similar to above.
  • Connected Papers visualizes connecteds papers in a graph by references and similarity.
  • Consensus searches research papers for Q&A.
  • Papers with Code ML, CS, etc papers with code, grouped by task and can see state of the art.
  • Emergent Mind trending arXiv papers based on discussion on social networks.
  • Papers Without Code prototype implementations from papers using LLMs.
  • Better Bibtex
  • papis powerful and highly extensible command-line based document and bibliography manager.

How to Read A Paper

How to Read a Paper defines three passes to truly understand a paper which corresponds to increasing detail. For the first pass, the goal is to skim in order to understand the Five Cs:

  1. Category: What type of paper is this? A measurement paper? An analysis of an existing system? A description of a research prototype?
  2. Context: Which other papers is it related to? Which theoretical bases were used to analyze the problem?
  3. Correctness: Do the assumptions appear to be valid?
  4. Contributions: What are the paper’s main contributions?
  5. Clarity: Is the paper well written?

About

Personalized Paper Recommender

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 100.0%