Octopoda OS
The open-source memory operating system for AI agents. Persistent memory, semantic search, loop detection, agent messaging, crash recovery, and real-time observability.
What is Octopoda OS?
Octopoda OS is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to open-source memory operating system for ai agents. persistent memory, semantic search, loop detection, agent messaging, crash recovery, and real-time observability.
The open-source memory operating system for AI agents. Persistent memory, semantic search, loop detection, agent messaging, crash recovery, and real-time observability.
This server falls under the Knowledge & Memory category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- The open-source memory operating system for AI agents. Persi
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx octopoda-osConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Octopoda OS
Octopoda OS is an open-source memory operating system for AI agents that provides persistent, cross-session memory, semantic search, inter-agent messaging, goal tracking, crash recovery via snapshots, and loop detection. It integrates with LangChain, CrewAI, AutoGen, and OpenAI Agents SDK, and exposes 28 MCP tools for direct use with Claude and other MCP-compatible clients. Agents can store structured facts, recall them semantically, share memory between agents in named spaces, and recover their state after unexpected failures.
Prerequisites
- Python 3.10 or later (3.9+ for core features without MCP)
- An Octopoda API key from octopodas.com (free tier available); or set OCTOPODA_LOCAL_MODE=1 for fully offline use
- pip or uv for package installation
- An MCP-compatible client such as Claude Desktop or Claude Code
Install Octopoda with MCP support
Install the octopoda package with the mcp extra to include the MCP server module. Python 3.10+ is required for the MCP extra.
pip install "octopoda[mcp]"Get your API key
Sign up for a free account at octopodas.com to obtain an OCTOPODA_API_KEY (format: sk-octopoda-...). Alternatively, skip this step and set OCTOPODA_LOCAL_MODE=1 to run fully offline.
export OCTOPODA_API_KEY="sk-octopoda-YOUR_KEY_HERE"Register with Claude Code
Add the Octopoda MCP server to Claude Code using the mcp add command. The server module is synrix_runtime.api.mcp_server.
claude mcp add octopoda -s user -e OCTOPODA_API_KEY=sk-octopoda-YOUR_KEY \
-- python -m synrix_runtime.api.mcp_serverOr configure Claude Desktop
Add the server to claude_desktop_config.json for Claude Desktop. Use the python binary from your virtual environment for isolated dependencies.
{
"mcpServers": {
"octopoda": {
"command": "python",
"args": ["-m", "synrix_runtime.api.mcp_server"],
"env": {
"OCTOPODA_API_KEY": "sk-octopoda-YOUR_KEY"
}
}
}
}Optional: configure local embedding model
Install the ai extra for local semantic search without sending data to a cloud provider. The default embedding model is BAAI/bge-small-en-v1.5.
pip install "octopoda[ai]"
export OCTOPODA_EMBEDDING_MODEL="BAAI/bge-small-en-v1.5"Octopoda OS Examples
Client configuration
Claude Desktop configuration for Octopoda OS. For fully local operation without cloud sync, replace the API key with OCTOPODA_LOCAL_MODE=1.
{
"mcpServers": {
"octopoda": {
"command": "python",
"args": ["-m", "synrix_runtime.api.mcp_server"],
"env": {
"OCTOPODA_API_KEY": "sk-octopoda-YOUR_KEY"
}
}
}
}Prompts to try
Example prompts that use Octopoda's 28 MCP tools for persistent memory, semantic search, goal tracking, and agent messaging.
- "Remember that my preferred database is PostgreSQL and I always use async Python"
- "What do you remember about my coding preferences?"
- "Search my memory for anything related to authentication decisions I've made"
- "Set a goal to migrate the API to GraphQL with milestones: schema design, resolver implementation, testing"
- "Take a memory snapshot called before-refactor so I can restore it if needed"
- "Share the API design decisions with agent-team-b in the shared knowledge space"Troubleshooting Octopoda OS
synrix_runtime module not found when starting the MCP server
Ensure octopoda was installed with the mcp extra: `pip install "octopoda[mcp]"`. The synrix_runtime package is only included in the mcp and all extras. Verify with `python -c "import synrix_runtime"`.
Memory is not persisting between sessions
If running in cloud mode, verify OCTOPODA_API_KEY is valid and you are connected to octopodas.com. If in local mode (OCTOPODA_LOCAL_MODE=1), check that SYNRIX_DATA_DIR points to a writable directory that persists between restarts.
Semantic search returns irrelevant results
For best results install the ai extra to enable local embeddings: `pip install "octopoda[ai]"`. Without it, search falls back to keyword matching. Set OCTOPODA_EMBEDDING_MODEL to a model suited to your data domain.
Frequently Asked Questions about Octopoda OS
What is Octopoda OS?
Octopoda OS is a Model Context Protocol (MCP) server that open-source memory operating system for ai agents. persistent memory, semantic search, loop detection, agent messaging, crash recovery, and real-time observability. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Octopoda OS?
Follow the installation instructions on the Octopoda OS GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Octopoda OS?
Octopoda OS works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Octopoda OS free to use?
Yes, Octopoda OS is open source and available under the NOASSERTION license. You can use it freely in both personal and commercial projects.
Octopoda OS Alternatives — Similar Knowledge & Memory Servers
Looking for alternatives to Octopoda OS? Here are other popular knowledge & memory servers you can use with Claude, Cursor, and VS Code.
MemPalace
★ 52.6kA local AI memory system that stores all conversations verbatim and organizes them into navigable structures. It provides 19 MCP tools for AI assistants to search and retrieve past decisions, debugging sessions, and architecture debates automatically
Kratos
★ 25.7k🏛️ Memory System for AI Coding Tools - Never explain your codebase again. MCP server with perfect project isolation, 95.8% context accuracy, and the Four Pillars Framework.
Context Mode
★ 15.4kAn MCP server that preserves LLM context by intercepting large data outputs and returning only concise summaries or relevant sections. It enables efficient sandboxed code execution, file processing, and documentation indexing across multiple programm
Memu
★ 13.7kMemory for 24/7 proactive agents like OpenClaw.
MemOS
★ 9.3kMemOS (Memory Operating System) is a memory management operating system designed for AI applications. Its goal is: to enable your AI system to have long-term memory like a human, not only remembering what users have said but also actively invoking, u
Everos
★ 5.4kBuild, evaluate, and integrate long-term memory for self-evolving agents.
Browse More Knowledge & Memory MCP Servers
Explore all knowledge & memory servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Octopoda OS in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Octopoda OS?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.