Quickstart: REST API

Learn how to build an AI agent with persistent memory using Memanto’s REST API.

What You’ll Build

A simple customer support agent that:

Remembers customer preferences
Recalls relevant context
Uses memories to provide personalized responses

Prerequisites

Memanto server running (memanto serve) with MOORCHEH_API_KEY configured in its environment
Python 3.10+
httpx library: pip install httpx

Memanto authenticates with Moorcheh on the server using the configured MOORCHEH_API_KEY. API clients do not send an Authorization header — they only send X-Session-Token for memory operations.

Architecture

Your Agent Code
      ↓
   REST API (X-Session-Token only)
      ↓
Memanto Server  (MOORCHEH_API_KEY env)
      ↓
Moorcheh.ai (Semantic Database)

Step 1: Start Memanto Server

In a terminal:

export MOORCHEH_API_KEY=your_moorcheh_key
memanto serve

Expected output:

INFO:     Application startup complete

Step 1.5: Create the Agent Once

Create the agent ID used by the example before running the script:

memanto agent create my-support-bot

Step 2: Create the Agent

Create customer_agent.py:

import httpx
from typing import Optional

class CustomerSupportAgent:
    def __init__(self, agent_id: str = "customer-support"):
        self.memanto_url = "http://localhost:8000"
        self.agent_id = agent_id
        self.session_token: Optional[str] = None
        self.client = httpx.Client()

    def _headers(self) -> dict:
        if not self.session_token:
            raise ValueError("Session not activated. Call activate_session() first.")
        return {
            "X-Session-Token": self.session_token,
            "Content-Type": "application/json",
        }

    def activate_session(self) -> str:
        """Start a new agent session."""
        response = self.client.post(
            f"{self.memanto_url}/api/v2/agents/{self.agent_id}/activate"
        )
        response.raise_for_status()
        data = response.json()
        self.session_token = data["session_token"]
        print(f"✓ Session activated for '{self.agent_id}'")
        print(f"  Session expires: {data['expires_at']}")
        return self.session_token

    def remember(self, content: str, memory_type: str = "fact") -> str:
        """Store a memory about the customer."""
        response = self.client.post(
            f"{self.memanto_url}/api/v2/agents/{self.agent_id}/remember",
            headers=self._headers(),
            json={
                "content": content,
                "type": memory_type,
                "title": f"{memory_type.title()}: {content[:50]}",
                "confidence": 1.0,
            },
        )
        response.raise_for_status()
        data = response.json()
        print(f"✓ Memory stored: {data['memory_id']}")
        return data["memory_id"]

    def recall(self, query: str, limit: int = 5) -> list[dict]:
        """Retrieve relevant memories about the customer."""
        response = self.client.post(
            f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall",
            headers=self._headers(),
            json={"query": query, "limit": limit},
        )
        response.raise_for_status()
        return response.json().get("memories", [])

    def answer(self, question: str) -> str:
        """Generate an answer grounded in agent memories."""
        response = self.client.post(
            f"{self.memanto_url}/api/v2/agents/{self.agent_id}/answer",
            headers=self._headers(),
            json={"question": question},
        )
        response.raise_for_status()
        return response.json().get("answer", "")

    def close(self):
        """Clean up resources."""
        self.client.close()

Step 3: Use Your Agent

Create main.py:

from customer_agent import CustomerSupportAgent

def main():
    agent = CustomerSupportAgent(agent_id="my-support-bot")

    try:
        agent.activate_session()

        # Remember customer preferences
        print("\n📝 Storing customer memories...")
        agent.remember("Customer name is Alice Johnson", "fact")
        agent.remember("Alice works in the finance industry", "fact")
        agent.remember("Alice prefers email communication", "preference")
        agent.remember("Alice's timezone is PST (UTC-8)", "fact")

        # Recall memories
        print("\n🔍 Recalling memories...")
        memories = agent.recall("What do I know about Alice?")
        print(f"Found {len(memories)} memories:")
        for mem in memories:
            print(f"  - {mem['content']} ({mem['type']})")

        # Get AI-powered answer
        print("\n🤖 Generating AI answer...")
        answer = agent.answer("How should I communicate with Alice and what time zone is she in?")
        print(f"Answer: {answer}")

        # Simulate another conversation
        print("\n\n--- Later Conversation ---\n")

        memories = agent.recall("Tell me about this customer")
        print(f"✓ Recalled {len(memories)} memories from first conversation")

        if memories:
            context = memories[0]["content"]
            print(f"Using context: {context}")

    finally:
        agent.close()

if __name__ == "__main__":
    main()

Step 4: Run Your Agent

python main.py

Expected output:

✓ Session activated for 'my-support-bot'
  Session expires: 2026-05-09T20:30:00Z

📝 Storing customer memories...
✓ Memory stored: mem_abc123
✓ Memory stored: mem_def456
✓ Memory stored: mem_ghi789
✓ Memory stored: mem_jkl012

🔍 Recalling memories...
Found 4 memories:
  - Alice works in the finance industry (fact)
  - Customer name is Alice Johnson (fact)
  - Alice prefers email communication (preference)
  - Alice's timezone is PST (UTC-8) (fact)

🤖 Generating AI answer...
Answer: Alice works in finance and is in the PST timezone.
She prefers email communication, so I should reach out
to her via email during business hours in PST.

--- Later Conversation ---

✓ Recalled 4 memories from first conversation
Using context: Alice works in the finance industry

Step 5: Use Memory Types Effectively

Different memory types help organize information:

# Facts - objective information
agent.remember("Customer ID is CUST-12345", "fact")

# Preferences - user likes/dislikes
agent.remember("Prefers concise responses", "preference")

# Decisions - choices made
agent.remember("Chose Plan B (Enterprise)", "decision")

# Commitments - promises made
agent.remember("Will provide report by Friday", "commitment")

# Events - what happened
agent.remember("Attended quarterly business review", "event")

# Goals - objectives
agent.remember("Target: Reduce support tickets by 20%", "goal")

# Errors - mistakes to avoid
agent.remember("Previous order had billing issue", "error")

Step 6: Extend Your Agent

Batch Store Memories

Store multiple memories at once:

def batch_remember(self, memories: list[dict]) -> dict:
    """Store multiple memories efficiently (max 100 per call)."""
    response = self.client.post(
        f"{self.memanto_url}/api/v2/agents/{self.agent_id}/batch-remember",
        headers=self._headers(),
        json={"memories": memories},
    )
    response.raise_for_status()
    return response.json()

# Usage
agent.batch_remember([
    {"content": "Alice Johnson", "type": "fact"},
    {"content": "Finance industry", "type": "fact"},
    {"content": "Email preferred", "type": "preference"},
])

Temporal Queries

Recall memories from specific time periods:

def recall_as_of(
    self,
    timestamp: str,
    type: list[str] | None = None,
    limit: int | None = None,
) -> list[dict]:
    """Get memories valid at a specific time."""
    body: dict = {"as_of": timestamp}
    if type:
        body["type"] = type
    if limit:
        body["limit"] = limit
    response = self.client.post(
        f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall/as-of",
        headers=self._headers(),
        json=body,
    )
    response.raise_for_status()
    return response.json()["memories"]

# Recall state as of yesterday
memories = agent.recall_as_of(
    timestamp="2026-05-08T12:00:00Z",
    type=["preference"],
)

Recall the Latest Memories

/recall/recent returns memories sorted newest-first (no query needed):

def recall_recent(self, limit: int = 10) -> list[dict]:
    response = self.client.post(
        f"{self.memanto_url}/api/v2/agents/{self.agent_id}/recall/recent",
        headers=self._headers(),
        json={"limit": limit},
    )
    response.raise_for_status()
    return response.json()["memories"]

Session Renewal

Sessions are auto-renewed on memory requests when they’re near expiry. To start a fresh session explicitly, call /activate again — the new token replaces the old one. There is no separate /extend endpoint.

agent.activate_session()  # returns a new session_token

Complete Example

For a production-ready example, see the API Reference with all endpoints documented.

Next Steps

Full REST API Reference: API Documentation
Memory Types: Memory Types Reference
Advanced Patterns: Agent Patterns Guide
CLI Alternative: CLI Commands
TypeScript SDK: TypeScript SDK Reference
Integrations: Connect to IDE Plugins

Congratulations! You’ve built your first memory-enabled agent. Now explore advanced features!

Getting Started

Guides

Reference

Quickstart: REST API

Quickstart: REST API

What You’ll Build

Prerequisites

Architecture

Step 1: Start Memanto Server

Step 1.5: Create the Agent Once

Step 2: Create the Agent

Step 3: Use Your Agent

Step 4: Run Your Agent

Step 5: Use Memory Types Effectively

Step 6: Extend Your Agent

Batch Store Memories

Temporal Queries

Recall the Latest Memories

Session Renewal

Complete Example

Next Steps

​Quickstart: REST API

​What You’ll Build

​Prerequisites

​Architecture

​Step 1: Start Memanto Server

​Step 1.5: Create the Agent Once

​Step 2: Create the Agent

​Step 3: Use Your Agent

​Step 4: Run Your Agent

​Step 5: Use Memory Types Effectively

​Step 6: Extend Your Agent

​Batch Store Memories

​Temporal Queries

​Recall the Latest Memories

​Session Renewal

​Complete Example

​Next Steps

Quickstart: REST API

What You’ll Build

Prerequisites

Architecture

Step 1: Start Memanto Server

Step 1.5: Create the Agent Once

Step 2: Create the Agent

Step 3: Use Your Agent

Step 4: Run Your Agent

Step 5: Use Memory Types Effectively

Step 6: Extend Your Agent

Batch Store Memories

Temporal Queries

Recall the Latest Memories

Session Renewal

Complete Example

Next Steps