Octopoda OS - Moses Yebei

Abstract

The open-source memory operating system for AI agents. Persistent memory, semantic search, loop detection, agent messaging, crash recovery, and real-time observability.

The Problem

AI agents lack durable memory across sessions, waste tokens on undetected loops, and offer no visibility into why they made decisions. Octopoda addresses these three failure modes with a single runtime that layers persistent storage, loop detection, and audit logging onto any agent.

What This Does

synrix/ is the core client library. synrix/agent_backend.py initializes storage backends (SQLite, PostgreSQL, cloud) and synrix/cloud.py handles remote sync. synrix_runtime/ contains the server-side daemon (synrix_runtime/core/daemon.py), the REST API (synrix_runtime/api/runtime.py), an MCP server (synrix_runtime/api/mcp_server.py), and a dashboard (synrix_runtime/dashboard/).

The examples/ directory holds 12 standalone demos covering loop detection, model debates, and framework comparisons. openclaw-skill/ and octopoda/ are separate packaging efforts. This is a portfolio of six self-contained projects, not one unified codebase.

How It Is Wired

Execution starts at main in synrix/cli.py:53, which reaches 234 functions. The daemon's background loops (_anomaly_detector_loop, _cold_start_recovery_bg, _gc_loop, _heartbeat_monitor_loop in synrix_runtime/core/daemon.py) handle recovery and cleanup. From any entry point, the code reaches external effects in 1-2 hops: main → call_gpt does a requests.post network call; _gc_loop → run_gc → vacuum executes SQLite conn.execute.

The highest-blast-radius modules are synrix/agent_backend.py (24 modules import it), synrix_runtime/config.py (22 importers), and synrix_runtime/core/daemon.py (18 importers). synrix_runtime/api/runtime.py and synrix/cloud.py sit inside circular imports—changing them risks breaking mutually-reachable modules. query_prefix (94 call sites) and remember (82 call sites) are the most-called functions; changing their signatures breaks the most code.

How To Use It

git clone https://github.com/moses-y/Octopoda-OS
cd Octopoda-OS
pip install -e .

Configure via .env.example (copy to .env): set OCTOPODA_API_KEY for cloud sync. Run the dashboard server with octopoda from the CLI, or use the Dockerfile/docker-compose.yml for containerized deployment. The README documents pip install octopoda and AgentRuntime("my_agent") as the primary API.

Real-World Use

from octopoda import AgentRuntime

agent = AgentRuntime("support_bot")
agent.remember("user_pref", {"tone": "concise"})
result = agent.recall("user_pref")

For a production deployment, run the daemon via Docker, point it at PostgreSQL, and use the MCP server to connect agent frameworks to the memory layer.

Code Health & Issues

Static analysis found 102 issues (18 high, 84 medium): 23 deep-nesting cases (max depth 8 in synrix_runtime/core/daemon.py), 22 broad exception handlers, 4 oversized files (up to 2,351 lines in synrix_runtime/api/runtime.py), 4 import-cycle members, and 129 duplicated 6-line blocks across 52 files. The most-connected modules (synrix/agent_backend.py, synrix_runtime/config.py) are hub modules—high churn risk.

SDLC observations: CI exists (GitHub Actions) but actions aren't pinned to SHAs, no lockfile is committed, the Docker base image isn't digest-pinned, and workflows lack least-privilege token permissions. Tests are present (34 files, 208 passing per README), and no secrets were found committed.

The Bottom Line

This is a functional agent-memory system with real depth—persistent storage, loop detection, and observability are all implemented and tested. The main risks are maintainability (large files, circular imports) and supply-chain hygiene (unpinned actions, no lockfile). Use it if you need agent memory with minimal setup and can tolerate the code quality trade-offs.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

197 files

Python124
Markdown10
YAML6
JavaScript4
Shell3
C3

FlaskDockerLangChain

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["synrix_runtime<br/>51 modules"] g1["synrix<br/>32 modules"] g2["tests<br/>28 modules"] g3["examples<br/>12 modules"] g2 -->|38| g0 g0 -->|32| g1 g2 -->|25| g1 g3 -->|5| g1 g3 -->|1| g0 g1 -->|1| g0

Module dependencies

The 10 most depended-upon modules of 126, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_synrix_agent_backend["agent_backend"] n1_synrix_runtime_config["config"] n2_synrix_runtime_core_daemon["daemon"] n3_synrix_cloud["cloud"] n4_synrix_runtime_api_runtime["runtime"] n5_x_runtime_monitoring_metrics["metrics"] n6_synrix_exceptions["exceptions"] n7_synrix_licensing["licensing"] n8_rix_runtime_api_cloud_server["cloud_server"] n9_synrix___init__["__init__"] n9_synrix___init__ --> n6_synrix_exceptions n9_synrix___init__ --> n7_synrix_licensing n9_synrix___init__ --> n0_synrix_agent_backend n9_synrix___init__ --> n3_synrix_cloud n3_synrix_cloud --> n9_synrix___init__ n7_synrix_licensing --> n6_synrix_exceptions n8_rix_runtime_api_cloud_server --> n5_x_runtime_monitoring_metrics n8_rix_runtime_api_cloud_server --> n4_synrix_runtime_api_runtime n8_rix_runtime_api_cloud_server --> n7_synrix_licensing n8_rix_runtime_api_cloud_server --> n2_synrix_runtime_core_daemon n4_synrix_runtime_api_runtime --> n3_synrix_cloud n4_synrix_runtime_api_runtime --> n0_synrix_agent_backend n4_synrix_runtime_api_runtime --> n2_synrix_runtime_core_daemon n4_synrix_runtime_api_runtime --> n1_synrix_runtime_config n4_synrix_runtime_api_runtime --> n5_x_runtime_monitoring_metrics n2_synrix_runtime_core_daemon --> n0_synrix_agent_backend n2_synrix_runtime_core_daemon --> n1_synrix_runtime_config n5_x_runtime_monitoring_metrics --> n0_synrix_agent_backend classDef cyc stroke:#ef4444,stroke-width:2px; class n3_synrix_cloud,n4_synrix_runtime_api_runtime,n9_synrix___init__ cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium6

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

appleboy/ssh-action@v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/ci.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.