> ## Documentation Index
> Fetch the complete documentation index at: https://hmm.heyhyper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ask Tool: Query Your Team's Shared Memory in Hyper

> Ask Hyper a natural-language question about your team or work. Retrieves synthesized answers from shared memory using vector search and reranking.

The `ask` tool lets you query everything your team has saved to Hyper using plain English. It uses vector search with reranking to find the most relevant memory documents, then synthesizes a coherent answer from what it finds. Whether you want to know what a teammate is working on, why a particular technology was chosen, or what decisions came out of last week's planning session, `ask` surfaces the answer without you knowing exactly where to look.

## Parameters

<ParamField name="question" type="string" required={true}>
  A natural-language question about your team, company, or work. Be specific when you can — the more context you give, the more targeted the retrieval. Examples: `"what is Maya working on?"`, `"why did we pick Postgres over MySQL?"`, `"what are the open tasks for the auth sprint?"`, `"what happened this week?"`.
</ParamField>

## Returns

<ResponseField name="answer" type="string">
  A synthesized answer drawn from the team's memory documents. The answer reflects the current state of knowledge in Hyper — it's generated at query time from retrieved context, not stored verbatim.
</ResponseField>

## How It Works

When you call `ask`, Hyper runs a vector search across your workspace's memory documents to find the most semantically relevant chunks. Those chunks are reranked for relevance, then passed to the synthesis layer, which composes a coherent answer. The whole pipeline runs in a single call — you get a ready-to-read answer, not a list of raw documents.

## Example Calls

### Technology decision

```python theme={null}
ask("why did we choose PostgreSQL over MySQL?")
```

```text theme={null}
Answer: The team chose PostgreSQL for row-level security (RLS), which is
essential for multi-tenant data isolation. MySQL's RLS support was
considered immature at the time of the decision (Q3 2024).
```

### Teammate status

```python theme={null}
ask("what is Marcus working on right now?")
```

```text theme={null}
Answer: Marcus is currently focused on the AML (anti-money laundering)
integration for the payments module. He's targeting a code-complete date
of May 9th and is blocked on API credentials from the compliance team.
```

### Open tasks

```python theme={null}
ask("what are the open tasks for the auth sprint?")
```

```text theme={null}
Answer: The following items are still open in the auth sprint:
- Row-level security implementation (Alex, in progress)
- OAuth token rotation endpoint (unassigned)
- Session invalidation on password reset (Maya, in review)
```

### Recent events

```python theme={null}
ask("what happened this week?")
```

```text theme={null}
Answer: This week the team merged the new onboarding flow, deferred the
billing integration to Q3, and started the RLS implementation. Maya's
PR for onboarding is in review. The team also resolved the staging
environment issue that was blocking QA.
```

## When to Use ask vs. ask-with-history

`ask` returns the **current state** of the answer — what Hyper knows right now. It's fast and the right tool for the vast majority of questions.

Use [`ask-with-history`](/mcp/tools/ask-with-history) instead when you explicitly need to understand **how something changed over time** — for example, "how has our pricing evolved?" or "what did the team decide about X before we reversed course?" If the question is "what is X right now?", `ask` is faster and sufficient.

<Tip>
  The `UserPromptSubmit` lifecycle hook calls `ask` automatically with your message text before the model responds. This means your AI assistant already has relevant team context pulled in before it formulates a reply — you don't need to call `ask` manually in most workflows.
</Tip>

## Tips for Better Answers

* **Name people specifically** — "what is Alex working on?" returns more targeted results than "what is the team working on?"
* **Reference project names** — "what's the status of the RLS project?" is better than "what's the status of the database work?"
* **Ask for reasoning** — "why did we decide to use edge caching?" surfaces rationale that `remember` captured alongside outcomes.
* **Use time references** — "what happened last week?" or "what did we decide in Q1?" constrains retrieval temporally.