Octopoda

The open-source memory operating system for AI agents.

Give your agents persistent memory, loop detection, audit trails, and real-time observability. Everything works automatically once you create an agent.

Track latency, error rates, memory usage, and health scores per agent.

Browse every memory, inspect version history, and see exactly how an agent's knowledge changed over time.

Quick Start

pip install octopoda

from octopoda import AgentRuntime

agent = AgentRuntime("my_agent")

That's it. Your agent now has persistent memory, loop detection, crash recovery, and an audit trail. Everything runs automatically in the background. Memory survives restarts, crashes, and deployments.

Store and retrieve memories when you need to:

agent.remember("key", "value")
agent.recall("key")

Want the dashboard? Run the server:

pip install octopoda[server]
octopoda

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

Want cloud sync across machines? Sign up free at octopodas.com, set your API key, and your agents sync to the cloud automatically:

export OCTOPODA_API_KEY=sk-octopoda-...

Same code, same dashboard — now backed by PostgreSQL with multi-device sync and team access.

Local vs Cloud

| | Local | Cloud | |---|---|---| | Setup | pip install octopoda | Sign up at octopodas.com | | Storage | SQLite on your machine | PostgreSQL + pgvector | | Dashboard | http://localhost:7842 | octopodas.com/dashboard | | Account needed | No | Yes (free) | | Data stays on your machine | Yes | Stored on cloud | | Multi-device sync | No | Yes | | Semantic search | Needs octopoda[ai] extra | Built-in | | Upgrade path | Set OCTOPODA_API_KEY | Already there |

Start local, upgrade to cloud when you need sync or team access. Both use the same API, same dashboard design, same code.

What You Get Out of the Box

When you create an AgentRuntime, all of this is handled for you automatically:

• Persistent memory — everything your agent stores survives restarts and crashes
• Loop detection — catches agents stuck in repetitive patterns before they burn tokens
• Audit trail — every decision, every write, every action is logged
• Crash recovery — automatic heartbeat monitoring with snapshot/restore
• Health scoring — continuous monitoring of memory quality and agent performance
• Heartbeats — background thread tracks agent liveness

You don't need to configure any of this. It just works.

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. Integrates with drift detection.

agent.set_goal("Migr

... [View full README on GitHub](https://github.com/RyjoxTechnologies/Octopoda-OS#readme)