The Problem
AI agents start every session with zero context. Each run loses prior decisions, repeated loops burn tokens unnoticed, and crashes wipe working state. Teams building multi-agent systems end up stitching together vector stores, session logs, and custom retry logic — none of which handle the full lifecycle of agent memory.
What This Does
Octopoda is a Python-based memory layer for AI agents. The core AgentRuntime (in synrix/agentbackend.py and synrix/agentmemory.py) gives agents persistent memory, loop detection, crash recovery, and audit trails. Storage is SQLite locally (synrix/sqliteclient.py) or PostgreSQL with pgvector for cloud sync (synrix/postgresclient.py). A Flask-based dashboard (synrixruntime/dashboard/app.py) provides real-time observability with a 3D neural graph visualization.
The repo also ships integration adapters for common agent frameworks: LangChain (synrix/langchain/), AutoGen (synrix/integrations/autogen.py), CrewAI (synrix/integrations/crewai.py), and OpenAI Agents (synrix/integrations/openaiagents.py). An MCP server (synrixruntime/api/mcpserver.py) exposes memory operations to MCP-compatible clients.
How To Use It
Setup: pyproject.toml is the dependency manifest. Install with pip install octopoda or pip install -e . for development. Docker deployment is available via Dockerfile and docker-compose.yml.
Configuration: Copy .env.example to .env and set OCTOPODAAPIKEY if you want cloud sync. Local mode needs no configuration. The dashboard runs on port 7842.
Running it: pip install octopoda python -c "from octopoda import AgentRuntime; agent = AgentRuntime('myagent')" Dashboard: pip install octopoda[server] octopoda
The CLI entry point is synrix/cli.py, invoked via python -m synrix or the octopoda command after installation.
Real-World Use
A customer-support automation setup with three agents — one triaging tickets, one drafting responses, one escalating edge cases. Each agent gets an AgentRuntime instance. When the triage agent crashes mid-session, synrixruntime/core/recovery.py restores its state from the audit log. The loop detector in synrix/memory.py flags the drafting agent if it repeats the same retrieval pattern, preventing token waste. The dashboard shows all three agents' activity in real time, so an operator sees a stuck agent before it burns through the monthly API budget.
Code Health & Issues
Med - No lockfile: pyproject.toml declares dependencies but there is no poetry.lock or requirements.txt with pinned versions. Builds are not reproducible. Med - Test breadth vs. reality: 34 test files exist, but several (testrealcustomer.py, testliveapi.py, testlivefull.py) suggest live-service dependencies that may not run in CI. The ci.yml workflow exists but its coverage is unclear. Low - C files in repo: tools/crashtest.c, tools/querylatencydiagnostic.c, tools/waltest.c are C utilities for testing WAL behavior. They are not integrated into the Python build and may confuse contributors. Low - Dashboard static assets: The synrix_runtime/dashboard/static/assets/ folder contains a large set of prebuilt JavaScript bundles and images. This is normal for a built frontend but makes the repo heavier than a pure Python project.
The Bottom Line
Octopoda solves a real problem — persistent agent memory with operational guardrails — and the codebase is well-organized with meaningful tests and integration adapters. The lack of a lockfile and the cloud-dependent test files are the main concerns. Teams building multi-agent systems on Python frameworks will find this immediately useful; solo developers experimenting with agents may prefer the simpler local mode.