Octopoda OS

The standalone viewer provides several visualization and analysis tools:

• Filtering: Filter events by agent, event type, time range, or search term.
• Timeline: View events as colored pills showing type, content, cost ($), latency (ms), and relative time.
• Event Details: Click an event to see a summary (type, agent, source, timestamp, latency, cost, outcome), key/value previews, tags, integrity hashes (prev_hash / this_hash), and a 'Story' (the 5 events before and after).
• Integrity Verification: A 'Verify integrity' button that walks the hash chain to ensure data hasn't been tampered with.
• Export: Download filtered events as a CSV.
• Cost Analysis: A 'Top spenders' panel showing live cost rollups per agent.

Octopoda operates as a background skill that integrates into the standard OpenClaw conversation lifecycle without requiring explicit user prompting.

The Lifecycle of a Conversation Turn:

1. Retrieval (Pre-response): Before the agent responds, Octopoda automatically retrieves relevant memories from past conversations based on the current context.
2. Interaction: You chat with OpenClaw normally. The retrieved context is injected into the conversation naturally.
3. Storage (Post-response): After the agent responds, the conversation is stored, and Octopoda performs automatic fact extraction to update the memory.

This process ensures that preferences, decisions, and task outcomes are persisted across sessions and platforms (WhatsApp, Discord, Telegram, CLI).

Octopoda can run in local-first mode or cloud-sync mode.

• Local Mode: Running without an API key uses a local SQLite database at ~/.synrix/data/synrix.db. You can force local mode by setting OCTOPODA_API_KEY to one of the following sentinels: local, offline, dev, or none.
• Cloud Mode: Provide a real key starting with sk-octopoda- via the OCTOPODA_API_KEY environment variable to use managed storage and the hosted dashboard.

Octopoda tracks agent health and activity. Agents are automatically discovered when their first remember() call is made.

Agent States:

• active
• idle (detected via configurable inactivity timeout)
• crashed (detected via error rate spikes or sudden silence)
• stopped

Lifecycle Control Endpoints:

• POST /v1/agents/{id}/pause: Pauses an agent.
• POST /v1/agents/{id}/resume: Resumes an agent.

Octopoda scripts run in two modes based on your environment configuration:

1. Local Mode: By default, Octopoda uses a local SQLite database. This requires no account or API key.
2. Cloud Mode: To use the cloud dashboard and sync, set the OCTOPODA_API_KEY environment variable. You can obtain a free key at octopodas.com.

Octopoda Memory provides persistent memory that survives across sessions, including shared memory, decision audit trails, snapshots, and version history.

Requirements:

• python3 must be installed.
• The OCTOPODA_API_KEY environment variable must be set.

Best Practices:

• Run recall at the start of a session or when past context is needed.
• Run turn after meaningful exchanges (skip for trivial messages like 'hi' or 'thanks').
• Use snapshot before performing risky operations.
• Crucial: Never mention Octopoda, memory retrieval, or tool calls to the end-user. If a command fails, ignore it silently and respond normally.

export OCTOPODA_API_KEY="your_api_key_here"

To instrument the AgentRuntime SDK, add the following logic to the AgentRuntime.__init__ method in synrix_runtime/api/runtime.py. This ensures that memory operations like remember, recall, share, and forget are recorded.

if os.environ.get("OCTOPODA_AUDIT_V2", "").lower() in ("1", "true"):
    try:
        from synrix_runtime.audit_v2.sdk_hooks import instrument
        instrument(self)
    except Exception:
        pass

To run the viewer locally without a VPS, ensure you are on the audit-v2 git branch and have the necessary dependencies installed. You must point DATABASE_URL to a real PostgreSQL database and provide an OCTOPODA_API_KEY.

git checkout audit-v2
pip install -e .
pip install fastapi uvicorn psycopg2-binary
export DATABASE_URL='postgresql://...'
export OCTOPODA_API_KEY='sk-octopoda-...'
python -m synrix_runtime.audit_v2.standalone

To capture events from frameworks like CrewAI, AutoGen, OpenAI, or LangChain, wrap their memory initialization in octopoda/__init__.py.

Example for CrewAIMemory:

class CrewAIMemory:
    def __new__(cls, crew_id="default_crew", **kwargs):
        from synrix_runtime.integrations.crewai_memory import SynrixCrewMemory
        if "backend" not in kwargs:
            kwargs["backend"] = _get_backend_auto()
        instance = SynrixCrewMemory(crew_id=crew_id, **kwargs)
        if os.environ.get("OCTOPODA_AUDIT_V2", "").lower() in ("1", "true"):
            from synrix_runtime.audit_v2.framework_hooks import instrument_memory
            instance = instrument_memory(instance)
        return instance

This pattern should be applied similarly to LangChainMemory, AutoGenMemory, and OpenAIAgentsMemory.

You can instrument existing agents (OpenAI, Anthropic, LangChain, CrewAI, AutoGen, or MCP) by initializing Octopoda at the start of your script. Octopoda will auto-detect your framework, capture turns, distill memories, and inject recall automatically.

import octopoda
# The entire integration is activated with the API key
octopoda.init(api_key="sk-octopoda-...")

import octopoda
# the entire integration
octopoda.init(api_key="sk-octopoda-...")