Octopoda-OS

Contents

• What is Octopoda
• The problems it solves
• Quick start
• Local vs cloud
• What you get out of the box
• Agents · Memory · Shared memory · Audit trail
• Advanced features
• Framework integrations
• MCP server
• How it compares
• Cloud & pricing
• Installation · Configuration

What is Octopoda

Octopoda is the layer between your AI agents and a production system that behaves. You write your agent however you like — plain Python, LangChain, CrewAI, AutoGen, the OpenAI Agents SDK, or MCP — and Octopoda sits underneath and handles four things agents consistently get wrong:

• Memory that survives every restart, crash, and deploy.
• Loop detection that flags a stuck agent in seconds, with the exact calls that caused it.
• An audit trail of every decision, write, and recovery — optionally hash-chained and verifiable.
• A live dashboard so you can actually see what your agents are doing.

It runs locally with one pip install and zero infrastructure. When you outgrow local, the same code syncs to the cloud with a single environment variable — no re-architecture, no migration. The whole thing is MIT-licensed.

If you have ever shipped an agent and watched it forget the user between sessions, loop on a failing API call, or vanish into a black box you couldn't debug, this is the missing layer.

The problems it solves

Agents forget on every restart. The moment your process restarts, the agent loses everything it knew about the user, the task, and the conversation. Octopoda gives every agent persistent memory that survives restarts, crashes, deployments, and kills — versioned by default.

Agents loop, and quietly burn money. A stuck agent retrying a failing tool call can spend real money before anyone notices. Octopoda's detector catches retry, oscillation, ping-pong, reflection, and recall-write patterns in seconds and surfaces exactly which calls caused them. Detection is automatic on every write; intervention (auto-pause, spend cap) is opt-in through the v2 circuit-breaker config, so the policy stays yours.

Agents are black boxes. When an agent does something surprising in production, you usually can't reconstruct why. Octopoda logs every decision, write, and recovery into a replayable timeline you can diff over time. Events written through the audit-v2 endpoint are hash-chained per agent (prev_hash → _this_hash), so you can verify integrity with a single call.

Quick start

Already have an agent on OpenAI, Anthropic, LangChain, CrewAI, AutoGen, or MCP? Add memory in two lines — no change to your agent's logic:

pip install octopoda

import octopoda
octopoda.init(api_key="sk-octopoda-...")   # the entire 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 the live dashboard within about ten seconds of the first turn.

Running multiple scripts that should share one brain? Set OCTOPODA_AGENT_ID=my-agent so they write to the same memory. On slow networks, raise OCTOPODA_RECALL_TIMEOUT=5 (seconds).

Or use the SDK directly — local-first, no account

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.

That is the whole 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?

octopoda-init

It walks you through pasting (or signing up free for) an API key, validates it, and saves it to ~/.octopoda/config.json. No environment variables to edit. The SDK auto-loads the key on the next import, and 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 Python API both ways. Start local; move to cloud when you need sync, team access, or the managed dashboard.

What you get out of the box

When you create an AgentRuntime, all of this runs in the background automatically — no configuration:

Agents

Every agent gets a live profile: score, operation count, read/write latency, spend, and loop-suppression stats. Drill into any agent for its latency trend, operation breakdown, timeline, memory, and checkpoints.

Memory

Browse every memory an agent has written, filter by type (fact, preference, summary, embedding), inspect version history, and see exactly how each value changed over time and which agent wrote it.

agent.remember("user_name", "Alice")
agent