Append a note to an existing idea when current work confirms, sharpens, corrects, or extends it. Use when: the current task materially updates an existing idea; you want to attach new evidence or a correction; you do not want to create a separate idea. Optional kind labels the note semantically (confirmation, counterexample, observation, follow-up, question, correction). Optional task_ref groups all writes from the same task and is normalized to lowercase kebab-case at the boundary.

Archive an idea (sets archived_at, writes kind='archive' note with reason). Idempotent. Archived ideas are excluded by default from list/search/dump.

Capture a new durable idea. Use when: you reach a stable synthesis; you discover a reusable pattern; you want a standalone idea that should survive task boundaries; a checkpoint has hardened into a first-class concept. If you only need a lightweight in-progress trace, use checkpoint instead. content is required. scope and actor default from cwd and environment. Optional task_ref groups all writes from the same task; it is normalized to lowercase kebab-case at the boundary, so 'Writeback Phase 1', 'writeback_phase_1', and 'writeback-phase-1' collapse onto the same key. Returns annotate_candidates and related_candidates so the next memory move is obvious. candidates (default 5, max 10, 0 to skip) controls how many annotate/related suggestions are returned — set to 0 for a fire-and-forget trace where you don't intend to act on suggestions, or raise to 10 when actively triaging. Deduplication: same actor + same content within 5 seconds is silently treated as the same write. Beyond the 5-second window, or across actors, content with the same SHA-256 hash (whitespace-collapsed, lowercased) in the same scope dedupes against the original idea — incoming tags are merged in and a dup_attempt note is appended for provenance.

Write a lightweight working-memory trace during a task. Use when: you form a non-trivial synthesis mid-task; you make a decision the session will depend on; you want a durable breadcrumb without promoting it to a full idea yet; you want to leave a visible trace of what changed in your understanding during the task. Do not use for final, standalone ideas that should survive the task — use capture for those. Optional task_ref groups all writes from the same task; it is normalized to lowercase kebab-case at the boundary, so casing and whitespace variants collapse onto the same key. Optional kind_label is a semantic hint (observation | decision | assumption | question | next_step). Returns scored annotate_candidates (existing ideas this trace may update) and related_candidates so the next memory move is obvious. candidates (default 5, max 10, 0 to skip) controls how many annotate/related suggestions are returned — set to 0 for a fire-and-forget trace where you don't intend to act on suggestions, or raise to 10 when actively triaging.

Dump the scoped corpus as a single text blob under a token budget. Use for orientation — 'what does this repo/user think about?'. Newest ideas first, latest note inlined by default, archived excluded by default. By default excludes kind='checkpoint' rows; pass include_checkpoints=True to include them.

Get a single idea by id with its notes and outbound links.

Connect two ideas when current work reveals they are structurally related, evolved, duplicated, superseding, part of a whole, or answering a question. kind ∈ {related, supersedes, evolved_from, duplicate, part_of, answers}. part_of goes from the part to the whole; answers goes from the answer to the question. related is canonicalized (smaller id becomes source). Self-links rejected. Optional task_ref groups all writes from the same task and is normalized to lowercase kebab-case at the boundary.

List ideas with filters (scope, actor, originator, tags_any, tags_all, since, until). Returns id, scope, actor, preview (120 chars), and created_at. Archived excluded by default. By default excludes kind='checkpoint' rows; pass include_checkpoints=True to include them.

Cheap health probe. Returns server name, package version, and store path. Use to confirm the ideahub_mcp server is connected and responsive.

Promote a checkpoint to a durable idea. Use when: a working-memory trace turns out to be load-bearing — the synthesis has hardened, the decision is stable, the observation is reusable. The id is preserved, so existing links, annotations, and task_ref groupings carry forward unchanged. A kind='promotion' note records the original kind_label for provenance. Promotion is one-way: an idea cannot be demoted back to a checkpoint.

Inspect the actor table. Pass id for detail on one actor; omit to list all.

Register an actor without writing an idea. Use before passing a person as originator (e.g. id='human:michael') when they have never written themselves. id must start with 'human:' or 'agent:'. Idempotent: an existing actor is returned unchanged with created=false. display_name only applies on first registration.

Find ideas related to the given id. Scoring: (1) tag overlap DESC, (2) shared originator (True first), (3) recency DESC. Within source scope unless cross_scope=True; archived excluded by default. By default excludes kind='checkpoint' rows; pass include_checkpoints=True to include them.

Full-text search ideas with FTS5 + bm25 ranking. Returns snippet, score, and id. Scope-optional; archived excluded by default. By default excludes kind='checkpoint' rows; pass include_checkpoints=True to include them. query_mode (default 'auto') controls how query is interpreted: 'auto' tokenizes and quotes the query so hyphens, colons, asterisks and other FTS5 operators are treated as content (use this when searching for kebab-case identifiers like task_refs or branch names); 'raw' passes the query through unchanged for FTS5 phrase, NEAR, or column-qualified syntax and raises a loud error on syntax failure.