# How to Reset the Conversation State in Needle 2: Complete Developer Guide

> Learn to reset conversation state in Needle 2 using Needle.reset() or the /reset endpoint. Start fresh conversations with this developer guide.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Call `Needle.reset()` to clear the engine's internal buffers and start a fresh conversation, or use the `/reset` HTTP endpoint when running the playground server.**

Needle 2 is a Python-native LLM inference library that maintains dialogue state inside a C++ shared library. When you need to discard conversation history and temporary state, the library exposes a clean reset mechanism through both its Python API and HTTP interface. This guide walks through the implementation details and practical usage based on the `cactus-compute/needle` source code.

## Understanding Needle 2's State Management

Needle 2 separates its architecture into two layers: a **native C++ engine** bundled as a shared library, and a **Python wrapper** that provides the public interface. Each `Needle` instance binds to the engine on first use, and all conversation context—including dialogue history, pending token buffers, and temporary state—lives inside that native layer.

This design means you cannot simply instantiate a new Python object to clear state. Instead, you must explicitly invoke the reset pathway that reaches into the shared library.

## Method 1: Using the Python API (Needle.reset)

The primary way to reset conversation state is calling `Needle.reset()`. In [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), this method is implemented as follows:

```python
def reset(self):
    self._bind()
    _lib().needle_reset()

```

The method performs two critical operations:

- **`self._bind()`** — Ensures the current `Needle` instance is registered as the active one in the engine, handling cases where multiple instances might exist
- **`_lib().needle_reset()`** — Forwards the reset request to the native C-API function, which clears all internal buffers

### Complete Python Example

```python
from needle import Needle

# Create an agent (optionally with tools, system prompt, etc.)

agent = Needle(tools=None, system="You are a helpful assistant")

# Run a few steps of a conversation

response1 = agent.run("What is the weather in Paris?")
print(response1["type"], response1["content"])

# Reset the conversation state – all previous context is discarded

agent.reset()

# Start a new conversation – the engine behaves as if it has just been initialized

response2 = agent.run("What is the capital of Italy?")
print(response2["type"], response2["content"])

```

After `reset()` returns, the engine contains no memory of prior exchanges. Subsequent `run()` calls operate on a clean state equivalent to a freshly initialized instance.

## Method 2: Using the HTTP Playground Endpoint

When running Needle 2's built-in playground server, you can trigger resets remotely via HTTP. The `/reset` endpoint in [`needle/playground/server.py`](https://github.com/cactus-compute/needle/blob/main/needle/playground/server.py) exposes the same functionality:

```python
@app.post("/reset")
async def reset():
    engine.reset()
    return {"status": "ok"}

```

This handler calls `engine.reset()` on the underlying `Needle` object—identical to the direct Python API method.

### HTTP Reset Example

```bash

# Trigger a reset via the server

curl -X POST http://localhost:8000/reset

```

The server responds with a simple status confirmation, and the engine immediately clears its state.

## Key Implementation Files

Understanding the reset pathway requires familiarity with these source locations:

| File | Purpose | Line Reference |
|------|---------|----------------|
| [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) | Python `Needle.reset()` implementation | [L66-L68](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py#L66-L68) |
| [`needle/playground/server.py`](https://github.com/cactus-compute/needle/blob/main/needle/playground/server.py) | HTTP `/reset` endpoint handler | [L141-L144](https://github.com/cactus-compute/needle/blob/main/needle/playground/server.py#L141-L144) |

These two files constitute the complete reset surface area in Needle 2. No other public API methods or configuration flags affect conversation state clearing.

## When to Reset vs. Create New Instances

**Reset the existing instance** when you want to preserve configuration (system prompts, tool bindings, sampling parameters) but discard dialogue history. This avoids repeated binding overhead and maintains any per-instance settings.

**Create a new `Needle` instance** when you need different configuration for the next conversation. Each new instance performs its own `_bind()` call on first use, effectively starting fresh without an explicit reset.

## Summary

- **Primary method**: Call `Needle.reset()` to clear native engine buffers via the C-API function `needle_reset`
- **HTTP alternative**: POST to `/reset` when using the playground server
- **Implementation**: Located in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py) (Python) and [`needle/playground/server.py`](https://github.com/cactus-compute/needle/blob/main/needle/playground/server.py) (HTTP)
- **Effect**: Complete erasure of dialogue history and temporary state without reconfiguration

## Frequently Asked Questions

### What happens if I don't call reset() between conversations?

The engine retains all prior context, causing the model to see accumulated dialogue history. This increases token usage and may cause the model to reference previous exchanges unexpectedly.

### Is reset() thread-safe in Needle 2?

The `reset()` implementation calls `_bind()` first, which establishes the calling instance as active. While this handles multiple Python instances, concurrent access to a single `Needle` instance should be serialized at the application level—the underlying C++ engine does not provide internal locking for reset operations during active generation.

### Can I reset state without the Python wrapper?

Direct C-API access is possible by loading the shared library and calling `needle_reset()`, though this is unsupported and bypasses the `_bind()` safety mechanism. The Python wrapper is the intended interface for all state management operations.

### Does reset() affect tool definitions or system prompts?

No. The reset operation clears **state buffers only**—dialogue history, pending tokens, and temporary computation state. Any tool bindings, system prompts, or sampling parameters passed to the `Needle` constructor remain intact.