Token-Budget Briefing (Prime)

Orient your AI agent at startup with a single, consolidated, and token-budget-aware command. The prime command generates a unified briefing that auto-scales to fit within a specified token limit.

Why use Prime?

Normally, briefing an AI agent requires running multiple commands (e.g. retrieving product context, active context, listing decisions, checking progress, and querying patterns). This causes high latency and manual overhead.

The prime command solves this by fanning out database queries, joining relevant metadata (like PRs and anchors), and packaging the result into a single JSON object.

How to use Prime

# Get a full, unconstrained briefing
engrams prime

# Get a briefing constrained to approximately 1000 tokens
engrams prime --budget 1000

Understanding Token Scaling

When you pass the optional --budget parameter, Engrams estimates the token count of the output payload (calculated as JSON string length divided by 4). If the estimated size exceeds your budget, it automatically discards less critical context sections to fit the boundary in the following order:

  1. Progress logs: Discarded first (newest to oldest).
  2. System patterns: Discarded next.
  3. Decisions: Discarded after patterns.
  4. Product Context: Set to null as a last resort.

Note: The active-context is never discarded as it contains the immediate goals, open questions, and next steps for the current session.

Briefing Content

A fully resolved briefing includes:

  • Product Context: High-level overview, target audience, and architecture.
  • Active Context: Current session focus, open questions, and next steps.
  • Decisions: Up to 10 active architectural decisions with their associated file anchors and pull request links.
  • Patterns: Up to 10 codebase patterns/conventions with their associated anchors and pull requests.
  • Progress: Up to 10 latest progress entries.

Example Output

{
  "product_context": {
    "content": "Building a high-performance CLI tool...",
    "timestamp": "2026-07-12T12:00:00Z"
  },
  "active_context": {
    "content": "Focusing on documentation and developer setup.",
    "timestamp": "2026-07-12T12:30:00Z"
  },
  "decisions": [
    {
      "id": 1,
      "uuid": "e44d03e1-7ceb-419b-b0b3-96b613271708",
      "summary": "Use SQLite FTS5 for local search",
      "rationale": "Fast and zero dependency",
      "implementation_details": "Create triggers for FTS tables",
      "tags": ["db", "search"],
      "timestamp": "2026-07-12T10:00:00Z",
      "status": "active",
      "commit_sha": "d41d8cd98f00b204e9800998ecf8427e",
      "pr_urls": [
        "https://github.com/stevebrownlee/engrams-cli/pull/42"
      ],
      "anchors": [
        "src/schema.rs"
      ]
    }
  ],
  "patterns": [],
  "progress": [],
  "budget": {
    "limit": 1000,
    "estimated_tokens": 420
  }
}