Needle Agent System Facts: Environment Context Reference

Needle agents accept a read-only system turn containing eight standardized facts—date, locale, device, battery, network, location, user, and assistant—formatted as semicolon-separated key-value pairs to ground temporal reasoning and personalize responses.

The cactus-compute/needle repository provides a lightweight agent framework where system facts supply critical environmental context without issuing instructions to the model. Understanding what system facts can be provided to a Needle Agent enables developers to optimize tool use for time-sensitive operations, device constraints, and user-specific personalization. These read-only variables describe the operational environment rather than directing behavior.

Recognized System Fact Keys

The Needle engine recognizes exactly eight keys when parsing the system turn. According to doc/apis.md, these keys provide factual context about the execution environment:

• date: Current date and time (e.g., 2026-07-21 Tue 14:30). Essential for resolving relative time expressions like "tomorrow at 7" into concrete timestamps.

• locale: Locale identifier (e.g., en-US). Determines language-specific formatting and region-appropriate responses.

• device: Type of device (e.g., phone, desktop, tablet). Influences UI assumptions and capability detection.

• battery: Battery level as a percentage (e.g., 62%). Enables power-aware decision making for intensive operations.

• network: Network status or type (e.g., wifi, offline). Affects connectivity-dependent tool selection.

• location: Physical location or region (e.g., NYC). Resolves ambiguous spatial references such as "my home."

• user: Identifier for the end-user (e.g., a username or user ID). Supports personalized addressing and user-specific data retrieval.

• assistant: Identity the model should adopt (e.g., friendly_assistant). Defines the persona used in responses.

Any keys outside this enumerated set are ignored by the agent parser. The system turn containing these facts is strictly read-only; it describes state rather than issuing directives.

Formatting Syntax and Agent Construction

System facts must be passed as a single string argument to the system parameter when instantiating needle.Needle. Each key-value pair uses a colon separator, with multiple pairs delimited by semicolons and spaces:

import needle

system_facts = (
    "date: 2026-07-21 Tue 14:30; "
    "locale: en-US; "
    "device: phone; "
    "battery: 62%; "
    "network: wifi; "
    "location: San Francisco; "
    "user: alice; "
    "assistant: helpful_bot"
)

agent = needle.Needle(
    tools=[my_tool_function], 
    system=system_facts
)

In needle/__init__.py, the system argument is stored internally and passed to the native engine during agent initialization. The implementation in needle/environments/_harness.py demonstrates how the agent harness consumes this context alongside declared tools during the run() execution cycle.

Practical Implementation Examples

Grounding Temporal Expressions

The date fact enables the model to convert relative time references into absolute timestamps. When provided with a current date, the agent resolves "tomorrow" and "in 5 minutes" without requiring external API calls:

agent = needle.Needle(
    tools=[set_thermostat],
    system="date: 2026-07-21 Tue 14:30; locale: en-US; device: phone"
)

agent.run("Set the thermostat to 21 degrees tomorrow at 7")

# The model converts "tomorrow at 7" → "2026-07-22 07:00" using the date fact

Device-Aware Behavior Adaptation

Battery and network facts allow the model to defer resource-intensive operations or request confirmation before executing high-consumption tasks:

system = "battery: 15%; device: phone; locale: en-US"
agent = needle.Needle(tools=[schedule_backup], system=system)

response = agent.run("Schedule a full backup of my photos for tonight")

# The model can decide to defer or ask for confirmation because the battery is low

User Identity and Personalization

The user and assistant facts enable consistent personalization across sessions without embedding personal details in individual prompts:

system = "user: alice; assistant: friendly_helper"
agent = needle.Needle(tools=[send_message], system=system)

agent.run("Send a reminder to my calendar for tomorrow at 9am")

# The assistant may address the user as "Alice" based on the user fact

Constraints and Validation Rules

The Needle agent imposes strict constraints on system fact processing:

• Instruction Neutrality: The model treats the system turn purely as factual context. Instructions or directives placed in the system string are not honored.

• Key Whitelist: Only the eight documented keys (date, locale, device, battery, network, location, user, assistant) are processed. Unrecognized keys are silently discarded.

• Read-Only Semantics: These facts describe environmental state. They cannot trigger behavior changes directly; they only inform the model's reasoning about tool use.

Summary

• Needle agents accept eight standardized system facts (date, locale, device, battery, network, location, user, assistant) as read-only context.

• Facts are formatted as semicolon-separated key-value pairs passed to the system parameter in needle.Needle.

• These variables ground temporal reasoning, enable device-specific adaptations, and support user personalization.

• The implementation resides in needle/__init__.py and needle/environments/_harness.py, with API documentation in doc/apis.md.

• Unrecognized keys are ignored, and the system turn cannot contain executable instructions.

Frequently Asked Questions

Can I add custom system facts beyond the eight documented keys?

No. The Needle agent parser, as defined in the source code, recognizes only the eight enumerated keys. Any additional key-value pairs included in the system string are silently ignored during processing.

How does the date fact handle different timezone formats?

The date fact expects a string representation of the current date and time (e.g., 2026-07-21 Tue 14:30). While the source code does not enforce a specific timezone syntax, you should provide the time in the user's local timezone to ensure accurate resolution of relative expressions like "tomorrow at 7" into concrete timestamps.

Can system facts change during an agent session?

System facts are static for the duration of the agent instance lifecycle. As implemented in needle/__init__.py, the system parameter is stored at initialization and passed to the native engine. To update facts such as battery or date, you must instantiate a new needle.Needle agent with the updated system string.

What happens if I include instructions in the system facts string?

Instructions or directives placed in the system turn are not honored. According to the implementation, the model treats the system turn purely as factual context describing the environment. To provide instructions or behavioral guidance, use the standard prompt interface rather than the system facts parameter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}