Tool reference

Start with the composable workspace tools. They expose the current product vocabulary and cover most work: list entries, open only what matters, update before creating, and archive stale context. The entry type files every new entry into one of the eight categories automatically.

First write from a new agent

1. Call ruminate_list_projects if you do not know the workspace. Its returned id is the workspaceId accepted by entry, session, and context tools.
2. Call ruminate_start_session with workspaceId and your intent so subsequent writes contribute to an attributed handoff.
3. Call ruminate_find_similar with workspaceId and the final entryType, title, and summary. Copy searchToken from the first text block or JSON result.
4. Update an existing subject, or call ruminate_create_item with the same fields and that token. Only likely duplicates (score at least 0.72) require a concrete dismissal reason. When nothing reaches the threshold, the strongest observed candidate is still returned as a weak match for calibration and needs no dismissal. Set includeWeakMatches: true to see the remaining weak matches; the guard still checks current workspace contents when creating.
5. Call ruminate_end_session with your outcome, next step, and touched-item dispositions when finished.

Read ruminate_get_policy at any time for the current rules and this workflow; it does not require a workspace. The legacy projectId parameter remains accepted on session and context tools, but means the same workspace. If both ids are supplied they must match. The retained list_projects and create_project tool names have not changed, so existing clients continue working.

Entry and structure creation without a session still succeeds, with a warning that the write is not attached to a handoff. Do not repeat a successful create to address that warning. Starting a session affects future writes and does not retroactively change attribution.

Omit collectionId for normal writes. The defaults are decision → Decisions, fact and assumption → Facts & Assumptions, question → Questions, goal and non_goal → Goals & Non-Goals, risk → Risks, brief/plan/task → Plans & Tasks, draft → Drafts, and note → Notes & Todos. Search responses name the destination before you create. Existing custom destination ids remain readable and refilable for compatibility.

Create a workspace from an AI chat

Workspace discovery and creation are in the default tool set on both transports. They retain the names ruminate_list_projects and ruminate_create_project for compatibility, but create the same top-level workspace people use in the app. Do not substitute ruminate_create_workspace: that hidden legacy tool creates a different grouping layer.

Tool	What it does
ruminate_list_projects	Lists workspaces reachable by the current account
ruminate_create_project	Creates a workspace with name and optional purpose, returning its stable workspaceId and human-openable URL

Ask, for example:

Create a Ruminate workspace called Learning Portuguese. Its purpose is to connect
my grammar, vocabulary, reading and the stories I want to tell. First check whether
it exists. Ask about my level, language variety and goals before claiming progress.

Creation requires the same administrator permission as the web app (a personal owner administers their own account). The authenticated account determines ownership; the model cannot choose another organization or grant access. A single active, case-insensitive exact-name match is reused without editing its purpose; ambiguous matches require selection or a different name. Name reuse protects sequential retries, not simultaneous creates. List before creating.

Use the returned workspaceId for entry and session tools. Start a session, let each entry type choose its category, and use the retrieval guard before creating entries. No learning template or evidence attachment is mandatory. Links between entries can connect a story draft to relevant grammar, vocabulary and reading without copying bodies.

This capability does not expose workspace deletion, archive, rename, membership changes or legacy grouping tools. It does not add an embedded chat runtime or cross-workspace context inheritance. Reconnect the MCP client after deployment to refresh its tool list. Server policy can disable workspace_creation.

Note

For a new or unfamiliar workspace, invoke /ruminate_compose when your client supports MCP prompts. It inspects the current workspace, asks focused questions, and proposes only the useful starting entries.

Composable workspace

Tool	What it does
ruminate_get_policy	Reads the current composition policy, starting workflow, and collection defaults without a workspace
ruminate_list_structures	Lists compact metadata and headings for structures agents refer to often
ruminate_get_structure	Opens one structure or one ## section without loading unrelated content
ruminate_write_structure	Creates a reusable template, text source file, or generated output
ruminate_update_structure	Enriches an existing structure while retaining its stable address
ruminate_list_items	Lists entries, optionally filtered by entry type, status, audience, or archive state
ruminate_get_item	Opens one entry with its content and provenance
ruminate_find_similar	Finds likely duplicates and issues independent single-use tokens for one entry or a batch of up to 25
ruminate_create_item	Creates a decision, fact, assumption, question, goal, non-goal, risk, brief, plan, task, draft, or note
ruminate_create_items	Creates up to 25 guarded entries with required summaries, per-item idempotency keys, and partial-success outcomes
ruminate_update_item	Revises, promotes, section-edits, archives, restores, or advances an existing entry
ruminate_merge_items	Merges duplicate entries while preserving provenance and a reversible revision

ruminate_undo_merge_items and ruminate_split_item are recovery operations behind the opt-in advanced capability. Reporting is also opt-in because it is outside the common read/write loop. Cached clients should reconnect after a surface change. HTTP clients opt in with X-Ruminate-Capabilities: advanced, reports, or a comma-separated list; stdio clients use the same values in RUMINATE_MCP_CAPABILITIES. Client values cannot enable administrative or compatibility groups. The retired ruminate_archive_item and ruminate_restore_item calls remain routable during their deprecation window and direct clients to ruminate_update_item({ archived: true | false }). The retired ruminate_resolve, ruminate_propose, ruminate_resolve_folder, ruminate_propose_folder, ruminate_resolve_collection, and ruminate_propose_collection calls remain routable only so cached clients fail loudly with category-only guidance. The retired ruminate_list_opinions call remains routable and directs cached clients to ruminate_list_collections. The retired ruminate_list_artefacts, ruminate_get_artefact, ruminate_write_artefact, and ruminate_update_artefact calls remain routable and direct cached clients to ruminate_list_structures, ruminate_get_structure, ruminate_write_structure, and ruminate_update_structure.

Structures

Structures keep working material agents refer to often beside the workspace — enriched slowly as context changes, or reused across high-volume workflows — without injecting long bodies into every context pack. Templates mirror forms, workflows, report structures, and presentations. Reference files hold text-readable source material. Generated outputs collect durable work such as Mermaid diagrams. Agents should list first, then fetch only the addressed ## section they need.

Citations and supporting evidence are optional linked structures, not mandatory fields on every entry or trace. Provenance remains inspectable where available; existing evidence should never be discarded merely because it is optional.

When a source is repeatedly mentioned but unavailable, agents are instructed to suggest uploading it under Structures → Reference files.

Sessions and activity

Tool	What it does
ruminate_resume_work	Returns where the latest session stopped and what it left to do
ruminate_start_session	Opens a session boundary for a stretch of work
ruminate_end_session	Closes a session with a summary and next step
ruminate_correct_handoff	Appends an attributed correction to a stale handoff without rewriting it
ruminate_list_sessions	Lists who worked here, from which client, and how the session ended
ruminate_get_activity	Lists changes, authors, sources, and timestamps

Workspace administration

These stable names predate the web app’s current terminology: in this group, a tool named project operates on what the product now calls a workspace.

Tool	What it does
ruminate_rename_workspace	Changes a workspace’s display name
ruminate_archive_workspace	Reversibly removes a workspace from active lists
ruminate_restore_workspace	Returns an archived workspace to active lists

The cached ruminate_rename_project, ruminate_archive_project, and ruminate_restore_project calls remain routable structured deprecations. The list/create names are available by default and remain ruminate_list_projects and ruminate_create_project until the hidden grouping tools currently named ruminate_list_workspaces and ruminate_create_workspace complete their own deprecation window; reusing those names sooner would silently repoint clients.

Context and reports

Tool	What it does
ruminate_compile_context	Builds a small, scored context pack for a task
ruminate_compile_report	Produces a status, handoff, decision, or onboarding report

Context-pack scores are relative ranking scores, not confidence estimates. The ranker favours title, summary, folder and collection matches, caps incidental long-body matches, and uses lifecycle state for action-shaped requests. A score is diagnostic; retrieval quality is established by useful, current selections.

Drafts

The composable item tools are the default interface. Create drafts with ruminate_create_item({ entryType: "draft" }); edit a single ## section through ruminate_update_item({ section: { slug, body } }). The draft store remains separate so list and context queries never load long bodies.

Tool	What it does
ruminate_list_drafts	Lists long-form drafts with titles, slugs, statuses, and section headings
ruminate_get_draft	Opens a whole draft or one section
ruminate_write_draft	Deprecated: use ruminate_create_item with entry type draft
ruminate_update_draft	Deprecated: use ruminate_update_item, including its section address

Typed memory compatibility

These tools expose the older, more detailed memory model. Prefer composable entries for new work unless you need typed relationships, confidence, or specialised decision and question fields.

Tool	What it does
ruminate_list_memories	Lists typed project memories
ruminate_get_memory	Opens one memory with evidence, relationships, and provenance
ruminate_record_memory	Deprecated write alias; reconnect and use ruminate_find_similar plus ruminate_create_item
ruminate_update_memory	Deprecated write alias; reconnect and use ruminate_update_item
ruminate_archive_memory	Removes a memory from active context during its retention period
ruminate_restore_memory	Restores an archived memory
ruminate_answer_question	Settles an open question and derives a reusable rule

Advanced legacy grouping

Most MVP workspaces do not need this layer. These tools group several legacy projects one level above them; they do not change organization access.

Tool	What it does
ruminate_list_workspaces	Lists advanced workspace groups and their legacy projects
ruminate_get_workspace_overview	Summarises a group, its projects, and their activity
ruminate_create_workspace	Creates an empty grouping
ruminate_upgrade_to_workspace	Turns a legacy project into a group containing that project
ruminate_move_project	Moves a legacy project into or out of a group
ruminate_move_memory	Relocates knowledge between legacy projects in one group

Team

Membership is organization-wide rather than workspace-specific.

Tool	What it does
ruminate_invite_member	Invites someone to the organization
ruminate_list_members	Lists members and pending invitations

Published prompt

Prompt	What it does
/ruminate_compose	Reads the live workspace index, asks focused questions, and composes the smallest useful set of entries

The prompt resolves current workspace state when it runs. It does not impose a blank template or create a project for every task.