> ## 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.
# Agents in Hyper: Lifecycle, Access, and Best Practices
> Learn how AI agents interact with Hyper across their session lifecycle, how to configure automatic hooks, and how agents should handle memory reads and writes.
Hyper is designed from the ground up with AI agents as the primary audience. Humans set things up, but agents do the reading. Every document in your workspace — every decision logged, every status captured, every goal recorded — is written so that a future AI agent can pick it up, understand it without clarification, and act on it immediately. This page explains how agents connect to Hyper, what happens at each phase of their lifecycle, and how they should behave when interacting with workspace memory.
## The agent lifecycle
An agent's interaction with Hyper spans three phases: session start, active work, and session end. Configure your AI client's hooks to trigger these phases automatically so no memory step gets skipped.
When a new session begins, the agent calls `connect()`. Hyper authenticates the session, identifies the active workspace, and returns a **briefing**: a synthesized digest of the team's current state, recent decisions, active goals, and any blockers.
```text theme={null}
connect(tz="America/Los_Angeles")
```
The briefing is not a raw dump of workspace documents — it's a curated summary generated for this specific agent, prioritizing what's most likely to be relevant to the session ahead. Agents should treat the briefing as ground truth for the current session and not ask follow-up questions about basic context it contains.
If you configure your AI client to run `connect()` automatically on session start via a system prompt or hook, agents will always be briefed without you having to remember to trigger it manually.
During an active session, agents should call `ask()` or `ask_with_history()` when a user asks something that might have an established answer in workspace memory — architecture questions, past decisions, team ownership, active constraints.
```text theme={null}
ask("What's our policy on third-party API retries?")
```
```text theme={null}
ask_with_history("How did we arrive at the current DB schema for payments?")
```
`ask()` returns the current synthesized answer. `ask_with_history()` returns the same answer plus the history of how that decision evolved over time, so the agent (and user) can trace the reasoning behind the current state.
Running these calls in the **background** — before composing a response — keeps latency low. The agent doesn't need to surface the retrieval step to the user unless the retrieved context is directly relevant to the reply.
When a session ends, the agent reviews the conversation and calls `remember()` for anything worth preserving. This is the most important step: a session that produces a decision, surfaces a constraint, or changes a status and doesn't call `remember()` is dead knowledge.
```text theme={null}
remember("Confirmed that the Stripe webhook retry handler now uses exponential
backoff with a max of 5 attempts. Previous implementation used fixed 30s
intervals, which caused duplicate charge events under load. Fix deployed in
PR #412.")
```
If the agent discovered that something in workspace memory is outdated or wrong during the session, it calls `correct()` here — not `remember()`.
Do not let agents call `remember()` for every message in a conversation. Memory writes cost **2,000 tokens each**. Reserve `remember()` for genuinely durable information: decisions, resolutions, status changes, and constraints.
## Writing for future agents
Every memory an agent writes should be readable by a future agent that has zero session context. Write with that reader in mind:
**Tag observations clearly.** When an agent adds an inference or interpretation — not a direct user statement — it should mark it:
```text theme={null}
remember("Auth latency spiked on 2025-06-08 during the migration. [agent note:
likely caused by connection pool exhaustion — observed 500ms+ P99 on auth
endpoints for 20 minutes post-deploy. Not confirmed by user but correlates with
migration timing.]")
```
**Capture the WHY, not just the WHAT.** A future agent reading "we use tRPC" can infer almost nothing useful. A future agent reading "we use tRPC for end-to-end type safety across the monorepo — evaluated GraphQL, ruled out due to schema stitching complexity" knows what to preserve and what would break if changed.
**Write in complete sentences, past tense for events, present tense for standing facts.** Structured but human-readable. Avoid bullet-only formatting — prose survives synthesis better.
Before calling `remember()`, confirm the content passes these checks:
* **Is it durable?** Will it still be true and relevant in a week?
* **Is it team-relevant?** Would another agent or teammate benefit from knowing this?
* **Does it include the WHY?** Is the rationale captured, not just the outcome?
* **Is it already in memory?** If yes, use `correct()` to update, not `remember()` to duplicate.
* **Is it inferential?** If the agent derived it rather than the user stating it, is it tagged with `[agent note]`?
## Handling contradictions
Agents will sometimes encounter a conflict between what a user says in a session and what's stored in workspace memory. Handle this explicitly — never silently fix a contradiction.
The correct pattern:
1. **Flag the conflict to the user.** "Workspace memory says we use Supabase Auth, but you've mentioned Firebase. Which is current?"
2. **Let the user confirm** before writing any correction.
3. **Call `correct()` with the confirmed truth**, not `remember()` with the new version alongside the old.
Silently accepting what the user says and writing it as a new memory creates a split-brain state where different agents get contradictory briefings depending on which document they happen to retrieve first.
If an agent is operating in a fully automated pipeline with no human in the loop and encounters a contradiction, it should halt the memory write and surface the conflict in its output for a human to resolve.
## Background vs. foreground calls
Not all Hyper calls need to be visible to the user:
| Call | Recommended mode | Reason |
| -------------------- | ----------------------------------- | ------------------------------------------------------------------- |
| `connect()` | Foreground (show briefing) | Users benefit from seeing the current state |
| `ask()` | Background | Retrieval enriches answers; users don't need to see the lookup |
| `ask_with_history()` | Foreground when history is relevant | Show the history when a user explicitly asks "how did we get here?" |
| `remember()` | Background with summary | Log silently; surface a brief "Saved to memory" confirmation |
| `correct()` | Foreground | Always confirm corrections with the user before writing |
| `mute()` | Foreground | Users should know when incognito mode is active |
## Access control for agents
Agents inherit the permissions of the authenticated user whose session they're running in. An agent running in an admin's session can write to org-level documents through the memory pipeline. An agent running in a member's session is restricted to the member's own areas and the shared feed.
Writes from admin sessions propagate to org/identity.md, org/decisions.md, and org/goals.md through the synthesis pipeline.
Writes from member sessions go to people/{name}/\* and feed.md. Org-level writes are still routed and synthesized but cannot override protected sections.
Never share admin credentials across agents or embed them in automated pipelines without careful review. An admin-level agent that misbehaves — or is fed adversarial input — can overwrite org-level documents that shape every future agent's understanding of your company.