# User Memory

Let your AVCodex agent remember facts about users across conversations, so a tech does not have to re-explain context every time they call back.

---

User Memory enables your agent to remember important facts about users across conversations. Instead of starting fresh every time, your agent can recall preferences, past tickets, and relevant context.

## What is User Memory

User Memory automatically extracts and stores durable facts from conversations:

| Memory type | Examples |
|---|---|
| **Saved Facts** | "User's company is Acme Integration", "Prefers email over phone for non-urgent dispatches." |
| **Preferences** | "Likes concise answers", "Uses metric for cable runs." |
| **User Insights** | "Senior commissioning engineer", "Owns the Acme HQ relationship." |
| **Topic Highlights** | "Asked about a 40-room corporate refresh RFP", "Interested in DM-NVX licensing." |

## How it works

```
User: "I'm the lead programmer at Acme Integration and we just took over service
       for the Foley Building."
           |
           v
    [Conversation ends]
           |
           v
    [Memory extraction runs]
           |
           v
    Memories stored:
    - Role: Lead programmer
    - Company: Acme Integration
    - Account: Foley Building service contract
           |
           v
    [Next conversation]
           |
           v
AI: "Welcome back. Last time we worked on the Foley Building handoff. What can
     I help with today?"
```

## Enabling User Memory

**1. Open Memory Settings.**

Go to your agent's **Build** page and find **Memory Settings** in the sidebar.

**2. Enable Memory Extraction.**

Toggle **Enable User Memory** on. This activates automatic memory extraction from conversations.

**3. Configure categories (optional).**

Choose which types of information to remember:

- **Saved Facts**: concrete information (names, companies, roles).
- **Preferences**: how users like to interact.
- **Topic Highlights**: key discussion topics.
- **User Insights**: inferred characteristics.
- **Recent Queries**: common questions asked.

**4. Set custom instructions (optional).**

Add specific extraction guidance:

```
Focus on:
- Integrator firm name and the user's role
- Active projects and accounts the user is responsible for
- Manufacturer mix the user works in (Crestron, Q-SYS, Extron, Biamp, Shure)
- Open service tickets and dispatch context

Do NOT remember:
- Personal contact information
- Specific contract dollar values
- Confidential client business details
```

## Memory categories

### Saved Facts

Concrete, verifiable information:

- Names and roles.
- Company / integrator firm information.
- Manufacturer mix and standards.
- Account and site details.

### Preferences

How users like to interact:

- Communication style (formal vs casual).
- Response length preference.
- Preferred formats (bullets vs paragraphs).
- Language preferences.

### Topic Highlights

Key subjects from conversations:

- Features or systems they are interested in.
- Problems they are trying to solve.
- Questions they have asked.
- Projects or rooms they have discussed.

### User Insights

Inferred characteristics:

- Technical expertise level (junior programmer vs senior commissioning engineer).
- Decision-making authority.
- Industry segment (corporate AV, higher-ed, broadcast, hospitality).
- Use case patterns.

## Viewing stored memories

Go to **Chats** > select a user > **Memories** to see:

- All memories for that user.
- When each memory was created.
- Which conversation it came from.
- Confidence score.

## Managing memories

### Editing memories

Click any memory to edit or correct it:

1. Update the content.
2. Change the category.
3. Adjust the confidence score.

### Deleting memories

Remove memories that are:

- Incorrect.
- Outdated (the user changed firms, the project closed out).
- No longer relevant.

Go to **Memories** > click the memory > **Delete**.

### Bulk management

For compliance or cleanup:

- **Delete all memories for a user**: User profile > Clear Memory.
- **Export memories**: download as CSV for review.

## Best practices

### What to remember

**Do remember:**

- Professional context (firm, role, manufacturer mix).
- Stated preferences.
- Key topics discussed.
- Problems they are solving.

**Do not remember:**

- Sensitive personal information.
- Temporary states ("having a rough day on a closeout").
- Information they asked you to forget.
- Confidential client business data without consent.

### Privacy considerations

> **Warning:** Always tell users your agent has memory capabilities. Consider adding to your system prompt:
>
> "I can remember relevant details from our conversations to provide better assistance. Let me know if you'd prefer I not remember something."

### Memory in your system prompt

Help your agent use memories well:

```
You have access to memories about this user from past conversations.
Use these to:
- Personalize greetings and responses
- Avoid asking questions they've already answered
- Reference their specific context (firm, projects, manufacturer mix)

Don't:
- Mention that you "remember" things in a creepy way
- Assume memories are 100% accurate
- Reference memories if they seem outdated
```

## How memory extraction works

Memory extraction runs automatically after conversations:

1. **Conversation ends**: user leaves or 10 minutes of inactivity.
2. **Queued for processing**: the conversation enters the memory queue.
3. **AI analysis**: GPT-4 analyzes the conversation for memorable facts.
4. **Structured extraction**: facts get categorized and scored for confidence.
5. **Storage**: memories are encrypted and stored with the user profile.

### Extraction timing

| Trigger | When it happens |
|---|---|
| Inactivity | 10 minutes without messages. |
| User leaves | Explicit session end. |
| Batch processing | Every 10 minutes for queued sessions. |

### Confidence scores

Each memory has a confidence score (0 to 1):

- **0.9 to 1.0**: explicitly stated by the user.
- **0.7 to 0.9**: strongly implied.
- **0.5 to 0.7**: reasonable inference.
- **Below 0.5**: uncertain, may need verification.

## Use cases

### Field service desk

Remember:

- Sites and rooms the tech works on.
- Past tickets the tech has reported.
- Preferred contact method.
- Technical expertise level.

### Pre-sales / RFP assistant

Remember:

- Firm size and segment.
- Active opportunities and project context.
- Decision timeline.
- Manufacturer preferences.

### Internal AV operations agent

Remember:

- The user's role on the team (PM, programmer, lead engineer).
- Active project assignments.
- Communication preferences.
- Recurring tasks (weekly reports, gear pulls).

### Programmer onboarding agent

Remember:

- Learning progress on Crestron SIMPL or Q-SYS Lua.
- Topics mastered.
- Areas needing work.
- Preferred learning style.

## Troubleshooting

### Memories not being extracted

1. Verify memory is enabled in settings.
2. Check that conversations are ending properly.
3. Allow 10 to 15 minutes for extraction to process.
4. Verify the user is identified (not anonymous).

### Incorrect memories

1. Review and edit incorrect memories.
2. Adjust custom extraction instructions.
3. Add negative examples to your instructions.

### Too many memories

1. Focus extraction on specific categories.
2. Add instructions to prioritize durable facts.
3. Periodically clean up outdated memories.

## Limitations

Current limitations to keep in mind:

- **Extraction delay**: memories are not available instantly (10+ minute delay).
- **No real-time recall**: the current implementation extracts memories but does not automatically inject them into prompts.
- **Token limits**: very long conversations may be truncated for extraction.

> **Note:** We are actively improving the memory system. Future updates will include real-time memory recall and more sophisticated memory management.

## Using with MCP

You can access user memories through code using the AVCodex MCP Server.

### Available tools

| Tool | Description |
|---|---|
| `get_user_memories` | Retrieve extracted memories for an application. |

### Example prompts

```
"Show me user memories for my service desk agent"
"What facts has my agent learned about users?"
"List memories with high confidence scores"
```

### Workflow: reviewing user insights

```
You: Show me the memories my pre-sales agent has extracted.

AI: [Calls get_user_memories]
Found 47 user memories:

High confidence (0.9+):
- User "john@acmeintegration.com": Lead programmer at Acme Integration, 50-person firm.
- User "sarah@bigcorp.com": Director of corporate IT, evaluating a 40-room refresh, budget approved.

Medium confidence (0.7-0.9):
- User "mike@startupav.io": Technical background, comparing Crestron and Q-SYS for a new HQ build.
...
```

> **Note:** MCP server access requires a Builder plan or higher. See the [MCP Setup Guide](../guides/mcp/setup) to get started.

*AVCodex · Your AV expertise. Amplified by AI.*