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
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
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
Congratulations! You’ve built your first memory-enabled agent. Now explore advanced features!
