Memstate + OpenAI Agents SDK
Give your OpenAI Agents SDK agents persistent, structured memory via MCP.
The OpenAI Agents SDK has first-class MCP support via MCPServerStdio and MCPServerSse. Memstate plugs in as a local stdio MCP server, giving every agent automatic access to versioned, project-scoped memory.
Requirements
- Python 3.12+ (openai-agents requires 3.12+)
- Node.js 18+ (for npx @memstate/mcp)
- OpenAI API key
- Memstate API key — get one free
Install the SDK
pip install openai-agentsSet environment variables
export OPENAI_API_KEY="sk-..."
export MEMSTATE_API_KEY="mst_..."Connect Memstate via MCP
Pass MCPServerStdio to your agent. The MCP server is spawned automatically as a subprocess — no separate process to manage.
"""
Memstate AI + OpenAI Agents SDK
Requires: pip install openai-agents
Env: OPENAI_API_KEY, MEMSTATE_API_KEY
"""
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStdio
async def main() -> None:
async with MCPServerStdio(
name="memstate",
params={
"command": "npx",
"args": ["-y", "@memstate/mcp"],
"env": {
**os.environ,
"MEMSTATE_API_KEY": os.environ["MEMSTATE_API_KEY"],
},
},
cache_tools_list=True,
) as mcp_server:
agent = Agent(
name="MemstateAgent",
instructions=(
"You are a helpful assistant with persistent memory via Memstate. "
"Before starting any task, call memstate_get to load project context. "
"After completing a task, call memstate_remember to save a summary."
),
mcp_servers=[mcp_server],
)
result = await Runner.run(
agent,
'Save a memory: memstate_remember(project_id="demo", '
'content="## Hello World\\nFirst memory saved via OpenAI Agents SDK.", '
'source="agent"). Then call memstate_get(project_id="demo") and show me the result.',
)
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())Add memory instructions
Add these instructions to your agent's instructions field (or an AGENTS.md file) so it loads and saves context automatically.
## Memory (Memstate)
Before starting any task:
- Call memstate_get(project_id="<your_project>") to load existing context.
After completing a task:
- Call memstate_remember(project_id="<your_project>", content="<markdown summary>", source="agent")
to persist what was done for future sessions.Test it — run the onboarding prompt
I'm onboarding Memstate AI memory for this project. Please:
1. Analyze this codebase and write a concise high-level architecture overview in markdown.
2. Save it with: memstate_remember(project_id="<your_project>", content="<the markdown>", source="agent")
3. Then call memstate_get(project_id="<your_project>") and show me the memory tree.Your agent will analyze the project, save a structured memory, then confirm it worked by displaying the memory tree.
Using remote MCP (MCPServerSse)
For production deployments, use MCPServerSse to connect to the hosted Memstate endpoint:
from agents.mcp import MCPServerSse
mcp_server = MCPServerSse(
name="memstate",
params={
"url": "https://mcp.memstate.ai/sse",
"headers": {"Authorization": f"Bearer {os.environ['MEMSTATE_API_KEY']}"},
},
)