> ## Documentation Index
> Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning Configuration

> Customize how Honcho reasons over peers, sessions, and messages

Honcho's reasoning can be configured at multiple levels to control how it processes messages, generates conclusions, creates summaries, and builds peer representations.

Configuration follows a hierarchy: **message > session > workspace > global defaults**. Settings at lower levels override those at higher levels, giving you fine-grained control over behavior.

## Configuration Hierarchy

Honcho uses a hierarchical configuration system where more specific settings override more general ones:

1. **Global Defaults**: Built-in system defaults
2. **Workspace Configuration**: Settings that apply to all sessions in a workspace
3. **Session Configuration**: Settings that apply to all messages in a session
4. **Message Configuration**: Settings that apply to a specific message

Separately, you can configure the reasoning status of a peer. This overrides defaults and workspace configuration, but not session or message configuration.

> [!NOTE]
>
> All configuration fields are optional. If not specified, the value is inherited from the next level up in the hierarchy.

## Replacing and clearing workspace configuration

Workspace `set_configuration()` (Python) and `setConfiguration()` (TypeScript)
replace the **entire** stored workspace configuration, rather than merging it.
Include every setting you want to retain. Passing an empty object clears all
explicit workspace settings, so global defaults apply again. Session and message
overrides are unaffected.

```python Python theme={null}
honcho.set_configuration({"summary": {"enabled": True}})
honcho.set_configuration({})  # Clear explicit workspace settings
assert honcho.get_configuration().model_dump(exclude_none=True) == {}
```

```typescript TypeScript theme={null}
await honcho.setConfiguration({ summary: { enabled: true } });
await honcho.setConfiguration({}); // Clear explicit workspace settings
console.log(await honcho.getConfiguration()); // {}
await honcho.refresh();
console.log(honcho.configuration); // {}
```

For REST `PUT /v3/workspaces/{workspace_id}`, `{"configuration": {}}` clears
the configuration, while omitting `configuration` or sending `null` leaves it
unchanged. Metadata-only updates therefore preserve the configuration.
`POST /v3/workspaces` still returns an existing workspace without updating it.
These replacement semantics are specific to workspace configuration updates;
they do not change peer or session partial-update behavior.

## Configuration Options

### Reasoning Configuration

Controls whether the system should reason over messages.

| Field | Type | Description |
| - | - | - |
| `enabled` | `bool` | Whether to enable reasoning functionality. When disabled, no facts or representations are generated. |

```python Python theme={null}
from honcho import Honcho

honcho = Honcho()

# Disable reasoning at session level
session = honcho.session("private-session", config={
    "reasoning": {"enabled": False}
})
```

```typescript TypeScript theme={null}
import { Honcho } from "@honcho-ai/sdk";

const honcho = new Honcho({});

// Disable reasoning at session level
const session = await honcho.session("private-session", {
    config: {
        reasoning: { enabled: false }
    }
});
```

### Peer Card Configuration

Controls how peer cards (containing key biographical information) are generated and used.

| Field | Type | Description |
| - | - | - |
| `use` | `bool` | Whether to use peer cards during the reasoning process. |
| `create` | `bool` | Whether to generate and update peer cards based on message content. |

```python Python theme={null}
# Disable peer card generation but still use existing cards
session = honcho.session("my-session", config={
    "peer_card": {"create": False, "use": True}
})
```

```typescript TypeScript theme={null}
// Disable peer card generation but still use existing cards
const session = await honcho.session("my-session", {
    config: {
        peer_card: { create: false, use: true }
    }
});
```

### Summary Configuration

Controls automatic conversation summarization. Available at workspace and session levels only.

| Field | Type | Description |
| - | - | - |
| `enabled` | `bool` | Whether to enable summary functionality. |
| `messages_per_short_summary` | `int` | Number of messages between short summaries. Must be ≥ 10. |
| `messages_per_long_summary` | `int` | Number of messages between long summaries. Must be ≥ 20 and greater than `messages_per_short_summary`. |

```python Python theme={null}
# Customize summary frequency
session = honcho.session("verbose-session", config={
    "summary": {
        "enabled": True,
        "messages_per_short_summary": 15,
        "messages_per_long_summary": 45
    }
})
```

```typescript TypeScript theme={null}
// Customize summary frequency
const session = await honcho.session("verbose-session", {
    config: {
        summary: {
            enabled: true,
            messages_per_short_summary: 15,
            messages_per_long_summary: 45
        }
    }
});
```

### Dream Configuration

Controls the "dreaming" process that consolidates and refines representations. Available at workspace and session levels only.

| Field | Type | Description |
| - | - | - |
| `enabled` | `bool` | Whether to enable dream functionality. Automatically disabled if reasoning is disabled. |

```python Python theme={null}
# Disable dreams for a workspace
honcho.set_configuration({
    "dream": {
        "enabled": False
    }
})
```

```typescript TypeScript theme={null}
// Disable dreams for a workspace
await honcho.setConfiguration({
    dream: {
        enabled: false
    }
});
```

### Custom Instructions

Custom instructions are free-text guidance added to the prompts Honcho's agents use, for example "Always write in German" or "Only track durable work preferences." Set one shared value for every agent, override it per agent, or both.

| Field | Applies to |
| - | - |
| `custom_instructions` (top level) | Shared fallback for the deriver, summarizer, dialectic, and dreamer |
| `reasoning.custom_instructions` | Deriver (conclusion extraction) |
| `summary.custom_instructions` | Session summaries |
| `dialectic.custom_instructions` | The peer and workspace chat endpoints |
| `dream.custom_instructions` | Dreaming (deductive and inductive conclusions) |
| `peer_card.custom_instructions` | Peer card updates during dreaming. Added on top of the dream instructions, applied within the peer card's allowed entry kinds, and never falls back to the shared value. |

Resolution rules:

1. **The most specific level wins.** Honcho checks session, then workspace configuration and uses the first level that sets a value, so a session's shared instructions beat a workspace's `summary.custom_instructions`. Messages can only set `reasoning.custom_instructions`, which overrides everything else for the deriver (see [Message Configuration](#message-configuration)).
2. **Within a level, a module's own value beats the shared value.**
3. **An empty string means "none".** Set `""` to turn off inherited instructions for a module at that level.
4. **Other sections never fall back to `reasoning`.** `reasoning.custom_instructions` only affects the deriver, as it always has.

Each value is limited to `DERIVER_MAX_CUSTOM_INSTRUCTIONS_TOKENS` (default 2000).

```python Python theme={null}
# German everywhere, bullet-point summaries, and no instructions for the dialectic
honcho.set_configuration({
    "custom_instructions": "Always write in German.",
    "summary": {"custom_instructions": "Write summaries as bullet points in German."},
    "dialectic": {"custom_instructions": ""},
})
```

```typescript TypeScript theme={null}
// German everywhere, bullet-point summaries, and no instructions for the dialectic
await honcho.setConfiguration({
    customInstructions: "Always write in German.",
    summary: { customInstructions: "Write summaries as bullet points in German." },
    dialectic: { customInstructions: "" },
});
```

***

## Peer Configuration

By default, all peers are "observed" by Honcho. This means that Honcho will reason over messages sent by the peer and generate a representation of them. In most cases, this is why you use Honcho! However, sometimes an application requires a peer that should not be observed: for example, an assistant or game NPC that your program will never need to access advanced reasoning for.

You may therefore disable observation of a peer by setting the `observe_me` flag in their configuration to `false`.

If the peer has a session-level configuration, it will override this configuration. If the flag is not set, or is set to `true`, the peer will be observed.

> [!NOTE]
>
> For session-level observation controls and local representations (where peers build separate models of each other), see [Directional Representations](https://honcho.dev/docs/v3/documentation/features/advanced/directional-representations.md).

```python Python theme={null}
from honcho import Honcho

# Initialize client
honcho = Honcho()

# Create peer with configuration
peer = honcho.peer("my-peer", configuration={"observe_me": False})

# Change peer's configuration
peer.set_configuration({"observe_me": True})

# Note: creating the same peer again will also replace the configuration
peer = honcho.peer("my-peer", configuration={"observe_me": False})
```

```typescript TypeScript theme={null}
import { Honcho } from "@honcho-ai/sdk";

(async () => {
    // Initialize client
    const honcho = new Honcho({});

    // Create peer with configuration
    const peer = await honcho.peer("my-peer", { configuration: { observeMe: false } });

    // Change peer's configuration
    await peer.setConfiguration({ observeMe: true });

    // Note: creating the same peer again will also replace the configuration
    await honcho.peer("my-peer", { configuration: { observeMe: false } });
})();
```

## Session Configuration

Sessions support the full configuration schema. You can disable reasoning entirely for a session, customize summary behavior, or adjust peer card settings.

```python Python theme={null}
from honcho import Honcho

# Initialize client
honcho = Honcho()

# Create session with reasoning disabled
session = honcho.session("my-session", configuration={
    "reasoning": {"enabled": False}
})

# Create session with custom summary settings
session = honcho.session("detailed-session", configuration={
    "summary": {
        "messages_per_short_summary": 10,
        "messages_per_long_summary": 30
    }
})
```

```typescript TypeScript theme={null}
import { Honcho } from "@honcho-ai/sdk";

(async () => {
    // Initialize client
    const honcho = new Honcho({});

    // Create session with reasoning disabled
    const session = await honcho.session("my-session", {
        configuration: { reasoning: { enabled: false } }
    });

    // Create session with custom summary settings
    const detailedSession = await honcho.session("detailed-session", {
        configuration: {
            summary: {
                messages_per_short_summary: 10,
                messages_per_long_summary: 30
            }
        }
    });
})();
```

## Message Configuration

Individual messages can override session and workspace configuration for fine-grained control. This is useful for excluding specific messages from processing or adjusting behavior on a per-message basis.

```python Python theme={null}
from honcho import Honcho

honcho = Honcho()
session = honcho.session("my-session")
user = honcho.peer("user")

# Create a message that skips the reasoning process
session.add_messages([
    user.message("This message won't be analyzed", configuration={
        "reasoning": {"enabled": False}
    })
])

# Give the deriver instructions for this message only
session.add_messages([
    user.message("Imported from our old CRM: renewal due in March", configuration={
        "reasoning": {"custom_instructions": "This is imported CRM data. Only extract account facts."}
    })
])
```

```typescript TypeScript theme={null}
import { Honcho } from "@honcho-ai/sdk";

(async () => {
    const honcho = new Honcho({});
    const session = await honcho.session("my-session");
    const user = await honcho.peer("user");

    // Create a message that skips the reasoning process
    await session.addMessages([
        user.message("This message won't be analyzed", {
            configuration: { reasoning: { enabled: false } }
        })
    ]);

    // Give the deriver instructions for this message only
    await session.addMessages([
        user.message("Imported from our old CRM: renewal due in March", {
            configuration: {
                reasoning: { customInstructions: "This is imported CRM data. Only extract account facts." }
            }
        })
    ]);
})();
```

## Full Configuration Schema Reference

### Workspace & Session Configuration

```json theme={null}
{
  "custom_instructions": null,
  "reasoning": {
    "enabled": true,
    "custom_instructions": null
  },
  "peer_card": {
    "use": true,
    "create": true,
    "custom_instructions": null
  },
  "summary": {
    "enabled": true,
    "messages_per_short_summary": 20,
    "messages_per_long_summary": 60,
    "custom_instructions": null
  },
  "dream": {
    "enabled": true,
    "custom_instructions": null
  },
  "dialectic": {
    "custom_instructions": null
  }
}
```

### Message Configuration

```json theme={null}
{
  "reasoning": {
    "enabled": true,
    "custom_instructions": null
  }
}
```

> [!NOTE]
>
> Message configuration only supports `reasoning` settings. Message-level `reasoning.custom_instructions` override session and workspace instructions for the deriver only. Peer card, summary, dream, dialectic, and shared `custom_instructions` are session/workspace-level only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.