Octopoda
Open-source memory and observability layer that gives AI agents persistent memory, loop detection, and hash-chained audit trails.
- Source repo
- RyjoxTechnologies/Octopoda-OS
- Stars
- ★ 486
- Last updated
- 2mo ago
- License
- NOASSERTION
- Primary language
- Python
- FA score
- 43/100 · Major gaps
At a glance
- Works with
- Universal · cross-platformClaude Code · Claude.ai · OpenAI APIChatGPT (Partial support)
- You'll need
- Typical use
- Developers shipping customer-facing chatbots: a process restart currently wipes what the agent knew about the user; AgentRuntime's remember/recall persists across restarts, crashes, and deploys.
- Main limitation
- Local semantic search needs the octopoda[ai] extra (~33 MB embedding model); without it recall_similar returns 0 results locally and logs a warning, so behavior differs from cloud.
- Source review
- 43/100 · Major gaps
What does this agent do, and when should you use it?
Octopoda is the open-source memory and observability layer for AI agents from Ryjox Technologies. It ships as a Python package and activates on pip install: the AgentRuntime class plus a small API (remember, recall, log_decision, snapshot, restore) gives each agent versioned memory that survives restarts, crashes, and deploys. Underneath, it runs a five-signal loop detector (retry, oscillation, ping-pong, reflection, recall), keeps a replayable audit timeline, and offers hash-chained per-agent audit events through the audit-v2 endpoints (prev_hash → _this_hash) with a verify-chain call. Local mode is SQLite at ~/.synrix/data/synrix.db with no account required; setting OCTOPODA_API_KEY moves the same code to cloud storage on PostgreSQL + pgvector. It also provides adapters for LangChain, CrewAI, AutoGen, and the OpenAI Agents SDK, plus an MCP server exposing 28 tools to Claude Code, Claude Desktop, Cursor, or any MCP-compatible client.
The entry points are octopoda.init() and the AgentRuntime class. octopoda.init(api_key=...) auto-detects your framework, captures each turn, distills memories, and injects relevant recall into later calls; octopoda-run python your_agent.py auto-instruments an existing script without editing it, and octopoda-run doctor checks the key and detected frameworks. Memory operations include remember, recall, recall_history, recall_similar, forget, forget_stale, consolidate, and memory_health. Multi-agent work uses named shared spaces via share and read_shared, with shared_conflicts to review concurrent writes. Loop detection runs automatically on every write, while intervention (auto-pause, spend caps) is opt-in through the v2 circuit-breaker config. Auditing has two paths: log_decision records a decision plus a memory snapshot taken at that instant, while POST /v1/auditv2/event, GET /v1/auditv2/events, and GET /v1/auditv2/verify-chain provide per-agent hash chaining and integrity verification. Agents also get snapshot/restore, set_goal/update_progress, and send_message/read_messages. For a UI, pip install octopoda[server] and run the octopoda command to serve the same dashboard as the cloud version at http://localhost:7842.
- Developers shipping customer-facing chatbots: a process restart currently wipes what the agent knew about the user; AgentRuntime's remember/recall persists across restarts, crashes, and deploys.
- Teams already on LangChain, CrewAI, AutoGen, or the OpenAI Agents SDK: drop in the matching memory class (LangChainMemory, CrewAIMemory, AutoGenMemory, OpenAIAgentsMemory) for persistence without standing up a vector database.
- Operators watching a stuck agent burn tokens: use the five-signal loop detector to see which retry, oscillation, or ping-pong calls caused it, then decide whether to enable auto-pause and spend limits.
- Teams with audit or compliance requirements: write key events through the audit-v2 endpoints to get a per-agent hash chain, then call verify-chain to confirm the log was not altered.
- Multi-agent projects: let a research agent and a coding assistant exchange findings through a shared memory space, and inspect conflicts when two agents write the same key.
- Individual developers using Claude Code or Cursor: install octopoda[mcp], register the MCP server, and give the assistant memory that survives across sessions.
How do you install or deploy this agent?
Requires Python 3.9+ for the core package ([mcp] requires 3.10+). Pick your extras: pip install octopoda for the core; pip install octopoda[ai] for local semantic-search embeddings (~33 MB model, CPU); pip install octopoda[server] for the Flask-based local dashboard; pip install octopoda[nlp] for spaCy knowledge-graph extraction; pip install octopoda[mcp] for the MCP server; pip install octopoda[all] for everything (Python 3.10+). On Python 3.9, use pip install octopoda[ai,server,nlp] to get everything except MCP. No account is needed for local mode, which stores data at ~/.synrix/data/synrix.db. For cloud sync, run octopoda-init to interactively validate and save a key to ~/.octopoda/config.json, or export OCTOPODA_API_KEY (real cloud keys start with sk-octopoda-; values like local, offline, dev, none, or YOUR_KEY_HERE force local mode).
How do you use this agent?
Fastest path: pip install octopoda, then import octopoda; octopoda.init(api_key="sk-octopoda-..."), or launch an existing script with octopoda-run python your_agent.py. Account-free SDK usage: from octopoda import AgentRuntime; agent = AgentRuntime("my_chatbot"); agent.remember("user_name", "Alice"); then after killing and restarting Python, agent.recall("user_name").value still returns 'Alice'. For the local dashboard, pip install octopoda[server] and run octopoda, then open http://localhost:7842. To wire it into Claude Code, pip install octopoda[mcp] and run claude mcp add octopoda -s user -e OCTOPODA_API_KEY=sk-octopoda-YOUR_KEY -- python -m synrix_runtime.api.mcp_server; for Claude Desktop, add the same command and args under mcpServers in claude_desktop_config.json. Note that clients prefix tool names with the server name, so the server-side octopoda_remember is exposed as octopoda_octopoda_remember. To have several scripts share one brain, set OCTOPODA_AGENT_ID=my-agent, and raise OCTOPODA_RECALL_TIMEOUT (seconds) on slow networks. After changing MCP registration env vars, restart the Claude Code window; a /mcp reconnect alone will not pick them up.
What are this agent's strengths and limitations?
- Local-first by design: a single pip install runs with zero infrastructure and no account, storing data in SQLite at ~/.synrix/data/synrix.db; a single environment variable later switches the same code to cloud.
- Five-signal loop detection (retry, oscillation, ping-pong, reflection, recall) that names the exact calls behind a stuck agent, with opt-in intervention so the policy stays yours.
- Audit-v2 endpoints provide per-agent hash chaining (prev_hash -> _this_hash) plus a verify-chain endpoint, enabling tamper-evident provenance for decisions and recoveries.
- Memory is versioned by default with recall_history for every prior value, and is complemented by shared memory spaces, conflict review, snapshots, and restore.
- A 28-tool MCP server plus adapters for LangChain, CrewAI, AutoGen, and the OpenAI Agents SDK keep integration cost low.
- Local semantic search needs the octopoda[ai] extra (~33 MB embedding model); without it recall_similar returns 0 results locally and logs a warning, so behavior differs from cloud.
- The MCP extra requires Python 3.10+, so users on Python 3.9 cannot use the MCP integration even though the core package supports 3.9.
- The repository metadata lists the license as NOASSERTION while the README and badge claim MIT, so the actual license terms should be confirmed before adoption.
- Cloud features depend on api.octopodas.com and keys issued via octopodas.com, and the free tier is capped at 5 agents, 5,000 memories, and 60 rpm.
- MCP clients double-prefix tool names (octopoda_remember surfaces as octopoda_octopoda_remember), and changing registration env vars requires restarting the Claude Code window since a /mcp reconnect is not enough.
How does this agent compare with similar options?
The README positions Octopoda against Mem0, Zep, and LangChain Memory: Mem0 (Apache 2.0) and Zep (partial community edition) are described as cloud-first, while LangChain Memory is in-process and needs its own vector database. Octopoda is local-first on SQLite and adds loop detection, agent messaging, hash-chained audit trails, crash recovery, shared memory, a 28-tool MCP server, and integrations for LangChain, CrewAI, AutoGen, and the OpenAI Agents SDK, with semantic search available locally or in the cloud.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Octopoda This agent | 43 · Major gaps | ★ 486 | 2mo ago | Python | Claude Code · Claude.ai · OpenAI API |
| Asqav SDK (Python + TypeScript) | 72 · Some gaps | ★ 507 | 11d ago | Python | — |
| Caura | 70 · Some gaps | ★ 533 | today | Python | Codex · Claude Code · Claude.ai |
| Ori Mnemos | 80 · Good | ★ 324 | 3d ago | TypeScript | Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Trust is thin overall. Least privilege: neither README nor pyproject states the runtime permission surface; only local SQLite and optional cloud calls can be inferred, with no permission declaration or sandbox constraint, deducted. User confirmation: loop-detection intervention (auto-pause, spend cap) is explicitly opt-in, but memory writes, shared-space writes, and audit writes all happen automatically with no per-action confirmation, deducted. Data-flow transparency: README documents the local SQLite path and the cloud-sync switch, but gives no field-level list of what leaves the machine, deducted. Sensitive data: SECURITY.md lists PBKDF2, SHA-256, RLS, and TLS for the cloud side, but no encryption or redaction of memory content is visible on the SDK side, deducted. Dependency security: pyproject pins only lower bounds (requests>=2.28.0, pydantic>=2.0.0, etc.) with no lockfile, hashes, or vulnerability scanning, deducted. External effects: the CLI starts a local server and writes ~/.synrix and ~/.octopoda config, which is expected but not centrally documented, deducted. Rollback: snapshot/restore, forget, versioned memory, and export/import give a reasonably complete rollback path, scored 2. Source attribution: LICENSE separates MIT SDK code from proprietary native engine, but the README MIT badge and the 'SDK Code Only' wording diverge, and the publisher is unverified, deducted.
Self-consistency: the README mixes octopoda with synrix/synrix_runtime, shows both ~/.synrix/data and OCTOPODA_DATA_DIR, and documents a double-prefixed MCP tool name, indicating naming and config legacy, deducted. Dependency availability: core deps are only requests and pydantic, extras are layered clearly, and the Python-version split (mcp needs 3.10+) is stated, scored 2. Failure messages: README notes recall_similar returns 0 results with a warning when the AI extra is absent locally, but there is no documented error-code or failure-semantics reference, deducted.
Audience and scenarios: README targets developers and covers local, cloud, MCP, and multiple framework integrations, scored 2. Capability boundaries: it claims automatic framework detection and recall injection but does not describe degradation when detection fails, the framework is unsupported, or recall times out, deducted. Trigger precision: five loop signals are named but no thresholds, false-positive rates, or tuning guidance are given, deducted. Environment fit: Python 3.9+, the macOS CI exclusion rationale, and Windows/Ubuntu coverage are stated concretely, scored 2.
Information architecture: the README has a full table of contents and clear sections, scored 2. Install notes: pip extras layering, Python-version differences, local-mode sentinels, and MCP re-registration caveats are all documented, scored 2. Naming stability: octopoda and synrix_runtime namespaces coexist and CLI entry points mix both module trees, so stability is questionable, deducted. Examples and FAQ: examples are rich, covering LangChain, CrewAI, AutoGen, OpenAI Agents SDK, and MCP config, scored 2. Known limitations: only scattered notes (macOS CI timeout, local semantic-search limit) with no consolidated limitations section, deducted. License: LICENSE is MIT but scoped to 'SDK Code Only' with a proprietary native engine, which does not fully match the README badge and the pyproject MIT field, deducted. Versioning and changelog: pyproject is at 3.3.5 and CI checks PyPI parity, but no CHANGELOG content is present in the repo, deducted. Maintenance responsibility: SECURITY.md gives an email and response timelines, but the publisher is unverified so the maintaining entity is unclear, deducted.
Output usability: memory read/write, audit, snapshot, and export APIs have directly usable examples with clear output shapes, scored 2. Marginal value: memory and observability layers already have mature alternatives such as Mem0 and Zep, and the README comparison table is self-reported with no independent benchmark, deducted. Cost benefit: zero-infrastructure local mode is a real advantage, but cloud pricing and the proprietary native-engine license boundary may add cost and compliance burden, deducted.
Claim traceability: many README claims (visible within ten seconds, five-signal engine, 28 tools) carry no reproducible evidence or benchmark data, deducted. Cross-source corroboration: CI workflows and tests/ci_smoke.py partially corroborate the quick-start and dashboard-boot paths, but cloud and hash-chain claims rest on README assertion alone, deducted. Fact-inference separation: the docs do not clearly separate verified facts from marketing statements, deducted.
- Publisher identity is unverified; the README shows an MIT badge while LICENSE scopes MIT to 'SDK Code Only' with a proprietary native engine, so commercial-use boundaries must be confirmed before adoption.
- Memory writes, shared-space writes, and audit writes run automatically by default; loop intervention is opt-in, but there is no per-action user confirmation overall.
- Dependencies specify only lower bounds with no lockfile or vulnerability scanning, so supply-chain risk must be assessed independently.
- The README mixes octopoda with synrix/synrix_runtime naming and shows two different data-directory conventions, so integration should follow the actual code.
- Many capability and performance claims lack reproducible evidence; cloud and hash-chain integrity claims rest on documentation assertion alone.