🐙 Octopoda

The open-source memory operating system for AI agents.

Persistent memory, loop detection, audit trails, and live observability — automatic on pip install.

Website · Docs · Dashboard · Quick start · MCP

_{Live overview from a real fleet. Agent health, operations volume, anomaly stream, and dollars saved by catching loops before they ran the bill.}

---

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

pip install octopoda

from octopoda import AgentRuntime

agent = AgentRuntime("my_agent")
agent.remember("user_pref", "dark mode")
agent.recall("user_pref")

That's it. Your agent now has persistent memory, loop detection, crash recovery, and an audit trail. No config, no setup, no Docker. Memory survives restarts, crashes, and deployments — automatically.

Want the 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?

Free at octopodas.com. Set the API key, same code, multi-device sync, team access.

export OCTOPODA_API_KEY=sk-octopoda-...

---

Local vs Cloud — same code, your choice

	Local	Cloud
Setup	pip install octopoda	Sign up at octopodas.com (free)
Storage	SQLite on your machine	PostgreSQL + pgvector
Dashboard	http://localhost:7842	octopodas.com/dashboard
Account	Not needed	Free, then optional paid tiers
Multi-device sync	No	Yes
Semantic search	octopoda[ai] extra (33 MB)	Built-in
Upgrade path	Set OCTOPODA_API_KEY	Already there

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

---

What You Get Out of the Box

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

Feature	What it does
Persistent memory	Survives restarts, crashes, deployments. Versioned by default.
Loop detection	5-signal engine catches retry, oscillation, ping-pong, reflection, recall.
Audit trail	Every write hashed and chained. Replayable, verifiable.
Crash recovery	Automatic snapshots and heartbeat-based restore.
Health scoring	Continuous performance and memory quality monitoring per agent.
Goal tracking	Set goals and milestones per agent (agent.set_goal()).

You don't configure any of it. It just works.

---

See Inside Your Agents

Track latency, error rates, memory usage, and health scores for every agent — with the same dashboard locally and in cloud.

Browse every memory the agent ever wrote, inspect version history, and see exactly how its knowledge changed over time.

---

Audit Trail

Every decision, crash, recovery, and anomaly your agents make is logged with full context — including a memory snapshot captured at the moment of decision. Replay any time window and see exactly what each agent knew, decided, and why.

agent.log_decision(
    decision="Keep single VPS instead of Kubernetes",
    reasoning="Current traffic doesn't justify K8s complexity. VPS handles 100x this load.",
    context={"current_rps": 14000, "threshold_rps": 1000000},
)

Every log_decision automatically captures a memory snapshot at that instant. The audit timeline shows decisions alongside crashes and recoveries, filterable per agent. Built-in similarity check warns you if a decision repeats a recent one.

Events logged via the audit-v2 endpoints (POST /v1/auditv2/log, GET /v1/auditv2/events) are hashed and chained per agent (prev_hash → _this_hash). Run GET /v1/auditv2/verify-chain to confirm integrity — it returns ok=true plus a per-agent breakdown. The legacy log_decision() SDK call writes a simpler audit row without the chain; route through the audit-v2 endpoint if you need tamper-evident provenance.

---

Shared Memory

Multiple agents working on the same problem can share knowledge through named memory spaces. Writes are atomic, reads are immediate, and every change is logged with its author — so you always know which agent contributed what.

research_agent.share("market_size", "$2.1B AI memory market by 2027", space="team-knowledge")
result = coding_assistant.read_shared("market_size", space="team-knowledge")
print(result.value)  # "$2.1B AI memory market by 2027"

Spaces track authorship and timestamps for every write. Use agent.shared_conflicts(space="team-knowledge") to surface disagreements when multiple agents write to the same key.

---

When You Need More Control

Everything below is optional. Use it when you need it.

Semantic Search

Find memories by meaning, not just exact keys.

agent.remember("bio", "Alice is a vegetarian living in London")
results = agent.recall_similar("what does the user eat?")
# Returns the right memory with a similarity score

Agent Messaging

Agents can talk to each other through shared inboxes.

agent_a.send_message("agent_b", "Found a bug in auth", message_type="alert")
messages = agent_b.read_messages(unread_only=True)

Goal Tracking

Set goals and track progress per agent.

agent.set_goal("Migrate to PostgreSQL", milestones=["Backup", "Schema", "Migrate", "Validate"])
agent.update_progress(milestone_index=0, note="Backup done")

Memory Management

agent.forget("outdated_config")                   # Delete a specific memory
agent.forget_stale(max_age_seconds=30*86400)      # Clean up memories older than 30 days
agent.consolidate(dry_run=False)                  # Merge near-duplicates
agent.memory_health()                             # Get a health report

Snapshots and Recovery

agent.snapshot("before_migration")
# ... something goes wrong ...
agent.restore("before_migration")

Export / Import

bundle = agent.export_memories()
new_agent.import_memories(bundle)

---

Framework Integrations

Drop into the framework you already use. One line, your agents get persistent memory.

LangChain — drop-in conversation memory

from octopoda import LangChainMemory
memory = LangChainMemory("my-chain")
memory.save_context({"input": "I prefer dark mode"}, {"output": "Got it!"})
variables = memory.load_memory_variables({})

CrewAI — persistent crew findings and task results

from octopoda import CrewAIMemory
crew = CrewAIMemory("research-crew")
crew.store_finding("researcher", "market_size", {"value": "$4.2B"})
finding = crew.get_finding("market_size")

AutoGen — multi-agent conversation memory

from octopoda import AutoGenMemory
memory = AutoGenMemory("dev-team")
memory.store_message("user_proxy", "assistant", "Research quantum computing")
history = memory.get_conversation_history()

OpenAI Agents SDK — thread and run persistence

from octopoda import OpenAIAgentsMemory
memory = OpenAIAgentsMemory()
memory.store_thread_state("thread_001", {"messages": [...]})
restored = memory.restore_thread("thread_001")

All integrations work locally (no API key) or with cloud sync (set OCTOPODA_API_KEY).

---

MCP Server

Give Claude, Cursor, or any MCP-compatible AI persistent memory with zero code.

pip install octopoda[mcp]

Claude Code:

claude mcp add octopoda -s user -e OCTOPODA_API_KEY=sk-octopoda-YOUR_KEY -- python -m synrix_runtime.api.mcp_server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "octopoda": {
      "command": "python",
      "args": ["-m", "synrix_runtime.api.mcp_server"],
      "env": { "OCTOPODA_API_KEY": "sk-octopoda-YOUR_KEY" }
    }
  }
}

28 tools for memory, search, loop detection, goals, messaging, decisions, snapshots, and more.

Full MCP tool list (the names your agent will actually see)

When you register the server with claude mcp add octopoda ..., the MCP client prefixes each tool with the server name. So the tool that the function defines as octopoda_remember ends up exposed to your agent as octopoda_octopoda_remember. This is correct behaviour from the client; just be aware of it when you write