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

```terminal
~/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:

```terminal
~/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:

```terminal
~/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](/docs/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.