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

# Agent Management

> Create, list, and delete agents in Memanto.

# Agent Management

Agents are the core identity in Memanto. Each agent maintains its own memory namespace and sessions.

## What is an Agent?

An **agent** represents a persistent identity that can maintain memories across sessions:

* **Unique identifier** - Never changes (e.g., `customer-support-bot`)
* **Memory namespace** - Isolated from other agents
* **Multiple sessions** - Can have sessions at different times
* **Long-term context** - Memories persist across sessions

## Agent Lifecycle

```
Create Agent (Auto-Activates) → Store/Recall Memories → Deactivate Session → Reactivate Later
                                                                                      ↓
                                                                               Delete Agent (optional)
```

## Managing Agents

Agent creation, listing, and session management are handled via the CLI or the REST API.

* **CLI Reference**: See [Agent Commands](/cli/agents/create) and [Session Commands](/cli/sessions/info).
* **API Reference**: See [Agents API](/api-reference/agents/create-agent) and [Sessions API](/api-reference/sessions/activate-agent).
* **Session Guide**: See [Session Management Guide](/guides/session-management) for details on session lifecycles.

## Agent Namespaces

Each agent automatically gets its own namespace in Moorcheh. Namespaces isolate semantic search so memories stay scoped to the correct agent.

```
Agent: customer-support
Namespace: memanto_agent_customer-support
```

All memories for that agent are stored in this namespace, and recall operations run against that namespace only.

### Search Isolation

Searches are isolated by default:

```
Agent: customer-support (namespace: memanto_agent_customer-support)
    Query: "user preferences"
    Search: ONLY in memanto_agent_customer-support

Agent: project-manager (namespace: memanto_agent_project-manager)
    Query: "project status"
    Search: ONLY in memanto_agent_project-manager
```

Agents never see each other's memories unless you intentionally implement a cross-agent access pattern.

### When You Need Shared Memory

If multiple agents need common context, use a dedicated shared agent:

```
Agent: shared-context
    Namespace: memanto_agent_shared-context
    Stores: company policies, product features, shared customer context

Sales Agent: recalls from its own namespace + shared-context
Support Agent: recalls from its own namespace + shared-context
```

This preserves isolation while allowing controlled sharing of common facts.

### Namespace Naming

Namespaces follow this pattern:

```
memanto_agent_{agent_id}
```

Examples:

* `customer-support` -> `memanto_agent_customer-support`
* `project-manager` -> `memanto_agent_project-manager`
* `research-bot` -> `memanto_agent_research-bot`

### Namespace Best Practices

DO:

* Create separate agents for different domains
* Keep related memories in the same agent
* Use a shared-context agent for cross-team knowledge

DON'T:

* Put all memories in one agent
* Expect cross-agent search automatically
* Reuse one agent for unrelated purposes

## Deleting Agents

When an agent is no longer needed, you can permanently delete it. The delete command walks you through two decisions: confirming the deletion, and choosing whether to keep a copy of the agent's memories in the Moorcheh cloud.

### CLI Method

```bash theme={null}
memanto agent delete customer-support
```

Skip confirmation with `--force`:

```bash theme={null}
memanto agent delete customer-support --force
```

### What Gets Deleted

| Item                                         | Default behavior | If you decline cloud preservation |
| -------------------------------------------- | ---------------- | --------------------------------- |
| Local agent metadata (`~/.memanto/agents/`)  | Always deleted   | Always deleted                    |
| Moorcheh cloud namespace (`memanto_agent_*`) | **Preserved**    | Deleted                           |

### REST API Method

By default the API endpoint removes local metadata only and leaves the Moorcheh namespace intact. Pass `delete-backup-too=true` to also delete the cloud namespace and its memories:

```python theme={null}
import httpx

# Local metadata only (cloud namespace retained)
response = httpx.delete(
    "http://localhost:8000/api/v2/agents/old-agent"
)

# Also delete the Moorcheh namespace
response = httpx.delete(
    "http://localhost:8000/api/v2/agents/old-agent",
    params={"delete-backup-too": "true"},
)

if response.status_code == 200:
    print(response.json()["message"])
```

API clients do not send an `Authorization` header — Memanto authenticates with Moorcheh server-side using the configured `MOORCHEH_API_KEY`.

***

## Agent Metadata

### View Agent Metadata

```bash theme={null}
memanto agent bootstrap customer-support
```

This shows:

* Agent ID
* Created timestamp
* Memory count by type
* Last session info
* Summary of important memories

## Agent Isolation & Scaling

Scale your architecture by creating distinct agents based on your needs:

* **Per User/Role:** `alice-support-rep`, `bob-support-rep`
* **Per Domain/Task:** `customer-preferences`, `billing-issues`
* **Per Environment:** `prod-support-bot`, `staging-support-bot`

Use clear, descriptive naming conventions to keep your agents organized as your project scales.

## Performance Considerations

### Agent Limits

* No hard limit on number of agents (free tier up to 5 agents)
* Each agent can have unlimited memories
* Sessions limited to 1 active per agent at a time
* Memories queryable in under 100ms on average

### Optimization Tips

1. **Reuse agent sessions** - Don't create new sessions frequently if active session is available
2. **Batch operations** - Store multiple memories at once
3. **Deactivate sessions** - Deactivate sessions when no longer needed to free resources

## Next Steps

* **Store Memories**: [Memory Operations Guide](./memory-operations)
* **Session Management**: [Session Management Guide](./session-management)
* **CLI Reference**: [Agent Commands](/cli/agents/create)

***

Agents are the foundation of Memanto. Master agent management to build powerful memory-enabled applications!