Octopoda-OS

What is Octopoda

Octopoda is the missing layer between your AI agents and a working production system. Think of it as the brain stem your agents always needed but never had.

You write your agent however you like. Pure Python, LangChain, CrewAI, AutoGen, OpenAI Agents SDK, MCP. Octopoda sits underneath and quietly handles the boring stuff that makes agents actually usable. Persistent memory that survives every restart. Loop detection that flags a stuck agent in seconds with structured signals you can wire into your runtime to pause or alert. A full audit trail of every decision, every memory write, every recovery, with a verifiable hash chain available via the audit-v2 API. A live dashboard that finally lets you see what your agents are doing.

It runs locally with one pip install and zero infrastructure. When you outgrow that, the same code syncs to the cloud with a single environment variable. No re-architecture, no migration, no lock-in. The whole thing is open source under MIT.

If you have ever shipped an AI agent and watched it forget who you are, loop on a failing API call for hours, or just disappear into a black box you cannot debug, this is the thing you wished existed.

Why Octopoda

Three things go wrong when AI agents leave your laptop. Octopoda handles all three out of the box, with no config, so you can focus on the agent and not the plumbing.

Agents forget, until they do not. Every time your process restarts, your agent loses everything it ever knew about the user, the task, and the conversation. Octopoda gives every agent persistent memory that survives restarts, crashes, deployments, and process kills. Memory just works, the way you always assumed it would.

Agents loop, and silently burn money. A stuck agent retrying a failing tool call can quietly burn hundreds of dollars in tokens before anyone notices. Octopoda's loop detector catches retry, oscillation, ping pong, reflection, and recall write patterns in seconds, and surfaces exactly which calls caused it. Detection is automatic on every write; intervention (auto-pause, spend cap) is opt-in via the v2 circuit-breaker config so the right policy is yours to set, not ours.

Agents are black boxes, and that is terrifying in production. Why did it do that? You had no idea, until now. Octopoda logs every decision, every write, every recovery into a replayable audit trail you can diff over time. The dedicated audit-v2 endpoint additionally hash-chains its events (prev_hash → _this_hash) so you can verify integrity via GET /v1/auditv2/verify-chain. Pair it with the live dashboard and you can finally see what your agents are doing in real time.

Quick Start — memory for your EXISTING agent in 2 lines (new in 3.3)

Already have an agent built on OpenAI, Anthropic, LangChain, CrewAI, AutoGen or MCP? You don't change a line of its logic:

pip install octopoda

import octopoda
octopoda.init(api_key="sk-octopoda-...")   # ← that's the whole integration

Octopoda auto-detects your framework, captures what matters from each turn, distills it into memories, and injects relevant recall into future calls — automatically. Or run any agent script unchanged from the terminal:

export OCTOPODA_API_KEY=sk-octopoda-...
octopoda-run python your_agent.py     # auto-instruments on launch
octopoda-run doctor                   # checks your key + detected frameworks

Get a free key at octopodas.com — your agents and their memories appear on a live dashboard ~10 seconds after the first turn.

Multiple scripts, one shared brain? Set OCTOPODA_AGENT_ID=my-agent so they write to the same memory. On slow networks, OCTOPODA_RECALL_TIMEOUT=5 (seconds).

Or use the SDK directly (local-first, no account needed)

from octopoda import AgentRuntime

agent = AgentRuntime("my_chatbot")
agent.remember("user_name", "Alice")

# kill the process. restart Python. then:
print(agent.recall("user_name").value)
# 'Alice' — still there. Survives every restart, deploy, and crash.

Either way that is the entire setup. Your agent now has persistent memory, loop detection, crash recovery, and an audit trail. No config, no Docker, no Redis, no extra services.

Want the local dashboard?

pip install octopoda[server]
octopoda

Open http://localhost:7842 — the same dashboard as the cloud version, running against your local data. No account, no API key.

Want cloud sync + a hosted dashboard?

One command after install:

octopoda-init

It walks you through: paste an API key (or sign up free at octopodas.com), validates it, and saves it to ~/.octopoda/config.json. No environment variables to set, no shell config to edit. The SDK auto-loads the key on next import.

After octopoda-init, the same Python code above writes to the cloud and shows up live at octopodas.com/dashboard.

export OCTOPODA_API_KEY=sk-octopoda-...

Both methods work. The SDK checks the env var first, then the config file.

Local vs Cloud — same code, your choice

Start local. Move to cloud when you need sync, team access, or the managed dashboard. Same Python API both ways.

How it stacks up