# Memory

> Give your agents persistent memory with five memory types, vector embeddings, and semantic search.

Source: https://0.0.0.0:8080/docs/memory

The memory system gives agents the ability to store and retrieve information across executions. This enables context-aware conversations, knowledge accumulation, and personalized interactions.

## Memory Types

PromptRails supports five types of memory, each suited to different use cases:

### Conversation Memory (`conversation`)

Stores conversation history and context. Used for maintaining context in multi-turn chat sessions.

```python
client.memories.create(
    agent_id="your-agent-id",
    content="User prefers responses in bullet point format.",
    memory_type="conversation",
    importance=0.7,
    chat_session_id="optional-session-id"
)
```

### Fact Memory (`fact`)

Stores discrete facts and knowledge. Used for accumulating knowledge about users, products, or domains.

```python
client.memories.create(
    agent_id="your-agent-id",
    content="Customer John Smith is a Premium tier subscriber since 2023.",
    memory_type="fact",
    importance=0.8,
    metadata={"entity": "customer", "customer_id": "john-smith-123"}
)
```

### Procedure Memory (`procedure`)

Stores step-by-step procedures and workflows. Used for remembering how to perform tasks.

```python
client.memories.create(
    agent_id="your-agent-id",
    content="To process a refund: 1) Verify order ID 2) Check refund eligibility 3) Submit refund request 4) Notify customer",
    memory_type="procedure",
    importance=0.9
)
```

### Episodic Memory (`episodic`)

Stores event records and experiences. Used for remembering specific interactions and outcomes.

```python
client.memories.create(
    agent_id="your-agent-id",
    content="On 2024-01-15, customer reported issue with order #45678. Resolved by issuing replacement.",
    memory_type="episodic",
    importance=0.6,
    metadata={"event_type": "support_ticket", "resolution": "replacement"}
)
```

### Semantic Memory (`semantic`)

Stores conceptual knowledge with vector embeddings for semantic similarity search. Used for knowledge bases and retrieval-augmented generation (RAG).

```python
client.memories.create(
    agent_id="your-agent-id",
    content="Our return policy allows returns within 30 days of purchase. Items must be in original packaging.",
    memory_type="semantic",
    importance=0.9,
    metadata={"topic": "return_policy", "version": "2024-Q1"}
)
```

## Vector Embeddings

Memories can be automatically embedded as vectors for semantic search. When a memory is created with content, PromptRails generates a vector embedding that enables similarity-based retrieval.

This is particularly powerful for semantic memory types, enabling agents to find relevant knowledge based on meaning rather than exact keyword matching.

## Semantic Search

Search memories by semantic similarity to find relevant context for the current interaction:

```python
results = client.memories.search(
    agent_id="your-agent-id",
    query="What is the refund policy?",
    memory_type="semantic",
    limit=5
)

for memory in results["data"]:
    print(f"[{memory['importance']}] {memory['content']}")
```

## Importance Scoring

Each memory has an importance score between 0.0 and 1.0:

| Range     | Meaning                                              |
| --------- | ---------------------------------------------------- |
| 0.0 - 0.3 | Low importance (casual observations, minor details)  |
| 0.3 - 0.6 | Medium importance (general knowledge, preferences)   |
| 0.6 - 0.8 | High importance (key facts, procedures)              |
| 0.8 - 1.0 | Critical importance (core rules, policies, identity) |

Importance scores influence which memories are retrieved when context limits are applied.

## Access Tracking

The memory system tracks how often each memory is accessed:

- `access_count` -- Total number of times the memory has been retrieved
- `last_accessed_at` -- Timestamp of the most recent access

This metadata helps identify frequently used vs. stale memories.

## Memory CRUD Operations

### Create

```python
memory = client.memories.create(
    agent_id="your-agent-id",
    content="The customer's preferred language is Spanish.",
    memory_type="fact",
    importance=0.7,
    metadata={"category": "preference"}
)
```

### List

```python
memories = client.memories.list(
    agent_id="your-agent-id",
    memory_type="fact",  # optional filter
    page=1,
    limit=20
)
```

### Get

```python
memory = client.memories.get(memory_id="memory-id")
```

### Update

```python
client.memories.update(
    memory_id="memory-id",
    content="Updated content",
    importance=0.9
)
```

### Delete

```python
client.memories.delete(memory_id="memory-id")
```

## Using Memories in Agents

When memory is enabled for an agent, the execution pipeline:

1. Retrieves relevant memories based on the input (using semantic search for semantic memories)
2. Injects the retrieved memories into the prompt context
3. Optionally creates new memories from the interaction
4. Updates access counts for retrieved memories

Enable memory in the agent configuration:

```python
client.agents.create_version(
    agent_id="your-agent-id",
    config={
        "memory_enabled": True,
        "memory_types": ["conversation", "fact", "semantic"],
        "max_memories": 10
    },
    message="Enabled memory system"
)
```

## Memory Response Fields

| Field              | Type      | Description                                               |
| ------------------ | --------- | --------------------------------------------------------- |
| `id`               | KSUID     | Unique memory identifier                                  |
| `workspace_id`     | KSUID     | Workspace this memory belongs to                          |
| `agent_id`         | KSUID     | Agent this memory is associated with                      |
| `content`          | string    | The memory content                                        |
| `memory_type`      | string    | One of: conversation, fact, procedure, episodic, semantic |
| `importance`       | float     | Importance score (0.0 to 1.0)                             |
| `access_count`     | integer   | Number of times accessed                                  |
| `last_accessed_at` | timestamp | Last access time                                          |
| `metadata`         | JSON      | Arbitrary metadata                                        |
| `chat_session_id`  | KSUID     | Optional linked chat session                              |
| `created_at`       | timestamp | Creation time                                             |
| `updated_at`       | timestamp | Last update time                                          |

## Related Topics

- [Agents](/docs/agents) -- Enabling memory in agent configurations
- [Sessions and Chat](/docs/sessions-and-chat) -- Conversation memory in chat sessions
- [Tracing](/docs/tracing) -- Memory operations appear as `memory` and `embedding` spans