Skip to main content
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.
1

SessionStart — Brief and orient

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.
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.
2

Per-message — Query before answering

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.
ask("What's our policy on third-party API retries?")

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.
3

Stop — Observe and remember

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.
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: 
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:
CallRecommended modeReason
connect()Foreground (show briefing)Users benefit from seeing the current state
ask()BackgroundRetrieval enriches answers; users don’t need to see the lookup
ask_with_history()Foreground when history is relevantShow the history when a user explicitly asks “how did we get here?”
remember()Background with summaryLog silently; surface a brief “Saved to memory” confirmation
correct()ForegroundAlways confirm corrections with the user before writing
mute()ForegroundUsers 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.

Admin agent

Writes from admin sessions propagate to org/identity.md, org/decisions.md, and org/goals.md through the synthesis pipeline.

Member agent

Writes from member sessions go to people//* 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.