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.

Automatic Recreation After Expiry

If a session has already lapsed past its expiry, Memanto issues a brand-new session on the next request rather than failing with 401. This is what keeps a CLI that has been idle overnight working — memanto status picks up where it left off instead of reporting No active session. Recreation only happens when the caller clears the same management-access check as an explicit activation: a valid management credential (Authorization: Bearer / X-Api-Key) or a request from the loopback interface. A remote caller holding nothing but a stale token still gets 401. It is governed by SESSION_AUTO_RECREATE_ENABLED (default True), settable as an environment variable, as session.auto_recreate_enabled in config.yaml, or from the Web UI settings panel. Two cases are never recreated:

A session ended deliberately with POST /api/v2/agents/{agent_id}/deactivate — logout is authoritative, so activate explicitly afterwards.
A stale token whose agent has since started a newer session — the newer session is never superseded.

The replacement token comes back in the X-Session-Token response header (or the refreshed memanto_session_token cookie for browser clients), the same handoff used for auto-renewal.

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. (With auto-recreation enabled, an authorized caller usually gets a fresh session transparently instead — but keep this fallback for the cases it does not cover.)
Cache and continue — reading any X-Session-Token response header, since a renewed or recreated session invalidates the token you sent.

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.
Auto-recreation: an authorized caller presenting an already-expired token gets a fresh session instead of a 401 (SESSION_AUTO_RECREATE_ENABLED, default True).
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 and auto-recreate sessions; only re-activate after a 401 that survives both
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

Automatic Recreation After Expiry

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

​Automatic Recreation After Expiry

​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

Automatic Recreation After Expiry

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