Skip to main content
Glama

Ruminate

把读过的资料,变成值得继续思考的问题和有出处的输出。

English · 使用指南 · 贡献指南 · 路线图

CI License: Apache 2.0

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 的片段和页图会进入当前会话上下文。 备份与恢复命令见使用指南,访问范围见安全说明。

文档与开发

文档

内容

使用指南 / 界面操作

导入、检索、反刍、输出和备份

插件安装 / 开发接入 / Skills

Codex 接入与工作流

架构 / 技术决策

模块、存储和证据模型

测试 / 验收记录

可复现命令与实际结果

功能范围 / 路线图

已有能力与后续方向

贡献指南 / 支持

开发和反馈

uv run pytest
uv run ruff check .
uv run mypy
node --test scripts/test_ui_transport.cjs
uv build

JavaScript 协议测试需要 Node.js 22+;使用工作台无需安装 Node.js。 CI 运行应用测试、静态检查、协议测试及构建后的独立安装检查。

许可证

Apache License 2.0。版权及依赖说明见 NOTICE 和 THIRD_PARTY_NOTICES.md。导入的文献和用户研究内容保留各自的权利。

Ruminate 是独立项目,与 OpenAI 没有隶属关系。ChatGPT、Codex 等名称用于说明兼容方式。

Available Tools

9 tools
get_claimRead a claim and its exact evidenceB
Read-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 versionB
Read-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 pageA
Read-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 contextB
Read-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 healthA
Read-only

Read local storage, schema and model availability without changing data.

Inputs: no named parameters. Returns: object

list_output_projectsList local output projectsC
Read-only

Read local research projects without creating or exporting a draft.

Inputs: limit, status, topic_id. Returns: object

list_review_queueRead the review queueA
Read-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 observationsB
Read-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 sourcesB
Read-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

    B3.1/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness2/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local-first paper RAG server that enables searching and managing academic PDFs via MCP tools, supporting metadata enrichment and citation graphs.
      2
      MIT