Context Management

Orbitmap's core value is persistent context. Your agents don't start from scratch - they access the history of prior work, decisions, and documentation.

Using Task History

When you reference a previous task, the agent loads its full context - logs, decisions, code changes, and status.

~/my-project

❯ HAL, we need to change how the auth
  middleware works. You implemented it in
  task TS-r2d2x1 - check what you did.

HAL: Loading task context...
✓ get_tasks(task_id='TS-r2d2x1')

Task TS-r2d2x1 - Set up authentication flow
Status: done

Work logs (4 entries):
1. [code_change] Created SupabaseAuth
   middleware, AuthController, login/register
   views with Livewire components
2. [decision] Used JWT validation via
   firebase/php-jwt instead of Sanctum
3. [decision] Chose Redis session driver
4. [note] Ready for review - all auth tests
   pass

I see the original implementation. The
middleware validates JWT tokens using
firebase/php-jwt. What change do you need?

Cross-entity Context

The same pattern works across all entity types - issues, vibes, documents, and ideas:

~/my-project

❯ JARVIS, remember that vibe where we
  explored Edge Functions? Check the vibes
  from last week.

JARVIS: Searching vibes...
✓ get_vibes()

Found vibe from 2026-03-11:
"Explored Supabase Edge Functions for
webhook processing. Promising but too
immature - missing retry logic and DLQ."

❯ Also check issue IS-err99x, it might be
  related

✓ get_issues(issue_id='IS-err99x')

IS-err99x - Timeout on large CSV export
Status: open
These could be related - both involve async
processing bottlenecks...

Token-Efficient Document Access

AI agents have limited context windows - every token counts. Orbitmap's document system is designed to minimize how much an agent needs to read before finding the right information.

Every document has a short context field (a few sentences) visible in document listings. This lets the agent decide which document is relevant without opening it. Once the right document is identified, the agent fetches only its table of contents (~200 tokens) - not the full content. From the TOC, the agent pinpoints the exact section it needs and fetches just that section (~500 tokens).

The result: an agent working with a 5,000-token document typically consumes only ~700 tokens - the context field, the TOC, and one section. The full document is never loaded unless explicitly needed.

This three-tier reading flow works like this:

~/my-project

❯ CORTANA, how does our auth middleware
  validate tokens?

CORTANA: Let me find the right document...

✓ get_project_docs()
  → 8 documents found
  → "Architecture Guide" context says:
    "Covers auth, middleware, DB schema..."
  → This is the one.

✓ get_document('arch-guide')
  → TOC: 14 sections
  → "## Authentication Flow" looks right

✓ get_document('arch-guide',
  section='## Authentication Flow')
  → 480 tokens loaded (not 5,200)

The SupabaseAuth middleware validates JWT
tokens using firebase/php-jwt on every
request. Tokens are checked for expiry and
signature validity against the Supabase
JWT secret...

This approach has three key benefits:

• Context window efficiency - agents preserve their limited context for reasoning and code, not for reading documentation they don't need
• Faster responses - less data to process means the agent responds quicker
• Scales with project size - whether your project has 3 documents or 30, the agent's token cost stays roughly the same per lookup

The same efficiency applies to editing - agents can patch a single section without downloading or re-uploading the entire document.

For details on how documents are imported, shared, and read, see Project Documentation.

Orbit - Contextual Grouping

Orbits let you group related tasks, issues, ideas, and documents into a thematic collection. Think of an Orbit as a "feature area" or "initiative" that spans multiple entities.

For example, an Orbit called "Authentication Overhaul" might contain:

• 3 tasks (implement, test, document)
• 1 issue (the bug that triggered the overhaul)
• 2 documents (auth spec, migration guide)
• 1 idea (future SSO support)

Agents can query orbits to get the full picture of an initiative, including all related entities and their current state.