# ideahub_mcp

An agent-first [MCP](https://modelcontextprotocol.io) server for capturing and recalling ideas — the agent's and their human's.

The primary user is a model. Tools are short, imperative, example-laden; errors carry a repair path; scope and actor resolve from context so the agent doesn't have to ask.

## Tools

| Tool         | Purpose                                                                                 |
| ------------ | --------------------------------------------------------------------------------------- |
| `capture`    | Durable idea. Use when work produces something worth preserving beyond the task.        |
| `checkpoint` | Lightweight working-memory trace. Use mid-task for observations, decisions, next steps. |
| `promote`    | Promote a checkpoint to a durable idea, preserving its id, links, and provenance.       |
| `dump`       | Text-blob summary of the scoped corpus under a token budget.                            |
| `search`     | FTS5 + bm25 ranked search with snippets. Auto-tokenizes by default.                     |
| `list`       | Filter ideas by scope, actor, tags, date range.                                         |
| `get`        | Full detail for one idea, with notes and outbound links.                                |
| `related`    | Nearest neighbors by tag overlap → shared originator → recency.                         |
| `annotate`   | Append a free-text note to an idea without mutating it.                                 |
| `archive`    | Hide an idea; write a typed `archive` note with reason.                                 |
| `link`       | Connect two ideas (`related`, `supersedes`, `evolved_from`, `duplicate`, `part_of`, `answers`). `part_of` goes from the part to the whole; `answers` from the answer to the question. |
| `recognize`  | Inspect the actor table.                                                                |
| `register`   | Add an actor (e.g. `human:you`) so it can be an `originator`. Idempotent.               |
| `ping`       | Cheap no-side-effect health probe for connection/debugging.                             |

## Writeback Loop

`ideahub_mcp` is designed to behave like working memory for an agent, not just searchable storage. Two write verbs close that loop:

- `capture` writes a durable idea that should survive the task.
- `checkpoint` writes a lightweight in-flight trace — observations, decisions, assumptions, open questions — without the semantic weight of a full idea.

When a checkpoint hardens into something load-bearing, `promote` flips its kind to `idea` while preserving the id, so existing links, annotations, and `task_ref` groupings carry forward unchanged. Promotion is one-way; an idea cannot be demoted.

All write-path verbs (`capture`, `checkpoint`, `annotate`, `link`) accept an optional `task_ref` — a free-form string that groups every write 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.

`capture` and `checkpoint` return scored `annotate_candidates` and `related_candidates` in their response so the model sees where a fresh trace probably belongs (usually as an annotation on an existing idea) without having to search. The `candidates` parameter (default 5, max 10, 0 to skip) lets a caller cap or skip that envelope when fire-and-forget is the right move.

Checkpoints are default-excluded from `search`, `list`, and `dump` so cheap traces do not bleed into orientation surfaces — opt in with `include_checkpoints=True`.

## Deduplication

`capture` runs two dedup paths before inserting:

- **Fast path** — same actor, same content, same scope, within 5 seconds: silently returns the existing id. This catches accidental double-fires.
- **Content-hash path** — same scope, same SHA-256 over normalized content (whitespace-collapsed, lowercased), any actor, any time, against live (non-archived) `kind='idea'` rows: returns the existing id, merges incoming tags into the row, and appends a `kind='dup_attempt'` note recording the second actor and tag delta.

Hash dedup makes re-derivation of the same idea observable in the row's note stream rather than silently creating duplicates.

## Search

`search` defaults to `query_mode='auto'`, which tokenizes the query and quotes each token so FTS5 operators (`-`, `:`, `*`, etc.) are treated as content. This is the right mode for searching kebab-case identifiers — task_refs, branch names, ULIDs.

For phrase queries, `NEAR`, or column-qualified syntax, pass `query_mode='raw'`. Raw mode validates the query and raises a loud error on syntax failure rather than the silent empty-result FTS5 returns by default.

## Discovery And Health

`ideahub_mcp` is intentionally tool-first, not resource-first. A client may show a healthy connection even when `list_resources()` is sparse or empty.

To make discovery cheap and host-agnostic, the server exposes:

- `ping`: a no-side-effect tool for "is the server connected and responsive?"
- `ideahub://status`: a status resource that reports package version, storage paths, and the current tool surface.

That design supports hosts that favor different MCP surfaces. Some clients reason primarily over tools. Others probe resources first. A healthy server should be easy to verify in either style.

For the full compatibility rubric, see [docs/mcp-health.md](docs/mcp-health.md).

## Direction

- [Direction: IdeaHub as the foundation for Grok Native](docs/direction-grok-native.md): one shared source of truth that many agents read and one writer appends to.
- [Sidecars](docs/sidecars.md): the transcript ingester, health check, and activity-log pipeline that run next to this package, outside it.

## Install

```bash
uvx ideahub_mcp        # try it
uv tool install ideahub_mcp   # keep it around
```

## Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "ideahub": {
      "command": "uvx",
      "args": ["ideahub_mcp"],
      "env": {
        "IDEAHUB_MCP_HOME": "/Users/you/.ideahub_mcp",
        "IDEAHUB_ACTOR": "human:you"
      }
    }
  }
}
```

## Configuration

| Var                | Default            | Purpose                                          |
| ------------------ | ------------------ | ------------------------------------------------ |
| `IDEAHUB_MCP_HOME` | `~/.ideahub_mcp/`  | Data directory (SQLite store, logs, backups).    |
| `IDEAHUB_ACTOR`    | —                  | Default actor id (`human:you` or `agent:name`).  |
| `IDEAHUB_SCOPE`    | —                  | Fallback scope when cwd isn't a git repo.        |

Actor resolution: explicit arg → `IDEAHUB_ACTOR` → MCP `clientInfo.name` → error.

The actor name is a label set by the caller (the `actor` argument, `IDEAHUB_ACTOR`, or the client's name). It is not a login check or authentication.

Scope resolution: explicit arg → `IDEAHUB_SCOPE` → `repo:<git-toplevel>` → `global`.

## Storage

One SQLite file with WAL, FTS5, and hand-rolled migrations. No ORM. Daily snapshots to `$IDEAHUB_MCP_HOME/backups/` with 14-day retention.

## Develop

```bash
uv sync --dev
uv run pytest
uv run ruff check .
uv run pyright
```

## License

MIT.