# Needle Agent System Facts: Environment Context Reference

> Discover what system facts Needle Agent accepts including date locale device battery network location user and assistant to enhance temporal reasoning and personalize responses. Learn more.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-08-28

---

**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`](https://github.com/cactus-compute/needle/blob/main/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:

```python
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`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) and [`needle/environments/_harness.py`](https://github.com/cactus-compute/needle/blob/main/needle/environments/_harness.py), with API documentation in [`doc/apis.md`](https://github.com/cactus-compute/needle/blob/main/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`](https://github.com/cactus-compute/needle/blob/main/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.