Ruminate
Integrates with OpenAI's Codex/ChatGPT hosts through MCP and Skills, exposing a local-first research workbench for importing sources, searching evidence, tracking ideas, and generating cited outputs within conversations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ruminate search my library for 'spaced repetition' and draft a cited outline"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ruminate
把读过的资料,变成值得继续思考的问题和有出处的输出。
Ruminate 是一个本地优先的研究工作台,通过 MCP 和 Skills 接入 Codex / ChatGPT。 资料、引用、想法和输出保存在你自己的电脑上,阅读与推理由现有 AI 宿主完成。 内核无需模型 API Key、云数据库或其他知识管理软件。
当前版本 0.6.0,处于早期开发阶段,可从 GitHub 一条命令安装到个人插件栏。 PyPI 包及公共插件市场发布尚未提供。Codex 插件工作台已完成实际验收, 不同客户端的支持范围见兼容性记录。
能做什么
收集资料:导入 PDF、Markdown、TXT、静态 HTML 和公开 URL,保留原件与历史版本。
整理资料:修改显示名称、调整所属主题,重命名主题并补充研究范围。
定位证据:全文检索中英文内容,引用回到具体版本、页面或原文片段。
回看想法:记录问题与证据关系,处理有启发、延后或略过的建议。
推进输出:从已有资料生成带引用的研究提纲,保留修订并导出 Markdown。
在对话中继续:工作台中的阅读内容可关联到宿主对话,复用现有聊天与视觉能力。
统一管理页默认打开“想法”,有 想法 / 资料 / 输出 三个入口。 自动反刍建议进入 想法 → 待回看;定时任务需在自己的 Codex 客户端中配置, 见自动反刍。
Related MCP server: Athena
安装到 Codex 插件栏
安装好 Codex 桌面客户端后,在终端执行:
curl -fsSL https://raw.githubusercontent.com/hanikasarfa94-max/Ruminate/main/install.sh | bash安装器自动准备 Python 和依赖、注册插件,并检查工作台能否通过 Codex 加载。 完成后重新打开 Codex,进入 插件 → Ruminate → 打开插件。 不需要预装 Python、GitHub 登录或 API Key;macOS 可直接使用桌面应用自带的 CLI。
再次运行同一命令即可更新,研究资料会保留。 自定义路径、卸载及已有开发版的迁移见安装指南。 支持 macOS / Linux;插件栏和内嵌页面需要宿主支持。
从源码开发或使用 CLI
需要 Python 3.11+、uv 和支持 FTS5 的 SQLite。macOS arm64 已实测;Linux Python 3.11 / 3.13 已通过 CI。 当前文件导入依赖 POSIX,Windows 尚未支持。
git clone https://github.com/hanikasarfa94-max/Ruminate.git
cd Ruminate
uv sync --locked
uv run ruminate init
uv run ruminate doctor用仓库自制材料体验导入与搜索:
uv run ruminate ingest tests/fixtures/notes.md --topic demo
uv run ruminate ingest tests/fixtures/single_column.pdf --topic demo
uv run ruminate search '证据' --topic demo也可运行 uv run python scripts/smoke_p2.py,在临时资料库里体验从多源证据、
反刍反馈到有引用输出的完整流程;结束后自动清理测试数据。
开发中需要将插件指向当前源码时,见开发版插件注册。 正式安装的工作台通过 MCP Apps 内嵌,不需要另启网页服务器。
如果只想预览页面,运行 uv run ruminate ui,打开终端显示的本地地址即可。
CLI 和 MCP 使用同一套应用逻辑;不支持内嵌界面的客户端仍可使用工具。
数据与隐私
默认数据目录在源码仓库外:macOS 为 ~/Library/Application Support/Ruminate/,
Linux 为 $XDG_DATA_HOME/ruminate/ 或 ~/.local/share/ruminate/。
可用 RUMINATE_DATA_DIR 或 --data-dir 指定其他位置。
导入、检索、引用和模板输出可在本地完成。URL 导入需要显式网络授权; 发送给 Codex / ChatGPT 的片段和页图会进入当前会话上下文。 备份与恢复命令见使用指南,访问范围见安全说明。
文档与开发
文档 | 内容 |
导入、检索、反刍、输出和备份 | |
Codex 接入与工作流 | |
模块、存储和证据模型 | |
可复现命令与实际结果 | |
已有能力与后续方向 | |
开发和反馈 |
uv run pytest
uv run ruff check .
uv run mypy
node --test scripts/test_ui_transport.cjs
uv buildJavaScript 协议测试需要 Node.js 22+;使用工作台无需安装 Node.js。 CI 运行应用测试、静态检查、协议测试及构建后的独立安装检查。
许可证
Apache License 2.0。版权及依赖说明见 NOTICE 和 THIRD_PARTY_NOTICES.md。导入的文献和用户研究内容保留各自的权利。
Ruminate 是独立项目,与 OpenAI 没有隶属关系。ChatGPT、Codex 等名称用于说明兼容方式。
Available Tools
9 toolsget_claimRead a claim and its exact evidenceBRead-only
Read a claim with its origin, type, evidence spans and review status.
Exact-span checks confirm where a quotation occurs in the saved source.
Inputs: claim_id (required). Returns: object
get_sourceRead a stored source versionBRead-only
Read saved text blocks; version_id selects the version used by a citation.
Continue long documents with block_start and block_limit.
Inputs: source_id (required), version_id, block_limit, block_start. Returns: object
get_source_page_imageView a preserved PDF pageARead-only
Return one stored PDF page as an image for the current host's vision capability.
Page numbers start at 1. Use this for scans, diagrams and tables. The current host
reads the returned image. Save a reading with record_visual_observation, keeping
its source_id, version_id and page; visual notes retain their model origin.
Inputs: source_id (required), page, version_id.
get_topic_contextRead a research topic contextBRead-only
Read source-backed claims, model inferences, disputes, gaps and explicit beliefs.
Confirmed user beliefs appear separately from model suggestions and candidates.
References include version/block locators; get_claim expands their quotations.
Inputs: topic_id (required), max_claims. Returns: object
health_checkCheck Ruminate healthARead-only
Read local storage, schema and model availability without changing data.
Inputs: no named parameters. Returns: object
list_output_projectsList local output projectsCRead-only
Read local research projects without creating or exporting a draft.
Inputs: limit, status, topic_id. Returns: object
list_review_queueRead the review queueARead-only
Preview up to three grounded cards without recording an exposure.
Cards include their evidence and review status. Use present_review_queue or
CLI review present when showing recommendations to record the daily allowance.
Inputs: limit, topic_id. Returns: object
list_visual_observationsRead host visual observationsBRead-only
Read saved model transcriptions or interpretations for a source version and page.
Visual notes carry their own origin and review status alongside the native text.
Inputs: source_id (required), page, limit, version_id. Returns: object
search_sourcesSearch stored sourcesBRead-only
Search saved source text and return excerpts with version and block locators.
Inputs: query (required), limit, topic_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools target distinct resources (sources, claims, visual observations, review queue, topics, projects) and the search-vs-read split between search_sources and get_source is clear. Minor overlap remains between get_topic_context and get_claim, but the descriptions explain that context summarizes while get_claim expands quotations.
Eight of nine tools follow a clean verb_noun pattern (search_sources, get_source, list_visual_observations, get_claim, etc.). The lone outlier is health_check, which uses noun_verb ordering, a small but visible deviation.
Nine tools is a reasonable, well-scoped size for a research/reading server. The count is fine, though the set is skewed entirely toward reads, which makes it feel thinner than the domain implies.
The surface is read-only, yet several descriptions direct agents to tools that are not exposed: record_visual_observation, present_review_queue, and CLI review present are all referenced but absent. Without create/record operations for visual notes or review exposures, agents will hit dead ends in the core workflow.
Maintenance
Related MCP Connectors
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
AI research library. Save, organise and reuse notes and webpages as clean markdown context.
Personal context for every AI: search, read, and write back to your private Markdown library.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local-first MCP server that analyzes research papers, maps citation graphs, and surfaces insights with verbatim-verified contradictions, all while keeping data private on your machine.1MIT
- FlicenseNot gradedqualityDmaintenanceA local academic research assistant that indexes PDFs into a searchable vector library and exposes MCP tools for semantic search, claim extraction, contradiction detection, and multi-step research synthesis.-
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for indexing and searching research materials (papers, notes, logs, READMEs) using SQLite FTS, with tools for memory management and evidence retrieval.MIT
- AlicenseNot gradedqualityCmaintenanceA local-first paper RAG server that enables searching and managing academic PDFs via MCP tools, supporting metadata enrichment and citation graphs.2MIT