> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/architecture-and-concepts/properties.md).

# Properties

[![Version](https://img.shields.io/github/v/release/labsai/EDDI?label=version\&color=blue)](https://github.com/labsai/EDDI/releases)

## Overview

**Properties** are EDDI's primary mechanism for storing and retrieving state within and across conversations. They are key-value pairs that can be set by agent configuration, extracted from API responses, or written by LLM tools — and they're accessible in every template (system prompts, HTTP call bodies, output templates, property instructions).

Properties are the glue that connects the pipeline's processing steps with persistent user state. Understanding how they work is essential for building stateful agents.

## Key Concepts

### What Properties Are

A property has:

* **Name** (key): The identifier used to access the property (e.g., `preferred_language`, `company_name`)
* **Value**: Can be a `String`, `Integer`, `Long`, `Float`, `Double`, `Map`, `List`, or `Boolean`
* **Scope**: How long the property lives
* **Visibility** (v6): Who can see the property

### Property vs Context vs Memory

| Mechanism      | Source                                    | Lifetime                       | Access Pattern         |
| -------------- | ----------------------------------------- | ------------------------------ | ---------------------- |
| **Properties** | Agent-set (via PropertySetter, LLM tools) | Configurable (step → longTerm) | `{properties.key}`     |
| **Context**    | Your application (passed per request)     | Per request                    | `{context.key}`        |
| **Memory**     | Pipeline (each task writes data)          | Per step (current turn's data) | `{memory.current.key}` |

Use **properties** when the agent needs to remember something. Use **context** when your application injects something. Use **memory** when you need data from the current or previous pipeline step.

***

## Scopes

Properties support four scopes that control their lifetime:

| Scope          | Lifetime                                                                     | Persistence                                                                                                                                                                                      | Use Case                                                            |
| -------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `step`         | Current conversation turn only                                               | Not persisted                                                                                                                                                                                    | Temporary data needed only for this response                        |
| `conversation` | Entire conversation session                                                  | Persisted in conversation memory                                                                                                                                                                 | User preferences within a session, extracted entities               |
| `longTerm`     | Across conversations                                                         | Persisted in user property store                                                                                                                                                                 | User profile data, preferences that should survive between sessions |
| `secret`       | Current conversation session (the property holds a `${vault:...}` reference) | Plaintext encrypted into SecretsVault, one slot per write (`<agentId>.u<userHash>.<nonce>.<propertyName>`); the property itself is conversation-scoped and is not reloaded in a new conversation | API keys, tokens, sensitive credentials                             |

### Choosing the Right Scope

```
Is this data only needed for the current response?
  → step

Will the user need this data later in the same conversation?
  → conversation

Should this data persist when the user starts a new conversation?
  → longTerm

Is this sensitive data (API keys, tokens)?
  → secret
```

***

## Visibility (v6)

Properties also have a **visibility** dimension that controls which agents can see them:

| Visibility | Who sees it                               | Use Case                                                                                                                                                            |
| ---------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `self`     | Only the owning agent                     | Agent-specific preferences, internal state. The default when the agent declares a `userMemoryConfig` block (its `defaultVisibility` is `self` unless set otherwise) |
| `group`    | All agents in the same group conversation | Shared context in multi-agent orchestration                                                                                                                         |
| `global`   | All agents for this user                  | Cross-agent user preferences (e.g., language, timezone). The default when the agent declares **no** `userMemoryConfig`                                              |

Visibility is orthogonal to scope — a property can be `longTerm` + `self` (persists across sessions, visible only to the owning agent) or `longTerm` + `global` (persists and visible to all agents).

A property without `visibility` gets the agent's `userMemoryConfig.defaultVisibility` (`self` when the block is declared, `global` when there is none) — with or without `enableMemoryTools`. A `group` property carries the conversation's group id (from the `groupId` context a group conversation injects); in a conversation that belongs to no group it is stored as `self`, since a group entry without a group id could never be read.

***

## Setting Properties

### Via PropertySetter Configuration (JSON)

The PropertySetter task (`ai.labs.property`) sets properties based on triggered actions:

```json
{
  "setOnActions": [
    {
      "actions": ["greet_user"],
      "setProperties": [
        {
          "name": "greeted",
          "valueString": "true",
          "scope": "conversation"
        },
        {
          "name": "preferred_language",
          "valueString": "{context.language}",
          "scope": "longTerm",
          "visibility": "global"
        }
      ]
    }
  ]
}
```

When the `greet_user` action fires:

1. `greeted` is set to `"true"` for this conversation session
2. `preferred_language` is set from the input context and persisted across all conversations and agents

`"actions": ["*"]` selects an entry on every turn that emitted at least one action. Each instruction runs **at most once per turn**, however many of the turn's actions select it — in the order of the turn's actions, then the order of `setOnActions`.

### Via Pre/Post Request Instructions

Properties can be set before or after any lifecycle task (HTTP calls, LLM calls):

```json
{
  "preRequest": {
    "propertyInstructions": [
      {
        "name": "requestTimestamp",
        "valueString": "{uuidUtils:generateUUID()}",
        "scope": "step"
      }
    ]
  },
  "postResponse": {
    "propertyInstructions": [
      {
        "name": "lastApiResponse",
        "fromObjectPath": "weatherApi",
        "scope": "conversation"
      }
    ]
  }
}
```

Inside a call's `postResponse`, the response sits at the top of the template data under the call's **`responseObjectName`** (`weatherApi` above), so a path starts there — `weatherApi.current.temperature`. There is no `httpCalls.` root. A `property.json` instruction that runs in a later task reads the same response through conversation memory instead: `memory.current.httpCalls.weatherApi.current.temperature`.

A `preRequest` / `postResponse` instruction and a `property.json` instruction are run by **one implementation** and behave identically: the same typed values, `override`, `toObjectPath`, `convertToObject`, the typed `value*` fields and the `scope: secret` rules below. The difference is what happens when one fails (a template that does not render): in `property.json` it fails the turn; in a `preRequest` / `postResponse` it is logged with the conversation id and recorded in the step under `propertyInstructions:errors` (visible in a detailed conversation snapshot), and the remaining instructions still run — except a `scope: secret` instruction, which fails closed everywhere. A `fromObjectPath` that reaches something that is not a JSON value (a live output item, say) sets nothing and logs a warning, in both.

### Via LLM Tools (Agent-Driven)

When `enableMemoryTools` is enabled in the agent configuration, the LLM can set properties using built-in memory tools:

```
Agent: "I'll remember that you prefer dark mode."
→ Tool call: rememberFact(key="ui_preference", value="dark_mode", category="preference", visibility="self")
```

See [Persistent User Memory](https://docs.labs.ai/architecture-and-concepts/user-memory.md) for full details on the LLM memory tools, visibility scoping, and Dream consolidation.

***

## Accessing Properties in Templates

Properties are available in **all** templates via the `properties` namespace.

> ⚠️ **`properties` exposes raw values, not `Property` objects.** `MemoryItemConverter.convert()` puts `ConversationProperties.toMap()` into the template context, and `toMap()` returns the unwrapped Java value that was stored (`String`, `Integer`, `Long`, `Float`, `Double`, `Boolean`, `List`, `Map`) — the `Property` wrapper never reaches the template. Use `{properties.key}` directly. A `.valueString` / `.valueInt` / … suffix resolves against the raw value (a `String` has no `valueString` property) and fails at render time. The `valueString`, `valueInt`, … names are **write-side** field names of the JSON property-setter config only. [Agent Config Authoring](https://docs.labs.ai/agent-configuration/agent-config-authoring.md#template-syntax) is the authoritative reference for the template data model.

### In Output Templates

```
Hello {properties.userName}! Your preferred language is {properties.preferred_language}.
```

### In System Prompts (LLM)

```
You are a helpful assistant. The user's name is {properties.userName}.
They prefer {properties.preferred_language} responses.
```

### In HTTP Call Bodies

```json
{
  "userId": "{properties.userId}",
  "language": "{properties.preferred_language}"
}
```

### Reading the Different Value Types

The property-setter config picks the value type by which `value*` field you write (`valueString`, `valueInt`, `valueLong`, `valueFloat`, `valueDouble`, `valueObject`, `valueList`, `valueBoolean`). In templates, all of them are read the same way — through the property name:

| Written as     | Read in a template             | Example                                                           |
| -------------- | ------------------------------ | ----------------------------------------------------------------- |
| `valueString`  | `{properties.name}`            | `Hello {properties.name}`                                         |
| `valueInt`     | `{properties.age}`             | `You are {properties.age}`                                        |
| `valueLong`    | `{properties.epochMillis}`     | a whole number beyond the `int` range                             |
| `valueFloat`   | `{properties.score}`           | `Score: {properties.score}`                                       |
| `valueDouble`  | `{properties.price}`           | `Price: {properties.price}` — full precision, unlike `valueFloat` |
| `valueObject`  | `{properties.profile.<field>}` | `{properties.profile.email}`                                      |
| `valueList`    | `{properties.tags}`            | `{#for item in properties.tags}...{/for}`                         |
| `valueBoolean` | `{properties.isPremium}`       | `{#if properties.isPremium}...{/if}`                              |

A decimal renders in plain digits — `12500000.5`, `0.00025` — not in the `1.25000005E7` / `2.5E-4` notation Java's `toString()` switches to (outside the range JavaScript also prints plainly, `1e-7 <= |x| < 1e21`, the notation is kept). A whole decimal keeps its `.0` (`3.0`).

***

## Property Lifecycle

Properties are managed by `Conversation.java` at session boundaries — NOT by pipeline tasks.

### 1. Conversation Init

```
Conversation.init()
  └─→ loadUserProperties()
      └─→ IPropertiesHandler.getUserMemoryStore()
      └─→ IUserMemoryStore.getVisibleEntries(userId, agentId, groupIds, recallOrder, maxEntries)
      └─→ Entries converted to Property objects with scope=longTerm
      └─→ Loaded into conversationProperties
      └─→ Available as {properties.key} in all templates
```

Recall order (`most_recent` or `most_accessed`) and the maximum number of recalled entries come from the agent's `userMemoryConfig`. The block applies whenever it is declared, with or without `enableMemoryTools`; when it is absent, the `UserMemoryConfig` defaults apply (**`most_recent` ordering and 50 entries**).

> **Note:** `enableMemoryTools` only controls the LLM memory tool. `maxRecallEntries` is 50 by default either way; declare `userMemoryConfig` with an explicit `maxRecallEntries` if the number matters to you.

### 2. Pipeline Execution

```
LifecycleManager runs pipeline
  └─→ PropertySetterTask sets properties based on actions
      └─→ scope=step (cleared after this turn)
      └─→ scope=conversation (lives for the session)
      └─→ scope=longTerm (persisted across conversations)
      └─→ scope=secret (auto-vaulted via SecretsVault)
```

### 3. Conversation Teardown

This runs at the end of **every turn** that completes, not only when the conversation ends.

```
Conversation.postConversationLifecycleTasks()
  └─→ storePropertiesPermanently()
      └─→ longTerm properties that changed this turn (or whose write an earlier,
          paused or failed turn still owes) saved via IUserMemoryStore.upsert();
          unchanged ones are not rewritten
      └─→ Visibility applied at persistence boundary:
          - Explicit visibility on property → used as-is
          - No visibility set → defaults to agent's defaultVisibility (or `global`)
```

> **Key insight**: Persistent state is a **session concern** handled at init/teardown — NOT in the pipeline. This means properties "just work" without any task ordering dependencies.

> **Storage**: In v6, all persistent properties are stored in the unified `usermemories` collection (MongoDB) or `usermemories` table (PostgreSQL). The legacy `properties` collection has been removed. See [Persistent User Memory](https://docs.labs.ai/architecture-and-concepts/user-memory.md) for the full unified memory model.

***

## Secret Properties

Properties with `scope=secret` are automatically handled by the SecretsVault — in a property setter and in the `preRequest` / `postResponse` property instructions of httpcalls, MCP calls and LLM tasks alike:

1. The moment the property instruction runs, the plaintext is stored in SecretsVault in a slot of its own, `<agentId>.u<userHash>.<nonce>.<name>` — **one slot per write**, so two users or conversations of the same agent never share, or overwrite, each other's secret (see [Secrets Vault](https://docs.labs.ai/security-and-compliance/secrets-vault.md#where-vault-references-work))
2. Every copy of the plaintext is scrubbed from the conversation step (the raw input, a saved API response it was read from)
3. The property value becomes a `${vault:<agentId>.u<userHash>.<nonce>.<name>}` reference with `conversation` scope
4. Downstream consumers (`ChatModelRegistry`, `ApiCallExecutor`, `SecretResolver`) resolve the reference at point-of-use

Only a string can be vaulted. `valueObject`, `valueList`, `valueInt`, `valueLong`, `valueFloat`, `valueDouble` and `valueBoolean` are rejected under `scope: secret` when the configuration is saved, and so is a literal name containing `/`, `{`, `}` or `$`. A value that only turns out not to be a string at run time — a `fromObjectPath` that yields an object or a number, a `convertToObject: true` value that parses as JSON — fails the turn, in the property setter and in the httpcall, MCP and LLM instructions alike. None of them is ever stored in plaintext.

If the vault is unavailable or disabled, the turn fails closed with a `LifecycleException` rather than persisting the plaintext — set `EDDI_VAULT_MASTER_KEY`. **The vault is disabled on a default install**, so there every `scope: secret` instruction fails its turn with an error naming `EDDI_VAULT_MASTER_KEY` — including a post-response instruction of an httpcall, which used to store the value in plaintext.

The slots are deleted when their conversation is permanently deleted and on GDPR erasure — see [Secrets Vault](https://docs.labs.ai/security-and-compliance/secrets-vault.md) for the details.

```json
{
  "name": "api_token",
  "valueString": "sk-abc123...",
  "scope": "secret"
}
```

See [Secrets Vault](https://docs.labs.ai/security-and-compliance/secrets-vault.md) for full documentation.

***

## Best Practices

### 1. Use Appropriate Scopes

```json
// ❌ Don't persist temporary data
{"name": "tempResult", "scope": "longTerm"}

// ✅ Use step scope for temporary data
{"name": "tempResult", "scope": "step"}
```

### 2. Use fromObjectPath for Extraction

Instead of storing entire API responses, extract only what you need:

```json
{
  "name": "temperature",
  "fromObjectPath": "memory.current.httpCalls.weatherApi.current.temperature",
  "scope": "conversation"
}
```

(In the call's own `postResponse`, the same value is `weatherApi.current.temperature` — see [Via Pre/Post Request Instructions](#via-prepost-request-instructions).)

A value read through `fromObjectPath` is stored **exactly as found** — with its type: a JSON number stays a number (`valueInt`, `valueLong` beyond the `int` range, `valueDouble` for a decimal), a boolean a boolean, an object a `valueObject`, an array a `valueList`. It is data, not a template, so braces in a user's message or an API response are kept literally and never evaluated. A path that resolves to nothing sets nothing — the property keeps its previous value, if any. (A `postResponse` instruction used to store `""` for every non-string and for a missing path.) Only `valueString` (and the property `name`) are rendered as templates; to combine a navigated value with text, reference it from a `valueString`, e.g. `"valueString": "Temperature: {memory.current.httpCalls.weatherApi.current.temperature}"`.

### 3. Use Visibility for Multi-Agent Scenarios

```json
// Agent-specific memory
{"name": "internal_state", "scope": "longTerm", "visibility": "self"}

// Shared within group conversation
{"name": "group_context", "scope": "longTerm", "visibility": "group"}

// Cross-agent user preference
{"name": "language", "scope": "longTerm", "visibility": "global"}
```

### 4. Naming Conventions

* Use `snake_case` for property names
* Use descriptive, specific names (`user_preferred_timezone` not `tz`)
* Prefix agent-specific properties with the agent's domain (`support_ticket_id`, `onboarding_step`)

***

## Related Documentation

* [Conversation Memory](https://docs.labs.ai/architecture-and-concepts/conversation-memory.md) - How memory flows through the pipeline
* [Secrets Vault](https://docs.labs.ai/security-and-compliance/secrets-vault.md) - Encrypted property storage
* [Passing Context Information](https://docs.labs.ai/agent-configuration/passing-context-information.md) - External data injection
* [Output Templating](https://docs.labs.ai/agent-configuration/output-templating.md) - Using properties in templates
* [LLM Integration](https://docs.labs.ai/agent-configuration/langchain.md) - Using properties in LLM prompts
* [HTTP Calls](https://docs.labs.ai/agent-configuration/httpcalls.md) - Using properties in API requests
