Needle System Facts: Complete List of Recognized Keys and Usage Guide

Needle recognizes eight specific keys for system facts—date, locale, device, battery, network, location, user, and assistant—and silently ignores any other keys you provide.

The Needle inference engine from Cactus Compute lets you supply contextual environment information through a system turn. This feature helps the model resolve relative references, adapt to device constraints, and personalize responses. According to the cactus-compute/needle source code, only a closed set of keys triggers special model behavior; unrecognized keys pass through as plain text without affecting grammar or tool selection.

How System Facts Work in Needle

When you initialize a Needle instance, the system parameter accepts a UTF-8 string that the native engine parses into structured facts. In needle/__init__.py (lines 55-64), the Python binding encodes this string and passes it to needle_init. The engine expects semicolon-separated key: value pairs, then extracts only the recognized keys for its internal context.

This design means you can safely experiment with custom metadata—anything outside the eight official keys simply won't influence the model's reasoning.

Complete List of Needle System Fact Keys

Based on the canonical documentation in llms.txt (lines 36-40) and doc/apis.md (lines 36-45), Needle supports the following keys:

Key	Purpose	Example Value
date	Current date and time	2026-07-21 Tue 14:30
locale	Language and region code	en-US, fr-FR
device	Hardware form factor	phone, laptop, tablet
battery	Power level or charging status	62%, charging
network	Connectivity state	wifi, offline, cellular
location	Geographic identifier	NYC, Paris
user	End-user identifier	alice@example.com
assistant	Assistant persona name	my-assistant

These keys are case-sensitive and must match exactly. The model uses this context to resolve ambiguities—for example, interpreting "tomorrow" relative to the provided date or selecting tools based on device capabilities.

Code Examples

Basic Usage with Common Facts

import needle

# Initialize with essential context

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

# The model resolves "tomorrow at 7" using the provided date

response = agent.complete("Remind me tomorrow at 7 to call Mom")
print(response["function_calls"])

Full System Turn with All Recognized Keys

# Comprehensive environment description

system_facts = (
    "date: 2026-09-15 Thu 09:00; "
    "locale: fr-FR; "
    "device: laptop; "
    "battery: 45%; "
    "network: wifi; "
    "location: Paris; "
    "user: jean@example.com; "
    "assistant: my-assistant"
)

agent = needle.Needle(tools=my_schema, system=system_facts)
print(agent.run("What's the weather like tomorrow?"))

Omitting System Facts Entirely

# Safe to initialize without context

agent = needle.Needle(tools=my_schema)
print(agent.complete("What time is it?"))

Key Implementation Files

Understanding the source helps avoid common pitfalls:

• llms.txt – The authoritative reference listing recognized keys and their semantics.
• doc/apis.md – Public API documentation with usage patterns and validation rules.
• needle/__init__.py – Python binding implementation showing how system strings are encoded and validated before native engine handoff.

Common Mistakes to Avoid

• Typos in keys: battery_level will not trigger battery-aware behavior—use battery exactly.
• Wrong separator: Use semicolons between pairs, not commas or newlines.
• Over-quoting: Pass the raw string; the library handles UTF-8 encoding internally.

Summary

• Needle recognizes eight system fact keys: date, locale, device, battery, network, location, user, and assistant.
• Format facts as semicolon-separated key: value pairs in the system parameter.
• Unrecognized keys are silently ignored—they don't cause errors but don't affect model behavior either.
• Source documentation lives in llms.txt and doc/apis.md, with implementation details in needle/__init__.py.

Frequently Asked Questions

What happens if I use a key that's not in the recognized list?

Unrecognized keys are treated as plain text and ignored by the model's context system. They pass through to the native engine without influencing grammar, tool selection, or reasoning. The llms.txt specification explicitly states this behavior for forward compatibility.

Can I update system facts after creating a Needle instance?

No. The system parameter is processed once during initialization in needle/__init__.py. To change facts, create a new Needle instance with updated values. This design keeps the native engine context immutable during inference.

Does the date key require a specific format?

While the examples show YYYY-MM-DD Ddd HH:MM, the engine accepts any reasonably unambiguous datetime string. The model extracts temporal references relative to whatever timestamp you provide, so consistency matters more than strict formatting.

Is the system parameter optional?

Yes. As shown in the third code example, needle.Needle() initializes successfully without a system argument. The model simply operates without environmental context, which may reduce accuracy for time-sensitive or location-dependent queries.

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