Session Management

Sessions control when agents are active and gate memory operations behind a short-lived token.

Understanding Sessions

Session Basics

A session is a time-bounded window (configured server-side, default ~6 hours) where:

The agent can store and retrieve memories
The session token authenticates memory operations
Memories persist after the session ends
Multiple sessions can exist over time

Sessions serve two core purposes:

Authorization — the session token proves your client is allowed to perform memory operations against a specific agent.
State boundaries — sessions create a clear active/inactive boundary for long-running workflows and produce a per-session summary on deactivation.

The Moorcheh API key is configured on the Memanto server (MOORCHEH_API_KEY). Clients never send it. The only client-side credential is the X-Session-Token header, used on memory endpoints.

Session Properties

Each session includes:

session_id — unique identifier
session_token — JWT used in X-Session-Token
agent_id — which agent the session is bound to
namespace — memanto_agent_{agent_id}
started_at / expires_at — lifetime
pattern — support, project, or tool
status — active, expired, or terminated

Session Lifecycle

Activate → Use (until expiry, auto-renewed near expiry) → Deactivate

Session States

+-----------------------------------------+
|   ACTIVE                                |
|   - Can store memories                  |
|   - Can recall memories                 |
|   - Session token valid                 |
+-----------------+-----------------------+
                  |
        (token expires or deactivate)
                  v
+-----------------------------------------+
|   INACTIVE                              |
|   - Memories still exist                |
|   - Cannot access without new session   |
|   - Can reactivate anytime              |
+-----------------------------------------+

Managing Sessions

Sessions can be activated, inspected, and deactivated using the CLI or REST API.

CLI Reference: see activate, info, deactivate.
API Reference: see Activate Agent, Get Current Session, Deactivate Agent.

Session Token Management

Token Handling

A session token is a JWT returned when activating an agent. It carries the agent ID and expiry, and must be sent with all memory operations:

import httpx

headers = {
    "X-Session-Token": session_token,
    "Content-Type": "application/json",
}

response = httpx.post(
    f"http://localhost:8000/api/v2/agents/{agent_id}/remember",
    headers=headers,
    json={"content": "...", "type": "fact"},
)

Automatic Token Refresh

Memanto auto-renews sessions that are near expiry on the next memory request — no separate “extend” call is needed. The CLI inherits this behavior:

memanto status   # if the session is near expiry, Memanto renews it

For API clients, simply keep using the current session_token; if Memanto renews it, the next response carries the refreshed expiration. If the token has fully expired (401), call /activate again to obtain a new one.

Multi-Session Patterns

Sequential Sessions

Same agent, different times:

Session 1 (Day 1) → Store facts about customer
     ↓ (session ends)
Session 2 (Day 1 later) → Recall facts, add new info
     ↓ (session ends)
Session 3 (Day 2) → Continue with full context

All memories persist across sessions.

Session vs Memory

Sessions are temporary. Memories are persistent.

Session A ends
    ↓
Memories remain
    ↓
Session B can still recall them

Parallel Sessions

Different agents, same time:

import httpx

agents = ["customer-support", "billing-bot", "technical-support"]

sessions = {}
for agent_id in agents:
    response = httpx.post(
        f"http://localhost:8000/api/v2/agents/{agent_id}/activate"
    )
    sessions[agent_id] = response.json()["session_token"]

# Now can use all agents simultaneously
for agent_id, token in sessions.items():
    # Perform operations with each agent using token in X-Session-Token
    ...

Session Persistence

Across Runs

Session information is tracked under ~/.memanto/sessions/ on the server, and the CLI cached state allows the same active session to be picked up across runs.

Explicit Session Management

For long-running processes, use this pattern:

Try the existing token.
On 401 Unauthorized, activate a new session.
Cache and continue.

import httpx

def ensure_session(agent_id: str, token: str | None) -> str:
    if token and is_token_valid(token):
        return token
    resp = httpx.post(
        f"http://localhost:8000/api/v2/agents/{agent_id}/activate"
    )
    return resp.json()["session_token"]

Session Timeouts & Limits

Default Duration

Standard session: configured server-side via SESSION_DEFAULT_DURATION_HOURS (typically 6 hours).
Auto-renewal: Memanto extends sessions near expiry automatically when memory requests are made.
Manual renewal: re-activate the agent to obtain a fresh token.

Handling Expiry

On 401 Unauthorized, treat the token as expired:

import httpx

resp = httpx.post(url, headers=headers, json=body)
if resp.status_code == 401:
    new_token = httpx.post(
        f"http://localhost:8000/api/v2/agents/{agent_id}/activate"
    ).json()["session_token"]
    headers["X-Session-Token"] = new_token
    resp = httpx.post(url, headers=headers, json=body)

Best Practices

DO

Let Memanto auto-renew sessions; only re-activate after a hard 401
Store session tokens in process memory, not on disk
Deactivate sessions when a workflow finishes to capture a session summary

DON’T

Create a new session for every request
Send the Moorcheh API key from clients (Memanto reads it server-side)
Reuse a session token across different agents

Next Steps

Memory Operations: Memory Operations Guide
CLI Reference: Session commands
API Reference: Session endpoints

Session management ensures reliable, long-running agent operations. Master it for production reliability!

Getting Started

Guides

Reference

Session Management

Session Management

Understanding Sessions

Session Basics

Session Properties

Session Lifecycle

Session States

Managing Sessions

Session Token Management

Token Handling

Automatic Token Refresh

Multi-Session Patterns

Sequential Sessions

Session vs Memory

Parallel Sessions

Session Persistence

Across Runs

Explicit Session Management

Session Timeouts & Limits

Default Duration

Handling Expiry

Best Practices

DO

DON’T

Next Steps

​Session Management

​Understanding Sessions

​Session Basics

​Session Properties

​Session Lifecycle

​Session States

​Managing Sessions

​Session Token Management

​Token Handling

​Automatic Token Refresh

​Multi-Session Patterns

​Sequential Sessions

​Session vs Memory

​Parallel Sessions

​Session Persistence

​Across Runs

​Explicit Session Management

​Session Timeouts & Limits

​Default Duration

​Handling Expiry

​Best Practices

​ DO

​ DON’T

​Next Steps

Session Management

Understanding Sessions

Session Basics

Session Properties

Session Lifecycle

Session States

Managing Sessions

Session Token Management

Token Handling

Automatic Token Refresh

Multi-Session Patterns

Sequential Sessions

Session vs Memory

Parallel Sessions

Session Persistence

Across Runs

Explicit Session Management

Session Timeouts & Limits

Default Duration

Handling Expiry

Best Practices

DO

DON’T

Next Steps